Files
xiaoqu_mcp_service/xiaoqu-agent-service/doc/contract-create-mcp-design.md
T
my_local_kimi_dev2 2aa99abddd feat(mcp): 新增合同批量补录上传与创建工具 (REQ-20261118-0011)
- contract.file.upload:单文件 Base64 上传(20 MiB 上限),OSS+DB 补偿,clientUploadId 持久化幂等
- contract.create:单事务创建合同/绑定附件/写创建记录/提交审批,clientRequestId 持久化幂等
- 补齐 ContractNew.contractType/renewed、ContractFile OSS 与幂等字段、审批流实体与 Mapper
- 新增 JacksonLargePayloadConfig,放宽 20 MiB Base64 的 Jackson 字符串上限至 32 MiB
- 附 m2 DDL 脚本(dev 已执行、prod 待执行)、设计稿、PRD/讨论记录与工具参考文档
2026-11-19 09:31:19 +08:00

34 KiB
Raw Blame History

合同附件上传与创建工具 — MCP 设计文档(决策已拍板)

  • 工具:contract.file.upload、contract.create(均为 kind=write,category=admin)
  • 对标老接口:POST /contract/uploadFile、POST /contract/add
  • 调研日期:2026-11-18
  • 当前状态:已实现并通过全量测试与本机 dev 真实 MCP 冒烟;尚未提交、部署或执行生产 DDL
  • 目标场景:批量补录合同;每份合同必须在基本信息完整、全部附件上传成功后,才形成一份完整合同并提交审批

本设计基于当前工作区行号级实查。老系统 ContractController.java、ContractDealService.java 等合同模块文件在当前 Git 工作区中仍是新增未提交文件;本文描述的是这份代码的行为,不据此断言老系统生产环境已经部署该版本。

1. 拍板结论与范围

  1. 新增 contract.file.upload,MCP 直接接收文件内容并上传 OSS,不再要求调用方先从老页面上传。
  2. 创建时不增加物业行级数据权限;只保留用户 Token、工具 scope、物业及关联数据有效性校验。
  3. contract.create 完成“创建并提交”即返回,不等待审批通过,不代做审核、续签或其他后续动作。
  4. 物业销售或销售所属公司缺失时拒绝创建,避免空公司绕过审批。
  5. expireRemind 默认 1(开启),remindDays 默认 30。
  6. 数据库已提交但审批通知失败时,仍返回创建成功并附 warning,不诱导重复创建。
  7. 实现范围补齐主工程缺失的 contractType、renewed、附件 OSS 字段,并正式处理合同名称可空的 schema 冲突。
  8. 为批量调用的超时重试补上持久化幂等,取代上一版“只有短时并发锁、超时后人工查重”的方案。

本期不包含:附件 OCR/日期识别、合同草稿、审批办理、修改再提交、续签、终止、删除、工作流配置、异步批任务和定时任务迁移。

2. 批量使用总体设计

2.1 两个原子工具,不引入半成品合同

系统没有独立合同草稿状态。contract.create 不允许只插 contract_new 而不绑定附件或不走审批,也不允许 fileIds 为空。

批量导入由调用方按“一份合同一个闭环”编排:

准备该合同基本信息和稳定的 clientRequestId
        │
        ├─ 为每个文件生成稳定的 clientUploadId
        │        ↓
        │   contract.file.upload(逐文件,可重试)
        │        ↓
        │   收齐该合同全部 fileId
        │
        ├─ 任一文件上传失败:本合同不调用 create,记录失败;其他合同可继续
        │
        └─ 全部文件上传成功
                 ↓
            contract.create(基本信息 + fileIds + clientRequestId)
                 ↓
            单事务创建合同、绑定全部附件、提交审批
                 ↓
            返回合同 id / 编号 / 状态;通知异常只附 warning

**完整性保证:**上传工具只产生可复用的未绑定附件,不产生合同;只有创建工具才产生合同,而创建事务要么“合同 + 全部附件绑定 + 创建/审批流程”一起成功,要么整体回滚。因此不会出现“有合同但没有附件”或“只绑了部分附件”的正式合同。

2.2 批量不是整批一个事务

