合同管理模块二次迭代整体方案设计

生成日期：2026-05-07 适用模块：yudao-module-contract、apps/web-antd/src/views/contract、pages-contract 文档目标：作为后续对话和开发的合同管理业务蓝图，统一当前实现现状、二次迭代目标、业务闭环和优先级。

一、定位与结论

合同管理模块已经从最初的“合同台账 CRUD”演进为面向全生命周期的独立合同中心。后续二次迭代不再围绕单页增删改查扩展，而是围绕以下业务闭环推进：

text

合同起草 -> BPM 审批 -> 合同签署 -> 合同生效 -> 履约/收付款 -> 变更/终止 -> 完成 -> 归档

当前应坚持三个业务视角：

视角	页面入口	数据范围	核心职责
合同起草	`views/contract/draft/list` + `info/detail`	`status <= 2`	新建合同、编辑草稿、提交 `contract_approve` 审批，维护起草稿与收付款计划
合同签署	`views/contract/sign/list` + `sign/info`	`contract_sign` 单据	审批通过后的线下签署确认，上传盖章件，提交 `contract_sign` 审批
合同台账	`views/contract/info/list` + `info/ledger`	`status >= 4`	已生效合同资产视图，聚合文件、履约、变更、收付款、终止、归档

二次迭代的核心目标是把“已能跑的功能”打磨为“状态严格、文件可追溯、流程可部署、跨模块可复用、前后端一致”的完整业务闭环。

二、当前实现基线

2.1 后端已具备能力

能力	当前状态	关键文件
合同主表与起草审批	已实现	`ContractInfoServiceImpl`、`ContractInfoController`
合同状态枚举	已实现	`ContractStatusEnum`
合同签署单据	已实现基础版	`ContractSignDO`、`ContractSignServiceImpl`、`ContractSignController`
合同台账生命周期 API	已有终止、归档、确认完成	`terminateContract`、`archiveContract`、`confirmComplete`
起草审批通过生成签署记录	已实现	`ContractInfoServiceImpl.onProcessApproved`
签署审批通过回写生效	已实现基础版	`ContractSignServiceImpl.onProcessApproved`
台账分页范围筛选	已实现	`ContractInfoPageReqVO.statusMin/statusMax`、`ContractInfoMapper.selectPage`
合同履约记录与汇总	已实现基础版	`ContractPerformanceServiceImpl`
合同变更流程	已实现基础版	`ContractChangeServiceImpl`
分类、模板、配置、统计	已实现基础版	`category/template/config/stats`
到期提醒 Job	有骨架	`ContractExpireNotifyJob`

2.2 PC 前端已具备能力

能力	当前状态	关键文件
合同起草列表	已按 `statusMax=2` 隔离	`views/contract/draft/list`
合同起草详情	已复用 `BasicForm` + BPM	`views/contract/info/detail`
合同签署列表与详情	已实现基础版	`views/contract/sign/list`、`sign/info`
合同台账列表	已按 `statusMin=4` 隔离，含状态 Tabs	`views/contract/info/list`
合同台账详情	已实现多 Tab 聚合视图	`views/contract/info/ledger`
台账生命周期操作	已接入终止、归档、确认完成	`info/list`、`info/ledger`
履约、变更、收付款展示	已有列表/详情基础能力	`performance`、`change`、`payment`

2.3 移动端已具备能力

移动端已有合同审批的基础入口：

src/api/contract/index.ts
src/pages-contract/info/index.vue
src/pages-contract/info/create/index.vue
src/pages-contract/info/detail/index.vue
src/config/bpm-menu-config.ts 中已注册 contract_approve

但移动端目前主要覆盖起草审批，尚未形成签署、台账、履约、变更、归档的完整闭环。

三、当前必须收口的问题

以下问题会直接影响全生命周期闭环，应作为二次迭代的优先处理项。

