dingdanquanliucheng/backend

Backend

当前进度

• 已完成 FastAPI 基础工程初始化
• 已完成 /health 健康检查接口
• 已完成 .env.example 和 requirements.txt
• 已完成 SQLAlchemy 模型与 Alembic 初始迁移
• 已完成角色、菜单、配置、分类、管理员初始化脚本
• 已完成文件上传与报表导出的统一对象存储发布链路

启动方式

uvicorn backend.main:app --reload

数据库迁移

执行 Alembic 迁移：

alembic upgrade head

初始化数据

迁移后执行初始化脚本：

python scripts/bootstrap_data.py

初始化内容包括：

• 角色：admin / salesman / manager / driver
• 菜单与角色授权关系
• 系统配置
• 默认产品分类
• 默认管理员账号 admin01

文件与导出链路说明

• /api/files/upload-token 已按 OSS URL 口径返回上传地址、公网访问地址、对象 key 和过期时间。
• /api/reports/performance/export 已生成真实 CSV，并发布到本地对象存储模拟目录，再返回 OSS 公网 URL 口径。
• 当前阶段未直连阿里云 SDK，发布目录用于本地和测试环境模拟 OSS 对象发布，后续可平滑切换到真实云上上传。

AI/OCR 链路说明

• /api/ai/recognize 当前支持通过 AI_PROVIDER 切换 OCR 提供方。
• AI_PROVIDER=mock 时，返回可联调用的 mock 识别结果，并保留识别记录、人工修正和审计日志链路。
• AI_PROVIDER=aliyun 时，会按 ALIYUN_OCR_ENDPOINT、ALIYUN_OCR_PATH、ALIYUN_OCR_APPCODE 发起真实 HTTP OCR 请求；如果配置不完整或第三方调用失败，会明确返回第三方调用失败，而不是继续伪装成功。

认证与提醒补充说明

• /api/auth/logout 当前会把 token 失效信息持久化到 AUTH_TOKEN_STORE_PATH，避免服务重启后已退出 token 重新生效。
• 订单与系统管理关键接口已开始同时走角色校验和权限码校验，和真实菜单授权结果对齐。
• 系统管理接口现已细化到“列表 / 新增 / 编辑 / 重置密码 / 角色授权 / 菜单维护”级别权限码，避免继续用单一 list 权限覆盖所有写操作。
• /api/reminders/check-all 已补齐统一提醒触发入口，会串行执行欠款提醒、沉默客户提醒和物流超时提醒检查。

报表导出补充说明

• /api/reports/performance/export 当前支持 export_format=csv 和 export_format=xlsx 两种导出格式。
• xlsx 导出会生成基础表头样式与列宽，便于直接给业务查看。
• 报表查询与导出接口现已分别补齐独立权限码，和管理层角色授权结果保持一致。

物流与 AI 权限补充说明

• /api/logistics/{order_id}/trace 与 /api/logistics/{order_id}/trace 新增节点接口已补齐权限码校验。
• /api/ai/recognize 与 /api/ai/recognize/{log_id}/correct 已补齐管理层/管理员角色限制与独立权限码校验。

OSS 上传补充说明

• /api/files/upload-token 当前会按 OSS V1 预签名 URL 规则生成真实 PUT 上传地址，而不是仅返回 mock 签名占位值。
• /api/files/attachments 保存附件时会再次校验文件大小、对象 key 与文件名匹配关系，避免错误附件直接入库。

自测脚本

• python scripts/smoke_check.py 可快速验证报表导出、OSS 上传签名和 token 持久化目录三项关键能力。