首版不另设 contract.batch.create,由客户端/Agent 循环调用两个原子工具:

  • 每份合同独立提交,某一份数据或文件失败不阻塞其他合同。
  • 单份失败只重试该份,不需要回滚或重传整批。
  • 避免一个大批量请求长期占用数据库事务、超过 MCP 超时后整批结果不明。
  • 调用方保存每份合同及每个文件的稳定幂等键;建议最多 3 份合同并行,单份合同内文件串行,防止 OSS/DB 瞬时压力过高。

批量结果按 clientRequestId 对账:成功项记录合同 id/编号,失败项记录阶段(UPLOAD/CREATE)、错误码和可重试性。创建成功后不强制再调用详情查询。

2.3 超时重试规则

  • 上传超时:用相同 clientUploadId、相同文件名和文件内容重试 contract.file.upload。
  • 创建超时:用相同 clientRequestId 和相同规范化参数重试 contract.create。
  • 不得因为超时就换幂等键;换键会被视为新的业务意图,可能生成重复附件或合同。
  • 同一幂等键对应不同内容/参数时返回 IDEMPOTENCY_CONFLICT,不覆盖第一次结果。
  • 幂等回放只返回已存在资源,不再次绑附件、写流程或发送审批消息。

3. 老系统流程实查

3.1 附件先于合同存在

  • ContractController.java:616-660:POST /contract/uploadFile 支持 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv,上传 OSS 后插入 contract_file,初始 contract_id=0,返回 fileId/url。
  • OSS 对象位于 xiaoqu-safefile 的 contract/ 目录;数据库同时保存 oss_bucket/oss_folder/file_url。
  • 老接口仅按扩展名校验,未限制文件大小;对象名使用毫秒时间戳。MCP 不复制这两个宽松/并发风险点。
  • ContractController.java:662-704:parseContractDate 是独立辅助接口,新增接口不会自动调用;本期也不自动识别日期。
  • ContractAddInput.java:20-54:新增提交只接收附件 fileIds,不接收文件二进制或 URL。

3.2 Controller 入参校验和快照

ContractController.java:286-310 是新增入口,登录后调用 buildContract,再进入 ContractDealService.add。

ContractController.java:755-812 的实际行为:

项目 当前代码行为
合同类型 contractType 必填,但只判非 null,没有限制在 0/1/2
合同名称、金额 二期已放开为非必填
客户所属公司 customerAgentId 必填;此处不校验公司是否存在或渠道类型
所属物业 propertyId 必填;按 id 查 m0 properyt,不存在或软删则拒绝
物业编号 properyt.serialnumber 空白或字符串 null 时拒绝,因为它用于合同编号
合同日期 startDate/endDate 必填,endDate >= startDate;不限制是否早于当天
到期提醒 老后端缺省 expireRemind=0;本工具按拍板改为默认 1
提醒天数 缺省或非正数时取 30;MCP 缺省 30,显式传入必须为正整数
提醒时间 开关开启时,取 endDate-remindDays 当天 09:30:00
客户快照 propertyName=properyt.name、customerNo=properyt.serialnumber、customerName=properyt.jinideName
销售快照 saleId/saleName=properyt.createId/createName
合同所属公司 再按 properyt.createId 查 m0 user,取该销售的 agentId;老代码查不到销售时留空

注意:customerAgentId(表单选择的客户所属公司)与 contractAgentId(物业销售所属公司、用于审批流)是两个不同字段,不能互相覆盖,也不能默认二者相等。

3.3 m2 事务内的写入顺序

ContractDealService.java:200-224 使用 txManager2 编程式事务:

  1. checkFilesBindable:附件必须存在、未软删且 contract_id=0(:742-758)。
  2. 写合同创建/修改审计字段。
  3. saveWithContractNo 保存合同(:590-605)。
  4. bindFiles:逐条把未绑定附件关联到新合同(:764-777);老代码没有检查每条更新的影响行数。
  5. submitFlow:写创建记录并决定审批状态(:612-675)。

3.4 合同编号

ContractDealService.java:587-605:

  • 格式:properyt.serialnumber + "C" + %03d;流水 = 同一 customer_no 下合同数 + 1。
  • 计数包含软删合同,避免编号复用。
  • contract_no 有唯一索引;捕获 DuplicateKeyException 后最多尝试 3 次。
  • 老实现把计数和重试放在同一个事务里;MCP 改为每次尝试使用独立完整事务。

3.5 审批流判断

工作流按 contractAgentId 查 m2 contract_flow_set,再查 contract_flow_user(ContractDealService.java:824-850)。