优先级	问题	当前事实	目标
P0	签署单据枚举错误	`ContractBillTypeEnum.CONTRACT_SIGN` 当前仍是 `202 / 合同变更审批 / contract_change`	修正为 `203 / 合同签署确认 / contract_sign`，确保流程路由、单号、附件业务类型隔离
P0	签署提交缺少签署件强校验	`submitContractSign` 未强制校验附件已上传	提交前必须存在签署件附件，否则禁止进入审批
P0	变更审批未回写主合同	`ContractChangeServiceImpl.onProcessApproved` 仍是 TODO	审批通过后按变更类型回写金额、期限、条款摘要等，并追加变更文件版本
P0	履约未推动合同状态	`syncContractPerformanceStats` 只更新履约金额/履约状态	首笔履约将合同从已生效推到履约中，满额后提示/允许确认完成
P0	履约缺少状态准入	`createPerformance` 仅校验合同存在	只允许已生效、履约中的合同登记履约
P1	台账文件版本未完全闭环	起草稿、签署件、变更协议聚合已有前端展示，但后端写入规则不完整	建立统一文件版本策略，确保每个阶段文件可追溯
P1	变更表单缺少文件上传区	当前 `change/modules/form.vue` 仍是普通表单 Modal	增加变更协议上传与提交校验
P1	对外 API 能力偏弱	`ContractInfoApi` 主要提供查询	补充履约写入、履约汇总、按业务关联查询等 API
P1	到期提醒未完成通知闭环	Job 中仍有通知 TODO	接入站内信/待办/邮件或系统通知
P2	移动端生命周期不完整	只覆盖起草审批主链路	增加签署、台账详情、履约/变更只读或操作入口

四、目标业务状态机

状态定义：

值	状态	业务含义	主要入口
0	草稿	起草人保存但未提交	合同起草
1	审批中	已进入 `contract_approve` 流程	合同起草/BPM
2	已审批	起草审批通过，等待签署或直接生效	合同起草/签署
3	签署中	签署确认单已提交 `contract_sign` 审批	合同签署
4	已生效	合同正式成为台账资产	合同台账
5	履约中	已登记履约记录，合同执行中	合同台账/履约
6	已完成	履约已确认完成	合同台账
7	已终止	合同提前终止或作废	合同台账
8	已归档	最终只读归档状态	合同台账

关键规则：

status <= 2 属于起草视角，status >= 4 属于台账视角，status = 3 由签署流程承接。
签署环节由 contract_config.sign_enabled 控制。开启时审批通过生成签署记录；关闭时审批通过直接生效。
已归档合同不可再新增履约、发起变更、终止或修改主数据。
合同变更默认只面向已生效、履约中合同。已审批未生效合同应优先通过退回/重新起草处理。
终止必须记录原因；终止后只能归档，不能回退。

五、核心业务域设计

5.1 合同起草

合同起草负责合同主数据创建、起草稿文件、合同明细、收付款计划与 contract_approve 审批。

后续重点：

起草详情中应独立展示“合同文件（起草稿）”，不要和普通附件混在一起。
提交审批前校验合同名称、合同类型、合同性质、我方主体、对方单位、金额/日期等核心字段。
审批中只允许按 BPM 字段权限修改指定字段。
审批通过后：
- signEnabled = true：状态保持已审批，自动生成 contract_sign 草稿记录。
- signEnabled = false：状态直接变为已生效，写入 effectiveDate。

5.2 合同签署

合同签署是独立流程单据，不是合同主表的简单按钮。

目标流程：

text

起草审批通过 -> 自动生成签署记录 -> 经办人上传签署件 -> 提交签署确认审批 -> 合同专员审核 -> 合同生效

后续重点：

修复 CONTRACT_SIGN 枚举为 203 / contract_sign。
contract_sign 附件使用独立业务类型 203，避免与变更附件混用。
签署提交前必须校验盖章件/扫描件已上传。
签署审批通过后：
- 回写 contract_info.signed_file_url。
- 写入 effective_date。
- 将合同状态更新为已生效。
签署审批撤回/驳回后合同回到已审批，签署记录回草稿。

5.3 合同台账

合同台账是已生效合同的资产视图，不承担新建合同职责。

列表页目标：

默认 statusMin = 4。
顶部 Tabs：全部、已生效、履约中、已完成、已终止、已归档。
合同编号链接进入台账详情，不进入起草详情。
行操作按状态显示：
- 已生效：登记履约、发起变更、终止、归档。
- 履约中：登记履约、发起变更、确认完成、终止。
- 已完成/已终止：归档。
- 已归档：仅查看。

