dingdanquanliucheng/docs/部署与验收说明.md

部署与验收说明

1. 当前可直接执行的后端自测

在项目根目录执行：

cd backend
python -m py_compile app/api/*.py app/services/*.py app/core/*.py app/schemas/*.py
python scripts/smoke_check.py

说明：

• py_compile 用于快速检查接口、服务、配置和请求模型的语法有效性。
• smoke_check.py 会校验三项关键能力：
  • 报表 xlsx 导出是否能真实生成文件
  • OSS 上传签名地址是否能正常生成
  • token 持久化失效目录是否可写

2. 当前可直接执行的前端构建

Web 管理后台：

cd frontend/web-admin
npm install
npm run build

Web 业务员端：

cd frontend/web-sales
npm install
npm run build

说明：

• 两个 Web 前端当前都已完成生产构建验证，可直接输出 dist 产物。
• 最终上线前请先按 最终替换清单 替换配置。

3. 测试环境部署步骤

1. 准备 MySQL 8.0+ 和 .env
2. 执行 alembic upgrade head
3. 执行 python scripts/bootstrap_data.py
4. 启动后端：uvicorn main:app --reload
5. 执行 python scripts/smoke_check.py
6. 构建 frontend/web-admin 与 frontend/web-sales
7. 按 开发细节/04-测试用例清单.md 依次跑认证、订单、履约、提醒、报表、系统管理用例

4. 当前已具备的关键验收点

• 认证：登录、/me、/logout、token 持久化失效
• 订单：建单、提交、审批、取消、发厂确认、状态流转
• 履约：司机任务创建、接单、揽货、送达、轨迹写入
• 文件：OSS 预签名上传地址、附件落库、文件校验
• 提醒：欠款、沉默客户、物流超时、统一触发入口
• 报表：月/季/年统计、CSV/XLSX 双导出、附件与审计留痕
• 前端：web-admin 已补审批、履约、系统管理、报表页，web-sales 已补订单和真实提醒页，两端已通过构建
• 配置：最终替换项已单独整理到 最终替换清单

5. 剩余外部联调项

• 第三方物流轨迹正式服务商地址与凭证
• 阿里云 OCR 正式生产配置
• 真实测试/生产 OSS Bucket 与域名策略确认