场景 当前代码结果
无工作流配置 contract_status=2 正常,只有创建记录,不生成待办/抄送,不发审批消息
有关闭部门内审批的配置,且有层级审核人 待审;待办人为 1 级审核人,node_type=2,audit_level=1
有配置但无层级审核人 正常
部门内审批开启,提交人是部门负责人 跳过部门负责人节点;有层级则进入 1 级审核,无层级则正常
部门内审批开启,提交人不是负责人,且能查到本部门负责人 待审;全部部门负责人为待办人,node_type=1,audit_level=0
部门内审批开启,提交人不是负责人,但查不到负责人 跳过部门节点;有层级则进入 1 级审核,无层级则正常

部门负责人岗位来自 Redis db5 Dictionary.authDeptPostId。老代码在字典缺失时按“无负责人”继续,可能使合同直接正常;MCP 改为 fail fast。

待审时(:680-707):

  • 创建记录:node_type=0, operation_type=0, schedule_state=0,创建人为提交人。
  • 当前待办:operation_type=0,schedule_state=1,每个待办人一行。
  • 抄送:node_type=4,operation_type=5,schedule_state=0,每个抄送人一行。
  • 消息按 userId 去重:待办 type=12、抄送 type=13,写 Redis list InvoiceMessageNotice。
  • 只有进入待审分支才生成抄送记录和消息;直接正常时即使配置了抄送人也不发送。

3.6 提交后副作用与后续任务

  • ContractDealService.java:925-947 使用 afterCommit 推送 Redis,避免数据库回滚后仍发消息。
  • ContractTask.java 的过期扫描、到期提醒和合同上传提醒由老系统定时任务异步执行,不是本次 MCP 调用内的同步写入。
  • 创建本身不联动资产、库存、商城订单或金蝶。
  • 当前老系统源码未找到实际清理 contract_file 未绑定附件的任务;表注释中的“定时清理”不能当成已有保障。

4. 数据模型与 schema 前置变更

4.1 涉及资源

库/服务 表/资源 访问 用途
m0 properyt 读 物业有效性、客户与销售快照、编号前缀;不做行级权限过滤
m0 user 读 当前提交人、销售所属公司、部门负责人
m0 agent 读 客户所属公司有效性
m2 contract_new 读/写 编号计数、创建幂等、合同主记录
m2 contract_file 读/写 上传幂等、附件记录、创建时绑定
m2 contract_process 写 创建、待办、抄送记录
m2 contract_flow_set / contract_flow_user 读 审批流配置和人员
svc audit_log 自动写 现有 GuardedToolCallback 工具审计
Redis Dictionary、InvoiceMessageNotice 读/写 部门岗位字典;提交后的审批/抄送消息
OSS 配置化 bucket,默认兼容 xiaoqu-safefile/contract/ 写/删 文件存储;仅在本次上传后的 DB 失败补偿中删除新对象

m0 只读;m2 的合同、附件绑定和流程记录放在一个本地事务中,不做跨库分布式事务。OSS 上传与附件 DB 插入不是同一事务,按第 6 节补偿。

4.2 必须补齐的既有映射

  • 主工程 entity/m2/ContractNew.java 缺少二期字段 contractType、renewed,实现时补齐;renewSourceId 已存在。
  • 主工程 entity/m2/ContractFile.java 缺少 ossBucket、ossFolder,实现时补齐。
  • 主工程需新增 ContractFlowSet、ContractFlowUser 实体和 Mapper。

4.3 合同名称可空

仓库 DDL contract-management-ddl.sql:24 仍写 contract_name VARCHAR(128) NOT NULL,而二期设计与当前 Controller 均允许名称为空。

实现前只读核对 dev/prod 实际表结构。若仍为 NOT NULL,先执行正式变更:

ALTER TABLE contract_new MODIFY contract_name VARCHAR(128) NULL;

不得用空字符串冒充 null 绕过。该 DDL 属于 m2 老系统业务库,不混入 MCP 的 svc Flyway migration。

4.4 为批量重试增加持久化幂等字段

只用 Redis 锁无法解决“DB/OSS 已成功但响应丢失”。为两个现有表增加可空字段;老系统插入时保持 null,不影响既有逻辑,MySQL 唯一索引允许多个 null 历史行。

