80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 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 持久化目录三项关键能力。
|