gaokao-volunteer-system/docs/P0_MINIMAL_API_CHANGES_2026-06-22.md

# P0_MINIMAL_API_CHANGES_2026-06-22

最后更新: 2026-06-22
状态词: P0 最小接口变更清单
真相源:
- `product/PRD_UPGRADE_2026-06-21.md`
- `docs/UPGRADE_EXECUTION_BOARD_2026-06-22.md`
- `docs/P0_EXECUTION_TASK_BREAKDOWN_2026-06-22.md`

> 本文只定义 P0 为了成立“审核优先主线”所需的最小接口与数据承接变更；不提前展开 P1 / P2。

---

## 1. 当前可复用接口盘点

当前已存在的关键接口 / 页面：

### 1.1 公开下单链

- `POST /api/public/orders`
- 返回：
  - `order_id`
  - `checkout_url`
  - `portal_status_url`
  - `portal_info_url`

当前作用：

- 创建订单
- 进入支付
- 进入 Portal 资料页 / 状态页

### 1.2 Portal 资料链

- `GET /portal/{token}/info`
- `POST /portal/{token}/info`
- `POST /portal/{token}/attachments`

当前作用：

- 四步资料向导
- 保存草稿 / 正式提交
- 上传已有方案附件

### 1.3 Portal 状态链

- `GET /portal/{token}/status`
- `GET /portal/{token}/report`
- `GET /portal/{token}/report.pdf`

当前作用：

- 看订单阶段
- 看报告 / PDF

### 1.4 当前主要限制

1. `POST /portal/{token}/info` 当前绑定 `IntakePayload`
2. `IntakePayload(mode=submit)` 当前要求至少一个偏好字段存在
3. 现有 `stage` 面向支付 / 补资料 / 交付，不面向审核结果分流
4. 现有接口无 `profile_minimum_complete` / `review_entry_source` / `review_followup_action` 语义

---

## 2. P0 最小接口策略

结论：

- **优先复用现有 Portal 链路**
- **最小新增页面域状态与轻量返回字段**
- **避免在 P0 修改订单六态状态机**

也就是：

1. 不新建整套用户系统接口
2. 先复用：
   - `/portal/{token}/info`
   - `/portal/{token}/attachments`
   - `/portal/{token}/status`
3. 必要时新增轻量接口或返回字段，承接：
   - 审核输入
   - Step 1 最小建档
   - 审核结果分流

---

## 3. P0 必改接口项

## 3.1 调整 `IntakePayload` 提交校验

### 当前问题

`data/orders/intake_schema.py` 当前在 `mode=submit` 时要求：

- `candidate_score`
- `candidate_rank`
- `candidate_subjects`
- 协议字段
- `candidate_interests`
- `target_cities`
- `target_majors`
- `university_preferences`

以上字段当前已不再作为 `mode=submit` 的阻塞校验；P0 Step 1 最小提交仅要求省份 / 分数 / 位次 / 选科 + consent。

### P0 目标

P0 提交只要求：

- `candidate_province`
- `candidate_subjects`
- `candidate_score`
- `candidate_rank`
- 协议字段

### 变更建议

把 `IntakePayload(mode=submit)` 的“至少一个偏好字段”校验下放到 P1 语义，不再阻塞 P0。

### 影响

- Step 1 可独立提交
- 审核入口不再被偏好字段卡死

---

## 3.2 把 `candidate_province` 纳入 Portal info 提交链

### 当前问题

当前 Portal info 表单主提交字段中：

- 有 `candidate_score`
- 有 `candidate_rank`
- 有 `candidate_subjects`
- **没有 Step 1 主视图里的 `candidate_province`**

而 PRD 已明确 Step 1 四字段必须包含省份。

### 变更建议

1. 给 `IntakePayload` 增加 `candidate_province`
2. 给 `/portal/{token}/info` 前端表单补 `candidate_province`
3. 在 `submit_order_info()` 中把 `candidate_province` 写回：
   - `order_intakes.payload_json`
   - 必要时冗余回 `orders.candidate_province`

### 影响

- Step 1 四字段闭环成立
- 审核最小约束与档案最小建档一致

---

## 3.3 为 `/portal/{token}/info` 响应补最小建档状态

### 当前返回

`PortalIntakeResponse` 目前只有：

- `intake_status`
- `stage`
- `order_id`

### P0 缺口

P0 需要知道：

- Step 1 是否完成
- 页面提交后是否可回到审核链路

### 变更建议

给 `PortalIntakeResponse` 增加：

- `profile_minimum_complete: bool`

可选增加：

- `profile_missing_fields: string[]`

### 计算规则

当以下字段齐全时：

- `candidate_province`
- `candidate_subjects`
- `candidate_score`
- `candidate_rank`

则 `profile_minimum_complete = true`

---

## 3.4 新增或补充首页 / 状态页聚合返回字段