表 新字段 约束/用途
contract_new client_request_id VARCHAR(64) NULL、request_hash CHAR(64) NULL UNIQUE(create_id, client_request_id);防止同一用户重复创建,识别同键不同参数
contract_file client_upload_id VARCHAR(64) NULL、request_hash CHAR(64) NULL UNIQUE(create_id, client_upload_id);防止同一用户重复上传,识别同键不同文件
  • 两个幂等键均为 1~64 位,只允许字母、数字、点、下划线、冒号和连字符;推荐 UUID。
  • request_hash 为 SHA-256。上传按“规范化原文件名 + 内容 SHA-256”计算;创建按“全部规范化业务字段 + 排序后的 fileIds”计算。
  • 唯一索引是最终防线,前置查询只用于快速回放,不能代替唯一约束。
  • 上线顺序:dev/prod 只读核对 → 执行 additive DDL 和名称可空变更 → dev 验证 → 再发布新工具。回滚代码时保留新增列,不随代码回滚 DROP。

5. MCP 工具契约

5.1 contract.file.upload

描述:上传一个合同附件到 OSS,并生成 contract_id=0 的附件句柄。它只是准备附件,不创建合同。

入参

参数 类型 必填 校验与说明
clientUploadId string 是 当前用户范围内稳定唯一的上传幂等键;重试必须不变
fileName string 是 原始文件名,1~255 字符;不得包含路径分隔符;扩展名属于 jpg/jpeg/png/doc/docx/pdf/xls/xlsx/csv
contentBase64 string 是 标准 Base64 文件内容,不带 data URL 前缀;严格解码,解码后 1 byte~20 MiB

约束:

  • 每次只传一个文件,避免多文件 Base64 导致请求体和内存占用叠加;20 MiB 文件编码后约增加 33% 体积。
  • 服务端计算实际字节数、内容 SHA-256 和 requestHash,不信任调用方声明的大小或摘要。
  • 除扩展名外,对 PDF/JPEG/PNG、OLE(doc/xls)及 ZIP(docx/xlsx)检查文件头;CSV 拒绝包含 NUL 的二进制内容。
  • OSS 对象名使用 UUID + 小写扩展名,不照搬毫秒时间戳,避免并发同名覆盖。
  • OSS endpoint、bucket、folder 和凭据走环境配置/密钥管理;不把密钥写入代码、日志、工具返回或 MCP 审计内容。

返回

字段 类型 说明
fileId long 附件句柄,供 contract.create 使用
fileName string 原始文件名
contractId long 当前绑定合同 id;刚上传为 0,幂等回放时可能已大于 0
idempotentReplay boolean 是否命中已有上传结果
requestId string 本次 MCP 请求追踪 id,不是幂等键

上传成功不返回文件内容;审计日志不记录 Base64、文件正文或 OSS 凭据。

5.2 contract.create

描述:用完整基本信息和已上传附件创建并提交一份合同。提交成功即返回,不等待审批通过。

入参

参数 类型 必填 校验与说明
clientRequestId string 是 当前用户范围内稳定唯一的创建幂等键;一份逻辑合同一个键
contractType int 是 0 租赁 / 1 售卖 / 2 其他
customerAgentId long 是 客户所属公司 id;必须是有效、未软删的总部/分公司(agent.channel_no ∈ {Z,F})
propertyId long 是 所属物业 id;校验存在、未软删和编号可用,不做行级数据权限过滤
fileIds array 是 至少 1 个、不得重复;必须全部存在、未软删、contract_id=0,且由当前用户通过 MCP 或老系统上传
contractName string 否 最长 128;空白归一为 null;实际 schema 必须允许 null
amount decimal 否 单位元,非负,最多 2 位小数并满足 decimal(14,2)
contact string 否 最长 64;空白归一为 null
startDate string 是 严格 yyyy-MM-dd 合法日历日期
endDate string 是 严格 yyyy-MM-dd,且不得早于 startDate
expireRemind int 否 0 关 / 1 开;默认 1
remindDays int 否 默认 30;显式传入必须为正整数

其他约束:

  • 普通新建固定写 renewSourceId=0、renewed=0、reminded=0、softDelete=0,不接受调用方指定合同编号、状态、创建人、销售或快照字段。
  • 日期不因早于今天而拒绝,保持补录历史合同能力。
  • expireRemind=0 时 remindTime=null;开启时为结束日期减提醒天数后的当天 09:30:00。
  • 附件的上传人校验是归属和并发一致性约束,不是物业数据权限;不得把一个 fileId 同时用于两份合同。
  • 创建失败时已上传附件保持未绑定,可在修正数据后重试;不会留下半份合同。

