📝 更新收票推送金蝶与票池选票业务流程文档，新增收票单推送全链路文档

doc/docs/业务流程/2026-09-17-客商档案同步金蝶（A902-1查询回填+A902-2审批推送）技术文档.md

@@ -57,7 +57,7 @@ TMS 新增客商，录入统一社会信用代码
 | --- | --- | --- | --- |
 | `none` | 未推送 | 新增客商默认值 | 审批通过后参与推送 |
 | `exist` | 金蝶已有档案 | A902-1 查到状态=已审核(C) | 审批通过后跳过推送（终态） |
-| `synced` | 已推送成功 | A902-2 返回成功，回写金蝶客户编码 | 终态，重推时幂等跳过 |
+| `synced` | 已推送成功 | A902-2 返回成功，回写金蝶客户编码 | 金蝶受理（status=B），A902-1 复查 status=C 已审核才是最终成功；定时任务每轮复查审核状态，审核中不重推（避免金蝶侧重复），重推时幂等跳过 |
 | `failed` | 推送失败 / 金蝶审核中 | A902-2 失败，或复查到 A/B 状态 | 列表「同步金蝶」按钮重推 |
 
 ### 2.3 前端查询回填时序（新增态）
@@ -302,5 +302,6 @@ VALUES (2075431800000000001, {客商档案菜单id}, 'customer_archive_sync', '
 - 2026-09-17（第八轮调整）：`nature_of_client` 字典重构为 dictKey 即金蝶伙伴类型编码（8 我区国企/国企控股、7 非我区国企/国企控股、6 民企/民企控股、12 三资企业、17 集体企业、5 个体），录入时按编码规范选择性质，推送侧 `resolvePartnerType` 直接取 dictKey 推送（1~17 校验，非法/为空/存量文本值兜底 `6`）；删除信用代码前缀转换与文本映射表及 `CustomerBfiConstants` 中相关常量。`mvn clean compile` 通过。
 - 2026-09-17（第九轮调整）：伙伴类型取消兜底，`resolvePartnerType` 在客商性质 dictKey 为空或非有效编码（1~17）时抛 `ServiceException`，由 `syncKingdee` 推送环节捕获置 `failed` 并记录原因，修正数据后可重推；删除 `DEFAULT_PARTNER_TYPE` 常量。`mvn clean compile` 通过。
 - 2026-09-20（第十轮调整）：移除 `customer.createOrg` 配置项，`createorg_number` 固定传 `CustomerBfiConstants.CUSTOMER_CREATE_ORG`（WLTMS），`BfiProperties` 删除 customer 节点，仓库与 Nacos（blade-dev）配置同步移除。前端修复：统一社会信用代码查询去除同码去重守卫（原 `kingdeeQueriedCode` 拦截导致改回历史代码不再触发 A902-1 查询），代码一经变化即防抖重新查询。`mvn clean compile` 与 `pnpm run build` 通过。
+- 2026-09-20（第十一轮调整）：定时同步 `syncKingdeeCustomerData` 增加 ③ 已推送（synced）客商的金蝶审核确认——A902-2 成功仅代表金蝶受理（status=B），按信用代码 A902-1 批量复查，status=C 已审核才记为最终成功，A/B 审核中保持 synced 等待下轮复查（不重推，避免金蝶侧重复建档），汇总文案与日志体现「金蝶已审核/审核中/未查询到」统计；`CustomerArchiveServiceImpl` 常量补充 Javadoc，新增 `@SpringBootTest` 手动触发测试类 `CustomerArchiveSyncKingdeeDataTest`（pom 补 `spring-boot-starter-test`），Controller 不加测试端点。`mvn clean compile` 与 `test-compile` 通过。
 - 待人工执行：`doc/sql/transport/blade_customer_archive_kingdee_20260917.sql`（含「同步金蝶」按钮菜单 INSERT）；与财务核对客商性质映射键与 `createorg_number` 取值。
 - 2026-09-17（第三轮新增定时任务）：新增 `task/CustomerKingdeeSyncTask`（仿 `PaymentKingdeeResultTask`，开关 `thirdParty.bfi.customer.syncEnabled` 默认关闭、cron `thirdParty.bfi.customer.cron` 默认每天 02:00）与 `ICustomerArchiveService.syncKingdeeCustomerData()`：① 待推送客商（approved 且 none/failed）复用 `syncKingdee` 自动推送（自代理逐条独立事务，单条失败不中断）；② 已同步客商（synced/exist）按信用代码分批（50/批）A902-1 查询，金蝶禁用（enable=0）联动停用客商档案并记变更，金蝶恢复可用不自动启用。A901-1 供应商查询仍待 SDK 提供能力后扩展。`mvn clean compile` 通过。

doc/docs/业务流程/2026-09-20-应付单与付款申请同步金蝶全链路业务流程（A102-2保存-A102-4查询-A103-1下推-A103-2回写）.md

@@ -4,7 +4,7 @@
 > 对接系统：金蝶云·星瀚（业财融合 BFI，经 iPaaS 网关）
 > 覆盖接口：A102-2 财务应付单保存、A102-4 财务应付单查询、A103-1 付款申请保存（应付下推）、A103-2 付款申请单查询
 > 关联文档：`2026-09-18-付款管理金蝶同步全链路逻辑梳理（推送链路与回写链路连贯性）.md`、`2026-09-16-付款管理正式付款同步金蝶（财务应付单+付款申请下推）技术文档.md`、`2026-09-17-付款管理金蝶付款结果定时回写（A103-2付款申请单查询+A103-4付款处理查询）技术文档.md`
-> 最后更新：2026-09-20（按当前代码重新梳理：A102-2 已由正式结算单页面触发推送）
+> 最后更新：2026-09-20（按当前代码重新梳理：A102-2 已由正式结算单页面触发推送；接口入参来源及对应前端字段直接内嵌在各环节业务流程步骤中）
 
 ---
 
@@ -61,50 +61,67 @@
    - 结算明细对应应付明细必须存在货物费用行（取数必须来自应付费用明细，无兜底）；
    - 货物类型必须在货物类型档案中维护货物编码（多种货物类型以「、/，」分隔时不拆行，取第一种类型）；
    - 运费计算单位不能为空（优先快照运费计算单位，兜底数量单位；计量单位档案暂无编码字段，暂以单位名称作编码）。
-5. A102-4 幂等预检：按防重键查询金蝶是否已生成财务应付单。
-   - **已生成** → 幂等跳过保存，直接取已有单据编号（说明上次同步已保存成功、在后续环节中断）；
-   - **未生成** → 调用 A102-2 保存。
-6. 落库回写正式结算单：金蝶单据编号（A102-2 返回的应付单编号）、同步状态 = synced、同步时间。应付单内部 id 不落库。
+5. **A102-4 财务应付单查询**：按防重键查询金蝶是否已生成财务应付单。
+   
+   - **已生成** → 幂等跳过保存，直接取已有单据编号进入第 7 步（说明上次同步已保存成功、在后续环节中断）；
+- **未生成** → 进入第 6 步调用 A102-2 保存。
+   
+A102-4 入参来源：
+   
+   | 接口字段 | 含义 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- |
+   | awrp_src_code | 外部系统来源单据号（支持多值） | 第 3 步组装的财务应付单防重键：正式结算单号_结算明细单据号拼接 | 系统组装：正式结算单页面「结算单号」formalSettlementNo + 结算明细「单据号」documentNo（`formal-settlement.vue` / `formalSettlementTable.js`） |
+   | awrp_src_sys | 外部系统编号 | 配置项 thirdParty.bfi.srcSys，默认 WLTMS | 无（后端配置，前端不出现） |
+| pageNo / pageSize | 分页 | 自动翻页（页大小 200，最大 50 页保护） | 无（系统生成） |
+   
+A102-4 返回取用：`billno` 单据编号（预检命中时即结算单回写的金蝶单据编号）；`planentity[].awrp_entry_code_p` 付款计划分录标识（环节二 A103-1 勾稽关联用）。
+   
+6. **A102-2 财务应付单保存**。
 
-### 3.2 A102-2 入参来源
+   A102-2 主表入参来源：
 
-主表：
+   | 接口字段 | 含义 | 必填 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- | --- |
+   | billtypeid_number | 单据类型.编码 | 是 | 常量默认名称「服务采购应付」经单据类型映射字典转为编码 `ApFin_service_BT_S` | 无（后端常量） |
+   | org_number | 结算组织.编码 | 是 | 合同所属组织：合同.organizationId → 部门编码（未维护报错） | 合同管理页面「所属组织」organizationId/organizationName（`contract-manage.vue`）；部门编码 deptCode 在系统部门管理维护 |
+   | bizdate | 单据日期 | 是 | 同步当日（格式 yyyy-MM-dd HH:mm:ss） | 无（系统生成） |
+   | asstacttype | 往来类型 | 是 | 按合同类别路由：合同类别=「客户合同」→ bd_customer（客户），否则 bd_supplier（供应商） | 合同管理页面「合同类别」contractCategory（下拉字典） |
+   | asstact_number | 往来户.编码 | 是 | 合同乙方 → 客商档案按全称/简称匹配取客商编码（乙方为空或未维护客商编码均报错） | 合同管理页面「乙方」partyB（下拉选择）→ 客商档案页面「客商编号」customerCode（按客商全称/简称匹配，`customer-archive.vue`） |
+   | purmode | 付款方式 | 是 | 常量 CASH（现购，金蝶自动 100% 推付款） | 无（后端常量） |
+   | currency_number | 结算币别.货币代码 | 是 | 合同结算币种，RMB 统一映射 CNY（为空报错） | 合同管理页面「结算币种」settlementCurrency（下拉选择） |
+   | payorg_number | 付款组织.编码 | 是 | 同结算组织编码 | 同 org_number |
+   | payproperty_number | 款项性质.编码 | 是 | 常量 2001（待金蝶确认） | 无（后端常量） |
+   | isincludetax / ispricetotal / isintax | 录入含税价/录入总价/是否含税 | 否 | 固定 true / true / false（录入总价免单价换算） | 无（后端常量） |
+   | awrp_src_sys | 外部系统编号 | 是 | 配置项，默认 WLTMS（应付单防重键之一） | 无（后端配置） |
+   | awrp_src_code | 外部系统来源单据号 | 是 | 第 3 步组装的防重键：正式结算单号_结算明细单据号拼接 | 系统组装：正式结算单页面「结算单号」formalSettlementNo + 结算明细「单据号」documentNo |
+   | awrp_src_type | 外部单据类型 | 是 | 常量「TMS财务应付单」（待金蝶确认） | 无（后端常量） |
 
-| 接口字段 | 含义 | 必填 | 来源 |
-| --- | --- | --- | --- |
-| billtypeid_number | 单据类型.编码 | 是 | 常量默认名称「服务采购应付」经单据类型映射字典转为编码 `ApFin_service_BT_S` |
-| org_number | 结算组织.编码 | 是 | 合同所属组织：合同.organizationId → 部门编码（未维护报错） |
-| bizdate | 单据日期 | 是 | 同步当日（格式 yyyy-MM-dd HH:mm:ss） |
-| asstacttype | 往来类型 | 是 | 按合同类别路由：合同类别=「客户合同」→ bd_customer（客户），否则 bd_supplier（供应商） |
-| asstact_number | 往来户.编码 | 是 | 合同乙方 → 客商档案按全称/简称匹配取客商编码（乙方为空或未维护客商编码均报错） |
-| purmode | 付款方式 | 是 | 常量 CASH（现购，金蝶自动 100% 推付款） |
-| currency_number | 结算币别.货币代码 | 是 | 合同结算币种，RMB 统一映射 CNY（为空报错） |
-| payorg_number | 付款组织.编码 | 是 | 同结算组织编码 |
-| payproperty_number | 款项性质.编码 | 是 | 常量 2001（待金蝶确认） |
-| isincludetax / ispricetotal / isintax | 录入含税价/录入总价/是否含税 | 否 | 固定 true / true / false（录入总价免单价换算） |
-| awrp_src_sys | 外部系统编号 | 是 | 配置项，默认 WLTMS（应付单防重键之一） |
-| awrp_src_code | 外部系统来源单据号 | 是 | 防重键：正式结算单号_结算明细单据号拼接 |
-| awrp_src_type | 外部单据类型 | 是 | 常量「TMS财务应付单」（待金蝶确认） |
+   A102-2 明细分录（detailentry，每条应付货物费用行一条）入参来源：
 
-明细分录（detailentry，每条应付货物费用行一条）：
+   | 接口字段 | 含义 | 必填 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- | --- |
+   | material_number | 物料编码.编码 | 是 | 货物类型 → 货物类型档案货物编码；**联调期临时固定传金蝶测试档案值 SP0324** | 应收应付明细页面「货物类型」cargoType（支持「、/，」多类型取第一种）→ 基础数据-货物类型页面「货物类型编码」cargoCode（`cargo-type.vue`） |
+   | measureunit_number | 计量单位.编码 | 是 | 快照运费计算单位（兜底数量单位）；**联调期临时固定传 TON** | 应收应付明细页面「运费计算单位」priceUnit（历史快照兜底数量单位 quantityUnit；计量单位档案暂无编码字段暂传单位名称） |
+   | quantity | 数量 | 是 | 该行运输数量，无吨位兜底 1 | 应收应付明细页面「运输总量」transportQuantity |
+   | price | 单价 | 否 | 费用明细运输单价（单据头录入总价，单价仅参考） | 应收应付明细页面「运输单价」unitPrice |
+   | e_pricetaxtotal | 应付金额（含税） | 是 | 该费用行调整后总金额（含税） | 应收应付明细页面「调整后金额」afterAmount（含调整金额 adjustAmount 调整） |
+   | e_amount | 金额（不含税） | 否 | 结算货物费用行不含税金额（应付费用行无不含税字段，经结算费用行回链；无映射兜底 0） | 正式结算明细「结算金额（不含税）」settlementAmountNoTax（`formalSettlementTable.js`） |
+   | project_number | 项目.项目编码 | 是 | **联调期临时固定传金蝶测试档案值 999**（真实取值：项目档案项目编码，无项目传 999） | 联调期无；真实来源=项目申请页面「项目编号」projectCode（`project-apply.js`） |
+   | awrp_entry_code | 外部系统来源分录标识 | 是 | 应付货物费用行 id（雪花 id 天然唯一）；A103-1 的 awrp_entry_code 与之对应 | 无（系统生成，前端不出现） |
+
+   付款计划（planentity）暂不传：由金蝶按明细自动汇总生成，其付款计划分录标识（awrp_entry_code_p）后续经 A102-4 反查。
+
+7. 返回与落库：
+   - 成功：返回 `result[0].number`（金蝶应付单编号）→ 写入正式结算单金蝶单据编号，同步状态 = synced，记录同步时间；`result[0].id` 为星瀚内部主键，不落库。
+   - 失败：金蝶单据级失败以 errors 明细抛出业务异常，本次同步失败（结算单同步状态保持原值，可重新触发）。
+
+### 3.2 最终金蝶数据
+
+![image-20260920114138689](F:\workspace\work\xdwl\dev\tms\tms-api\doc\docs\业务流程\2026-09-20-应付单与付款申请同步金蝶全链路业务流程（A102-2保存-A102-4查询-A103-1下推-A103-2回写）.assets\image-20260920114138689.png)
 
-| 接口字段 | 含义 | 必填 | 来源 |
-| --- | --- | --- | --- |
-| material_number | 物料编码.编码 | 是 | 货物类型 → 货物类型档案货物编码；**联调期临时固定传金蝶测试档案值 SP0324** |
-| measureunit_number | 计量单位.编码 | 是 | 快照运费计算单位（兜底数量单位）；**联调期临时固定传 TON** |
-| quantity | 数量 | 是 | 该行运输数量，无吨位兜底 1 |
-| price | 单价 | 否 | 费用明细运输单价（单据头录入总价，单价仅参考） |
-| e_pricetaxtotal | 应付金额（含税） | 是 | 该费用行调整后总金额（含税） |
-| e_amount | 金额（不含税） | 否 | 结算货物费用行不含税金额（应付费用行无不含税字段，经结算费用行回链；无映射兜底 0） |
-| project_number | 项目.项目编码 | 是 | **联调期临时固定传金蝶测试档案值 999**（真实取值：项目档案项目编码，无项目传 999） |
-| awrp_entry_code | 外部系统来源分录标识 | 是 | 应付货物费用行 id（雪花 id 天然唯一）；A103-1 的 awrp_entry_code 与之对应 |
 
-付款计划（planentity）暂不传：由金蝶按明细自动汇总生成，其付款计划分录标识（awrp_entry_code_p）后续经 A102-4 反查。
 
-### 3.3 返回与落库
 
-- 成功：返回 `result[0].number`（金蝶应付单编号）→ 写入正式结算单金蝶单据编号；`result[0].id` 为星瀚内部主键，不落库。
-- 失败：金蝶单据级失败以 errors 明细抛出业务异常，本次同步失败（结算单同步状态保持原值，可重新触发）。
 
 ---
 
@@ -113,57 +130,67 @@
 ### 4.1 业务流程
 
 1. 操作入口：付款管理页面勾选记录点「批量同步」（也支持单笔同步接口）；权限码 `payment_application_sync`。
+
 2. 批量语义：
    - 逐单独立事务：**单条失败不中断整批**，失败单据落「生成失败（failed）」状态并返回失败原因；
    - 整批共享档案缓存（合同/客商/货物类型/结算明细等），首单加载后全批复用；
-   - 批量开始前整批一次 A102-4 批量查询（每批最多 50 个防重键），预热应付单是否已生成的缓存，消除逐单远程查询。
+   - 批量开始前整批一次 A102-4 批量查询（每批最多 50 个防重键，入参来源同环节一第 5 步：防重键 + WLTMS + 自动翻页），预热应付单是否已生成的缓存，消除逐单远程查询。
+   
 3. 前置状态校验（逐单，不满足不调金蝶）：
    - 审批状态必须是 **审批通过（approved）**；
    - 金蝶同步状态为 **synced / paying / paid / closed** 的幂等跳过，直接返回已有金蝶单据 id，不重复推送；
    - 付款类型为**结算付款（settlement_payment）** 走本链路；预付款（project_advance / progress_advance）走 A103-3 直推，不在本文范围。
-4. 结算付款链路逐步动作：
-   1. **结算类型路由**：关联正式结算单结算类型为应收（receivable）时拦截报错（A302-2 未启用）；聚合多结算单场景暂按应付处理。
-   2. **应付单已生成前置校验（A102-4）**：按每张关联正式结算单的防重键查询，任一应付单未生成则报错提示「请先在正式付款单页面同步金蝶」——即环节一未完成时环节二不允许执行。
-   3. **A103-2 幂等预检（恢复勾稽）**：按付款申请号查询金蝶付款申请单是否已生成（防上次下推成功但本地回滚的断链场景）。已生成 → 直接回填单据 id 与编号，视为同步成功，跳过下推。
-   4. **解析付款申请分录**：与环节一应付单明细分录同源（逐条应付货物费用行一条，含校验项相同）。
-   5. **A103-1 应付下推**：每条分录先经 A102-4 按所属结算单防重键反查金蝶生成的付款计划分录标识（awrp_entry_code_p，同一结算单只反查一次），用于分录勾稽关联。
-   6. **落库**：金蝶单据 id（星瀚付款申请单内部主键）、金蝶单据编号（下推返回的单据编号，立即可见）、同步状态 = synced。
-5. 失败处理：任一步异常 → 单据事务回滚，独立事务落「生成失败（failed）」（仅审批通过单据生效），返回原因（含金蝶 errors 明细）。failed 单据可重新勾选同步，从断点续传。
+   
+4. **结算类型路由 + 应付单已生成校验（A102-4）**：关联正式结算单结算类型为应收（receivable）时拦截报错（A302-2 未启用）；随后按每张关联正式结算单的防重键调 A102-4 校验应付单已生成，任一未生成都报错提示「请先在正式付款单页面同步金蝶」——即环节一未完成时环节二不允许执行。
 
-### 4.2 A103-1 入参来源
+5. **A103-2 幂等预检（恢复勾稽）**：按付款申请号查询金蝶付款申请单是否已生成（防上次下推成功但本地回滚的断链场景）。已生成 → 直接回填单据 id 与编号，视为同步成功，跳过下推进第 8 步；未生成 → 继续。
 
-主表：
+   A103-2 入参来源（幂等预检）：
 
-| 接口字段 | 含义 | 必填 | 来源 |
-| --- | --- | --- | --- |
-| awrp_src_code | 外部系统来源单据号 | 是 | 付款申请号（付款申请单防重键） |
-| awrp_src_sys | 外部系统编号 | 是 | 配置项，默认 WLTMS |
-| applydate | 申请日期 | 是 | 付款申请申请日期（空取当天，格式 yyyy-MM-dd HH:mm:ss） |
+   | 接口字段 | 含义 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- |
+   | awrp_src_code | 外部系统来源单据号（支持多值） | 付款申请号 paymentNo（付款申请单防重键） | 付款管理列表「单据号」paymentNo（系统生成，`payment-application.vue`） |
+   | awrp_src_sys | 外部系统编号 | 配置项 thirdParty.bfi.srcSys，默认 WLTMS | 无（后端配置） |
+   | pageNo / pageSize | 分页 | 自动翻页（页大小 200，最大 50 页保护） | 无（系统生成） |
 
-其余主表字段（付款组织、采购组织、请款事由、汇率、付款渠道、申请人等）当前不传，由金蝶根据应付单自动带出。
+   取数规则：查询结果按来源单号归并，同一单号取最近修改（modifytime 最大）的一条；查到 `id`/`billno` 即回填并视为已生成。
 
-分录（entry，与应付单明细分录一一对应）：
+6. **解析付款申请分录**：与环节一应付单明细分录同源（逐条应付货物费用行一条，校验项相同）。
 
-| 接口字段 | 含义 | 必填 | 来源 |
-| --- | --- | --- | --- |
-| e_paymenttype_number | 付款类型.编码 | 是 | 常量 201（正式付款） |
-| awrp_finapbill_entryid | 结算单分录id（勾稽键） | 是 | 经 A102-4 反查该分录所属正式结算单应付单的付款计划分录标识 awrp_entry_code_p |
-| awrp_entry_code | 对方系统唯一行id（不能重复） | 是 | 应付货物费用行 id（与环节一应付单明细 awrp_entry_code 同源同值） |
-| e_assacct | 往来账户 | 是 | 付款申请收款账户（收款方银行账号） |
-| e_bebank_number | 往来银行.编码 | 是 | **联调期临时固定传金蝶测试档案值 001110012009**（待建立银行档案编码映射） |
-| e_applyamount | 申请金额 | 是 | 该分录应付金额（含税），与对应应付单分录一致 |
-| project_number | 项目.项目编码 | 是 | **联调期临时固定传 999** |
-| awrp_src_type | 外部单据类型 | 是 | 配置项（默认 0KzXs，待金蝶确认） |
+7. **A103-1 付款申请保存（应付下推）**：每条分录先经 A102-4 按所属结算单防重键反查金蝶生成的付款计划分录标识（awrp_entry_code_p，同一结算单只反查一次，入参来源同环节一第 5 步），用于分录勾稽关联。
 
-### 4.3 A103-2 幂等预检入参来源
+   A103-1 主表入参来源：
+
+   | 接口字段 | 含义 | 必填 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- | --- |
+   | awrp_src_code | 外部系统来源单据号 | 是 | 付款申请号 paymentNo（付款申请单防重键） | 付款管理列表「单据号」paymentNo（系统生成） |
+   | awrp_src_sys | 外部系统编号 | 是 | 配置项，默认 WLTMS | 无（后端配置） |
+   | applydate | 申请日期 | 是 | 付款申请申请日期（空取当天，格式 yyyy-MM-dd HH:mm:ss） | 付款申请表单「申请日期」applyDate（`payment-application-form.vue`，页面禁用、自动当天） |
+
+   其余主表字段（付款组织、采购组织、请款事由、汇率表、付款渠道、申请人等）当前不传，由金蝶根据应付单自动带出。
+
+   A103-1 分录（entry，与应付单明细分录一一对应）入参来源：
+
+   | 接口字段 | 含义 | 必填 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- | --- |
+   | e_paymenttype_number | 付款类型.编码 | 是 | 常量 201（正式付款） | 无（后端常量） |
+   | awrp_finapbill_entryid | 结算单分录id（勾稽键） | 是 | 经 A102-4 反查该分录所属正式结算单应付单的付款计划分录标识 awrp_entry_code_p | 无（系统反查，前端不出现） |
+   | awrp_entry_code | 对方系统唯一行id（不能重复） | 是 | 应付货物费用行 id（与环节一应付单明细 awrp_entry_code 同源同值） | 无（系统生成） |
+   | e_assacct | 往来账户 | 是 | 付款申请收款账户（收款方银行账号） | 付款申请表单「收款账号」：选择收款方收款账号 receiptAccountId，落库字段 bankAccount（只读展示为 form.bankAccount） |
+   | e_bebank_number | 往来银行.编码 | 是 | **联调期临时固定传金蝶测试档案值 001110012009**（待建立银行档案编码映射） | 联调期无；真实对应付款申请表单「开户银行」bankName（随收款账号带出、只读） |
+   | e_applyamount | 申请金额 | 是 | 该分录应付金额（含税），与对应应付单分录一致 | 应收应付明细页面「调整后金额」afterAmount（非付款申请表单「申请付款金额」appliedAmount，分录金额不按申请金额分摊） |
+   | project_number | 项目.项目编码 | 是 | **联调期临时固定传 999** | 联调期无；真实来源=付款申请表单「所属项目」projectId → 项目申请「项目编号」projectCode |
+   | awrp_src_type | 外部单据类型 | 是 | 配置项（默认 0KzXs，待金蝶确认） | 无（后端配置） |
+
+8. **落库**：金蝶单据 id（星瀚付款申请单内部主键）、金蝶单据编号（下推返回的单据编号，立即可见）、同步状态 = synced。
+
+9. 失败处理：任一步异常 → 单据事务回滚，独立事务落「生成失败（failed）」（仅审批通过单据生效），返回原因（含金蝶 errors 明细）。failed 单据可重新勾选同步，从断点续传。
+
+### 4.2 最终金蝶数据
+
+![image-20260920114206305](F:\workspace\work\xdwl\dev\tms\tms-api\doc\docs\业务流程\2026-09-20-应付单与付款申请同步金蝶全链路业务流程（A102-2保存-A102-4查询-A103-1下推-A103-2回写）.assets\image-20260920114206305.png)
 
-| 接口字段 | 含义 | 来源 |
-| --- | --- | --- |
-| awrp_src_code | 外部系统来源单据号（支持多值） | 付款申请号 |
-| awrp_src_sys | 外部系统编号 | 配置项 WLTMS |
-| pageNo / pageSize | 分页 | 自动翻页（页大小 200，最大 50 页保护） |
 
-查询结果按来源单号归并，同一单号取最近修改（modifytime 最大）的一条；查到 `id`/`billno` 即回填并视为已生成。
 
 ---
 
@@ -179,9 +206,18 @@
 
 1. 轮询范围（同时满足）：审批状态 = approved，且金蝶同步状态 ∈ {synced, paying, failed}。paid / closed 为终态不再轮询；failed 纳入勾稽——金蝶查到说明上次推送实际成功（如请求超时但远端已落单），自动纠偏回填，防止人工重推产生重复单据。
 2. 查询方式：按付款申请号分批（每批 50）调 A103-2，自动翻页；同一来源单号取最近修改一条。
+
+   A103-2 入参来源（定时回写）：
+
+   | 接口字段 | 含义 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- |
+   | awrp_src_code | 外部系统来源单据号（批量分批，每批 50，支持多值） | 待回写付款申请的付款申请号 paymentNo | 付款管理列表「单据号」paymentNo（系统生成） |
+   | awrp_src_sys | 外部系统编号 | 配置项 thirdParty.bfi.srcSys，默认 WLTMS | 无（后端配置） |
+   | pageNo / pageSize | 分页 | 自动翻页（页大小 200，最大 50 页保护） | 无（系统生成） |
+
 3. 回写内容（查到才更新，未查到状态不变）：
    - 金蝶单据编号 ← 返回 billno；金蝶单据 id ← 返回 id；
-   - 金蝶同步状态 ← 按「A103-2 状态映射」（见 6.2）；
+   - 金蝶同步状态 ← 按「A103-2 状态映射」（见 6.3）；
    - 已付金额 ← 分录已付金额（e_paidamt）汇总；分录缺失且已付款时兜底取申请金额。
 4. 付款完成（paid）联动：更新履约付款数据（预结算预付记录、正式结算付款记录）。
 
@@ -190,7 +226,16 @@
 1. 回填候选：
    - 本轮 A103-2 查到付款状态 ≠ Unpaid（已开始付款）的单据；
    - 已付款（paid）但尚无真实付款记录的单据（补偿轮询）。
-2. 查询方式：按**付款人（公司）编码**分组查询（编码优先取 A103-2 返回的付款组织编码，兜底按合同所属组织解析）；业务日期窗口固定最近 1 个月（接口限制）；自动翻页。
+2. 查询方式：按**付款人（公司）编码**分组查询；业务日期窗口固定最近 1 个月（接口限制）；自动翻页。
+
+   A103-4 入参来源：
+
+   | 接口字段 | 含义 | 来源 | 前端字段（来源页面） |
+   | --- | --- | --- | --- |
+   | org_number | 付款人（公司）编码（支持多值，按编码分组查询） | 优先 A103-2 返回的付款组织编码 payorg_number，兜底按合同所属组织解析部门编码 | 兜底来源=合同管理页面「所属组织」organizationId → 系统部门管理「部门编码」deptCode |
+   | begin_bizdate / end_bizdate | 业务日期窗口 | 最近 1 个月（接口限制不超过 1 个月），截止当天 | 无（系统生成） |
+   | pageNo / pageSize | 分页 | 自动翻页（页大小 200，最大 50 页保护） | 无（系统生成） |
+
 3. 勾稽匹配：付款处理单的源单 id = 本地金蝶单据 id 优先；源单编号 = 本地金蝶单据编号 兜底。
 4. 回填：按付款处理单号 upsert 付款记录——实际付款金额、付款日期、付款处理单整体 JSON 留档（凭证号、银行流水、电子回单等）；同时清理历史模拟（MOCK-PAY- 前缀）付款记录。
 

doc/docs/业务流程/2026-09-20-收票管理同步金蝶全票池发票（A801-1查询+批量同步+定时绑定关联）业务流程.md

@@ -4,6 +4,8 @@
 > 对接系统：金蝶发票云旗舰版·票易通（piaozone）全票池，经业财融合 BFI 网关（rim 契约）透传
 > 关联文档：`doc/docs/TMS业财融合-集成流程图文字版与业务流程梳理.md`（进项收票 A801-1 章节）、`2026-09-17-BFI分页查询通用翻页工具（BfiUtil-queryAllPages）技术文档.md`、`2026-09-17-付款管理金蝶付款结果定时回写（A103-2付款申请单查询+A103-4付款处理查询）技术文档.md`、`2026-09-17-客商档案同步金蝶（A902-1查询回填+A902-2审批推送）技术文档.md`
 > 最后更新：2026-09-20
+>
+> **⚠️ 退役声明（2026-09-22）**：本文档描述的**链路二（定时任务全量拉取、增量窗口、批量 upsert、定时绑定、漏绑补偿）及票种/客商税号双白名单、手动全量同步端点、按票号补查已全部退役删除**，选票改为实时查询 A801-1、镜像降级为登记存根（保存时单票重查落库），终态口径见 `2026-09-22-金蝶票池选票统一查镜像（收票登记+结算单认领+按票号补查+统一组件）业务流程.md`（已改写为实时查询版）。**仍然有效的部分**：链路一的手动逐单同步 `POST /invoice-receipt/sync-kingdee`（职责收敛为刷新已登记票的镜像行）、A801-1 契约与 `queryPoolByInvoiceNo` 单查口径、镜像表结构（含 `serial_no/buyer_tax_no/saler_tax_no/check_status` 等列，图05 推送链消费 `invoice_type_code/items_json`）。下文与退役链路相关的叙述保留作历史口径，不再代表现状。
 
 ---
 

doc/docs/业务流程/2026-09-22-收票单推送金蝶全链路业务流程（A303-2保存-A302-6指定应付-A801-3预检回写）.md

@@ -0,0 +1,197 @@
+# 收票单推送金蝶全链路业务流程（A303-2 收票单保存 → A302-6 收票指定应付 → A801-3 幂等预检与定时回写）
+
+> 适用系统：TMS（BladeX 微服务平台，服务：blade-transport）
+> 对接系统：金蝶云·星瀚（业财融合 BFI，经 iPaaS 网关 `/gwzh/BFI` 直连，不经过合同合规系统）
+> 覆盖接口：A303-2 收票单批量保存、A302-6 收票指定应付、A801-3 收票单查询、A102-4 财务应付单查询（预检）、A801-1 查询全票池发票数据（镜像明细回填）
+> 关联文档：`TMS业财融合-集成流程图文字版与业务流程梳理.md` 第 6 节（图05 定稿口径）、`2026-09-20-收票管理同步金蝶全票池发票（A801-1查询+批量同步+定时绑定关联）业务流程.md`（环节①镜像链路，本文档叠加其字段）、`2026-09-22-金蝶票池选票统一查镜像（收票登记+结算单认领+按票号补查+统一组件）业务流程.md`（选票统一查镜像）、`2026-09-21-应收结算与开票申请同步金蝶全链路业务流程….md`（销项侧对称链路）
+> 最后更新：2026-09-22（按当前代码梳理；已编码完成，未联调）
+
+---
+
+## 1. 整体业务链路
+
+图05「付款-收票查询及认领（进项收票）」分三个环节，环节①已建成，本文档覆盖环节②③：
+
+```
+环节①（已建成，不在本文）：票池镜像拉取 + 收票登记选票 + 审批 + 批量同步/定时绑定
+    A801-1 拉全票池入镜像 blade_kingdee_invoice_pool（票种白名单 + 购销双税号 AND 白名单）
+    → 收票登记查镜像选票（一票一登记）→ 审批通过 → 定时绑定回填 kingdeeInvoicePoolId/流水号
+
+环节②：收票登记「推送金蝶收票单」（人工批量，POST /invoice-receipt/push-kingdee）
+    前置校验（审批通过 + 已绑定镜像 + 查验通过 + 恰好分摊一张应付结算单）
+    → A102-4 预检关联财务应付单已在金蝶生成（缺则拦截"请先同步金蝶应付单"）
+    → A801-3 幂等预检（按发票号防重键，命中跳过保存续推指定）
+    → A303-2 收票单批量保存 → 回写金蝶收票单号 + pushed
+    → 立即 A302-6 收票指定应付（一票一应付）→ assigned（终态，锁单）
+
+环节③：PaymentKingdeeResultTask 第④子流程 定时回写（A801-3，独立开关，默认每10分钟）
+    金蝶侧红冲/作废/部分红冲/全部红冲 → 回收为 failed 提示人工（不自动作废登记）
+    pushed（保存成功后中断、指定未完成）→ 指定补偿重发 A302-6
+    assigned 仅补登缺失的金蝶收票单号（保存成功但响应丢失的历史数据）
+```
+
+核心设计原则（与付款/应收链路一致）：
+
+1. **先内后外**：收票登记先审批通过（approved）并绑定镜像才允许推送。
+2. **以金蝶侧实际生成为准**：每次推送前按防重键查询确认，已生成则幂等跳过保存、续推指定；推送接口真正报错才算失败。
+3. **断点续传**：任一环节中断后重新触发（人工重推或定时补偿），从断点恢复，不产生重复单据。
+4. **一票一应付**：金蝶当前不支持一张发票指定多张应付单分摊金额，收票登记分摊结算单数 ≠ 1 直接拦截（A302-6 按一对一指定）。
+5. **异常回收人工处置**：金蝶侧删除/解除指定/红冲 → 本地置 failed 提示人工，须先在金蝶处置完毕再由人工重推。
+
+---
+
+## 2. 五个接口在链路中的角色
+
+| 接口 | 名称 | 方向 | 触发环节 | 业务用途 |
+| --- | --- | --- | --- | --- |
+| A303-2 | 收票单批量保存 | TMS → 金蝶 | 环节② | 一张收票登记生成一张金蝶收票单（ap_invoice），票面明细逐行落分录 |
+| A302-6 | 收票指定应付 | TMS → 金蝶 | 环节② / 环节③补偿 | 按「收票单防重键 ↔ 财务应付单防重键」绑定（op=assign），一票一应付 |
+| A801-3 | 收票单查询 | TMS → 金蝶（查询） | 环节②前置 / 环节③ | 幂等预检 + 定时回写；契约无来源单号参数，按购方名称+修改时间窗口翻页、本地按防重键匹配 |
+| A102-4 | 财务应付单查询 | TMS → 金蝶（查询） | 环节②前置 | 校验关联结算单的财务应付单已在金蝶生成（付款侧 A102-2 同步的产物），缺则拦截 |
+| A801-1 | 查询全票池发票数据 | TMS → 金蝶（查询） | 环节②兜底 | 推送时镜像缺发票明细行/票种编码（早于字段上线或滑出增量窗口）按票号窄查回填 |
+
+合同侧履约收票同步（C107-1）开发中、本期不接；进项发票附件下载（A801-2）备用。
+
+---
+
+## 3. 环节②：推送金蝶收票单编排
+
+代码入口：`InvoiceReceiptController.pushKingdee` → `InvoiceReceiptServiceImpl.pushKingdeeReceivedInvoice(List<Long> ids)` → 逐单 `pushOneReceivedInvoice` → `KingdeeReceivedInvoiceSyncSupport`。
+
+### 3.1 前置校验（预组装计划，逐单报因不拦截整批）
+
+| # | 校验 | 拦截提示 |
+| --- | --- | --- |
+| 1 | 审批状态 = approved | 仅审批通过的收票登记允许推送金蝶 |
+| 2 | 推送状态 ≠ assigned | 收票单已指定应付，无需重复推送 |
+| 3 | 已绑定票池镜像（kingdeeInvoicePoolId 且镜像存在） | 收票登记未绑定票池镜像，请先完成同步绑定 |
+| 4 | 镜像查验状态 checkStatus ≠ 2（金蝶每5分钟查验） | 金蝶发票查验不通过，请先人工核实票池发票 |
+| 5 | 分摊结算单恰好 1 张（金蝶不支持多应付分摊） | 金蝶不支持一张发票指定多张应付单，收票登记须恰好分摊一张应付正式结算单 |
+| 6 | 分摊结算单为审批通过、未作废的应付正式结算单，且有结算明细 | 结算单不是审批通过的应付正式结算单 / 无结算明细，无法组装应付单防重键 |
+| 7 | A102-4 批量预检：财务应付单已生成（本批防重键一次查询） | 请先同步金蝶应付单：结算单 xxx 未生成财务应付单 |
+
+预检拦截（1~7）**不改动推送状态**；仅保存/指定阶段真正失败才置 failed。
+
+### 3.2 幂等预检与保存
+
+1. **A801-3 幂等预检**：未终态计划按购方单位（接口必填）分组，回看窗口（`thirdParty.bfi.receivedInvoice.queryWindowDays`，默认 30 天，金蝶约束 ≤1 个月）`BfiUtil.queryAllPages` 翻页，返回行按 `awrpSrcSys + awrpSrcCode(=发票号码)` 本地匹配，同键多行取修改时间最新。
+   - 命中且发票状态正常 → 跳过 A303-2 保存，取金蝶单号**续推指定**（上次保存成功、指定中断的断点恢复）；
+   - 命中但发票状态异常（作废2/红冲3/部分红冲7/全部红冲8）→ 置 failed 报人工，金蝶处置完毕重推；
+   - 未命中 → 执行保存。
+2. **镜像明细兜底回填**：镜像 `items_json` 或 `invoice_type_code` 为空（入镜像早于字段上线/滑出 30 天增量窗口）→ 按票号窄查 A801-1（`fetchMirrorItemsFromPool`，镜像入池时已过白名单，回填不再复检）补写镜像后再组装。
+3. **A303-2 保存**：`saveReceivedInvoice`（网关 body 为批量 data 数组，服务端当前单笔包装），成功取 `result[0].number` 即金蝶收票单号。
+
+### 3.3 A303-2 报文取数
+
+主表（联调口径：先只送 DTO 标注【必填】+ 票面核心字段，非必填 setter 注释保留）：
+
+| 字段 | 取数 |
+| --- | --- |
+| awrp_src_sys / awrp_src_code | `thirdParty.bfi.srcSys`（默认 WLTMS）/ **发票号码**（一票一登记天然唯一，重推同键幂等） |
+| invoiceno | 发票号码（非必填但为收票单核心字段，必送） |
+| receivedate / issuedate | 推送当日 / 镜像开票日期（yyyy-MM-dd HH:mm:ss） |
+| biztype | `PUR`（采购，**待金蝶确认**，常量 `KingdeeBfiConstant.BFI_RECEIVED_BIZ_TYPE`） |
+| invoicetypef7_number | 镜像 `invoice_type_code`（票易通原始编码 26/27，名称反查不可靠故新增此列） |
+| paymenttype / asstacttype | `CREDIT` 赊购（不让金蝶自动推付款）/ `bd_supplier` 供应商 |
+| org_number / currency_number | 分摊结算单关联合同的组织编码（部门编码）/ 结算币种（RMB→CNY），复用 `KingdeeApBillSyncSupport.bfiOrgNumber/bfiCurrency` |
+| receivablessupp_number | 合同乙方（开票供应商）客商档案编码，复用 `bfiAsstactNumber`（含编码缓存） |
+| exratetable_number / awrp_src_type | `01` / `TMS收票登记`（**待金蝶确认**） |
+| buyername / asstactname | 镜像受票单位 / 开票单位 |
+| isincludetax | true（录入价税合计） |
+| 销/购方税号、地址、电话、开户行账号 | 非必传，setter 注释保留（被金蝶强校验时从镜像 `saler_tax_no/buyer_tax_no/bank_name/bank_account/phone` 补齐，参照 A303-1 联调经验） |
+
+分录 entry（逐 A801-1 明细行展开，来源镜像 `items_json`）：
+
+| 字段 | 取数 |
+| --- | --- |
+| e_pricetaxtotal / e_amount / e_tax | 明细行 金额+税额 / 金额 / 税额（2 位小数） |
+| quantity / price | 票面数量（≤0 兜底 1）/ 票面单价 |
+| material_number | **联调临时值**，Nacos `thirdParty.bfi.receivedInvoice.materialNumber`（默认 SP0324，与应收/应付调试值同源，校准后移除） |
+| e_taxclass_number | 票面明细税收分类编码 goodsCode（缺失报错拦截） |
+| taxrateid_number | 票面税率（小数）换算金蝶税率编码：0.13→V13、0.01→V1、0→V0 |
+| awrp_entry_code | **发票号码-行号**（候选键） |
+
+### 3.4 A302-6 收票指定应付
+
+保存成功先落 `pushed`（断点可恢复），随后立即执行指定：`invoiceAssign(op=assign, data=[{ap_invoice:[{发票号码,srcSys}], ap_finapbill:[{应付单防重键,srcSys}]}])`。财务应付单防重键与付款侧同源：**正式结算单号_结算明细单据号下划线拼接**（`KingdeeApBillSyncSupport.apBillSrcCode`）。成功后置 `assigned` 终态并记同步流水；失败置 failed + 原因，人工重推（重推凭 3.2 幂等预检跳过保存、仅补指定）。
+
+---
+
+## 4. 状态机与锁单
+
+`blade_invoice_receipt.kingdee_push_status`（与票池绑定层 `kingdee_status` 语义分离，互不覆盖）：
+
+```
+unsynced（默认）──保存成功──▶ pushed ──指定成功──▶ assigned（终态，锁作废）
+     │                          │
+     └────保存/预检异常──────────┴──▶ failed ──人工处理后重推──▶（幂等续推）
+                                      ▲
+定时回写：金蝶红冲/作废/删除 ── pushed/assigned ──┘（异常回收）
+```
+
+| 状态 | 含义 | 允许操作 |
+| --- | --- | --- |
+| unsynced | 未推送 | 编辑（草稿态本不允许推送）、推送 |
+| pushed | 金蝶收票单已保存、指定未完成/未确认（瞬态，正常链路即被指定接管） | 推送（幂等续推）、定时指定补偿 |
+| assigned | 已指定应付，终态；金蝶侧生成收票单并锁定 | 仅定时回写轮询；**禁止作废**（锁单），金蝶异常回收获占 |
+| failed | 保存/指定失败或金蝶侧异常回收（红冲/作废/状态异常） | 人工在金蝶删除/解除指定后重推（同防重键幂等） |
+
+锁单防护：`voidBill` 在 pushed/assigned 时拦截「金蝶已生成收票单[xxx]，不允许作废；请先在金蝶删除收票单/解除指定」；编辑/删除仅草稿、驳回态（既有约束，推送不受影响）。金蝶侧删除/解除指定**不自动执行**（unassign 不启用），一律人工处置后重推。
+
+---
+
+## 5. 环节③：A801-3 定时回写
+
+代码入口：`PaymentKingdeeResultTask.syncKingdeeReceivedInvoiceResult`（独立开关 `thirdParty.bfi.receivedInvoiceResult.syncEnabled` 默认 false、`cron` 默认每10分钟）→ `InvoiceReceiptServiceImpl.syncKingdeeReceivedInvoiceResult`；联调可手动 `POST /invoice-receipt/sync-kingdee-result`。
+
+轮询对象：pushed/assigned 且非作废、已绑定镜像的收票登记；按镜像购方名称分组、回看窗口（`thirdParty.bfi.receivedInvoice.resultWindowDays`，默认 30 天）批量翻页匹配防重键。
+
+| 场景 | 处置 |
+| --- | --- |
+| 金蝶发票状态异常（作废/红冲/部分红冲/全部红冲） | → failed + 原因「已回收推送状态，请在金蝶删除/解除指定后重推」，不自动作废登记 |
+| pushed 且金蝶侧收票单正常 | 指定补偿：批量预组装应付单防重键后重发 A302-6 → assigned；分摊关系不满足一票一应付的置 failed 报人工 |
+| assigned 且本地缺金蝶收票单号 | 单号补登（保存成功但响应丢失的历史数据），不写流水 |
+| 窗口内查不到 | **不改状态**（金蝶修改时间延迟/滑窗不误判删除），由人工重推兜底 |
+
+---
+
+## 6. 防重键与幂等体系汇总
+
+| 单据/对象 | 防重键/幂等依据 | 使用接口 |
+| --- | --- | --- |
+| 金蝶收票单 | awrp_src_sys=WLTMS + awrp_src_code=**发票号码** | A303-2（保存候选键）/ A801-3（预检+回写本地匹配）/ A302-6（ap_invoice 引用） |
+| 收票单分录 | awrp_entry_code=发票号码-行号 | A303-2 |
+| 财务应付单（被指定方） | awrp_src_code=正式结算单号_结算明细单据号拼接（与 A102-2 同源） | A102-4 预检 / A302-6（ap_finapbill 引用） |
+| 票池镜像 | 唯一索引（tenant_id, invoice_no），票面指纹含新增 items_json/invoice_type_code | A801-1 upsert |
+| 收票登记 | 发票号码同租户唯一（一票一登记） | 登记层保证 |
+
+断点恢复：保存成功响应丢失 → 重推 A801-3 命中跳过保存；指定失败 → failed 重推仅补指定（幂等预检在位）；pushed 崩溃残留 → 定时指定补偿。
+
+---
+
+## 7. 数据前提与上线操作
+
+| # | 事项 | 说明 |
+| --- | --- | --- |
+| 1 | 变更 SQL | `doc/sql/transport/blade_invoice_receipt_kingdee_push_20260922.sql`（幂等可重复执行）：镜像表 `items_json`/`invoice_type_code`，收票登记表 `kingdee_received_invoice_no`/`kingdee_push_status`/`kingdee_push_msg`/`kingdee_push_time`。**执行后方可启动服务** |
+| 2 | Nacos 配置 | 任务开关 `thirdParty.bfi.receivedInvoiceResult.syncEnabled/cron`；窗口 `thirdParty.bfi.receivedInvoice.queryWindowDays/resultWindowDays`（默认 30）；联调临时值 `thirdParty.bfi.receivedInvoice.materialNumber`（默认 SP0324）。均有代码默认值，不配置也能跑 |
+| 3 | 存量镜像补齐 | items/票种编码随 30 天增量窗口逐轮自动补写（指纹变更触发重写）；窗口外老票由推送时 A801-1 窄查回填兜底 |
+| 4 | 数据前提 | 收票登记须新链路登记（票在镜像、绑定收敛）；**本地 21 条造数收票登记镜像悬空推不动，联调须新登记票**；供应商须建档并维护统一社会信用代码 + 客商编码；合同须维护组织编码/结算币种/乙方；结算单先完成付款侧 A102-2 应付单同步 |
+| 5 | 联调校准项 | `biztype=PUR`、`awrp_src_type=TMS收票登记`、`materialNumber=SP0324`、金蝶税率编码 V13 命名、分录必填范围（金蝶强校验常多于 DTO 标注，参照 A303-1 经验逐步放开注释字段）、A302-6 结果结构与 `requireBfiSaveSuccess` 兼容性 |
+| 6 | 联调顺序 | 执行 SQL → 全票池同步（补 items）→ 新收票登记选票→审批→批量同步绑定 → 付款侧结算单同步生成应付单 → `/push-kingdee` 推送 → 金蝶查收票单与指定关系 → 手动 `/sync-kingdee-result` 验证回写 |
+
+---
+
+## 8. 关键代码索引
+
+| 环节 | 代码位置 |
+| --- | --- |
+| 推送端点 | `blade-service/blade-transport controller/InvoiceReceiptController.pushKingdee / syncKingdeeResult`（`POST /invoice-receipt/push-kingdee`、`POST /invoice-receipt/sync-kingdee-result`，菜单权限 invoice_receipt） |
+| 推送编排/回写 | `service/impl/InvoiceReceiptServiceImpl.pushKingdeeReceivedInvoice / pushOneReceivedInvoice / buildReceivedInvoicePushPlan / syncKingdeeReceivedInvoiceResult / applyReceivedInvoicePushResult` |
+| 报文组装 | `support/KingdeeReceivedInvoiceSyncSupport`（pushReceivedInvoice / assignApBill / queryReceivedInvoiceBySrcCodes / parseItems），应付侧复用 `support/KingdeeApBillSyncSupport`（apBillSrcCode / queryApBillExistNos / requireContract / bfiOrgNumber / bfiCurrency / bfiAsstactNumber） |
+| 镜像明细落库 | `InvoiceReceiptServiceImpl.fillInvoicePool / buildItemsJson`（items_json、invoice_type_code 随收票登记保存时 `persistMirrorFromRemote` 单票 upsert 落库，无指纹比对表——票池改回实时查询后指纹机制已退役） |
+| 定时任务 | `task/PaymentKingdeeResultTask.syncKingdeeReceivedInvoiceResult`（第④子流程独立调度） |
+| 接口契约 | `blade-third-party-api/blade-bfi-api`：`BfiReceivedInvoiceSaveDTO/EntryDTO`（A303-2）、`BfiInvoiceAssignItemDTO/RefDTO`（A302-6）、`BfiReceivedInvoiceQueryDTO/VO/EntryVO`（A801-3）、`IBfiService.saveReceivedInvoice/invoiceAssign/queryReceivedInvoice` |
+| 常量/配置 | `constant/KingdeeBfiConstant`（RECEIVED_PUSH_* 状态机、BFI_RECEIVED_BIZ_TYPE、BFI_RECEIVED_INVOICE_SRC_TYPE）、`config/BfiProperties.ReceivedInvoice` |
+| 展示 | `InvoiceReceiptVO.kingdeePushStatusName` + `InvoiceReceiptWrapper` 翻译；列表查询支持 kingdeePushStatus 过滤 |
+| 前端 | 本期未接按钮，收票管理页面「批量推送金蝶」与推送状态列后续迭代接入 |

doc/docs/业务流程/2026-09-22-金蝶票池选票统一查镜像（收票登记+结算单认领+按票号补查+统一组件）业务流程.md

@@ -1,94 +1,75 @@
-# 金蝶票池选票统一查镜像（收票登记 + 结算单认领 + 按票号补查 + 统一组件）业务流程
+# 金蝶票池选票实时查询（镜像降级为登记存根）业务流程
 
 > 适用系统：TMS（BladeX 微服务平台，服务：blade-transport；前端：tms-erp-web）
 > 对接系统：金蝶发票云旗舰版·票易通（piaozone）全票池 A801-1，经业财融合 BFI 网关（rim 契约）透传
-> 关联文档：`2026-09-20-收票管理同步金蝶全票池发票（A801-1查询+批量同步+定时绑定关联）业务流程.md`（镜像同步与定时绑定链路，本文档不改变其行为）、`2026-09-20-piaozone-invoice-pool-claim`（结算单认领实时透传初版，本文档将其推翻并本地化）
-> 最后更新：2026-09-22（实现完成于工作树，提交时机待定）
+> 关联文档：`2026-09-20-收票管理同步金蝶全票池发票（A801-1查询+批量同步+定时绑定关联）业务流程.md`（同步链已整体退役，仅存推送/回写侧仍有效的键与端点见该文档退役声明）、`2026-09-22-收票单推送金蝶全链路业务流程（A303-2保存-A302-6指定应付-A801-3预检回写）.md`（图05 推送链路，镜像字段 invoice_type_code/items_json 由其取数消费）
+> 设计依据：`docs/superpowers/specs/2026-09-22-invoice-pool-remote-reversal-design.md`
+> 最后更新：2026-09-22（本文档原为「金蝶票池选票统一查镜像」，同日二次决策改回实时查询后整篇重写；文件名保留以免断链）
 
 ---
 
 ## 1. 背景与决策
 
-结算单认领查询曾是 A801-1 **实时透传**：接口不返回总数，后端用"多取 1 条探测 hasMore + 合成 total"实现下一页式翻页，前端分页器显示的是假总数（可跳空页）；收票登记新增则查本地镜像表（`limit 200` 无分页、前端本地切页）。两处口径不一、且实时链路每次开弹窗都打远程。
+2026-09-22 上午曾定稿"选票统一查本地镜像 + 全量同步维护镜像"方案。同日二次决策**推翻该方案**：同步体系（定时任务、增量窗口、批量 upsert、定时绑定、漏绑补偿、票种/客商税号双白名单）维护过重，且选票以金蝶侧实时状态为准更可靠。
 
-**定稿口径（2026-09-22 逐步确认）**：两处选票**统一查本地镜像表 `blade_kingdee_invoice_pool`，数据库真分页**。镜像本地化后"金蝶接口无分页"问题直接消失，前端回归标准分页弹窗；防重不依赖金蝶 `expenseStatus`（A801-1 响应根本不回传该字段），改用本地事实 `claimed/registered` 标记；缺口由"按发票号码精确补查"兜底。
+**定稿口径**：
 
-| 变更点 | 改造前 | 改造后 |
-| --- | --- | --- |
-| 结算单认领查询 | A801-1 实时透传 + 合成 total（假分页）+ expenseStatus 条件 | 查镜像真分页，条件集与收票统一，expenseStatus 删除 |
-| 收票登记选票 | 镜像 `limit 200`、关键字模糊、前端本地切页、编辑态走 Mock | 查镜像真分页，统一组件；Mock 全删 |
-| 防重依据 | 无（两处均可重复选） | 每行 `claimed`（存在有效结算单发票行）/`registered`（存在非作废收票登记）标记 + 三态筛选 |
-| 票不在镜像里 | 无法处理 | 弹窗内"按发票号码补查"：精确单查金蝶→过同一套白名单→upsert 入镜像 |
-| 时效兜底 | 无 | 收票侧弹窗"立即同步"按钮（复用既有手动全票池同步端点，per-request 超时 300s） |
+- 收票登记新增、正式结算单认领两处选票改为**实时查 A801-1 全票池**；A801-1 无总数，采用"多取 1 条探测 hasMore"的**游标式下一页翻页**（无跳页能力）。
+- `blade_kingdee_invoice_pool` 语义降级为**登记存根**：只存被业务选中的发票，写入时机=**收票登记保存时服务端重查金蝶落库**（否决"选中即写"）。
+- 全量同步体系**退役删除**：定时任务、增量窗口、镜像批量 upsert、定时绑定（receiptMap）、漏绑补偿、白名单过滤（票种 + 客商税号 AND，客商建档不再是选票前置）、手动全量同步端点与"立即同步"按钮、按票号补查（语义并入主查询）。
+- 金蝶不可用时查询与保存重查均**直接报错**（镜像不再提供读服务，无降级路径——接受"每次开弹窗/每次保存打一次金蝶"的一次性成本，换取同步体系归零）。
 
 ## 2. 接口契约（后端）
 
-两个门面端点分挂各自菜单（类级 `@PreAuth` 按菜单隔离，刻意不做跨菜单合并），**同一服务方法落点**：
+两个门面端点分挂各自菜单（类级 `@PreAuth` 按菜单隔离），同一服务方法落点；**路径/方法不变、语义换芯**：
 
 | 端点 | 说明 |
 | --- | --- |
-| `GET /invoice-receipt/invoice-pool`、`GET /formal-settlement/invoice-pool` | 统一分页查询，收参 `KingdeeInvoicePoolQueryDTO`，返回 `R<IPage<KingdeeInvoicePoolVO>>` |
-| `POST /invoice-receipt/invoice-pool/fetch?invoiceNo=`、`POST /formal-settlement/invoice-pool/fetch?invoiceNo=` | 按票号精确补查，返回单张 `R<KingdeeInvoicePoolVO>`，校验不过报业务异常 |
-| `POST /invoice-receipt/sync-invoice-pool` | 既有全票池手动同步（本文档仅新增前端调用方，含 300s 超时覆盖） |
+| `GET /invoice-receipt/invoice-pool`、`GET /formal-settlement/invoice-pool` | 实时统一查询，收参 `KingdeeInvoicePoolQueryDTO`，返回 `R<KingdeeInvoicePoolPageVO>`（游标分页） |
 
-**A801-1 统一查询口径**：所有出站查询（定时同步窗口分页 `queryPoolPage`、按票号窄查 `queryPoolByInvoiceNo`——补查/批量同步/漏绑补偿共用）一律携带 `invoiceStatus = "0"`（票易通字典：正常），作废/异常票不再进入镜像、也不可被补查命中。注意：仅约束**查询侧**，历史镜像中已存在的非正常票不受影响（如需剔除既有非正常镜像，另立清理口径）。
+- 已删除端点：`POST /*/invoice-pool/fetch`（按票号补查，语义并入主查询的发票号码条件）、`POST /invoice-receipt/sync-invoice-pool`（手动全量同步）。
+- **保留端点**：`POST /invoice-receipt/sync-kingdee`（列表"批量同步"，职责收敛为刷新**已登记票**的镜像行与状态，镜像行此时必已存在）。
 
-**查询条件**（`KingdeeInvoicePoolQueryDTO`）：`current/size`（size 钳位 1~100）、`invoiceNo` 模糊、`invoiceDateStart/End`（服务端强校验 yyyy-MM-dd）、`salerName/buyerName` 模糊（镜像列 issuer_name/receiver_name）、`invoiceType` 名称模糊、`salerTaxNo/buyerTaxNo` 精确、`claimed/registered`（true/false/null 三态）。
+**查询条件**（`KingdeeInvoicePoolQueryDTO`）：`current/size`（size 钳位 1~100，透传为 A801-1 pageSize=size+1 探测）、`invoiceNo`、`invoiceDateStart/End`（服务端强校验 yyyy-MM-dd）、`salerTaxNo/buyerTaxNo`、`invoiceType`（票易通编码，如 26/27，选项取 `BfiConstant.INVOICE_TYPE_NAMES`）、`expenseStatus`（1 未用/30 在用/60 已用/65 已入账）。**删除**了镜像时代的 `salerName/buyerName/claimed/registered` 条件（远程不支持名称模糊；本地状态不可下推）。
 
-**统一视图**（`KingdeeInvoicePoolVO`，字段名与镜像实体一致以复用收票回填）：镜像票面全字段 + `availableInvoiceAmount = matchedAmount = invoiceAmount`（价税合计，认领口径不变）+ `claimed/registered`；`id` 为镜像主键（ToStringSerializer），收票登记保存仍绑 `kingdeeInvoicePoolId`。
+**A801-1 统一查询口径**：所有出站查询一律携带 `invoiceStatus = "0"`（正常票）；返回行按 `invoiceNo` trim 全等防御过滤后再截断 size 条（防接口模糊匹配语义假命中）。
 
-## 3. 查询链路（`KingdeeInvoicePoolMapper.xml`）
+**返回体**（`KingdeeInvoicePoolPageVO`）：`{ records: List<KingdeeInvoicePoolVO>, current, size, hasMore }`——**不再合成 total**。行映射：票种编码→中文名、税率小数转百分数（顶层优先、回退明细首行）、`invoiceAmount = availableInvoiceAmount = matchedAmount = totalAmount`、`attachmentJson = {source:'piaozone', path:downloadUrl, name:票号.pdf}`；`id` 置空（未入镜像）。
 
-复杂查询入 XML（AGENTS 规范），自定义 SQL 不吃 MP 租户/逻辑删除插件，**手工带 `tenant_id` + `is_deleted = 0`**：
+**claimed/registered 纯展示装饰**：对本页票号批量查 `blade_formal_settlement_invoice`（关联主单未删且非 voided）与 `blade_invoice_receipt`（未删且非 voided），内存打标；只读展示，**不落库、不进查询条件**。
+
+## 3. 保存时落库（收票登记，`persistMirrorFromRemote`）
+
+`InvoiceReceiptSaveRequest` 已删除 `kingdeeInvoicePoolId` 字段（前端不再传）。save/submit 链路新增"镜像绑定"步骤：
 
 ```
-主查询：blade_kingdee_invoice_pool p（status=1、租户、动态条件、
-        ORDER BY source_updated_time DESC, create_time DESC，MP 分页插件真 count）
-claimed 标记/过滤：EXISTS blade_formal_settlement_invoice c
-        （c 租户+未删，且嵌套 EXISTS 主单 blade_formal_settlement s 未删且 approval_status != 'voided'
-         ——作废结算单不占坑，票据自动释回"未认领"）
-registered 标记/过滤：EXISTS blade_invoice_receipt r
-        （r 租户+未删且 approval_status != 'voided'）
+① 按 invoiceNo 调 queryPoolByInvoiceNo 远程 A801-1 精确单查（含票号全等防御）
+② 未命中或 delete="1" → ServiceException("金蝶票池未查询到发票 X 或已作废，不能保存")，保存中止
+   （选中→保存竞态：票被删/红冲在此拦截；不主动作废既有登记，与列表同步口径一致）
+③ 命中 → fillInvoicePool 构建/刷新镜像行（保留图05 的 invoiceTypeCode/itemsJson 映射）
+④ 保存/更新镜像行 → receipt.kingdeeInvoicePoolId = mirror.id，
+   回填 kingdeeBillNo = serialNo、kingdeeStatus
 ```
 
-三张表同为 TenantEntity，EXISTS 片段经 `<sql>` 复用于 SELECT 列（打标记）与 WHERE（做过滤），单一事实源。
+镜像按 `(tenant_id, invoice_no)` 唯一（既有 uk），多单登记同票共享同一镜像行；单票 upsert，**无指纹表、无批量写**。编辑态表单"同步"按钮（`syncReferenceData`）为**纯预览**——调查询接口按票号取单行（records[0]）回填表单，不写镜像；镜像刷新统一收敛到保存动作。
 
-## 4. 补查链路（`InvoiceReceiptServiceImpl.fetchKingdeeInvoiceByNo`）
+## 4. 前端统一组件（`src/components/kingdee-invoice-pool-dialog/main.vue`）
 
-```
-① 镜像优先回读（selectInvoicePoolVO，租户+status=1）
-│    命中 → 直接返回。不打远程：编辑态"同步"按钮不受金蝶可用性影响；
-│    口径：白名单只约束"入镜像"，回读既有镜像不受限
-② 未命中 → A801-1 按票号窄查（复用 queryPoolByInvoiceNo，pageSize=500）
-│    返回行按票号 trim 全等匹配才取（防接口模糊语义假命中）；无 → 报"金蝶票池未查询到"
-③ 白名单校验（与定时同步同一套代码，非复制实现，顺序一致）：
-│    filterByInvoiceTypes（票种白名单）→ 不过：报"票种不在同步白名单内"
-│    filterByArchiveTaxNos(customerTaxNoSet())（购、销双税号 AND 命中客商档案）
-│    → 不过：报"请先在客商档案维护统一社会信用代码"
-④ batchUpsertInvoicePool 入镜像（自带票面指纹比对，幂等，重复点击安全）
-⑤ selectInvoicePoolVO 回读统一视图返回（含 claimed/registered）
-```
+- Props：`modelValue / title / confirmText / multiple / initialInvoiceNo / queryApi`（`fetchApi/syncApi` 已删除）；事件 `confirm(rows)`（单选 `[row]`、多选选中数组）。打开时重置查询、按 `initialInvoiceNo` 预填、清勾选、回第 1 页加载。
+- 查询表单六条件：发票号码、开票日期区间、销方税号、购方税号、发票类型（编码下拉）、单据使用状态；查询/重置按钮在加载期间禁用。
+- 表格：票面列 + **认领状态/登记状态**两个 tag（仅展示）；"金蝶同步"列已删除（远程票恒在池中无意义）；行主键用发票号码兜底（`rowKey = invoiceNo || id`，远程票 id 恒空）；单选 radio/双击直选，多选 `reserve-selection` 跨页保留。
+- 分页区：**游标式**——"上一页/下一页" + "第 N 页" + 每页条数（10/20/50/100）；`hasMore=false` 禁用下一页，第 1 页禁用上一页，加载中全部禁用；查询条件变更或换页大小即回第 1 页；翻页请求失败时页码回滚到发起前值（不停错页）。
+- 接线：收票登记表单（`multiple=false`，回填不再取 `id`，金蝶单据号取 `serialNo`、状态固定显示"未同步"，保存落库后由后端刷新）；结算单编辑器（`multiple=true`、`confirm-text="确认认领"`，`handleInvoiceClaimConfirm` 把复数 `attachmentsJson` 归一为认领契约单数 `attachmentJson`）。
+- 翻页期间票池数据变动：游标页可能重复/漏行（组件按发票号码做行主键与选择去重，结算认领确认前还有票号集合查重）；最终一致性以保存/提交时服务端重查为准，无资金风险。
 
-**与定时任务的关系（刻意设计）**：同步、镜像 upsert、定时绑定（receiptMap 回填 `kingdeeInvoicePoolId`）、漏绑补偿链路一行未动；补查只是 batchUpsert 的新调用方，不触发绑定回填——补查进来的票若已有登记未绑，由下一轮补偿链路自然收敛。窗口故障自愈性：瞬时失败下轮滑动窗口重拉；票滑出 30 天窗口造成的永久缺口由补查兜底（补查不受时间窗口约束）。
+## 5. 数据清理
 
-## 5. 前端统一组件（`src/components/kingdee-invoice-pool-dialog/main.vue`）
+`doc/sql/transport/blade_kingdee_invoice_pool_prune_20260922.sql`（幂等可重跑）：删除 `blade_kingdee_invoice_pool` 中未被任何未删 `blade_invoice_receipt.kingdee_invoice_pool_id` 引用的历史全量同步镜像行。**执行前必须先跑脚本内盘点 SELECT 并向用户报数确认**（dev 库清理口径：事务 + 回滚 SQL + mysqldump 文本兜底）。
 
-- Props：`modelValue / title / confirmText / multiple / initialInvoiceNo / queryApi / fetchApi / syncApi(可空)`；事件 `confirm(rows)`（单选 `[row]`、多选选中数组）。打开时重置查询、按 `initialInvoiceNo` 预填、清勾选、回第 1 页加载。
-- 查询表单：发票号码、开票日期区间、开票单位、受票单位、发票类型（可搜索下拉，选项与后端 `BfiConstant.INVOICE_TYPE_NAMES` 中文名对齐）、认领状态、登记状态（布尔下拉清空后传空串，Spring 绑定为 null，"不限"语义正确）。
-- 表格：票面列 + 三个显式状态列——**认领状态**（已认领红/未认领灰）、**登记状态**（已登记橙/未登记灰）、**金蝶同步**（未同步/已同步/同步失败，镜像 `kingdee_status`）；单选模式操作列"选择"+ 双击直选，多选模式复选列 `reserve-selection`；底部左"按票号补查"输入区、右标准分页。
-- 接线：收票登记表单（`multiple=false`，注入 query/fetch/sync 三个 api，`confirmInvoice(row)` 回填零改动，页面 Mock 与本地切页全删；编辑态"同步"按钮改走补查）；结算单编辑器（`multiple=true`、`confirm-text="确认认领"`、不传 syncApi——结算菜单无全量同步端点；`handleInvoiceClaimConfirm` 中转时把复数 `attachmentsJson` 归一为认领契约的单数 `attachmentJson`，`confirmInvoiceClaims` 本体零改动）。
-- 同步等待体验：服务端全量同步为分钟级接口（前端 per-request 超时 300s），点击"立即同步"展示全屏 ElLoading（"预计 1~3 分钟，请勿关闭窗口"），期间锁定弹窗关闭按钮/esc/遮罩点击，完成后自动刷新列表。
+## 6. 已知限制与验证
 
-## 6. 业务口径与已知限制
-
-- **认领场景收紧**：镜像入池受"票种白名单 + 购销双税号 AND 命中客商档案"约束（见 2026-09-20 文档口径），本地化后认领可选集合从裸票池收紧为该白名单集合——**供应商未建档/未维护统一社会信用代码，其进项票在两个弹窗都选不到**，客商档案维护是前置条件。
-- `claimed` 语义 = 被任一**有效**正式结算单认领过；不做跨单认领金额校验的变更（后端仍只查本单金额上限），"已认领"票默认仍可见（claimed 过滤默认不限，拆分认领等场景需要）。
-- 金蝶侧已删除的票（delete=1）补查会以 `kingdee_status=failed` 入镜像并可见（与既有 syncKingdee 存量同模式）。
-- `invoice_no` 在 `blade_formal_settlement_invoice` 无独立索引，claimed 过滤现阶段数据量无感；后续量大建议按幂等模板补 `(tenant_id, invoice_no)` 索引。
-- 无表结构、无 Nacos、无菜单 SQL 变更。
-
-## 7. 验证状态
-
-- 后端：`mvn clean compile -DskipTests -pl blade-service/blade-transport -am` 通过；前端 `pnpm run build` 通过；死符号（`getInvoicePool/invoicePoolQuery/FormalSettlementInvoicePool*/Mock 函数/expenseStatusOptions`）两仓库 grep 归零。
-- 手工回归清单（9 条）：`docs/superpowers/plans/2026-09-22-invoice-pool-mirror-unified-picker.md` Task 8 Step 4，含作废释放、金蝶不可用兜底、立即同步 300s 超时三个新增场景。
-- 过程与评审记录：`.superpowers/sdd/2026-09-22-invoice-pool-mirror-unified-picker/`（台账 progress.md、各任务简报/报告/评审包）。
+- 每次打开弹窗、每次保存都是一次金蝶远程调用（预期成本）；金蝶不可用期间选票/收票保存均不可用。
+- `expenseStatus` 仅作查询条件下推 A801-1，响应回传与否不影响 claimed/registered 本地装饰。
+- 无表结构、无菜单 SQL 变更；Nacos 三份模板中 `thirdParty.bfi.invoiceReceipt.*` 同步相关键已随任务删除（图05 `sync-kingdee`/推送链使用的键保留）。
+- 后端验证：`mvn clean compile -DskipTests -pl blade-service/blade-transport -am` + `mvn test-compile` 通过；前端 `pnpm run build` 通过；退役符号两仓库 grep 归零。
+- 手工回归清单与过程记录：`.superpowers/sdd/2026-09-22-invoice-pool-remote-reversal/`（各任务简报/报告/评审包）。