详情页目标：

聚合基本信息、合同文件、合同明细、收付款计划、履约记录、变更记录、附件信息。
顶栏展示合同编号、名称、状态 Tag 和主操作按钮。
从履约或变更页面返回时自动刷新。
已归档状态所有 Tab 只读。

5.4 合同履约

履约记录用于记录交付、验收、开票、收款、付款、服务交付等执行节点。

后续重点：

创建履约前校验合同状态必须为已生效或履约中。
首笔履约自动推进合同状态为履约中。
每次新增、修改、删除履约后重新汇总 performanceAmount、performanceStatus。
履约金额达到或超过合同金额时，不强制自动完成合同，但前端要提示可“确认完成”。
未来跨模块对接时，CRM 回款、ERP 入库/付款、项目验收可通过 contract-api 自动写入履约记录。

5.5 合同变更

合同变更负责已生效合同的金额、期限、条款、范围等调整，必须保留历史和审批痕迹。

后续重点：

变更只允许已生效、履约中合同发起。
变更表单增加“变更协议文件”上传区，提交前必传。
审批通过后按 changeType 回写主合同：
- 金额变更：回写 totalAmount。
- 期限变更：回写 startDate/endDate 或约定的目标日期字段。
- 条款/范围变更：回写摘要字段或保留在变更记录中，台账展示最新变更摘要。
变更协议文件追加到台账“合同文件”版本列表。
变更通过后重新计算履约进度，避免金额变化后百分比不准确。

5.6 合同归档与终止

终止与归档都不走 BPM，作为台账生命周期操作处理。

规则：

终止允许状态：已审批、签署中、已生效、履约中。
终止必须填写终止原因，写入 terminateReason 和 terminateDate。
归档允许状态：已生效、已完成、已终止。
归档写入 archiveDate 和 archiveRemark。
归档后所有业务操作关闭，只允许查看和下载。

六、合同文件版本策略

合同文件要形成“阶段文件独立存储，台账统一聚合展示”的规则。

阶段	文件	存储建议	上传入口	台账展示
起草	合同草稿、审批稿	`contract_info.contract_file_urls`	合同起草详情	起草稿 V1/V2
签署	盖章件、扫描件	`contract_sign` 附件 + `contract_info.signed_file_url`	合同签署详情	签署件/正式版
变更	补充协议、变更协议	`contract_change.file_urls` 或变更附件	合同变更表单	变更版
履约	验收单、发票、付款凭证	`contract_performance.file_url` 或附件	履约记录	履约凭证
普通附件	报价单、沟通材料等	`contract_info.file_urls`	起草/台账附件	附件信息

统一要求：

台账“合同文件”Tab 聚合展示起草稿、签署件、变更协议。
普通附件和合同正文文件分区展示。
文件预览复用现有 AttachmentList / KKFileView / 浏览器预览能力。
后端写入规则要优先保证可追溯，不要求一开始实现复杂版本模型。

七、流程模型设计

7.1 合同审批 `contract_approve`

默认节点：

关键变量：

billCode：合同编号。
contractAmount：合同金额，用于金额分支。
cause：流程摘要，可由合同名称/对方单位拼接。
deptName、ownerUserName：审批展示信息。

7.2 合同签署 `contract_sign`

默认节点：

目标是确认线下签署材料齐备，不替代电子签章平台。

7.3 合同变更 `contract_change`

默认节点：

流程部署检查清单：

BPM 模型 Key 与 ContractBillTypeEnum 完全一致。
自定义表单路由指向 PC 端对应详情页。
起草、签署、变更三个流程均可在单体/微服务三通道回调下找到对应 FlowBillService。
合同专员岗位 CONTRACT_SPECIALIST 已初始化并有用户绑定。

八、跨模块对接目标

合同模块应作为平台通用合同能力，不直接依赖 CRM/ERP/HRM/OA 的内部表结构。

8.1 主关联模型