返回

字段 类型 说明
id long 新合同或幂等回放合同 id
contractNo string 服务端生成的合同编号
contractStatus / contractStatusText int / string 提交后的状态:0 待审或 2 正常;不代表已经审批通过
fileIds array 本次成功绑定的附件 id
clientRequestId string 创建幂等键,供批量对账
idempotentReplay boolean 是否命中已有合同;true 时没有再次执行写入和通知
warnings array 提交后通知异常等警告;无警告为空数组
requestId string 本次 MCP 请求追踪 id,不是幂等键

5.3 错误码

  • PERMISSION_DENIED:服务身份 Token、缺少用户上下文或无工具 scope。
  • INVALID_ARGUMENT:必填缺失、幂等键非法、枚举/日期/金额/长度非法、Base64/文件头非法、文件为空或超过 20 MiB、附件列表为空或重复。
  • NOT_FOUND:物业、客户所属公司或附件不存在/已删除。
  • DATA_INTEGRITY_ERROR:物业编号缺失、销售或销售所属公司缺失、工作流配置损坏、附件条件更新影响行数异常、编号重试耗尽。
  • ATTACHMENT_NOT_BINDABLE:附件已绑定、非当前用户上传,或并发绑定导致状态已变化。
  • IDEMPOTENCY_CONFLICT:同一用户复用了相同幂等键,但文件内容/文件名或创建参数与第一次不同。
  • UPSTREAM_UNAVAILABLE:OSS、创建所需 DB 或 Redis 字典暂时不可用;数据库已提交后的通知异常不使用此错误伪装失败。

6. 核心实现行为

6.1 上传:OSS 与 DB 的补偿边界

  1. 校验用户 Token、scope、参数和文件内容,计算 requestHash。
  2. 按 create_id + client_upload_id 查询(含已绑定行):
    • 已存在且 hash 相同:返回已有 fileId,idempotentReplay=true,不上传新对象。
    • 已存在但 hash 不同:IDEMPOTENCY_CONFLICT。
  3. 用随机 UUID 对象名上传 OSS;OSS 未确认成功时不插 DB。
  4. 插入 contract_file,写原文件名、bucket/folder、HTTPS URL、创建/修改人、时间、contract_id=0、soft_delete=0 和幂等字段。
  5. 若 DB 插入失败或唯一冲突:先查询是否已有同键记录。
    • 同键同 hash:删除本次刚上传的冗余 OSS 对象,回放已有 fileId。
    • 同键不同 hash:删除本次对象,返回冲突。
    • 其他 DB 失败:尽力删除本次对象后返回失败;删除失败记录对象 key 供运维清理。
  6. 不让 DB 失败触发对已存在附件或其他合同文件的删除。

OSS 成功而 DB 未提交时最多遗留一个未登记对象,不会生成不完整合同;该对象通过告警和运维清单补偿清理。

6.2 创建:前置校验

  1. 必须为用户委托 Token,创建人、修改人均取 Token 用户 id。
  2. 校验完整入参并计算规范化 requestHash;按 create_id + client_request_id 查询(含软删行),存在时按 hash 回放或拒绝冲突。
  3. 物业只校验存在、未软删、编号可用,不调用 applyPropertyRowFilter,不新增其他物业行级权限判断。
  4. 校验客户所属公司为有效 Z/F 公司,但不强制它等于物业或销售所属公司。
  5. 反解物业、销售快照;销售不存在、软删或 agentId 为空时明确拒绝。
  6. 校验附件列表;Redis 岗位字典在工作流需要时 fail fast。

6.3 编号冲突、幂等冲突与 m2 事务

每次尝试都在一个独立完整 m2 事务中执行:

  1. 统计同一 customer_no 的全部合同(含软删),生成编号。
  2. 插入合同主记录,包含审计字段、client_request_id 和 request_hash。
  3. 逐附件执行条件更新:id匹配 AND soft_delete=0 AND contract_id=0 AND create_id=当前用户,同时写合同 id、修改人和修改时间;每条影响行数必须为 1,否则整体回滚。
  4. 写创建流程记录。
  5. 读取并校验工作流,写最终合同状态、当前待办和抄送记录。
  6. 注册事务提交后的 Redis 消息动作。

