# 外包执行计划：P0/P1 稳定性与自动化治理（2026-03-04）

> 文档版本: v1.0  
> 创建日期: 2026-03-04  
> 适用范围: AgomTradePro 平台工程治理专项（非业务功能新增）  
> 对接对象: 外包开发团队、测试团队、项目负责人

---

## 1. 目标与范围

本计划聚焦以下 4 个事项（按优先级）：

1. P0：统一所有容器健康检查到 `/api/health/`，并完成一次 PostDeploy Gate 实测。
2. P0：AI Provider 密钥加密（字段加密或 KMS/Vault），并完成审计日志脱敏。
3. P1：统一 CI 与运行时 Python 版本策略（双版本 3.11/3.13 或锁定 3.11）。
4. P1：建立“文档-路由-SDK”自动一致性校验，降低口径漂移。

不在本期范围内：

1. 业务规则变更（策略逻辑、评分逻辑、风控阈值）。
2. 页面 UI 改版。
3. 新业务模块扩展。

---

## 2. 基线信息（执行前确认）

当前已识别基线（用于外包团队对齐）：

1. 系统主健康检查路由为 `/api/health/`（`core/urls.py`）。
2. 部分 Docker/Compose 健康检查仍使用 `/health/`，存在口径不一致风险。
3. AI Provider 配置中 `api_key` 当前为明文字段。
4. CI 工作流当前使用 Python 3.13；项目工具链主要按 3.11 配置。

---

## 3. 工作拆解（WBS）

## WP-1（P0）：容器健康检查统一 + PostDeploy Gate

### 3.1 目标

将容器/反向代理/镜像内 HEALTHCHECK 统一到 `/api/health/`，并在 Docker 环境完成一次完整 PostDeploy 验证。

### 3.2 实施任务

1. 盘点所有健康检查配置引用（Dockerfile、Compose、Nginx、启动脚本）。
2. 统一替换为 `/api/health/`。
3. 修正与健康检查联动的部署文档与运行手册。
4. 编写或更新 PostDeploy Gate 执行脚本（建议 `scripts/postdeploy-gate.ps1`）。
5. 在目标部署环境执行一次实测，输出报告。

### 3.3 预期修改文件（最小集合）

1. `Dockerfile`
2. `docker/Dockerfile.prod`
3. `docker-compose.yml`
4. 如有需要：`docker/Dockerfile.prod.mirror`、`nginx` 配置、部署文档
5. 新增：`scripts/postdeploy-gate.ps1`（或等效脚本）
6. 新增：`reports/regression/<date>/postdeploy-gate.md`

### 3.4 验收标准（DoD）

1. 所有容器健康检查统一为 `/api/health/`，无残留 `/health/` 口径。
2. `docker compose up` 后 `web/nginx` 健康状态为 healthy（如启用 nginx）。
3. PostDeploy Gate 覆盖并通过以下项：
   1. `/api/health/` 可用。
   2. 核心读写路径验证通过（至少 1 读 + 1 写 + 1 回读）。
   3. Celery 关键任务成功触发并可观测。
   4. 告警链路可触发并记录。
4. 形成可归档证据：命令、截图/日志、结论。

---

## WP-2（P0）：AI Provider 密钥加密 + 审计日志脱敏

### 4.1 目标

消除明文密钥落库与日志泄露风险，保证密钥在“存储、传输、展示、日志”四个环节均受控。

### 4.2 方案约束

外包团队先给出方案评审，二选一：

1. 方案 A（推荐，短周期）：应用层字段加密（Fernet/等效）+ 环境主密钥。
2. 方案 B（长期）：外部 KMS/Vault 托管（需要运维环境配合）。

本期要求至少落地方案 A；方案 B 可作为后续增强项。

### 4.3 实施任务

1. 数据模型改造：
   1. 新增加密存储字段（如 `api_key_encrypted`）。
   2. 明文 `api_key` 进入兼容迁移期，禁止新写入。
2. 数据迁移：
   1. 编写 migration + 管理命令，完成历史明文密钥加密迁移。
   2. 迁移后执行一致性校验与回滚预案演练。
3. 读写路径改造：
   1. 仓储层统一解密读取，不允许业务层直接处理明文。
   2. Admin/Serializer/API 返回值默认掩码（只显示后 4 位）。
4. 审计日志脱敏：
   1. 全链路排查 `api_key/token/authorization` 字段写日志行为。
   2. 增加统一脱敏函数并替换调用点。
5. 自动化测试：
   1. 单测覆盖“加密存储、解密读取、掩码展示、日志脱敏、迁移脚本”。
   2. 增加回归用例，防止明文回归。

### 4.4 预期交付

1. 模型与迁移脚本。
2. 管理命令（历史密钥重加密）。
3. 脱敏工具与接入改造。
4. 测试报告与安全自查表。

### 4.5 验收标准（DoD）

1. 数据库内无新增明文 `api_key` 写入。
2. 历史存量完成加密迁移并可验证。
3. API/Admin/UI 不回显明文密钥。
4. 日志中无明文密钥、无完整 Authorization 值。
5. 安全回归测试通过。

---