### 当前问题

首页目标态要求显示：

- 当前阶段
- 是否有最近审核结果
- 是否可看报告
- Step 1 是否完成

现有公开链路没有专门的工作台聚合结构。

### P0 建议

二选一：

#### 方案 A：新增轻量聚合接口

建议新增：

- `GET /portal/{token}/workspace-summary`

最小返回：

- `stage`
- `profile_minimum_complete`
- `has_recent_review_result`
- `has_report`
- `primary_action`

#### 方案 B：复用 `_build_portal_context()` 输出

如果暂不新开接口，则在现有状态页 / 首页承接层统一从 `_build_portal_context()` 衍生：

- `profile_minimum_complete`
- `has_report`
- `primary_action`

### 推荐

- P0 推荐 **方案 B 先落**
- 等首页工作台稳定后再决定是否抽独立聚合接口

---

## 3.5 定义审核输入最小承接结构

### 当前可复用资产

现有已存在：

- `existing_plan_summary`
- attachments 上传

### P0 目标

审核最小输入统一为：

- `existing_plan_summary`
- `attachments[]`
- `candidate_province`
- `candidate_subjects`
- `candidate_score`
- `candidate_rank`

### 变更建议

不急着在 P0 新建复杂审核对象表；先定义轻量审核输入契约，供页面和后端处理链共用。

建议文档化结构：

- `review_input_summary`
- `review_input_attachments`
- `review_constraints`

如果后端要临时落地，可先存在：

- `order_intakes.payload_json`
- 或单独轻量 JSON artifact

---

## 3.6 定义审核结果最小返回结构

### 当前问题

现有 Portal 链路没有“审核结果分流”的最小对象。

### P0 最小返回建议

新增轻量审核结果返回结构：

- `review_result_id`
- `risk_level`
- `top_findings[]`
- `recommended_action`
- `available_actions[]`

其中：

- `recommended_action ∈ {go_cwb, go_step1, go_full_plan}`
- `available_actions[]` 至少含三类入口

### 注意

P0 可以先把它定义成页面域结构，不强制先做完整持久化模型。

---

## 3.7 定义审核分流记录字段

### 当前缺口

现有代码中尚未实现：

- `review_entry_source`
- `review_followup_action`

### P0 建议

最小先定义语义，不必一开始改重 schema：

- `review_entry_source ∈ {home, status, report, direct}`
- `review_followup_action ∈ {cwb, step1, full_plan, none}`

### 落地方式建议

P0 可先落在：

- 页面埋点事件
- 轻量 metadata 字段
- 或会话态 / 结果对象中

只要保证：

- 来源可追踪
- 分流动作可统计

---

## 4. P0 不建议现在改的接口项

以下内容不要提前混入 P0：

1. Step 2-4 全量偏好字段接口
2. 政策中心完整 API
3. 同分段参考完整 API
4. 完整报告资产列表 API
5. 多版本方案管理 API
6. 订单六态状态机扩容

原因：

- 这些都属于 P1 / P2
- 先改只会扩大范围

---

## 5. 最小接口变更表

| 变更项 | 类型 | 当前状态 | P0 动作 | 必须性 |
| --- | --- | --- | --- | --- |
| `IntakePayload` 去掉偏好字段提交门槛 | 校验逻辑 | 与 P0 冲突 | 修改 | 必须 |
| `IntakePayload` 增 `candidate_province` | 请求字段 | 缺失 | 新增 | 必须 |
| `/portal/{token}/info` 表单补省份 | 页面 + 提交 | 缺失 | 修改 | 必须 |
| `/portal/{token}/info` 响应补 `profile_minimum_complete` | 响应字段 | 缺失 | 新增 | 建议 |
| 统一审核最小输入结构 | 契约定义 | 未定义 | 新增 | 必须 |
| 定义审核结果最小返回结构 | 契约定义 | 未定义 | 新增 | 必须 |
| 定义 `review_entry_source` | 状态 / 埋点语义 | 未定义 | 新增 | 必须 |
| 定义 `review_followup_action` | 状态 / 埋点语义 | 未定义 | 新增 | 必须 |
| 首页工作台聚合接口 | 新接口 | 无 | 可延后 / 先复用 | 可选 |

---

## 6. 推荐实现顺序

1. 先修改 `IntakePayload`，解除 P0 与当前提交校验冲突
2. 把 `candidate_province` 接入 `/portal/{token}/info`
3. 定义 `profile_minimum_complete`
4. 定义审核输入 / 审核结果最小契约
5. 定义分流动作与来源字段
6. 最后再决定是否补首页工作台聚合接口

---

## 7. 下一步建议

1. 基于本文继续落《报告版本与档案版本关系说明》
2. 确认 `review_result` 是页面态还是轻量持久化对象
3. 确认 `profile_minimum_complete` 是纯派生字段还是落库存字段