异常分类:

  • 唯一冲突后先回滚,再按 create_id + client_request_id 查询。若查到同 hash 合同,按幂等成功返回;若 hash 不同,返回 IDEMPOTENCY_CONFLICT。
  • 若不是创建幂等键冲突,而是 contract_no 冲突,则在事务外重新计数并开启下一次完整尝试,最多 3 次。
  • 不能靠解析数据库错误文本区分冲突;以回滚后的幂等记录查询和后续编号重试为准。
  • 有效工作流按 agent_id + soft_delete=0 应最多一条;多配置、层级损坏或所需岗位字典缺失时拒绝,不以 limit 1 或自动生效掩盖异常。

6.4 提交后消息与返回时点

  • 仅在待审时发送,JSON 字段保持 type/no/content/userId,队列和文案与老系统一致。
  • 同事务待办与抄送按 userId 去重消息,但流程记录仍按各自业务语义写入。
  • Redis 推送发生在 m2 成功提交之后。
  • 推送异常逐条记录日志,工具仍返回合同创建成功及 warnings;不等待审批通过,不做额外审批操作。
  • 幂等回放不补发消息,避免一次逻辑提交产生重复待办通知。
  • 首版不新增通知 outbox;若以后要求通知必达,另立需求。

6.5 大载荷 JSON 约束(实现补充)

20 MiB 文件的标准 Base64 约 27.96 MB 字符,超过 Jackson 2.15+ 默认 maxStringLength=20,000,000。 实现通过 JacksonLargePayloadConfig 将容器 ObjectMapper、Spring AI JsonParser 静态 mapper 及 MCP 中间层 mapper 的上限统一放宽到 32 MiB;否则请求会在 MCP SDK 反序列化阶段被拒绝,尚未进入工具方法。 该配置只放宽字符串长度,不改变其他解析限制。

6.6 未绑定附件生命周期

  • 上传成功但创建未调用/失败:附件保持 contract_id=0,可用原 fileId 继续创建,不属于正式合同。
  • 创建事务失败:已条件更新的附件随事务回滚,仍可重试。
  • 创建成功:全部 fileIds 同事务绑定,不允许继续被其他合同使用。
  • 首版不假设已有孤儿附件定时清理,也不提供自动删除工具。批量任务结束后按 create_id/create_time/client_upload_id/contract_id=0 输出未使用附件清单,由运维审计后清理;自动清理必须另做任务并避开进行中的导入。

7. 权限与 scope

  • 两个工具都必须用户身份 Token;服务身份 Token 不允许代传或代建,保证上传人、创建人可追溯。
  • 按拍板,不增加物业行级数据权限,也不改变既有 contract.list/detail.query 的查询权限。
  • 保留附件当前上传人约束和原子条件更新,防止串用附件及并发双绑。
  • prod 只绑研发专用 scope 6(code=code);dev 只绑测试专用 scope。
  • 不绑业务 scope 1/2/3/5;已有合同查询权限不自动获得上传或创建权限。

8. 与老系统差异汇总

差异 原因
MCP 新增 Base64 附件上传工具 支持不经过老页面的批量合同补录
单文件最大 20 MiB、严格 Base64 和文件头校验 控制请求/内存风险,不只依赖可伪造的扩展名
OSS 对象名使用 UUID 避免毫秒时间戳并发冲突
上传与创建均有数据库持久化幂等 解决批量超时重试产生重复文件/合同的问题
不增加物业行级权限 按拍板复刻老新增接口只登录、直接传物业 id 的口径
枚举、字符串长度、金额和日期严格校验 避免非法数据静默入库
客户所属公司有效性和 Z/F 渠道校验 与老公司选择口径一致,避免脏 id
销售/所属公司缺失拒绝 防止空公司被当成无审批配置
expireRemind 默认开启 按拍板采用二期前端默认口径,而非老后端默认关闭
附件条件更新必须影响 1 行 防止并发创建时两份合同都成功但其中一份没有附件
编号冲突按完整独立事务重试 避免同事务快照重复冲突及部分写入
Redis 岗位字典缺失、工作流多配置或层级损坏时拒绝 防止审批被静默跳过
通知失败透出 warning 防止数据库已提交但整体响应失败造成重复创建
创建返回精简为 id/编号/状态/附件/警告 提交完成即结束,不要求调用方处理审批人列表或等待审批结果

9. 变更文件清单(实现阶段)

新增