## WP-3（P1）：CI 与运行时 Python 版本策略统一

### 5.1 目标

消除 CI 与本地/生产运行时版本漂移，降低“CI 通过但运行异常”风险。

### 5.2 决策项（D-1）

由项目负责人在第 1 周确定策略：

1. 策略 S1（推荐）：CI 双版本矩阵 `3.11 + 3.13`，运行时主版本 `3.11`。
2. 策略 S2（保守）：CI 与运行时全部锁定 `3.11`。

### 5.3 实施任务

1. 更新 GitHub Actions 工作流 Python 版本配置。
2. 校准 `pyproject.toml`、Docker 基础镜像、开发文档版本口径。
3. 补充版本兼容性说明与升级策略。
4. 增加一次版本一致性检查（脚本或 CI step）。

### 5.4 验收标准（DoD）

1. CI 版本声明与文档一致。
2. 运行时镜像版本与策略一致。
3. 全量关键门禁在目标版本集通过。
4. 外包交付含“版本决策记录 + 风险说明”。

---

## WP-4（P1）：文档-路由-SDK 自动一致性校验

### 6.1 目标

建立自动检查机制，识别三类漂移：

1. 文档写了但路由不存在。
2. 路由存在但 SDK 未覆盖或映射错误。
3. SDK 声明能力与文档/API 实际不一致。

### 6.2 实施任务

1. 编写一致性检查脚本（建议：`scripts/check_doc_route_sdk_consistency.py`）。
2. 数据源定义：
   1. 路由：Django URL resolver + 各模块 `urls.py`。
   2. SDK：`sdk/agomtradepro/modules` + MCP 工具注册清单。
   3. 文档：`docs/` 下 API 路径文本提取（正则/规则化）。
3. 产出机器可读报告（JSON）+ 人类可读报告（Markdown）。
4. 接入 CI：新增 workflow，在 PR 阶段执行。
5. 建立 baseline 机制：历史遗留问题可登记，不阻断新增 PR。

### 6.3 验收标准（DoD）

1. 新增 workflow 稳定执行。
2. 报告可清楚列出 missing/mismatch。
3. 对“新增不一致”强阻断；对“基线遗留”告警但可控。
4. 文档维护流程有明确责任人与更新时机。

---

## 7. 里程碑与工期建议（外包版）

总工期建议：**10 个工作日**（2 周）

1. M1（D1-D2）：方案确认与技术设计冻结  
   输出：技术设计说明、任务拆解、风险清单。
2. M2（D3-D5）：完成 WP-1、WP-2 核心开发  
   输出：代码提交、迁移脚本、初版测试证据。
3. M3（D6-D8）：完成 WP-3、WP-4 与 CI 接入  
   输出：workflow、检查脚本、版本策略文档。
4. M4（D9-D10）：联调、回归、验收与归档  
   输出：验收报告、风险关闭记录、操作手册更新。

---

## 8. 测试与验收矩阵

1. 单元测试：
   1. 密钥加解密、掩码、日志脱敏。
   2. 一致性校验脚本解析逻辑。
2. 集成测试：
   1. `/api/health/` 容器联动。
   2. AI Provider 配置读写全链路。
3. 回归测试：
   1. Guardrails 全量通过。
   2. 关键业务 API 不回归。
4. 发布后验证：
   1. PostDeploy Gate 报告。
   2. 生产/准生产健康看板观察 24 小时。

---

## 9. 外包交付清单（必须）

1. 代码 PR（按 WP 分支提交，禁止大杂烩 PR）。
2. 数据迁移与回滚说明。
3. 测试报告（命令、结果、失败项说明）。
4. PostDeploy Gate 证据包。
5. 更新后的技术文档与运维手册。
6. 风险与未决项列表（含建议优先级）。

---

## 10. 管理机制与沟通节奏

1. 日报：每天提交进度、阻塞、次日计划（固定模板）。
2. 里程碑评审：M1/M2/M3/M4 四次强制评审。
3. 变更控制：
   1. P0 项变更需主项目负责人批准。
   2. 影响 DB schema 的改动需先过评审再实施。
4. 质量门禁：
   1. 未附测试证据的 PR 不评审。
   2. 未更新文档的接口改动不合并。

---

## 11. 风险清单与应对

1. 风险：密钥迁移导致历史配置不可用。  
   应对：先灰度迁移 + 可逆回滚脚本 + 迁移前备份。
2. 风险：健康检查统一后暴露隐藏依赖问题。  
   应对：先在 dev/staging 演练，再执行生产。
3. 风险：一致性检查脚本误报过多影响开发效率。  
   应对：引入 baseline 文件，新增问题阻断、存量问题告警。
4. 风险：Python 版本策略未统一导致 CI 震荡。  
   应对：先冻结策略，再一次性同步工作流与文档。

---

## 12. 一次性验收口径（最终）

满足以下条件视为该专项完成：

1. 4 个 WP 均有代码、测试、文档、证据包交付。
2. P0 项全部 closed，且无新增 P0/P1 安全缺陷。
3. CI 稳定通过，PostDeploy Gate 完整通过并归档。
4. 项目负责人完成最终验收签字。

