ai-contract-platform/project-docs/MAINLINE-CANDIDATE-HANDOFF.md

主线候选交接说明

生成时间: 2026-06-30
当前分支: feat/contract-content-qa-pass
目标: 正式上线前主线收口

---

一、当前代码状态

1.1 工作区状态

当前有 17 个已修改文件，均为治理功能增强和审查回归覆盖：

后端修改 (9 个):

• backend/app/services/governance_service.py - 发布摘要/详情增强
• backend/app/services/legal_document_draft_service.py - 文书起草增强
• backend/app/services/legal_document_type_service.py - 文书类型增强
• backend/app/services/legal_domain_registry.py - 领域注册增强
• backend/tests/test_governance_api.py - 治理 API 测试
• backend/tests/test_governance_service.py - 治理服务测试
• backend/tests/test_legal_document_draft_service.py - 文书起草测试
• backend/tests/test_legal_document_drafts_api.py - 文书起草 API 测试
• backend/tests/test_legal_document_type_service.py - 文书类型测试
• backend/tests/test_legal_document_types_api.py - 文书类型 API 测试

前端修改 (8 个):

• frontend/src/app/documents/new/[type]/page.tsx - 文书起草页面
• frontend/src/app/governance/assets/[id]/page.tsx - 资产详情页增强
• frontend/src/app/governance/imports/page.tsx - 导入页增强
• frontend/src/app/governance/releases/page.tsx - 发布页增强
• frontend/src/app/governance/workbench/page.tsx - 工作台增强
• frontend/src/components/governance/governance-meta.tsx - 治理元数据组件
• frontend/src/services/legal-document.ts - 文书服务
• frontend/src/types/api.ts - API 类型定义

1.2 分支状态

* feat/contract-content-qa-pass    739d2f5 [origin/feat/contract-content-qa-pass]
  main                             e376c1c [origin/main: ahead 1]

关键发现:

• main 分支比 origin/main 领先 1 个提交
• 当前 feature 分支基于较新的代码
• 需要决定如何将 feature 分支的变更整合到 main

---

二、最小发布候选补丁集

2.1 核心补丁文件（按优先级排序）

优先级	文件	说明
P0	governance_service.py	发布摘要/详情上线指标核心
P0	governance-meta.tsx	前端治理元数据展示
P0	workbench/page.tsx	工作台完成条件约束
P0	releases/page.tsx	发布页 blocker 提示
P1	assets/[id]/page.tsx	资产详情完成条件
P1	imports/page.tsx	导入后下一步指引
P1	test_governance_service.py	后端测试覆盖
P1	test_governance_api.py	API 测试覆盖
P2	文书起草相关文件	增强功能
P2	api.ts	类型定义更新

2.2 为什么这些文件必须进主线

governance 功能:

• 发布摘要现在能显示 launch readiness 指标
• 能识别 missing_reviewer / approved_missing_evidence / template_evidence_blockers
• 能给出 next_actions 指引
• 能显示协作包推进状态

workbench 功能:

• reviewer 任务现在有明确的完成条件 checklist
• 没负责人时不会误判为完成
• 没决议时不会误判为完成
• 证据 READY 前不会误判为可上线

测试覆盖:

• 后端 18 个 governance 测试通过
• 候选 40 个后端测试通过
• 前端 lint/build 通过

---

三、主线收口前检查单

3.1 代码层面检查

• 功能开发完成
• 后端测试通过 (18/18)
• 候选测试通过 (40/40)
• 前端 lint 通过
• 前端 build 通过
• 主线同步（main → origin/main）
• 特性分支合并策略确定

3.2 发布前最终验证

• database truth gate 复跑
• formal-launch approval gate 通过（database 口径）
• FINAL_APPROVER 批准
• Docker 部署执行
• 部署后 health/readiness 复测

---

四、分支合并建议

方案 A: 直接合并到 main（推荐）

# 1. 先同步 main 和 origin/main
git checkout main
git pull origin main
# 如果本地 main 领先，可能需要处理

# 2. 合并 feature 分支
git merge feat/contract-content-qa-pass

# 3. 推送
git push origin main

方案 B: 创建 PR 审查后合并

如果希望有一次最终人工审查，可以创建 PR。

---

五、当前阻塞项

阻塞项	状态	说明
main/ origin/main 同步	⚠️ 需处理	main 领先 1 个提交
database truth gate	⚠️ 需复跑	当前 csv 口径通过，需 database 口径
FINAL_APPROVER	⚠️ 需人工	必须由人类执行
Docker 部署	⚠️ 需人工	用户保留动作

---

六、结论

本仓库内影响生产上线的主要开发项已经基本补完。

剩余的主要是：

1. 主线同步与合并策略
2. database truth gate 最终复跑
3. FINAL_APPROVER 批准
4. Docker 部署执行

建议下一步: 决定主线合并策略后，进入 database-truth gate 最终复跑。