文件 层级 改动说明
src/main/java/me/iiv/agent/mcp/tool/ContractFileAdminTools.java MCP Tool 单文件上传、校验、OSS/DB 补偿和上传幂等
src/main/java/me/iiv/agent/mcp/tool/ContractCreateAdminTools.java MCP Tool 参数、快照、编号、附件绑定、创建幂等和审批提交
src/main/java/me/iiv/agent/config/ContractOssProperties.java Config OSS endpoint/bucket/folder 和凭据配置映射
src/main/java/me/iiv/agent/service/ContractOssService.java Service OSS 上传与本次新对象补偿删除
src/main/java/me/iiv/agent/entity/m2/ContractFlowSet.java Entity 工作流设置实体
src/main/java/me/iiv/agent/entity/m2/ContractFlowUser.java Entity 工作流人员实体
src/main/java/me/iiv/agent/mapper/m2/ContractFlowSetMapper.java Mapper 工作流设置查询
src/main/java/me/iiv/agent/mapper/m2/ContractFlowUserMapper.java Mapper 工作流人员查询
src/test/java/me/iiv/agent/mcp/tool/ContractFileAdminToolsTest.java Test 上传及幂等测试
src/test/java/me/iiv/agent/mcp/tool/ContractCreateAdminToolsTest.java Test 创建、附件、审批及幂等测试
m2 正式 DDL 变更脚本 Schema 名称可空、两张表的幂等字段和唯一索引;按环境执行并留核验结果

修改

文件 层级 改动说明
pom.xml Build 显式引入 com.aliyun.oss:aliyun-sdk-oss:3.18.5(JDK17 兼容,避免 3.8.0 的旧传递依赖;已实测 20 MiB 上传)
src/main/resources/application-dev.yml / application-prod.yml Config 只增加配置键引用;凭据通过安全注入,不在文档或日志展开
src/main/java/me/iiv/agent/entity/m2/ContractNew.java Entity 补 contractType、renewed、创建幂等字段
src/main/java/me/iiv/agent/entity/m2/ContractFile.java Entity 补 ossBucket、ossFolder、上传幂等字段
src/main/java/me/iiv/agent/mcp/tool/ContractTools.java 既有查询工具 列表/详情补合同类型及文案,便于需要时回读;不改变既有筛选和权限
src/test/java/me/iiv/agent/mcp/tool/ContractToolsTest.java Test 补合同类型回读断言
doc/agent-mcp-tools-reference.md 文档 上线时追加两个工具契约及查询新增字段
AGENTS.md 项目指引 上线收尾时登记正式需求号、提交和部署结果

没有前端改动,没有 MyBatis-Plus 分页需求。m2 DDL 不走 svc Flyway,不新增异步批任务或通知表。

10. 开发任务拆分

# 任务 完成标准
1 核对 dev/prod schema,执行并验证正式 DDL 名称可空、幂等字段/索引存在;老系统插入回归正常
2 补实体、Mapper、OSS 配置和依赖 不泄露凭据;OSS 连接及小文件 dev 验证通过
3 实现上传工具 格式/大小校验、OSS+DB 补偿、上传幂等及并发测试通过
4 实现创建工具 快照、编号、附件全绑、审批路由、创建幂等及通知 warning 测试通过
5 批量编排与失败恢复验证 多份合同部分失败互不影响;同键重试无重复;无半成品合同
6 全量测试、dev MCP 冒烟、文档与上线 ./mvnw clean package 全绿;dev 真实写冒烟及清理完成后才走标准发布

11. 测试要点

11.1 上传工具

  1. 用户 Token 守卫、scope、write annotations 和审计;审计不含 Base64。
  2. 每种允许扩展名;无扩展名、非法扩展名、路径文件名、错误 Base64、空文件、20 MiB 边界和超限。
  3. PDF/图片/OLE/ZIP 文件头与扩展名不符时拒绝;CSV 二进制 NUL 拒绝。
  4. OSS 失败不插 DB;DB 失败删除本次新对象;补偿删除失败有对象 key 告警。
  5. 同用户同 clientUploadId 同文件串行/并发只保留一个 DB 附件,返回同一 fileId。
  6. 同键不同文件名或内容返回冲突;不同用户可使用相同键但互不影响。
  7. 幂等回放不产生新 OSS 对象;已绑定附件回放可返回当前 contractId。
  8. 对象 key 随机且不覆盖既有对象,bucket/folder/URL 与数据库一致。

