# AI 合同平台 V2 Phase 3 UI 缓存字段 cleanup 设计评审

## 当前基线

本设计继续对齐《AI 合同平台 V2 下一阶段开发优化方案》的 Phase 3 schema 硬化方向，目标是把 `contracts` 表中的旧 UI 缓存字段从“历史兼容缓存”逐步治理到“可安全停写、可选删列”的状态。

截至本记录：

- 远端 smoke PostgreSQL：`192.168.3.90`
- Contract API：`http://192.168.3.90:18100`
- Alembic actual/head：`20260630_0021`
- `display_cache_consistency.status`：`ok`
- `checked_rows`：12010
- `mismatch_count`：0
- 回滚 snapshot：`/opt/apps/ai-contract-platform-v2-smoke/backups/display-cache/display-cache-backfill-candidate-2026-06-30T17-37-24.json`
- 本地备份：`project-docs/qa-artifacts/display-cache-governance/2026-06-30T17-37-24/display-cache-backfill-candidate-2026-06-30T17-37-24.json`

这说明当前 smoke 环境已经处于 cleanup migration 前的稳定状态：旧列仍保留，但值已与派生规则一致。

## 字段分层判断

目标字段：

- `contracts.status_label`
- `contracts.status_tone`
- `contracts.next_action`
- `contracts.next_actions`

分层结论：

1. `status_label/status_tone` 是纯展示字段，可以完全由 `contracts.status` 派生。
2. `next_action/next_actions` 不是纯展示字段，当前混合了三类含义：
   - 状态默认动作，例如待提交、待审批、已审批。
   - 结构化上下文动作，例如审查任务、审批实例、条款修复、履约任务。
   - 少量人工/业务上下文提示，例如合同编辑页仍允许编辑 `next_action`。

因此不建议直接创建一次性 migration 删除四列。更稳的路径是先把 `status_label/status_tone` 和 `next_action/next_actions` 拆开治理。

## 当前仍在写旧列的位置

### 合同主写路径

- `persistence/contract_core.py`
  - 创建合同时仍从 `ContractCreateData` 写入 `status_label/status_tone/next_action/next_actions`。
  - 更新合同时仍允许更新 `next_action/next_actions`。

### 状态流/审计/时间线

- `persistence/audit.py`
  - `transition_contract` 与 `transition_contract_in_session` 仍将状态流参数写回四个旧列。
- `sqlalchemy_transition_orchestration.py`
  - 状态流仍传递四个展示字段。
- `sqlalchemy_approval_orchestration.py`
  - 审批提交、重提、通过、退回仍提供展示字段。

### 审查/文件/条款修复

- `sqlalchemy_review_orchestration.py`
  - 审查开始、完成、失败后仍写 `status_label/status_tone/next_action/next_actions`。
- `sqlalchemy_file_orchestration.py`
  - 文件上传后仍写 `next_action/next_actions`。
- `sqlalchemy_clause_repair_orchestration.py`
  - 条款修复后仍写 `next_action/next_actions`。

### 支撑路径

- `sqlalchemy_support_orchestration.py`
  - 归档动作仍写展示字段。
- `seed_data.py`
  - demo/seed 数据仍包含旧字段。
- `in_memory_repository.py`
  - 测试/demo 内存仓储仍维护旧字段。

### 不属于本轮删除目标的字段

- `review_tasks.status_label`：这是审查任务自己的状态标签，不是 `contracts` 表 UI 缓存列。
- `contract_search_documents.status_label`：这是搜索索引/搜索展示冗余字段，后续可以单独治理，但不应与 `contracts` 表删列混在同一刀。
- OpenAPI 和前端 TypeScript 响应字段：仍应保留兼容，因为前端合同列表、详情、搜索、dashboard 仍依赖这些响应字段。

## 当前读路径状态

读路径已经基本完成派生化：

- 合同列表 mapper 使用 `derive_contract_display`。
- 合同详情 mapper 使用 `derive_contract_display`。
- 搜索文档同步/重建使用 `derive_contract_display`。
- `ContractActionContext` 已纳入审查、审批、条款修复、履约任务等上下文。
- `runtime/schema-check` 已复用同一套 display cache governance 逻辑做只读一致性检查。

这意味着 API 响应可以继续返回 `status_label/status_tone/next_action/next_actions`，但来源应逐步变为 serializer/domain 派生，而不是依赖数据库旧列。

## 推荐 cleanup 顺序

### Slice 3.5.1：停写前设计锁定

目标：

- 保留数据库旧列。
- 保留 API/OpenAPI/前端字段。
- 明确 `next_action/next_actions` 中人工提示的归属。

建议动作：

1. 审计前端合同编辑页的 `next_action` 输入是否仍是产品需求。
2. 如果仍需要人工提示，新增事实字段或结构：
   - 方案 A：`contracts.action_hint` 文本字段。
   - 方案 B：`contract_action_overrides` JSON/子表。
   - 方案 C：完全移除人工编辑入口，只保留结构化派生动作。
3. 不在此片写 migration。

验收：

