feat: add contract delivery export diff

2026-05-21 21:33:28 +08:00
parent 901648e903
commit f89d9d0057
8 changed files with 838 additions and 15 deletions
@@ -4325,3 +4325,42 @@
 - 剩余边界：
  - 本轮未新增通用 `ai_quality_eval_runs/items` 表；这是未来跨 Prompt、跨业务对象统一质量平台的增强项。
  - 本轮未做全量法规向量化、真实微信或支付宝支付、电子签章、小程序等生产级增强。
+
+## 2026-05-21 合同交付专业化增强：DOCX 导出与版本对比本地闭环
+
+- 已按“现在不做完整 Word 级编辑器，先做合同交付够专业”的取舍推进本轮开发。
+- 后端新增能力：
+  - `GET /api/v1/contracts/{contract_id}/versions/diff`
+    - 默认对比上一版本与当前最新版本。
+    - 支持 `from_version_id`、`to_version_id` 指定版本。
+    - 返回新增、删除、修改、未变化、段落数和变化明细。
+  - `GET /api/v1/contracts/{contract_id}/versions/{version_id}/download`
+    - 支持导出 `base`、`latest` 或指定版本 ID。
+    - 当前只开放 DOCX，避免扩大到完整 Word 级编辑器范围。
+    - 导出的 DOCX 会包含合同标题、版本号、导出时间、经办人、条款段落和页脚。
+- 前端新增能力：
+  - `frontend/src/app/documents/[id]/edit/page.tsx`
+    - 工具栏新增“导出当前版本 Word”。
+    - 右侧新增“交付文件”面板。
+    - 面板支持“导出当前版本 DOCX”和“刷新版本对比”。
+    - 对比结果展示版本范围、新增、删除、修改数量和前 5 条段落/条款级变化。
+  - `frontend/src/services/contract.ts`
+    - 新增版本对比类型与 `diffGeneratedContractVersions`。
+    - 新增 `downloadGeneratedContractVersion`。
+- 实现边界：
+  - 本轮没有新增数据库表，也没有新增 Alembic。
+  - 本轮不是专业 Word 级编辑器，不做多人实时协同、不做 Word 高保真往返、不做逐字段修订模式。
+  - 当前实现定位为“合同交付专业化增强”：让客户能拿到当前版本 Word 文件，并能在页面看清版本变化。
+- 本地验证：
+  - `python -m compileall backend\app\api\contracts.py backend\app\services\contract_generation_service.py`
+  - `$env:PYTHONPATH='backend'; python -m unittest backend.tests.test_contracts_api`
+  - 结果：`Ran 25 tests in 1.869s`，`OK`。
+  - `cd frontend; npx eslint "src/app/documents/[id]/edit/page.tsx" "src/services/contract.ts"`
+  - `cd frontend; npm run build`
+  - 构建结果：`Compiled successfully`，静态页面生成 `40/40`，路由清单包含 `/documents/[id]/edit`。
+- 当前闭环结论：
+  - “DOCX 导出 + 版本对比”已形成本地开发闭环。
+  - Phase15-D 从“编辑/保存/AI 侧栏”升级为“编辑/保存/AI 侧栏/版本对比/DOCX 交付文件”的轻量专业交付闭环。
+- 剩余边界：
+  - 尚未提交推送远程 Git。
+  - 尚未部署到 `192.168.3.90` 做真实库烟测。
@@ -19,7 +19,7 @@

 1. 本轮新增 `/quality-evals` 独立页面，不新增数据库迁移，继续复用 Prompt 评测运行记录作为质量评测真相源。
 2. 文档建议路径与代码仍保留一个等价实现差异：文档建议 `/clauses/apply`，当前落在合同编辑器版本链中；`/quality-evals` 已补成独立产品入口。
-3. 后续增强项：专业富文本库、字段级差异对比、通用 `ai_quality_eval_runs/items`、全量法规向量化、真实微信或支付宝支付、电子签章、小程序等不属于当前 Phase15 主线硬阻塞。
+3. 后续增强项：专业富文本库、真正字段级差异对比、多人协同编辑、通用 `ai_quality_eval_runs/items`、全量法规向量化、真实微信或支付宝支付、电子签章、小程序等不属于当前 Phase15 主线硬阻塞；合同交付专业化增强已先补 DOCX 当前版本导出和段落/条款级版本对比。

 ## 三、逐阶段对齐表