contract_info 当前落地采用“对方单位快照 + 通用业务关联预留”的双层模型。CRM/ERP 这类明确对方主体的场景优先使用 counterpartyType + counterpartyId；项目、OA、HRM 等业务来源关系可继续使用 bizType + bizId 做松耦合扩展。

字段	含义
`bizType`	来源业务类型，如 `crm`、`erp`、`hrm`、`oa`、`project`
`bizId`	来源业务主键
`counterpartyType`	对方单位类型，如客户、供应商
`counterpartyId`	对方单位 ID
`counterpartyName`	对方单位名称快照

8.2 API 扩展方向

当前 ContractInfoApi 已支持合同查询和精简列表，二次迭代建议补充：

API 能力	目的
按 `bizType + bizId` 查询合同列表	CRM/ERP/HRM 查看关联合同
新增履约记录	CRM 回款、ERP 入库/付款、项目验收自动回写
查询履约汇总	项目、CRM、ERP 展示合同执行进度
查询可选合同列表	OA 用印、项目立项、采购单选择合同
查询合同文件摘要	其他模块快速查看正式签署件

8.3 典型对接场景

模块	对接方式	业务价值
CRM	销售合同关联客户/商机，回款写入履约	销售到回款闭环
ERP	采购合同关联供应商/采购单，入库和付款写入履约	采购执行闭环
OA	用印申请选择合同，合同文件作为用印依据	印章与合同闭环
HRM	劳动合同关联员工，做续签/到期提醒	员工合同管理
项目	项目关联合同，验收节点写入履约	项目收入/交付闭环

九、PC 与移动端工作目标

9.1 PC 管理端

PC 端是二次迭代的主战场，目标是可完整处理合同生命周期。

页面	二次迭代目标
合同起草	补强合同文件起草稿区域、字段校验、审批态只读/可编辑权限
合同签署	修正流程 Key，强制签署件，优化起草稿预览，支持审批前保存
合同台账列表	保持状态 Tabs，完善操作权限和只读规则
合同台账详情	完善文件版本聚合、履约/变更回跳刷新、归档只读
合同变更	增加变更协议上传，审批通过回写与文件版本追加
合同履约	增加状态准入、首笔推进、满额提示
合同配置	明确签署环节开关、到期提醒配置
统计分析	以后续真实状态和履约金额为基础重新校准指标

9.2 UniApp 移动端

移动端分阶段推进，不一次性追平 PC。

阶段	范围
M1	保持合同起草审批可用，补齐字段与 PC 日期/字典一致性
M2	增加合同签署待办详情，支持上传/查看签署件
M3	增加台账只读详情，展示基本信息、正式签署件、履约摘要
M4	视业务需要开放移动端登记履约、发起变更

移动端文件预览默认使用 uni.downloadFile + uni.openDocument，不做复杂内嵌预览。

十、二次迭代开发分期

阶段 0：流程与状态底座修复

目标：先修正会导致流程串线或状态错误的问题。

修复 ContractBillTypeEnum.CONTRACT_SIGN 为 203 / 合同签署确认 / contract_sign。
检查 contract_sign 菜单、字典、BPM 模型、附件业务类型均使用 203。
签署提交增加附件必传校验。
补齐流程模型部署检查文档和本地测试数据。
用窄范围 Maven compile 验证合同模块。

阶段 1：履约与变更闭环

目标：让合同生效后的执行链路真实改变主合同状态。

履约新增/修改/删除后同步金额、履约状态、合同状态。
履约新增增加状态准入。
变更表单增加变更协议文件上传区。
变更审批通过后回写主合同字段。
变更文件进入台账合同文件版本列表。

阶段 2：台账体验与文件版本

目标：让台账成为真正的合同资产视图。

台账详情补齐生命周期时间线或审批摘要。
合同文件 Tab 区分起草稿、签署件、变更协议、履约凭证。
归档状态全页只读。
终止/归档弹窗统一为可复用 Modal，支持归档说明。
列表和详情操作权限保持一致。

阶段 3：跨模块服务与通知

目标：合同模块成为平台公共能力。