11.2 创建工具

  1. 所有必填、合同类型、公司、文本长度、金额精度、日期和提醒参数校验;缺省提醒为开启 + 30 天。
  2. 物业不存在/软删拒绝;确认不调用 applyPropertyRowFilter。
  3. 物业、客户、销售和双公司快照正确;销售或所属公司缺失拒绝。
  4. 附件为空、重复、不存在、软删、已绑定、他人上传、条件更新 0 行;任一种均无合同或流程残留。
  5. 编号计数包含软删,格式正确;编号唯一冲突完整重试,耗尽后整体无写入。
  6. 无配置、空层级、部门开关、负责人/非负责人、无部门负责人、1 级会签和抄送分支。
  7. 岗位字典缺失、有效工作流多条、审核层级缺 1 级时 fail fast。
  8. 任意 DB 写入失败时 m2 全回滚,附件仍未绑定,Redis 没有消息。
  9. 消息只在 commit 后发送;type/no/content/userId、接收人去重和文案正确。
  10. Redis 通知失败时数据库仍已提交,返回合同 id 和 warning,不返回“未创建”。
  11. 同用户同 clientRequestId 同参数串行/并发只产生一份合同、一套流程和一次通知;回放不重新绑附件。
  12. 同键不同参数返回冲突;创建幂等唯一冲突与合同编号冲突能正确分流。
  13. contract.list/detail.query 能回读合同类型,既有查询权限和测试不回归。

11.3 批量场景与 dev 真实 MCP 冒烟

  • 至少模拟 3 份合同:一份完整成功、一份上传失败、一份创建校验失败;验证后两份没有合同记录,且不影响成功份。
  • 对上传和创建分别模拟响应丢失后同键重试,核对 OSS 对象数、contract_new/contract_file/contract_process 和 Redis 不重复。
  • 修正失败基本信息后可复用原未绑定 fileIds;成功合同的附件不能再被另一合同使用。
  • 使用 dev 专用测试物业、用户和小型一次性附件,核对 create/modify 人、提醒时间、合同状态及附件绑定。
  • 历史合同默认开启提醒时,确认老任务可能立即发送到期提醒;测试需关闭该用例提醒或选择不会触发通知的日期,生产不做写冒烟。
  • 测试结束后按本次 id 精确清理 dev 合同、流程、附件和 OSS 对象,恢复工作流,不触碰既有行。
  • 全量构建通过后,才允许按标准流程 push main、remote-deploy、绑 prod scope 6;生产只做 tools/list、未授权和无写入参数错误核验。

12. 风险与回退

风险 等级 应对
老系统合同代码尚未提交,实际生产行为可能不同 高 实现前确认目标老系统版本及 dev/prod schema;本设计不冒充生产调研
Base64 增大请求体与堆内存 高 单文件 20 MiB 上限、逐文件调用、限制批量并发;实现时核对 MCP 网关请求上限
OSS 成功而 DB 失败产生未登记对象 中 删除本次新对象补偿;失败告警并保留对象 key
上传后放弃创建产生未绑定附件 中 创建失败保留以便重试;输出未使用清单;不虚构已有自动清理能力
客户端超时后换幂等键造成重复 高 契约要求同键同内容重试;唯一索引防同键重复,换键属于新业务意图
无审批配置导致直接正常 高 保持老规则,返回实际状态;销售公司缺失不得静默走此分支
合同编号并发冲突 中 唯一索引 + 完整独立事务重试 + 幂等冲突分流
附件被并发绑定 高 上传人约束 + 条件更新影响行数强校验 + m2 回滚
DB 成功而通知失败 中 成功返回带 warning;幂等回放不补发;通知必达另做 outbox
历史日期 + 默认提醒开启造成即时通知 中 契约和风险明示;不希望提醒的历史数据须显式传 expireRemind=0
新 DDL 与老系统兼容性 高 只用可空新增列并先验证;名称可空按二期口径;先库后代码,禁止隐式 DDL

回退时先解绑/停用两个工具并回滚服务版本,阻止新增调用。保留 additive 幂等列,不随代码回滚删除。已经创建的合同和附件是正式业务数据,不自动删除;受影响记录需逐笔审计并通过老系统业务操作处理。若需恢复合同名称为 NOT NULL,必须先审计并处理所有 null 名称,不能作为代码回滚的默认动作。