dingdanquanliucheng/开发细节/05-开发实施与部署准备清单.md

# 开发实施与部署准备清单

## 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 推荐目录结构

```text
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，但真实上线前必须完成阿里云真实服务联调。