contract-api 增加履约写入、履约汇总、业务关联查询。
OA 用印申请支持选择合同并带出合同金额/对方/文件。
CRM/ERP/项目模块按需接入履约回写。
到期提醒 Job 接入站内信或待办。

阶段 4：移动端与统计校准

目标：补齐常用移动场景，并确保统计可信。

移动端支持签署待办和台账只读详情。
统计分析使用真实状态、履约金额、到期日期重新校准。
补充核心业务测试用例和回归清单。

十一、验收主链路

后续每轮开发应围绕以下链路做回归。

11.1 标准签署链路

合同起草保存草稿。
上传起草稿文件。
提交 contract_approve。
审批通过后生成 contract_sign 记录。
经办人上传签署件并提交 contract_sign。
签署审批通过。
合同进入台账，状态为已生效，台账文件能看到起草稿和签署件。

11.2 跳过签署链路

合同配置关闭签署环节。
合同起草提交并审批通过。
合同直接进入已生效台账。
effectiveDate 正确写入。

11.3 履约链路

对已生效合同登记履约。
合同状态自动变为履约中。
已履约金额和履约进度刷新。
满额后前端可确认完成。
确认完成后状态为已完成。

11.4 变更链路

对已生效/履约中合同发起变更。
上传变更协议。
提交 contract_change 审批。
审批通过后主合同字段被回写。
台账文件中出现变更协议版本。
履约进度按新金额重新计算。

11.5 终止归档链路

对已生效/履约中合同填写原因并终止。
合同状态为已终止，记录终止日期和原因。
对已终止合同归档。
归档后详情只读，不能新增履约、变更或再次终止。

十二、后续对话默认约定

以后提到“合同起草”，默认指 status <= 2 的流程单据视角。
以后提到“合同签署”，默认指 contract_sign 独立流程单据，流程 Key 为 contract_sign。
以后提到“合同台账”，默认指 status >= 4 的合同资产视图。
所有状态判断优先使用 ContractStatusEnum，不要新增魔法数字。
LocalDate 字段前后端统一使用 YYYY-MM-DD 字符串。
新增 DDL/DML 必须写入 ruoyi-office-db/{YYYYMMDD}_update/。
PC 端优先使用 Vben 现有封装：Page、useVbenVxeGrid、TableAction、BasicForm、AttachmentList。
移动端业务表单不得放入 pages-bpm，合同业务继续放在 pages-contract。
不再扩展 CRM 旧合同作为主线；合同中心是后续合同能力的主入口。

十三、近期最高优先级清单

建议下一轮开发从以下 8 件事开始：

修复 ContractBillTypeEnum.CONTRACT_SIGN 的 code/name/key。
校验并补齐 contract_sign BPM 模型、菜单、字典、附件业务类型。
submitContractSign 增加签署件必传校验。
ContractPerformanceServiceImpl 增加状态准入和 4->5 推进。
ContractChangeServiceImpl.onProcessApproved 实现主合同回写。
change/modules/form.vue 增加变更协议文件上传。
台账合同文件 Tab 确保变更协议、签署件、起草稿都能聚合展示。
补充合同全生命周期测试用例，覆盖签署、履约、变更、终止、归档。

十四、与《功能方案设计 v2》的差异合并补充

本节合并 合同管理模块功能方案设计.md 中对二次迭代有价值、且不改变本方案主线的补充内容。两份文档核心路线一致：起草/签署/台账三视角、contract_sign 独立流程、状态机闭环、合同文件分阶段管理、变更/履约/归档闭环。

14.1 v1 到 v2 的关键调整

调整项	初版设计	二次迭代设计
功能入口	单一“合同台账”入口承载全生命周期	拆分为“合同起草”与“合同台账”，中间由“合同签署”承接
签署环节	状态预留但无独立实现	新增 `contract_sign` 独立流程单据，`typeCode=203`
签署可选	默认强约束签署	由 `contract_config.sign_enabled` 控制，可跳过签署直接生效
文件版本	`file_urls` 混放合同正文和附件	起草稿、签署件、变更协议分阶段存储，台账聚合展示
甲乙方录入	直接填写甲方/乙方	用户填写我方/对方，后端按 `ourRole` 自动映射甲乙方
台账体验	普通 CRUD 列表	状态 Tabs + 生命周期操作 + 多 Tab 详情
CRM 旧合同	计划渐进迁移	暂不作为主线，新合同能力统一走合同中心

