开发实施与部署准备清单
1. 文档定位
本文用于补齐《开发任务清单与验收标准.md》和 开发细节 前 4 份文档之外的实施准备内容，重点解决以下问题：
- 开发前需要准备哪些账号、环境、配置和资料。
- 前后端、小程序、数据库、第三方服务按什么顺序开发和联调。
- 测试环境、生产环境如何部署、初始化和验收。
- 哪些事项不应写死在代码里，需要通过环境变量或后台配置管理。
本文不替代以下文档：
| 文档 |
职责 |
01-页面级原型字段说明.md |
页面、字段、按钮、筛选项、弹窗和权限状态 |
02-API细化设计.md |
接口 request/response、枚举、错误码和业务规则 |
03-数据库调整设计.md |
表结构调整、迁移 SQL、初始化配置 |
04-测试用例清单.md |
可执行测试用例和验收通过标准 |
2. 技术栈落地约定
| 层级 |
技术 |
约定 |
| 后端 |
Python + FastAPI |
提供 HTTP/JSON API，统一响应、统一错误码、JWT 鉴权 |
| ORM/迁移 |
SQLAlchemy + Alembic |
所有表结构变更必须走 migration |
| 数据库 |
MySQL 8.0+ |
字符集 utf8mb4，金额使用 decimal，不使用 float |
| 缓存/任务 |
一期可先用数据库 + 定时任务 |
如后续引入 Redis/Celery，需另行补充部署说明 |
| WEB 前端 |
Vue 3 + Vite + Element Plus + Pinia + Vue Router |
业务员端和管理后台可共用工程能力，也可拆成两个入口 |
| 小程序 |
微信原生小程序 |
管理层端、司机端按原生 WXML/WXSS/JS 开发 |
| 文件存储 |
阿里云 OSS |
图片、视频、导入文件、导出文件、附件统一存储 |
| AI/OCR |
阿里云模型/OCR |
通过后端适配层调用，禁止前端直接持有密钥 |
| 部署 |
Nginx + 后端进程服务 + MySQL |
生产环境必须使用 HTTPS |
3. 开发前必备资料
3.1 业务资料
| 资料 |
用途 |
责任方 |
状态 |
| 角色清单 |
初始化管理员、管理层、业务员、司机权限 |
甲方确认 |
待准备 |
| 初始用户清单 |
初始化登录账号 |
甲方提供 |
待准备 |
| 产品分类初始数据 |
初始化 product_category |
甲方提供 |
待准备 |
| 产品资料样例 |
产品管理、订单录入联调 |
甲方提供 |
待准备 |
| 客户资料样例 |
客户导入、订单录入联调 |
甲方提供 |
待准备 |
| 工厂/供应商资料 |
下发文本、司机任务分配 |
甲方提供 |
待准备 |
| 下发工厂文本样例 |
生成和确认下发文本 |
甲方提供 |
待准备 |
| AI/OCR 样例图片 |
OCR 字段识别、人工修正联调 |
甲方提供 |
待准备 |
| 报表统计口径确认 |
月/季/年、分类、提成汇总 |
甲方确认 |
待准备 |
3.2 微信小程序资料
| 资料 |
说明 |
状态 |
| 小程序 AppID |
管理层端和司机端是否共用 AppID 需确认 |
待准备 |
| 小程序主体认证 |
发布正式版前必须完成 |
待准备 |
| 服务器域名备案 |
API 域名必须备案并支持 HTTPS |
待准备 |
| request 合法域名 |
后端 API 域名加入白名单 |
待准备 |
| uploadFile 合法域名 |
OSS 上传域名加入白名单 |
待准备 |
| downloadFile 合法域名 |
OSS 下载或 CDN 域名加入白名单 |
待准备 |
| 体验成员名单 |
联调和验收阶段使用 |
待准备 |
3.3 阿里云资料
| 资料 |
说明 |
状态 |
| OSS Bucket |
建议区分测试和生产 Bucket |
待准备 |
| OSS Endpoint |
与 Bucket 所在地域一致 |
待准备 |
| OSS 访问域名 |
可使用默认域名或绑定自定义域名/CDN |
待准备 |
| OSS AccessKey |
后端服务端使用，禁止前端写死 |
待准备 |
| OSS 上传大小限制 |
图片、视频、导入文件分别设置上限 |
待确认 |
| OSS 生命周期策略 |
临时文件、导出文件是否自动清理 |
待确认 |
| 阿里云 OCR/模型服务 |
开通服务、确认地域、模型能力 |
待准备 |
| AI/OCR 调用凭证 |
后端环境变量管理 |
待准备 |
| AI/OCR 费用预算 |
设置费用告警，避免失控调用 |
待确认 |
4. 环境规划
4.1 环境划分
| 环境 |
用途 |
数据要求 |
外部服务 |
| 本地开发环境 |
开发调试 |
可使用本地 MySQL 或开发库 |
可使用测试 OSS/OCR |
| 测试环境 |
前后端联调、验收测试 |
独立测试库，允许构造数据 |
使用测试 Bucket 和测试配置 |
| 生产环境 |
正式业务使用 |
真实业务库，必须备份 |
使用生产 Bucket、生产域名、生产凭证 |
4.2 推荐目录结构
project/
backend/
app/
migrations/
tests/
requirements.txt
.env.example
frontend/
web-admin/
web-sales/
mini-manager/
mini-driver/
docs/
deploy/
说明：
- 当前文档在项目根目录维护，后续实现时可将部署脚本放入
deploy/。
- 如果 WEB 管理后台和业务员端共用一个 Vue 工程，应通过路由和权限区分入口。
- 如果拆分两个 Vue 工程，需要共用 API SDK、枚举和响应处理逻辑，避免字段重复维护。
5. 后端环境变量清单
后端必须提供 .env.example，真实 .env 不提交代码仓库。
| 变量名 |
示例 |
说明 |
APP_ENV |
dev/test/prod |
当前环境 |
APP_NAME |
order-flow |
应用名称 |
API_PREFIX |
/api |
API 前缀 |
SECRET_KEY |
change-me |
JWT 签名密钥，生产必须更换 |
JWT_EXPIRE_MINUTES |
1440 |
token 有效期 |
MYSQL_HOST |
127.0.0.1 |
MySQL 地址 |
MYSQL_PORT |
3306 |
MySQL 端口 |
MYSQL_DATABASE |
order_flow |
数据库名 |
MYSQL_USER |
order_user |
数据库用户 |
MYSQL_PASSWORD |
password |
数据库密码 |
SQL_ECHO |
false |
是否输出 SQL |
ALIYUN_OSS_BUCKET |
bucket-name |
OSS Bucket |
ALIYUN_OSS_ENDPOINT |
oss-cn-hangzhou.aliyuncs.com |
OSS Endpoint |
ALIYUN_OSS_ACCESS_KEY_ID |
xxx |
OSS AccessKey ID |
ALIYUN_OSS_ACCESS_KEY_SECRET |
xxx |
OSS AccessKey Secret |
ALIYUN_OSS_PUBLIC_BASE_URL |
https://cdn.example.com |
文件访问基础域名 |
OSS_UPLOAD_MAX_IMAGE_MB |
10 |
图片上传上限 |
OSS_UPLOAD_MAX_VIDEO_MB |
200 |
视频上传上限 |
ALIYUN_AI_REGION |
cn-hangzhou |
AI/OCR 地域 |
ALIYUN_AI_ACCESS_KEY_ID |
xxx |
AI/OCR AccessKey ID |
ALIYUN_AI_ACCESS_KEY_SECRET |
xxx |
AI/OCR AccessKey Secret |
ALIYUN_OCR_MODEL |
default |
OCR/模型服务标识 |
CORS_ALLOW_ORIGINS |
https://admin.example.com |
WEB 跨域白名单 |
LOG_LEVEL |
INFO |
日志级别 |
6. 前端和小程序配置清单
6.1 Vue WEB 配置
| 配置 |
示例 |
说明 |
VITE_API_BASE_URL |
https://api.example.com/api |
后端 API 地址 |
VITE_APP_TITLE |
订单全流程系统 |
页面标题 |
VITE_UPLOAD_MODE |
oss-token |
通过后端获取 OSS 上传凭证 |
VITE_ENV_NAME |
test/prod |
页面展示和问题定位 |
前端不得配置任何 OSS 或 AI 密钥。
6.2 微信小程序配置
| 配置 |
示例 |
说明 |
appId |
微信公众平台 AppID |
project.config.json 使用 |
apiBaseUrl |
https://api.example.com/api |
小程序请求后端 |
ossUploadDomain |
https://bucket.oss-cn-hangzhou.aliyuncs.com |
上传域名需加白名单 |
envName |
test/prod |
环境识别 |
发布前必须确认：
- API 域名、上传域名、下载域名均已加入小程序合法域名。
- 生产域名证书有效且证书链完整。
- 小程序体验版能在真实微信环境调用 API 和上传文件。
7. 数据库实施准备
7.1 建库要求
| 项 |
要求 |
| MySQL 版本 |
8.0+ |
| 字符集 |
utf8mb4 |
| 排序规则 |
建议 utf8mb4_0900_ai_ci 或统一使用项目约定 |
| 时区 |
统一使用 Asia/Shanghai |
| 金额字段 |
decimal(18,2) |
| 数量字段 |
decimal(18,4) 或与数据库设计保持一致 |
7.2 迁移顺序
| 顺序 |
内容 |
说明 |
| 1 |
导入基础表结构 |
基于 数据库.sql |
| 2 |
执行结构调整 migration |
对应 03-数据库调整设计.md |
| 3 |
初始化角色、菜单、权限 |
支撑登录和页面权限 |
| 4 |
初始化系统配置 |
如 arrears_generate_mode=delivered |
| 5 |
初始化产品分类 |
默认分类可后续在后台维护 |
| 6 |
初始化管理员账号 |
首次登录后台使用 |
| 7 |
导入测试数据 |
测试环境使用，生产谨慎执行 |
7.3 初始化数据清单
| 数据 |
必需 |
说明 |
管理员角色 admin |
是 |
拥有全部系统管理权限 |
管理层角色 manager |
是 |
审批、下发确认、任务分配、报表 |
业务员角色 salesman |
是 |
录单、本人订单、提醒 |
司机角色 driver |
是 |
本人任务、接单、揽货、送达 |
| 菜单数据 |
是 |
对应 Vue 和小程序页面入口 |
| 权限编码 |
是 |
对应按钮和接口权限 |
| 初始管理员 |
是 |
首次登录使用，首次登录后应修改密码 |
| 产品分类 |
是 |
默认可初始化工业品、日用品，也允许后台新增 |
| 系统配置 |
是 |
欠款生成模式、提醒周期、OSS/AI 摘要配置 |
| 测试客户/产品/工厂 |
测试环境必需 |
用于联调和验收 |
8. 开发实施顺序
8.1 阶段一：基础工程
| 任务 |
产物 |
验证 |
| 后端 FastAPI 工程初始化 |
后端服务、健康检查、统一响应 |
/health 可访问 |
| 数据库连接和 migration |
SQLAlchemy、Alembic |
可创建和升级数据库 |
| JWT 登录鉴权 |
登录、当前用户、退出 |
token 有效和失效场景通过 |
| 角色菜单权限 |
用户、角色、菜单、授权接口 |
/api/auth/me 返回菜单权限 |
| 前端工程初始化 |
Vue 工程、小程序工程 |
本地可启动 |
8.2 阶段二：基础资料
| 任务 |
产物 |
验证 |
| 客户管理 |
客户 CRUD、导入 |
去重和导入统计正确 |
| 产品分类和产品管理 |
分类 CRUD、产品 CRUD |
产品可关联分类 |
| 工厂/供应商管理 |
工厂 CRUD、模板类型 |
下发文本可引用工厂 |
| OSS 文件服务 |
上传凭证、附件记录 |
图片/视频上传并写库 |
8.3 阶段三：订单主流程
| 任务 |
产物 |
验证 |
| 订单创建和编辑 |
订单主表、明细、费用计算 |
金额和利润计算正确 |
| 提交审核 |
draft -> pending_approve |
重复提交被拦截 |
| 管理层审批 |
pending_approve -> approved/rejected |
审批记录和通知正确 |
| 下发工厂文本 |
生成、复制、确认 |
确认后进入 pending_factory |
| 取消流程 |
cancel_pending 和取消审批 |
拒绝后恢复原状态 |
8.4 阶段四：履约和物流
| 任务 |
产物 |
验证 |
| 手动创建司机任务 |
管理层/管理员分配任务 |
司机端可见本人任务 |
| 司机任务流转 |
接单、揽货、送达 |
状态流转正确 |
| 揽货附件 |
图片、视频上传 |
OSS 和附件记录正确 |
| 手动物流节点 |
节点录入、轨迹查询 |
按时间展示轨迹 |
| 欠款生成 |
shipped/delivered 两种模式 |
生成节点符合配置 |
8.5 阶段五：提醒、AI 和报表
| 任务 |
产物 |
验证 |
| 提醒中心 |
欠款、物流超时、沉默客户 |
不重复生成无效提醒 |
| AI/OCR 识别 |
上传图片、识别、保存结果 |
原始结果和置信度留存 |
| 人工修正 |
修正结果和留痕 |
不覆盖原始识别结果 |
| 报表统计 |
月/季/年、分类、固定提成 |
与数据库手工核对一致 |
| 报表导出 |
导出文件写入 OSS |
文件内容与页面一致 |
8.6 阶段六：联调验收
| 任务 |
产物 |
验证 |
| 接口契约联调 |
前后端字段一致 |
无临时字段依赖 |
| 小程序真机联调 |
管理层端、司机端 |
登录、审批、任务、上传可用 |
| 全流程 E2E |
从录单到送达、欠款、报表 |
核心流程跑通 |
| 权限回归 |
四类角色越权测试 |
越权被拦截 |
| 验收测试 |
执行 04-测试用例清单.md |
阻断和严重缺陷为 0 |
9. 联调检查清单
9.1 后端自测
- 所有接口返回统一结构：
code/message/data。
- 所有受保护接口无 token 返回
40002。
- 越权访问返回
40003 或按安全策略返回 40004。
- 非法状态流转返回
40005。
- 业务重复数据返回
40006。
- 第三方服务失败返回
40008 或 40009。
- 关键写操作写入
audit_log。
9.2 Vue WEB 联调
- 登录后菜单和按钮由
/api/auth/me 控制。
- 业务员端不能看到成本、利润、回扣等无权限字段。
- 管理后台可维护用户、角色、菜单、产品分类、产品、客户、工厂、配置。
- 表格分页参数与 API 文档一致：
page_no/page_size。
- 金额显示保留 2 位小数，数量按业务字段要求显示。
- 文件上传先取后端上传凭证，再上传 OSS，再保存附件记录。
9.3 小程序联调
- 真机能访问 API 域名。
- 真机能上传图片和视频到 OSS。
- 管理层端能完成审批、取消审批、下发确认、任务分配。
- 司机端只显示本人任务。
- 司机端揽货必须上传照片。
- token 过期后跳转登录页。
9.4 第三方服务联调
- OSS 上传、下载、删除或过期策略符合预期。
- AI/OCR 成功调用时保存
raw_result、confidence、suggested_result。
- AI/OCR 失败时不影响订单主流程，只返回明确错误并记录日志。
- 费用告警已开启。
10. 部署准备
10.1 服务器准备
| 项 |
要求 |
| 操作系统 |
Linux 服务器，建议 Ubuntu LTS 或 CentOS/Rocky |
| Python |
3.11+ |
| Node.js |
20 LTS |
| MySQL |
8.0+ |
| Nginx |
用于 HTTPS、静态资源、反向代理 |
| 磁盘 |
预留数据库备份和日志空间 |
| 时间同步 |
开启 NTP，避免 token 和日志时间异常 |
10.2 后端部署
| 步骤 |
说明 |
| 安装依赖 |
使用虚拟环境安装 requirements.txt |
| 配置环境变量 |
根据第 5 节配置 .env |
| 执行 migration |
升级数据库到最新版本 |
| 初始化数据 |
角色、菜单、权限、配置、管理员 |
| 启动服务 |
使用 systemd/supervisor 管理进程 |
| 健康检查 |
/health 返回正常 |
| 日志检查 |
启动日志无异常，错误日志可追踪 |
10.3 Vue WEB 部署
| 步骤 |
说明 |
| 安装依赖 |
npm install 或约定包管理器 |
| 配置环境变量 |
设置 API 地址和环境名 |
| 构建 |
生成静态资源 |
| Nginx 发布 |
配置静态目录和 history 路由 fallback |
| 验证 |
登录、刷新页面、接口调用正常 |
10.4 小程序发布
| 步骤 |
说明 |
| 配置 AppID |
微信开发者工具项目配置 |
| 配置环境 |
API 地址、上传域名 |
| 上传体验版 |
添加体验成员 |
| 真机测试 |
登录、审批、任务、上传、OCR |
| 提交审核 |
确认类目、隐私协议、接口域名 |
| 发布正式版 |
审核通过后发布 |
11. Nginx 配置要求
| 项 |
要求 |
| HTTPS |
生产环境必须启用 |
| API 反向代理 |
/api 转发到 FastAPI 服务 |
| 静态资源 |
Vue dist 目录由 Nginx 托管 |
| 上传大小 |
client_max_body_size 大于业务上传上限 |
| 超时 |
AI/OCR 接口可适当提高代理超时 |
| 日志 |
开启 access/error 日志 |
| 安全头 |
建议配置基础安全响应头 |
12. 备份和恢复
| 内容 |
要求 |
| 数据库备份 |
生产环境每日自动备份，至少保留 7-30 天 |
| OSS 文件 |
开启版本控制或生命周期策略，按成本决定 |
| 配置备份 |
.env、Nginx 配置、部署脚本需安全备份 |
| 恢复演练 |
上线前至少完成一次测试库恢复验证 |
| 导出文件 |
可设置生命周期自动清理 |
13. 安全要求
- OSS、AI、JWT、数据库密码不得提交代码仓库。
- 生产环境禁止使用默认管理员密码。
- 后端必须控制字段权限，前端隐藏不能作为安全边界。
- 业务员只能访问本人订单、客户和提醒。
- 司机只能访问本人任务。
- 管理后台系统管理接口默认仅管理员可用。
- 所有关键写操作必须有审计日志。
- 文件上传必须限制类型、大小和业务归属。
- AI/OCR 输入图片必须来自已授权 OSS 文件或后端可校验的文件地址。
14. 上线前验收检查
| 检查项 |
标准 |
| 数据库迁移 |
测试和生产 migration 可重复执行且可回滚 |
| 初始化数据 |
角色、菜单、权限、配置、管理员存在 |
| 登录鉴权 |
四类角色登录和 token 过期处理正常 |
| 核心流程 |
录单、审批、下发、任务、揽货、送达、欠款、报表跑通 |
| 取消流程 |
cancel_pending、取消审批通过/拒绝正确 |
| 欠款模式 |
shipped 和 delivered 两种模式验证通过 |
| OSS |
图片、视频、导入、导出均可用 |
| AI/OCR |
成功、失败、人工修正均验证通过 |
| 小程序 |
体验版真机通过，合法域名配置正确 |
| 权限 |
越权访问被后端拦截 |
| 审计日志 |
关键操作可追溯 |
| 备份 |
数据库备份任务已配置并验证恢复 |
| 缺陷 |
阻断缺陷 0，严重缺陷 0 |
15. 交付物清单
| 交付物 |
内容 |
验收方式 |
| 后端源码 |
FastAPI、模型、服务、接口、任务、第三方适配 |
接口和测试通过 |
| 数据库迁移 |
Alembic migration、初始化数据脚本 |
新库可完整初始化 |
| Vue WEB |
业务员端、管理后台 |
浏览器可访问并完成流程 |
| 小程序源码 |
管理层端、司机端 |
微信开发者工具和真机可运行 |
| 部署配置 |
Nginx、服务进程、环境变量模板 |
新环境可按文档部署 |
| 测试报告 |
用例执行结果、缺陷记录 |
验收标准满足 |
| 操作说明 |
角色登录、录单、审批、任务、配置、报表 |
业务人员可按说明操作 |
16. 仍需甲方确认或提供的事项
| 事项 |
影响 |
建议完成时间 |
| 小程序 AppID 和合法域名 |
影响小程序真机联调和发布 |
开发联调前 |
| 阿里云 OSS Bucket 和凭证 |
影响文件上传、司机揽货、AI 图片识别 |
文件模块开发前 |
| 阿里云 OCR/模型凭证和预算 |
影响 AI/OCR 开发和联调 |
AI 模块开发前 |
| 初始用户、角色权限范围 |
影响权限初始化和页面入口 |
基础工程阶段 |
| 产品分类初始数据 |
影响产品录入和报表分类 |
基础资料阶段 |
| 下发工厂文本模板样例 |
影响下发文本生成效果 |
订单主流程阶段 |
| 服务器和域名 |
影响测试环境、生产环境部署 |
联调前 |
| 视觉风格或 UI 参考 |
影响页面观感，不影响字段级功能开发 |
前端开发前 |
17. 开发启动判定
满足以下条件即可正式启动开发：
- 后端、Vue、小程序技术栈已确认。
- 数据库设计和 API 细化文档已确认。
- 至少有测试环境 MySQL 可用。
- 至少有测试 OSS Bucket 和上传凭证可用。
- 小程序 AppID 可在联调前提供。
- 初始角色和管理员账号规则已确认。
- 核心流程验收用例已确认。
如果 AI/OCR 凭证暂未准备好，可以先实现后端适配层和 mock provider，但真实上线前必须完成阿里云真实服务联调。
