dingdanquanliucheng/backend/README.md

# Backend

## 当前进度

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

## 启动方式

```bash
uvicorn 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 重新生效。
- 订单与系统管理关键接口已开始同时走角色校验和权限码校验，和真实菜单授权结果对齐。
- `/api/reminders/check-all` 已补齐统一提醒触发入口，会串行执行欠款提醒、沉默客户提醒和物流超时提醒检查。

## 报表导出补充说明

- `/api/reports/performance/export` 当前支持 `export_format=csv` 和 `export_format=xlsx` 两种导出格式。
- `xlsx` 导出会生成基础表头样式与列宽，便于直接给业务查看。