14.2 背景、目标与设计原则补充

合同模块的长期定位是平台级合同中心，覆盖销售、采购、服务、租赁、劳动、框架协议等中小企业常见场景。CRM 旧合同能力保留兼容，但后续新业务入口优先使用 yudao-module-contract。

补充设计原则：

复用本项目已有后端分层、Vben 页面封装、BPM 流程回调和附件体系。
中小企业场景优先可用闭环，不内置电子签章、AI 审查、在线 Word 编辑器等重型能力。
合同分类、合同类型、履约类型、签署方式等尽量使用字典/枚举驱动。
合同文件必须贯穿起草、审批、签署、变更、履约和归档各阶段。

14.3 架构与目录补充

后端模块依赖：

text

yudao-module-contract
├── contract-api      # 对外 DTO、枚举、服务接口
└── contract-server   # Controller / Service / Mapper / FlowBillService / Job
    ├── 依赖 bpm-api：流程提交、审批回调
    ├── 依赖 system-api：用户、部门、岗位、租户
    └── 依赖 infra/common attachment：文件与附件管理

PC 前端目录约定：

text

apps/web-antd/src/
├── api/contract/
│   ├── info/ sign/ change/ performance/ payment/
│   └── category/ template/ config/ stats/
└── views/contract/
    ├── draft/list/          # 合同起草，status <= 2
    ├── sign/list|info/      # 合同签署，contract_sign
    ├── info/list|detail|ledger/
    ├── change/ performance/ config/ stats/
    └── info/components/     # 对方单位选择等共享组件

14.4 数据模型补充

当前合同中心围绕 9 张核心表展开：

表名	职责	二次迭代关注点
`contract_category`	合同分类	树形分类，保持稳定
`contract_template`	合同模板	模板下载、线下编辑
`contract_info`	合同主表	起草与台账共用，状态区分视角
`contract_item`	合同明细	合同货物/服务/项目明细
`contract_payment_plan`	收付款计划	计划金额、计划日期、实际收付、逾期状态
`contract_change`	合同变更	增加变更协议文件，审批通过后回写主合同
`contract_performance`	合同履约	汇总已履约金额，推动履约状态
`contract_config`	合同配置	`sign_enabled`、到期提醒、编号规则
`contract_sign`	合同签署	独立 BPM 单据，附件业务类型应为 `203`

contract_info 二次迭代核心字段分组：

签约主体：ourCompanyId、ourCompanyName、ourRole、counterpartyType、counterpartyId、counterpartyName。
甲乙方快照：partyACompanyId、partyACompanyName、partyBName 等，由后端自动映射。
履约汇总：performanceAmount、performanceStatus。
合同正文文件：contractFileUrls、signedFileUrl。
生命周期：effectiveDate、terminateReason、terminateDate、archiveDate、archiveRemark、completeDate。
扩展关联：bizType、bizId。

contract_sign 二次迭代约定：

单据编号字段为 billCode。
流程字段为 processInstanceId、processStatus。
关联合同字段为 contractId、contractCode、contractName。
签署件通过 AttachmentService 保存，业务类型必须使用 ContractBillTypeEnum.CONTRACT_SIGN.getTypeCode()，目标值为 203。

14.5 字典与配置补充

需要持续保持前后端一致的字典：

字典类型	含义
`contract_type`	销售、采购、服务、租赁、劳动、框架、其他
`contract_nature`	收入、支出、无金额
`contract_status`	0 草稿到 8 已归档
`contract_change_type`	金额、期限、条款、范围、其他
`contract_performance_type`	交付、验收、开票、收款、付款、服务交付、其他
`contract_payment_status`	待收付、已收付、已逾期
`contract_sign_method`	线下签署、电子签署（预留）
`contract_our_role`	我方为甲方、我方为乙方
`contract_counterparty_type`	CRM 客户、ERP 供应商

合同配置页除编号规则、到期提醒外，需要明确展示 signEnabled 签署环节开关。

