yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
6.0 KiB
6.0 KiB
V2 模板库类型树与模板起草入口回补记录
日期：2026-06-27
背景
按 V1/V2 对比结论，第一批最值得回补到 V2 的资产是 V1 的模板化合同起草体系、标准条款库、审查规则库和黄金样本。其中模板体系不应复制 V1 的大而全页面结构，而应进入 V2 已确定的左侧导航与合同工作台结构。
本次增量把 V1 模板资产进一步产品化为 V2 的“模板库”入口，并补齐后端类型树 API，使用户可以从“模板库浏览合同类型 -> 选择模板 -> 进入合同页并预选模板 -> 填变量生成合同草稿”。
已完成
-
新增后端模板类型树能力：
GET /api/v1/templates/tree- 按
contract_type聚合模板，返回类型标签、模板数、关联条款数、审查规则数、必填变量数和模板列表。 - 支持
keyword过滤。 - 路由放在
/api/v1/templates/{template_id}前，避免tree被当作模板 ID。
-
新增 V2 前端模板库入口：
- 左侧导航增加“模板库”。
- 新增
/templates页面。 - 页面保留 V2 左右结构：左侧类型索引，右侧按类型分组的模板卡片。
- 视觉上沿用当前 V1 风格基线：轻玻璃质感、细边框、低饱和统计卡片和精简 hover。
-
接通模板库到合同起草链路：
- 模板卡片“使用模板起草”跳转到
/contracts?template=<template_id>。 - 合同页读取
template查询参数，但不把它混入合同列表筛选条件。 TemplateDraftPanel根据 URL 参数自动选中模板；参数无效时回退到第一个模板。
- 模板卡片“使用模板起草”跳转到
-
同步 OpenAPI 契约：
- 补充模板列表、模板类型树、模板详情、模板起草、模板关联法务资产接口。
- 补充标准条款与审查规则列表/详情接口。
- 补充相关 schema：
ContractTemplateItem、ContractTemplateTree、StandardClauseItem、ReviewRuleItem、TemplateLegalAssets等。
-
补齐 V1 Phase13 模板资产绑定完整性：
- V1 Phase13
contract-templates可起草模板资产为 30 个，V2 已完成 30/30 同步。 - 本次补齐 7 个模板缺失的
review_rule_ids：TPL-DATA-PROCESSING-001、TPL-FINANCIAL-LEASE-001、TPL-GUARANTEE-001、TPL-INTERMEDIARY-001、TPL-IP-LICENSE-001、TPL-PARTNERSHIP-001、TPL-WORKS-001。 - 数据处理模板绑定
RULE-DATA-PI-PROCESSING-001，知识产权许可模板绑定RULE-IP-SOFTWARE-OWNERSHIP-001，其余模板绑定通用授权、格式条款、违约责任、解除通知、争议解决和电子签约证据规则。 - 新增测试门校验所有模板都有
required_variables、clause_ids、review_rule_ids，并且条款 ID、规则 ID 均能解析到 V2 标准条款库和审查规则库。
- V1 Phase13
-
新增模板生命周期管理 MVP：
- 后端新增模板发布、下线、回滚和历史查询接口：
/templates/{template_id}/publish、/offline、/rollback、/history。 - 新增
template_lifecycle_events持久化事件表与 Alembic 迁移，按租户记录模板生命周期操作人、版本、摘要、时间和元数据。 - 默认导入的 V1 模板视为已发布；显式下线后仍可在模板库管理中查看，但不能用于生成合同草稿。
- 回滚支持指定事件/版本；未指定目标时回到上一状态，若只有下线事件则恢复到静态资产默认发布态。
- V2
/templates页面显示模板发布状态、生命周期版本、变更次数和最近历史，并提供发布、下线、回滚操作。 - OpenAPI 已同步新增生命周期接口和 schema。
- 后端新增模板发布、下线、回滚和历史查询接口：
-
新增模板编辑、diff 与发布前校验：
- 后端新增编辑草稿、差异对比和发布前校验接口：
/templates/{template_id}/edit-draft、/diff、/validate。 - 新增
template_edit_drafts持久化表，用于保存 V2 管理态草稿，不直接改写 V1 静态模板资产。 - 发布时若存在编辑草稿，必须先通过发布前校验；发布事件会保存草稿快照，后续起草优先使用最近一次已发布快照。
- 发布前校验覆盖正文长度、必填变量是否出现在正文、未知变量占位符、条款 ID/规则 ID 是否存在、条款/规则绑定是否为空。
- V2
/templates卡片新增编辑面板，支持正文、变量、条款 ID、规则 ID、校验规则编辑，展示 diff 摘要和校验结果。 - OpenAPI 已同步编辑草稿、diff、校验相关 schema。
- 后端新增编辑草稿、差异对比和发布前校验接口：
验证
python -m pytest yuqei-contract-platform/services/contract-api/tests/test_contract_workflow.py -q- 29 passed
npm run web:typecheck- 通过
npm run web:build- 通过
python -c "import pathlib, yaml; yaml.safe_load(pathlib.Path('yuqei-contract-platform/packages/contract-openapi/openapi.yaml').read_text(encoding='utf-8')); print('contract openapi ok')"- contract openapi ok
说明：.venv-project 当前未安装 pytest，本次后端测试使用系统 Python 执行通过。
当前边界
- V2 当前已加载的 V1 Phase13 可起草模板资产为 30 个，和 V1 Phase13
contract-templates目录下的*-variables.json数量一致。 - 早前“V1 约 53 个模板”的口径来自全仓
TPL-*命中，混入了测试、签收、pilot、CSV 派生 ID 等非可起草模板资产，不应作为模板迁移目标。 - 本次已完成模板正文/变量 schema 的管理态编辑与差异对比，但还没有做多人协同锁、审批流、可视化逐行 diff。
- 标准条款库和审查规则库已有 API 与模板关联展示，但还没有独立的 V2 管理页面。
后续建议
- 若后续确认 V1 还有 Phase13 之外的正式可起草模板，先建立来源清单、变量 schema 和业务验收样本，再决定是否纳入 V2。
- 做模板编辑审批流、多人协同锁、逐行 diff 和发布审批审计。
- 做标准条款库/审查规则库的 V2 管理页：支持搜索、详情、启停、规则到条款的跳转。
- 再进入第二批回补：审查结果风险项到条款推荐/一键修订的更深闭环，以及法律全文精选迁移。