From 78dd523e2fd9034f19eab5eaafe9b9f11051408d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=88=98=E6=B3=89=E4=BD=B3?= <1107186916@qq.com>
Date: Sat, 10 Oct 2026 20:19:17 +0800
Subject: [PATCH] =?UTF-8?q?:memo:=20=E6=96=B0=E5=A2=9EC102-1=E4=B8=8EC103-?=
 =?UTF-8?q?1=E6=8E=A5=E5=8F=A3=E9=A1=B5=E9=9D=A2=E5=AD=97=E6=AE=B5?=
 =?UTF-8?q?=E5=8F=96=E5=80=BC=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=EF=BC=88?=
 =?UTF-8?q?=E5=90=AB=E5=BF=85=E5=A1=AB=E9=A1=B9=E6=A0=87=E8=AE=B0=E4=B8=8E?=
 =?UTF-8?q?=E8=87=AA=E6=A3=80=E6=B8=85=E5=8D=95=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...-10-10-C102-1与C103-1接口页面字段取值说明.md | 134 ++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 doc/docs/hcs合同/2026-10-10-C102-1与C103-1接口页面字段取值说明.md

diff --git a/doc/docs/hcs合同/2026-10-10-C102-1与C103-1接口页面字段取值说明.md b/doc/docs/hcs合同/2026-10-10-C102-1与C103-1接口页面字段取值说明.md
new file mode 100644
index 00000000..038b97f0
--- /dev/null
+++ b/doc/docs/hcs合同/2026-10-10-C102-1与C103-1接口页面字段取值说明.md
@@ -0,0 +1,134 @@
+# C102-1 项目立项新建 / C103-1 合同新建 —— 页面字段取值说明
+
+> 数据组装代码：
+> - C102-1：`HcsProjectSyncSupport#addProject` / `buildFormData`（blade-service/blade-transport/.../support/hcs/HcsProjectSyncSupport.java）
+> - C103-1：`HcsContractSyncSupport#draftContract` / `buildDraftParam`（blade-service/blade-transport/.../support/hcs/HcsContractSyncSupport.java）
+>
+> 触发链路：审批通过（approved）自动即时推送，扫描任务兜底；页面"推送合规/重推"按钮可手动触发。
+>
+> 必填标记图例：✅必填（HCS 接口文档 required）｜⚠️TMS必传（文档未强校验，TMS 业务必传）｜选填｜固定（代码写死）｜不传
+
+---
+
+## 一、C102-1 项目立项新建
+
+数据源：**项目立项单页面**（ProjectApply / blade_project_apply），整单审批通过后推送。
+
+### 1. 表头固定项（非页面字段）
+
+| HCS 入参 | 取值 | 页面字段 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| bpmOperation | 流程操作节点 | — | ✅ | 节点整体必填 |
+| bpmOperation.operationType | `drafter_submit` | — | ✅ | 固定，以起草人身份直接提交 |
+| bpmOperation.templateCode | 配置 `thirdParty.hcs.project.template-code` | — | ✅ | 立项表单模板编码，未配置直接失败 |
+| checkAuth | `false` | — | 选填 | 固定 |
+| curUser.fdLoginName | 经办人登录名 | 经办人 handlerUserId | ✅ | ⚠️ 当前代码临时写死 `srvadmin`（requireLoginName 内原逻辑被注释，联调需恢复） |
+| formData | 表单数据节点 | — | ✅ | 节点整体必填 |
+| saveOption.saveDraft | `false` | — | ✅ | 固定，直接提交 |
+
+### 2. 表单业务字段（formData.dynamicProps）
+
+HCS 文档 required 仅列：`fd_pro_name`、`fd_is_available`、`fd_sources`；其余为选填。
+
+| HCS 字段 | HCS 含义 | 页面字段（ProjectApply） | 必填 | 取值 / 转换规则 |
+| --- | --- | --- | --- | --- |
+| fd_pro_name | 项目名称 | 项目名称 projectName | ✅ | 原值 |
+| fd_pro_simple_name | 项目简称 | 项目简称 projectShortName | 选填 | 原值 |
+| fd_num | 项目编号 | 项目编号 projectCode | ⚠️TMS必传 | 原值；HCS 文档未列 required，但为 C102-3 判重键，TMS 侧必传 |
+| fd_creator_unit | 创建单位 | —（无页面字段） | 选填 | 固定取配置 `creator-unit-id/name`；任一未配置时回退"开题部门名称 businessDeptName"仅传 fdName |
+| fd_head | 项目负责人 | 负责人 principalUserId | 选填 | 按用户ID查登录名，传 `{fdLoginName: 登录名}` |
+| fd_taker_dept | 承接部门 | 承接部门 undertakeDeptName | 选填 | 传部门名称 |
+| fd_taker | 承接人 | 经办人 handlerUserId | 选填 | 登录名 `{fdLoginName}` |
+| fd_pay_limit | 付款额度 | 付款额度（万元） fundLimit | 选填 | × 10000 换算为元 |
+| fd_out_invoice_limit | 开票额度 | 开票额度（万元） receivableLimit | 选填 | × 10000 换算为元 |
+| fd_pro_content | 项目建设内容 | 项目建设内容/情况说明 situationRemark | 选填 | 原值 |
+| fd_settlement_type | 结算类型 | 结算方式 settlementMode | 选填 | 字典原值直传（字典映射待联调 §9-U3） |
+| fd_pro_plan_deposit | 计划保证金 | 资金需求（万元） fundDemand | 选填 | × 10000 换算为元 |
+| fd_is_available | 是否可用 | — | ✅ | 固定 `true` |
+| fd_avail_units | 可用单位列表 | — | 选填 | 与创建单位一致（同走 creator-unit 配置） |
+| fd_is_self_pro | 是否自营项目 | — | 选填 | 固定 `"1"`（联调确认） |
+| fd_kingdee_sync_status | 金蝶同步状态 | — | 选填 | 固定 `"1"` |
+| fd_sources | 来源标识 | — | ✅ | 配置 `src-system`（约定值 WLTMS） |
+| fd_kingdee_id | 来源系统主键 | — | 选填 | TMS 立项单主键 id（对账/幂等候选键） |
+| fd_creator | 创建人 | 经办人 handlerUserId | 选填 | 登录名（扫描推送无登录上下文，取单据承办人） |
+| fd_pro_income_goal | 项目收入目标 | — | 不传 | TMS 无对应字段，一期不传 |
+
+---
+
+## 二、C103-1 合同发起（合同新建）
+
+数据源：**合同新建页面**（ContractManage / blade_contract_manage），合同审批通过后推送。
+推送前置：① 客商风险校验（C101-1，甲乙双方）→ ② 附件转传（C103-2，仅缓存不挂载）→ ③ 判重（C103-3）→ ④ C103-1 发起。
+
+### 1. 顶层字段
+
+HCS 文档 required：`fdTemplateId`、`fdOuterSystem`、`fdLoginName`、`saveType`、`fdFieldJson` 全部必填。
+
+| HCS 入参 | HCS 含义 | 页面字段（ContractManage） | 必填 | 取值 / 转换规则 |
+| --- | --- | --- | --- | --- |
+| fdTemplateId | 合同模板ID | 合同类别 contractCategory | ✅ | 经配置 `contract.template-mapping[合同类别]` 映射为 HCS 模板ID（§9-U7），未配置直接失败 |
+| fdOuterSystem | 外部系统标识 | — | ✅ | 配置 `src-system`（WLTMS） |
+| fdLoginName | 操作人登录名 | 经办人 handlerUserId | ✅ | 按用户ID查登录名（§9-U2），解析不到直接失败 |
+| saveType | 保存类型 | — | ✅ | 固定 `submit` |
+| fdFieldJson | 合同字段节点 | — | ✅ | 节点整体必填（内含 xformFields + signer） |
+
+### 2. xformFields 模板字段
+
+HCS 文档未对 xformFields 单项列 required；下表"✅"为 TMS 按合同模板必填项标注（缺失会被 HCS 模板校验拦截）。
+
+| HCS 字段 | HCS 含义 | 页面字段（ContractManage） | 必填 | 取值 / 转换规则 |
+| --- | --- | --- | --- | --- |
+| fdNumber / CONTRACT_NO | 合同编号 | 合同编号 contractNo | ✅ | 原值（双字段同值传） |
+| fdSubject | 合同标题 | 合同名称 contractName | ✅ | 原值 |
+| CONTRACT_NAME | 合同名称 | 合同名称 contractName | 选填 | 原值（与 fdSubject 同值） |
+| fdAmount / AMOUNT | 合同金额 | 合同金额 contractAmount | ✅ | 原值，字符串传值（双字段同值传） |
+| fdCurrencyId / CURRENCY | 币种 | 结算币种 settlementCurrency | 选填 | 经 `currency-name-mapping` 映射（默认 RMB→人民币），未命中传原值 |
+| fdSettlementType | 合同结算类型 | 结算方式 settlementMode | 选填 | 经 `settlement-type-mapping` 映射（付款/收款，待联调 §9-U3），未配置不传 |
+| fdSepcailContract | 特批流程 | — | 选填 | 固定 `false`（配置项预留，原文拼写笔误必须沿用） |
+| CONTRACT_TYPE | 合同类型 | 合同类别 contractCategory | 选填 | 字典原值 |
+| PARTY_A | 甲方名称 | 甲方 partyA | 选填 | 名称原值 |
+| PARTY_B | 乙方名称 | 乙方 partyB | 选填 | 名称原值 |
+| SIGN_DATE | 签订日期 | 签订日期 signDate | ✅ | `yyyy-MM-dd`，fdType=timestamp |
+| fdEstimateStartTime | 预计开始时间 | 开始日期 startDate | 选填 | fdType=timestamp |
+| fdEstimateEndTime | 预计结束时间 | 结束日期 endDate | 选填 | fdType=timestamp |
+| CREATE_TIME / fdCreateTime | 创建时间 | —（系统字段 createTime） | 选填 | `yyyy-MM-dd HH:mm:ss`，fdType=timestamp |
+| fd_syn_time | 同步时间 | — | 选填 | 推送时刻 |
+| CREATE_USER_NAME | 承办人名称 | 经办人 handlerUserName | 选填 | 名称原值 |
+
+### 3. signer 相对方（签署方）
+
+HCS 文档未对 signer 单项列 required，均按选填处理；TMS 固定传甲、乙两方。
+
+| HCS 字段 | 甲方 | 乙方 | 必填 |
+| --- | --- | --- | --- |
+| fdStanding | `甲` | `乙` | 选填（TMS 固定传） |
+| fdName | 页面"甲方" partyA | 页面"乙方" partyB | 选填（TMS 必传，业务标识） |
+| fdNumber | 按甲方名称反查客商档案 CustomerArchive.customerCode（全称/简称匹配） | 按乙方名称反查 | 选填（反查不到留空，§9-U6） |
+| fdType | — | — | 不传（inner/外部判定规则待联调 §9-U6） |
+
+### 4. 不传项说明
+
+| HCS 字段 | 原因 |
+| --- | --- |
+| CONTRACT_STATUS 合同状态 | TMS 无直接对应，一期不传（是否必传待联调 §9-U3） |
+| 附件字段 | C103-1 入参未定义附件字段；附件已先经 C103-2 转传并缓存合规ID，挂载方式待合规方确认（§9-U8） |
+
+---
+
+## 三、必填项汇总（推送前自检清单）
+
+**C102-1 必填**：templateCode（配置）、curUser.fdLoginName、fd_pro_name（页面：项目名称）、fd_is_available（固定）、fd_sources（配置）；fd_num 建议按必传对待（判重键）。
+
+**C103-1 必填**：fdTemplateId（页面：合同类别 → template-mapping 必须有映射）、fdOuterSystem（配置）、fdLoginName（页面：经办人，必须能解析登录名）、saveType（固定）、fdFieldJson；模板字段中合同编号（fdNumber）、合同标题（fdSubject）、合同金额（fdAmount）、签订日期（SIGN_DATE）按模板必填传。
+
+## 四、两个接口取值差异速览
+
+| 维度 | C102-1 项目立项 | C103-1 合同 |
+| --- | --- | --- |
+| 页面数据源 | 项目立项单 ProjectApply | 合同单 ContractManage |
+| 金额单位换算 | 万元 × 10000 转元（付款/开票额度、资金需求） | 原值字符串直传（合同金额） |
+| 字典/映射 | 结算方式原值直传 | 合同类别→模板ID、币种→名称映射、结算方式→结算类型映射 |
+| 人员取值 | 负责人/经办人 → 登录名（fdLoginName 结构） | 经办人 → 登录名（顶层 fdLoginName）+ 经办人名称原值 |
+| 相对方 | 无 | 甲乙方名称 + 反查客商编号 |
+| 操作人 curUser | ⚠️ 临时写死 srvadmin | 承办人真实登录名（解析不到直接失败） |
+| 必填校验 | required 集中在表头 + 3 个业务字段 | 顶层 5 项全部必填，模板字段按模板校验 |