14.6 PC 页面细化补充

合同起草详情：

使用 BasicForm 承载 BPM 表单。
基本信息包括编号、名称、类型、性质、分类、我方主体、我方角色、对方类型、对方单位、金额、币种、签订/生效/截止日期、负责人。
子区域包括合同文件（起草稿）、合同明细、收付款计划、普通附件。
起草稿文件应绑定 contractFileUrls，普通附件绑定 fileUrls。

合同签署详情：

使用 BasicForm，流程 Key 为 contract_sign。
签署件上传区域使用 AttachmentList，建议限制 PDF、JPG、JPEG、PNG，数量和大小按当前页面约束。
起草稿区域只读展示 contractInfo.contractFileUrls。
提交签署确认前必须已上传签署件。

合同台账详情：

以 Page + Tabs + Card 为主结构，不使用 BPM 表单。
Tab 包括基本信息、合同文件、合同明细、收付款计划、履约记录、变更记录、附件信息。
合同文件 Tab 的聚合规则为：contractFileUrls 作为起草稿、signedFileUrl 作为签署件、change.fileUrls 作为变更协议。

合同变更：

当前基础 CRUD 和提交审批已具备。
二次迭代需要把普通 Modal 表单升级出“变更协议文件”区域，并在提交前校验。

合同履约：

当前已有 CRUD、履约金额汇总和履约状态推导。
二次迭代需要补状态准入、首笔履约推动合同状态、满额提示。

统计分析：

已有概览、月度和分类统计后，建议增加生命周期分布、履约完成率排行、即将到期合同列表。

14.7 流程模型与候选人补充

BPM 部署阶段应确认：

contract_approve 按金额分支，小额走分管领导，大额走主要领导。
contract_change 走发起人、部门负责人、合同专员、分管领导。
contract_sign 走经办人提交、合同专员审核、结束。
CONTRACT_SPECIALIST 岗位已初始化，并绑定实际用户。
三个流程的自定义表单路由都指向 PC 对应详情页。

14.8 更细的待办分组

在本方案“阶段 0-4”之外，第一份文档还拆出了更细工作包，可作为后续排期参考：

分组	任务
A 后端补齐	修复 `CONTRACT_SIGN`、变更回写、履约准入与推进、`ContractInfoApi` 扩展、确认 `contract_change.file_urls` DDL
B 前端补齐	起草稿文件卡片、签署开关、变更协议文件卡片、API 类型补全、履约满额提示
C 移动端	台账列表、台账详情、合同 API 补全、签署/变更移动端能力
D BPM	部署 `contract_approve`、`contract_change`、`contract_sign`，绑定岗位用户
E 定时任务	到期提醒、收付款逾期检查
F 跨模块	CRM 回款、ERP 入库/付款、OA 用印、HRM 劳动合同
G 统计增强	生命周期分布、履约完成率、即将到期合同

14.9 关键设计决策补充

起草与台账拆分，是因为起草关注审批进度，台账关注已生效合同资产。
签署做成独立流程，是因为签署确认的经办人、审核人、材料校验和起草审批不同。
ourRole + counterparty* 更符合用户“我方/对方”的录入习惯，甲乙方字段保留为合同展示和打印快照。
合同文件分阶段存储，是为了审计可追溯、权限可区分、台账可聚合。
电子签章、AI 合规检查、在线编辑器、多币种汇率均为扩展预留，不作为当前闭环主线。

14.10 文档关联补充

文档	用途
`docs/design/合同审批流程节点设计.md`	BPM 设计器配置参考
`合同管理模块业务流程测试用例.md`	集成测试场景
`合同全生命周期业务设计_78230c32.plan.md`	起草、签署、台账三视角来源
`合同全生命周期状态机_74e6923e.plan.md`	状态机来源
`合同台账模块重设计_14a8a008.plan.md`	台账列表重构来源
`合同台账详情页改造_4db6bb73.plan.md`	台账详情多 Tab 来源

14.11 已确认决策：移动端页面归属

第一份文档的移动端待办中提到“起草/变更/签署三个流程详情页”可放到 pages-bpm/ 配置和详情页；但本工作区规则要求业务模块表单继续放在 pages-contract，pages-bpm 只承载 BPM 引擎自身页面和公共审批详情能力。