@@ -37,7 +37,7 @@
 | Phase15-C | 智能条款推荐 | `POST /api/v1/clauses/recommend` 支持缺失条款和行业惯例，`POST /api/v1/clauses/rewrite` 支持措辞优化 | 已闭环 |
 | LAW-CLAUSE-001 | 缺失条款推荐 | 推荐结果含插入位置、建议文本、理由、依据和行业惯例说明 | 已闭环 |
 | LAW-CLAUSE-002 | 措辞优化 | 支持专业化、简化、偏甲方、偏乙方、均衡等改写模式，返回法律边界和谈判建议 | 已闭环 |
-| Phase15-D | 富文本编辑器与 AI 侧边栏 | `/documents/[id]/edit` 支持正文编辑、自动保存、版本历史、条款推荐、措辞改写、相关法条和 Chat 入口 | 主线已闭环 |
+| Phase15-D | 富文本编辑器与 AI 侧边栏 | `/documents/[id]/edit` 支持正文编辑、自动保存、版本历史、条款推荐、措辞改写、相关法条、Chat 入口、当前版本 DOCX 导出和段落/条款级版本对比 | 主线已闭环 |
 | Phase15-E | Prompt 资产治理 | `/prompt-assets` 支持 Prompt 类型、版本、评测、发布、下线、回滚和运行证据 | 已闭环 |
 | Phase15-F | 黄金样本与质量评测 | 已有 Prompt 评测运行记录、逐条黄金样本报告、发布前门禁、`/prompt-assets` 治理入口和 `/quality-evals` 独立质量评测中心 | 已闭环 |
 | Phase15-G | 法规变更影响分析 | 已有法条变更入队、结构化和语义影响扫描、影响项、页面、后台 worker 和 Docker 服务 | 已闭环 |
@@ -50,6 +50,8 @@
 - 文书类型：`backend/app/api/legal_document_types.py`
 - 文书草稿：`backend/app/api/legal_document_drafts.py`
 - 合同生成和版本：`backend/app/api/contracts.py`
+  - `GET /api/v1/contracts/{contract_id}/versions/diff`
+  - `GET /api/v1/contracts/{contract_id}/versions/{version_id}/download`
 - 审查建议动作：`backend/app/api/reviews.py`
 - 条款推荐和改写：`backend/app/api/clauses.py`
 - Prompt 治理：`backend/app/api/prompt_assets.py`
@@ -150,14 +152,20 @@ Phase15-C、Phase15-F、Phase15-G 已完成提交、推送和 `192.168.3.90` 真

 ### 6.3 专业级富文本增强

-当前 `/documents/[id]/edit` 已经支持编辑、自动保存、版本历史、推荐插入、改写替换和 AI 侧边栏。尚未做的增强包括：
+当前 `/documents/[id]/edit` 已经支持编辑、自动保存、版本历史、推荐插入、改写替换和 AI 侧边栏。本轮“合同交付专业化增强”又补齐：
+
+- 当前版本 DOCX 重新导出：按版本正文生成 Word 文件，保留标题、条款段落、版本号、导出时间和页脚。
+- 段落/条款级版本对比：默认对比上一版本和当前版本，也支持指定版本对比。
+- 编辑页交付面板：提供“导出当前版本 DOCX”和“刷新版本对比”入口。
+
+仍未做、且暂不建议近期作为主线强攻的增强包括：

 - 专业富文本编辑器库。
- 段落级或字段级差异对比。
- Word 样式还原和导出增强。
+- 真正字段级差异对比。
+- Word 高保真样式还原。
 - 多人协同编辑。

-这些是体验增强，不影响当前 Phase15-D 主线闭环。
+这些是体验增强，不影响当前 Phase15-D 主线闭环。当前路线是“不做完整 Word 级编辑器，先做合同交付够专业”。

 ### 6.4 全量法规向量化