docs: 金蝶单据锁定与解锁业务说明（锁定-解锁-删单-补偿）

doc/docs/业务流程/2026-10-30-金蝶单据锁定与解锁说明（业务版）.md

@@ -0,0 +1,201 @@
+# 金蝶单据锁定与解锁说明（业务版）
+
+> 业务域：正式结算单、开票申请、付款申请在「同步金蝶」成功后的单据锁定、金蝶侧解锁/删单通知、锁定失败自动补偿
+> 核心规则：**单据推送金蝶成功后，本系统会请金蝶"锁单"；锁定期间本系统对应单据被冻结，不能作废或改动。金蝶侧解锁或删单后，会通知本系统，本系统据此解除锁定或自动还原单据。**
+> 最后更新：2026-10-30
+
+---
+
+## 一、为什么要锁单
+
+一张单在 TMS 和金蝶各存一份。如果 TMS 推完单后继续改、继续作废，金蝶那边还是老单，就会出现"两套账"。
+
+锁单就是把两边"绑住"：
+
+1. 推送成功后，本系统立即请求金蝶把这张单锁住（金蝶侧不允许随意改动）；
+2. 同时本系统把这边的单冻结（不能作废、不能改）；
+3. 金蝶那边解锁或删单后，会主动通知本系统，本系统再解除冻结或把单据还原。
+
+锁定与否**不影响已推送成功的结果**：金蝶单一旦生成，不会因为锁单没成功而重复生成。
+
+---
+
+## 二、适用范围（总览）
+
+| 业务单据 | 什么时候推送 | 金蝶侧单据 | 对应关系 |
+| --- | --- | --- | --- |
+| 正式结算单（应付） | 审批通过后系统自动推送，也可页面点「同步金蝶」 | 财务应付单 | 一张结算单 → 一张金蝶单 |
+| 正式结算单（应收） | 同上 | 财务应收单 | 一张结算单 → 一张金蝶单 |
+| 开票申请单 | 审批通过后系统自动推送，也可页面点「同步金蝶」 | 开票单 | 一张申请单 → **按发票张次 N 张金蝶单，逐张锁定** |
+| 付款申请单 | 审批通过后系统自动推送（正式结算付款、预付款均适用），也可页面点「同步金蝶」 | 付款申请单 | 一张付款申请 → 一张金蝶单 |
+| 收票单 | — | — | **暂未纳入锁定范围**（接口已预留） |
+
+> 开票申请按"张"锁：一张申请里有几张发票，就有几条锁定记录，各张单独锁、单独补偿，互不影响。但只要其中任意一张被金蝶删除，整张开票申请会被作废（见场景三）。
+
+---
+
+## 三、页面上的"金蝶锁状态"怎么读
+
+列表和详情页的「金蝶锁状态」列会显示以下标签，悬停可看原因或操作人：
+
+| 标签 | 含义 | 单据能不能操作 | 业务该做什么 |
+| --- | --- | --- | --- |
+| **金蝶锁定中**（红） | 金蝶已锁单，单据被冻结 | 不能作废、不能改动（开票申请/付款申请点作废会提示"该单据已被金蝶锁定，不可修改"；结算单本身"已同步金蝶"就不可编辑/作废） | 确实要改，先去金蝶侧解锁，等状态变为"金蝶锁单"后再处理 |
+| **锁定失败·补偿中**（橙） | 金蝶单已生成，但"锁单"这一步没成功，系统正在自动重试 | 不建议作废或重建 | **不要作废单据**，等待自动补偿；着急可在页面点「同步金蝶」立即补锁 |
+| **锁定失败·已达上限**（红） | 自动补偿已重试满 5 次仍未成功 | 同上 | 点「同步金蝶」立即补锁（会重新开始补偿）；仍失败请把金蝶单号和失败原因给技术排查 |
+| **金蝶删单**（红） | 金蝶侧把这张单删除了 | 结算单/开票申请已自动作废；付款申请转为"生成失败" | 结算单/开票申请：重新走业务流程；付款申请：核实后重新推送 |
+| **金蝶锁单**（橙） | 金蝶侧解锁了，但单据还在 | 锁已解除，按单据自身状态规则操作 | 注意两边不再自动联动，改动/作废前先确认金蝶侧如何处理 |
+| **结算调整重推**（橙） | 结算调整生成新单后，原单的旧锁自动解除 | 原单只做标记，不删不改 | 无需处理，以调整后的新单为准 |
+| 空白 | 没有锁记录（从未推送，或锁定早已解除且无留痕） | 按单据自身状态规则操作 | — |
+
+---
+
+## 四、主流程（业务视角）
+
+```
+单据审批通过
+  └─ 系统自动推送金蝶（失败不影响审批结果）
+       ├─ 推送失败 → 金蝶状态记"生成失败"，可重推，不产生金蝶单
+       └─ 推送成功 → 回填金蝶单号 → 请求金蝶锁单
+             ├─ 锁定成功 → 单据冻结（页面：金蝶锁定中）
+             └─ 锁定失败 → 系统每5分钟自动重锁，最多5次
+                             （页面：锁定失败·补偿中 / 已达上限）
+
+金蝶侧后续动作：
+  ├─ 解锁（单据还在） → 通知本系统 → 解除锁定（页面：金蝶锁单）
+  └─ 删单            → 通知本系统 → 结算单/开票申请自动作废并还原
+                                     付款申请转"生成失败"，等人工重推
+```
+
+---
+
+## 五、场景一：推送成功后锁定
+
+**触发方式**
+
+1. 审批通过后系统自动推送（不需要人工点）；
+2. 页面手动点「同步金蝶」（补推、重推、补锁都走这里）。
+
+**系统做了什么**
+
+1. 推送成功即回填金蝶单号，随后逐张请求金蝶锁单；
+2. 每张金蝶单对应一条锁定记录，先登记"待锁"再调金蝶，保证漏不掉；
+3. 单张锁失败不影响其他张，也不影响主单的"已同步"状态。
+
+**重复操作会怎样**
+
+- 已经推送成功、已有金蝶单号的，再点「同步金蝶」不会重复生成金蝶单；
+- 已锁定成功的单据不会重复锁。
+
+**锁定期间的业务影响**
+
+- 开票申请、付款申请：作废入口被拦截；
+- 正式结算单：本身"已同步金蝶"就不能编辑、调整、作废，锁定期同样被拦截。
+
+---
+
+## 六、场景二：金蝶解锁（单据还在）
+
+1. 金蝶侧对单据执行解锁后，通知本系统；
+2. 本系统把锁定记录置为"已解锁"，页面显示橙色「金蝶锁单」标签，悬停显示**谁在什么时间解锁**；
+3. 本系统单据的业务状态**不会因此改变**（结算单仍是"已同步"，开票申请/付款申请仍保持原审批状态）；
+4. 重复收到同一条解锁通知不会重复处理，也不会报错。
+
+> 注意：解锁只解除"金蝶锁单"这一层限制。正式结算单即使解锁，仍受"已同步金蝶不可直接作废"的约束；要作废/调整需走结算调整，或让金蝶侧删单由系统自动作废。
+
+---
+
+## 七、场景三：金蝶删单（三种单据处理不同）
+
+金蝶侧删除单据后，系统按单据类型分别处理：
+
+| 业务单据 | 本系统处理 | 单据状态 | 后续 |
+| --- | --- | --- | --- |
+| 正式结算单 | 自动作废，并还原到推送前的同步信息：清空金蝶单号、金蝶内码、同步时间，同步状态改回"未同步" | 已作废（终态），当前节点"已作废" | 变更流水记录"金蝶删单回调自动废除"，操作人显示金蝶侧操作人；需重新推单请新单重走流程 |
+| 开票申请 | 自动作废，清空金蝶单号、同步时间，同步状态改回"未同步"，并刷新关联结算单的开票状态 | 已作废（终态） | 操作流水记"金蝶删单回调作废"，操作人为金蝶侧操作人；需重新开票请重新发起申请 |
+| 付款申请 | **不作废源单**：金蝶状态由"已生成/付款中"改为"生成失败"，清空金蝶单号、内码（原值留日志） | 审批状态不变 | **不自动重推**，人工核实后重新推送；页面显示红色「金蝶删单」标签，以便与普通推送失败区分 |
+
+补充说明：
+
+- 开票申请有多张金蝶单时，任意一张被删，**整张开票申请作废**；
+- 付款申请只有"已生成/付款中"状态会转为"生成失败"，已完成付款等终态不受影响；
+- 结算单作废时会同步释放项目预付核销占用，避免残留；
+- 重复的删单通知不会重复作废、重复还原。
+
+---
+
+## 八、场景四：锁定失败与自动补偿
+
+**什么情况会锁定失败**：推送成功后，请求金蝶锁单时接口报错或超时。
+
+**系统怎么处理**
+
+1. 该张单据保留"锁定失败"记录并记录原因，页面显示橙色「锁定失败·补偿中」；
+2. 定时任务自动重锁，默认每 5 分钟一轮，最多自动重试 5 次；
+3. 5 次仍未成功，页面转为红色「锁定失败·已达上限」，不再自动重试。
+
+**业务注意事项**
+
+- **锁定失败不影响已推送成功的结果**，单据仍是"已同步金蝶"，不会重复生成金蝶单；
+- 补偿期间建议**先不要作废或重建单据**，避免本系统与金蝶不一致；
+- 已达上限时，在页面点「同步金蝶」会立即补锁，并重新开始补偿计数；
+- 仍失败时，请提供单据号、金蝶单号、页面上的失败原因给技术排查。
+
+> 自动补偿是否开启由各环境配置决定（默认开启锁定、默认关闭定时补偿），如发现"一直没人补锁"，请联系技术确认环境配置。
+
+---
+
+## 九、场景五：结算调整重推（本系统主动解锁）
+
+已推送金蝶的正式结算单需要调整时，走结算调整：系统生成一张新的结算单并推送金蝶，**原单的旧锁自动解除**，页面显示橙色「结算调整重推」标签。
+
+- 原单只加"已调整"标记，不删除、不改业务字段；
+- 后续收付款、开票以新单为准；
+- 这是本系统主动解锁，不是金蝶回调，操作人显示发起调整的人。
+
+---
+
+## 十、常见问题
+
+**1. 单据显示"金蝶锁定中"，我要改内容/作废怎么办？**
+先到金蝶侧解锁，等本系统状态变成「金蝶锁单」后再处理。正式结算单还要注意"已同步金蝶"本身就不能直接作废，需要走结算调整或由金蝶删单。
+
+**2. 金蝶那边已经解锁了，为什么本系统还不能作废？**
+解锁只解除"金蝶锁单"，不改变单据的业务状态。结算单仍受"已同步不可作废"限制；开票申请/付款申请解锁后恢复可作废，但作废不会反向同步金蝶，请确认金蝶侧单据的处理方式。
+
+**3. 显示"金蝶删单"是什么意思？**
+金蝶侧把单据删了。结算单、开票申请已自动作废，需要重新走流程；付款申请没有作废，但变成了"生成失败"，核实后重新推送即可。
+
+**4. 显示"锁定失败"要不要人工处理？**
+先等系统自动补偿（每 5 分钟一次，最多 5 次）。已达上限时点「同步金蝶」立即补锁；补偿期间不要作废或重建单据。
+
+**5. 金蝶重复发解锁/删单通知，会不会把单据作废两次？**
+不会。系统按"当前是否仍锁定/是否已作废"判断，重复通知自动跳过。
+
+**6. 开票申请有多张发票，其中一张锁失败怎么办？**
+各张独立锁定、独立补偿，其他张照常冻结。页面会提示哪一张失败；该张补偿成功前，整张申请仍按"锁定失败"提示。
+
+**7. 已推送的单据能不能直接在 TMS 作废？**
+不能。开票申请、付款申请在锁定中被拦截；正式结算单已同步即不可作废。要么金蝶侧删单由系统自动作废，要么走结算调整生成新单。
+
+---
+
+## 十一、留痕在哪里查
+
+| 想查什么 | 在哪看 |
+| --- | --- |
+| 单据当前锁状态、失败原因、重试次数、解锁操作人与时间 | 列表/详情「金蝶锁状态」列，悬停查看提示 |
+| 结算单被金蝶删单自动作废的过程 | 结算单变更流水（内容含"金蝶删单回调自动废除"） |
+| 开票申请被金蝶删单自动作废的过程 | 开票申请操作流水（动作"金蝶删单回调作废"） |
+| 付款申请解锁原因 | 付款申请金蝶失败原因（"金蝶侧单据已删除解锁……等待重新推送"） |
+| 每张金蝶单的完整锁定/解锁明细 | 技术侧锁定记录表 `blade_kingdee_bill_lock`（一张金蝶单一行） |
+
+---
+
+## 十二、口径边界（给管理员/技术）
+
+1. 锁定总开关关闭时：推送后不锁单，金蝶的解锁/删单通知只应答、不处理；
+2. 补偿定时任务需按环境开启，默认每 5 分钟一轮，重试上限 5 次；
+3. 金蝶回调为无登录态公开接口，需保持网关白名单配置有效（异常时金蝶会重试）；
+4. 锁单与解锁均为逐张调用，单张成败互不影响；解锁回调整批处理，任一张还原失败则整批回滚、由金蝶重试闭环；
+5. 后续新增单据（如收票单）接入锁定时，锁定状态、解锁标识与本文口径保持一致即可复用。