已确认采用方案 A：

选项	做法	影响
A	业务详情页继续放 `pages-contract`，`pages-bpm` 只做审批容器/配置	符合当前仓库规则，作为后续迭代基准
B	将合同流程详情页集中放入 `pages-bpm`	不采用

合同管理模块二次迭代整体方案设计 ​

一、定位与结论 ​

二、当前实现基线 ​

2.1 后端已具备能力 ​

2.2 PC 前端已具备能力 ​

2.3 移动端已具备能力 ​

三、当前必须收口的问题 ​

四、目标业务状态机 ​

五、核心业务域设计 ​

5.1 合同起草 ​

5.2 合同签署 ​

5.3 合同台账 ​

5.4 合同履约 ​

5.5 合同变更 ​

5.6 合同归档与终止 ​

六、合同文件版本策略 ​

七、流程模型设计 ​

7.1 合同审批 contract_approve ​

7.2 合同签署 contract_sign ​

7.3 合同变更 contract_change ​

八、跨模块对接目标 ​

8.1 主关联模型 ​

8.2 API 扩展方向 ​

8.3 典型对接场景 ​

九、PC 与移动端工作目标 ​

9.1 PC 管理端 ​

9.2 UniApp 移动端 ​

十、二次迭代开发分期 ​

阶段 0：流程与状态底座修复 ​

阶段 1：履约与变更闭环 ​

阶段 2：台账体验与文件版本 ​

阶段 3：跨模块服务与通知 ​

阶段 4：移动端与统计校准 ​

十一、验收主链路 ​

11.1 标准签署链路 ​

11.2 跳过签署链路 ​

11.3 履约链路 ​

11.4 变更链路 ​

11.5 终止归档链路 ​

十二、后续对话默认约定 ​

十三、近期最高优先级清单 ​

十四、与《功能方案设计 v2》的差异合并补充 ​

14.1 v1 到 v2 的关键调整 ​

14.2 背景、目标与设计原则补充 ​

14.3 架构与目录补充 ​

14.4 数据模型补充 ​

14.5 字典与配置补充 ​

14.6 PC 页面细化补充 ​

14.7 流程模型与候选人补充 ​

14.8 更细的待办分组 ​

14.9 关键设计决策补充 ​

14.10 文档关联补充 ​

14.11 已确认决策：移动端页面归属 ​

合同管理模块二次迭代整体方案设计

一、定位与结论

二、当前实现基线

2.1 后端已具备能力

2.2 PC 前端已具备能力

2.3 移动端已具备能力

三、当前必须收口的问题

四、目标业务状态机

五、核心业务域设计

5.1 合同起草

5.2 合同签署

5.3 合同台账

5.4 合同履约

5.5 合同变更

5.6 合同归档与终止

六、合同文件版本策略

七、流程模型设计

7.1 合同审批 `contract_approve`

7.2 合同签署 `contract_sign`

7.3 合同变更 `contract_change`

八、跨模块对接目标

8.1 主关联模型

8.2 API 扩展方向

8.3 典型对接场景

九、PC 与移动端工作目标

9.1 PC 管理端

9.2 UniApp 移动端

十、二次迭代开发分期

阶段 0：流程与状态底座修复

阶段 1：履约与变更闭环

阶段 2：台账体验与文件版本

阶段 3：跨模块服务与通知

阶段 4：移动端与统计校准

十一、验收主链路

11.1 标准签署链路

11.2 跳过签署链路

11.3 履约链路

11.4 变更链路

11.5 终止归档链路

十二、后续对话默认约定

十三、近期最高优先级清单

十四、与《功能方案设计 v2》的差异合并补充

14.1 v1 到 v2 的关键调整

14.2 背景、目标与设计原则补充

14.3 架构与目录补充

14.4 数据模型补充

14.5 字典与配置补充

14.6 PC 页面细化补充

14.7 流程模型与候选人补充

14.8 更细的待办分组

14.9 关键设计决策补充

14.10 文档关联补充

14.11 已确认决策：移动端页面归属