- 形成明确决策：`next_action` 人工提示是保留、迁移还是废弃。
- `schema-check` 仍为 `ok`。

### Slice 3.5.2：停止写 `status_label/status_tone`

目标：

- `contracts.status_label/status_tone` 不再由业务编排手写。
- 仍保留列，用于兼容、回滚和 schema-check。

建议动作：

1. 创建集中 helper，例如 `apply_contract_display_cache(row, action_context=None)` 或 `sync_contract_display_cache(row)`。
2. 对状态流写路径，改为只写事实字段 `status`，展示字段由 helper/派生层统一刷新。
3. 对 create/seed/in-memory 路径，改为由 `status` 派生默认展示字段。
4. 增加测试：制造错误旧值后，读路径仍返回派生值；写路径不会再写手写 status label/tone。

验收：

- `schema-check.display_cache_consistency` 保持 `ok`。
- 合同列表、详情、workspace、搜索抽样通过。
- OpenAPI/前端响应字段不变。

### Slice 3.5.3：拆分 `next_action/next_actions` 语义

目标：

- 将 `next_action/next_actions` 从“旧 UI 缓存列”转成真正的 Action Context 派生。
- 如果保留人工提示，迁移到新事实字段或覆盖结构。

建议动作：

1. 将合同编辑页的 `next_action` 输入改名/改语义，避免继续把它当展示缓存。
2. 将文件上传、审查任务、条款修复等写路径改成写结构化事实，而不是写 `next_action` 文案。
3. 扩展 `ContractActionContext`，覆盖合同版本/草稿编辑状态。
4. 搜索文档继续保留派生后的展示文案，但来源来自 domain/serializer。

验收：

- 写路径不再直接设置 `contracts.next_action/next_actions`，或仅通过兼容 helper 写入派生结果。
- 旧列一致性检查仍为 `ok`。
- 前端主要动作按钮展示不退化。

### Slice 3.5.4：cleanup migration 设计评审

只有满足以下条件后才进入删列 migration：

- API 响应字段完全由 mapper/serializer 派生。
- 后端业务写路径不再依赖四个旧列。
- 前端不再提交旧 UI 缓存字段作为业务输入。
- 搜索索引重建可以完全从事实字段和派生规则生成展示文案。
- smoke 环境连续多轮 `display_cache_consistency` 为 `ok`。
- 已保留可回滚 snapshot，且 rollback 演练流程可执行。

删列顺序建议：

1. 第一片只删除或弃用 `status_label/status_tone`，因为它们最纯粹。
2. 第二片再处理 `next_action/next_actions`，前提是人工提示语义已经迁出。
3. 每片 migration 后都复跑 Docker smoke、schema-check、合同列表、详情、搜索、workspace 抽样。

## 不建议的做法

- 不建议一次性删除四个旧列。
- 不建议为了“数据库更干净”破坏 OpenAPI/前端兼容字段。
- 不建议在 `next_action` 人工提示归属未决时删除 `next_action/next_actions`。
- 不建议把 `contract_search_documents.status_label` 和 `contracts.status_label` 放在同一个 migration 里治理。

## 当前建议

2026-07-01 已完成完整上下文口径的 display cache prestate 重新固化：

- 旧列 `status_label/status_tone/next_action/next_actions` 仍保留。
- `display_cache_governance` 已按完整 `ContractActionContext` 判断一致性。
- smoke 环境已执行可回滚 backfill，`display_cache_consistency.mismatch_count=0`。
- `display_cache_cleanup_prestate.status=ok`。
- 详细记录见 `project-docs/V2-phase3-display-cache-context-prestate-2026-07-01.md`。

下一步最稳仍不是直接写删列 migration，而是继续停写旧 `contracts.next_action/next_actions` 的生产写路径：

1. 让文件上传、审查任务、条款修复、审批流、归档等路径只写结构化事实。
2. API 响应继续由 `derive_contract_display(...)` 和完整 `ContractActionContext` 派生 `next_action/next_actions`。
3. 旧列只作为兼容缓存和回滚面保留，继续由 schema-check 保护。
4. 连续多轮 smoke 保持 `display_cache_consistency=ok` 后，再进入 Slice 3.5.4 cleanup migration 设计评审。

这个顺序能避免把“UI 文案缓存治理”和“合同下一步动作业务模型”混成一次高风险 schema 大改，同时保留对旧前端/API 调用方的兼容面。

## 2026-07-01 停写旧动作缓存列进展

已完成第一片停写：

- 生产 SQLAlchemy 写路径不再刷新 `contracts.next_action / contracts.next_actions`。
- 旧动作列仍保留，用于兼容、回滚和后续 cleanup migration 前保护。
- `display_cache_consistency` 调整为只检查 `status_label/status_tone` 与派生状态展示一致。
- `next_action/next_actions` 的用户可见值继续由 `derive_contract_display(...)` 和完整 `ContractActionContext` 派生。
- 详细记录见 `project-docs/V2-phase3-stop-legacy-next-action-writes-2026-07-01.md`。

下一步应先部署 smoke 验证，而不是直接删列。