dingdanquanliucheng/backend/README.md

# Backend

## 当前进度

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

## 启动方式

```bash
uvicorn backend.main:app --reload
```

## 数据库迁移

执行 Alembic 迁移：

```bash
alembic upgrade head
```

## 初始化数据

迁移后执行初始化脚本：

```bash
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 持久化目录三项关键能力。