docs: 补充金蝶冲销状态落库与列表展示设计说明
This commit is contained in:
刘泉佳
@@ -133,6 +133,7 @@
|
||||
- 预检为**软提示**，不阻断建单（默认建议）；是否升级为硬拦截由业务另行确认。
|
||||
- **降级**：金蝶查询超时/不可用/接口异常时，预检返回"未校验"，**不阻断**建单与回带，由后续审批分流与重推闸门兜底。
|
||||
- 预检结果**只用于提示**，不作为后续环节的结论缓存：审批（操作 2）、重推（操作 3）各自按**当下**状态重新判定。
|
||||
- 预检查询结果**顺带回写**正式结算单的冲销状态字段（`kingdee_writeoff_status`，见 §15）供列表展示；异常降级时不回写、保留上次值。
|
||||
|
||||
> 为什么不把硬拦截放在选单：冲销是金蝶侧**不可逆/需人工撤销**的对外操作，而审批只是 TMS 内部决策。若选单即要求已冲销，会出现"旧单已冲销、调整单却被驳回/删除"的**应付单空档**（详见第 13 节）。
|
||||
|
||||
@@ -165,7 +166,7 @@
|
||||
`repush(调整单id)` 重写为：
|
||||
|
||||
1. **前置校验**：调整单 `approvalStatus = approved`；原单存在。
|
||||
2. **冲销校验（硬闸门）**：取调整单号 + 原单号，按旧键（`原结算单号_明细单据号`）查 A102-4（应付）/ A302-4（应收）；要求存在且 `hadwrittenoff = true`，否则抛出「原应付/应收单尚未在金蝶冲销，禁止重推」。
|
||||
2. **冲销校验（硬闸门）**：取调整单号 + 原单号，按旧键（`原结算单号_明细单据号`）查 A102-4（应付）/ A302-4（应收）；要求存在且 `hadwrittenoff = true`，否则抛出「原应付/应收单尚未在金蝶冲销，禁止重推」。**闸门查询结果无论放行还是拦截均回写**正式结算单冲销状态（§15.3③），拦截后列表即同步为"未冲销"。
|
||||
3. **克隆新正式结算单**：`cloneFormalSettlement(原单, 调整单)`
|
||||
- 新号由 `nextNo` 取正式流水（`FJS`/`SJS`+日期+4 位）；
|
||||
- 克隆明细、明细费项、汇总费项、发票、汇率等；
|
||||
@@ -190,7 +191,7 @@
|
||||
|
||||
- 只认 `hadwrittenoff = true`（`BfiApBillVO` 158 / `BfiArBillVO` 138）。部分冲销同样放行。
|
||||
- `iswrittenoff` 不单独作为放行依据。落地前需用 Apifox 实测 A102-4/A302-4 确实回传 `hadwrittenoff`。
|
||||
- **两处判定，用途不同**：操作 1 选单预检 = 软提示（第 6.2 节）；操作 3 重推 = **硬闸门**（第 8 节）。预检不替代闸门——冲销在金蝶可被撤销，且建单到重推期间状态可能变化。
|
||||
- **三处判定，用途不同**：操作 1 选单预检 = 软提示（第 6.2 节）；操作 3 重推 = **硬闸门**（第 8 节）；定时回写 = 列表展示供数（第 15 节）。预检不替代闸门——冲销在金蝶可被撤销，且建单到重推期间状态可能变化；定时回写值**只用于展示**，闸门放行永远以实时查询为准。
|
||||
|
||||
### 9.3 克隆新正式结算单
|
||||
|
||||
@@ -288,3 +289,47 @@ ALTER TABLE blade_formal_settlement ADD COLUMN adjust_status VARCHAR(32) NULL CO
|
||||
5. **按钮与菜单**：「推送金蝶」与「重新推送」合并为**单一入口**（按金蝶状态分流：未同步/失败→推原结算单；已同步→冲销后重推新单），统一复用既有菜单 `settlement_adjustment_repush`，不新增菜单。
|
||||
6. **待实测**：A102-4/A302-4 的 `hadwrittenoff` 实际回传（§13.1）；克隆新单对 `PreSettlement` 占用的影响（§13.2）。
|
||||
|
||||
---
|
||||
|
||||
## 15. 金蝶冲销状态落库与列表展示（2026-10-30 新增）
|
||||
|
||||
### 15.1 背景与定位
|
||||
|
||||
预检（§6.2）与重推闸门（§8）是**事件触发**的单点实时校验：只有建调整单、点重推时才会查金蝶，覆盖不到结算单列表的全量展示；而列表是高频页面，不能每次刷新/翻页都实时查金蝶（外部依赖与延迟会拖垮列表）。因此把冲销状态**持久化 + 定时回写**（与 `PaymentKingdeeResultTask` 既有回写模式一致）；决策时刻（预检提示、闸门放行）仍坚持实时查询。三条链路互补：**接口查询保证决策正确，定时回写保证列表有数**。
|
||||
|
||||
### 15.2 数据模型（DDL）
|
||||
|
||||
脚本 `doc/sql/transport/lqj/temp/06_blade_formal_settlement_kingdee_writeoff_20261030.sql`（可重复执行）：
|
||||
|
||||
```sql
|
||||
ALTER TABLE blade_formal_settlement ADD COLUMN kingdee_writeoff_status VARCHAR(20) NULL COMMENT '金蝶冲销状态：unwrittenoff-未冲销 writtenoff-已冲销（NULL=未推送金蝶或未校验）';
|
||||
ALTER TABLE blade_formal_settlement ADD COLUMN kingdee_writeoff_time datetime NULL COMMENT '金蝶冲销状态确认时间（定时回写/预检回写时间）';
|
||||
```
|
||||
|
||||
实体 `FormalSettlement` 同步加 `kingdeeWriteOffStatus` / `kingdeeWriteOffTime`；`FormalSettlementVO` 继承实体自动带出，无需改 VO。
|
||||
|
||||
### 15.3 三条查询/回写链路
|
||||
|
||||
| 链路 | 触发 | 行为 |
|
||||
|---|---|---|
|
||||
| ① 定时回写（兜底供数） | `PaymentKingdeeResultTask` 子流程④（默认每 10 分钟，single-flight 锁 `kingdee-writeoff-sync`） | 扫 `kingdeeSyncStatus=synced` 的结算单 → 结算明细分批一次查全（消除 N+1）组装防重键 → A102-4/A302-4 整批查询 `hadwrittenoff` → 状态有变化的 `updateBatchById` 批量回写；金蝶异常整轮告警、保持上次值 |
|
||||
| ② 预检实时回写 | 操作 1 选单预检 | 查询成功即回写该单状态（已冲销/未冲销都存）；异常降级"未校验"不回写 |
|
||||
| ③ 闸门实时回写 | 操作 3 重推硬闸门 | 查询结果无论放行/拦截均回写（拦截=未冲销也存，提示后列表即同步） |
|
||||
|
||||
回写统一走 `FormalSettlementServiceImpl.refreshKingdeeWriteOff(id, writtenOff)`：状态未变化不落库，避免预检反复点击重复写库。
|
||||
|
||||
### 15.4 列表展示口径
|
||||
|
||||
| 场景 | 显示 |
|
||||
|---|---|
|
||||
| 未推送金蝶（unsynced/failed） | `-` |
|
||||
| 已推送，尚未回写过（存量上线初期） | 未校验 |
|
||||
| 已推送，旧单未冲销 | 未冲销（黄） |
|
||||
| 已推送，旧单已冲销（含部分冲销） | 已冲销（绿） |
|
||||
|
||||
前端：`formalSettlementTable.js` 新增「金蝶冲销状态」列（`formalSettlement.js` COLUMN_EXTRA 标记 `slot`）、`formal-settlement-table-panel.vue` 单元格插槽渲染标签、`utils/kingdee.js` 新增 `kingdeeWriteOffTagType` 颜色映射、`formalSettlementSearch.js` 新增 `kingdeeWriteOffStatusOptions` 文案。
|
||||
|
||||
### 15.5 与硬闸门的关系（重要）
|
||||
|
||||
定时回写值**只用于展示**，允许滞后一个调度周期（默认 10 分钟）；重推放行与否**永远以闸门实时查询为准**（§8.2），不读取定时值——避免拿旧状态放行导致金蝶重复生成应付/应收单。
|
||||
|
||||
|
||||
@@ -51,6 +51,25 @@
|
||||
| 已同步 | 已在金蝶生成应付/应收单，调整单上可看到金蝶单据号 |
|
||||
| 生成失败 | 推送失败，可用"推送金蝶"重试或等定时重推 |
|
||||
|
||||
### 2.4 正式结算单列表的「金蝶冲销状态」（2026-10-30 新增）
|
||||
|
||||
正式结算单列表在"金蝶单据状态"旁新增一列，显示该单在金蝶侧的旧应付/应收单是否已被财务冲销：
|
||||
|
||||
| 显示 | 含义 |
|
||||
|---|---|
|
||||
| 已冲销（绿） | 金蝶侧旧单已冲销（含部分冲销），场景 B 此时可以点"重新推送" |
|
||||
| 未冲销（黄） | 金蝶侧旧单还在，需先由财务在金蝶完成冲销 |
|
||||
| 未校验（灰） | 已推送金蝶但系统还没查过（上线初期存量单的初始态，跑一轮定时任务后自动补齐） |
|
||||
| - | 未推送金蝶的单，没有冲销状态可言 |
|
||||
|
||||
状态由系统在三个途径自动更新，**无需人工维护**：
|
||||
|
||||
1. 定时任务每约 10 分钟批量核对一次金蝶；
|
||||
2. 新建调整单**选单预检**时即时刷新该单；
|
||||
3. 点**"重新推送"**时即时刷新该单（被拦截未冲销也会同步为"未冲销"）。
|
||||
|
||||
> 列表状态允许滞后约一个定时周期（10 分钟）；点"重新推送"时系统以**当下实时查询**结果为准，不会因列表滞后而误放行。
|
||||
|
||||
---
|
||||
|
||||
## 三、通用操作说明（每个操作：前置条件 → 系统动作 → 结果）
|
||||
@@ -62,7 +81,7 @@
|
||||
| 入口 | 结算调整单列表 → 新增 |
|
||||
| 前置 | 必须先选定一张**可调整的正式结算单**，条件缺一不可：① 审批通过；② 未完成收款/付款；③ 非尾款结算；④ 未发起尾款付款/付款申请。不满足的单在选单列表里根本搜不到 |
|
||||
| 系统动作 | 选定结算单后自动回带：客商、调整类型（应收/应付）、合同、原结算金额、原单费用明细；同时做一次**金蝶冲销预检（软提示）** |
|
||||
| 预检提示 | ① 未推送金蝶 → 正常继续；② 已推送且旧单已冲销 → 提示"审批后可重新推送新单"；③ 已推送且旧单未冲销 → 醒目提示"审批后需先由财务在金蝶完成冲销，才能重新推送"；④ 金蝶查不到/超时 → 提示"未校验"，**不阻断建单** |
|
||||
| 预检提示 | ① 未推送金蝶 → 正常继续；② 已推送且旧单已冲销 → 提示"审批后可重新推送新单"；③ 已推送且旧单未冲销 → 醒目提示"审批后需先由财务在金蝶完成冲销，才能重新推送"；④ 金蝶查不到/超时 → 提示"未校验"，**不阻断建单**。预检查询结果同时回写该结算单列表的「金蝶冲销状态」（见 2.4） |
|
||||
| 结果 | 生成一张草稿，获得单号 |
|
||||
|
||||
> 预检只是提示，不拦人；真正的拦截在"重新推送"那一步。填单时必须至少录入一条调整费用，否则无法提交。
|
||||
@@ -129,7 +148,7 @@
|
||||
|---|---|---|---|
|
||||
| 1 | 业务 | 新增调整单（选单时预检会提示"旧单未冲销"或"已冲销"），提交 | 同场景 A 步骤 1-2 |
|
||||
| 2 | 审批人 | 审批通过 | ① 原结算单业务数据**零改动**，只追加 1 条变更记录（"调整单XX审批通过，调整金额XX，待重推金蝶"）；② 调整单 → 审批通过，金蝶状态保持"已同步"快照（"重新推送"按钮因此亮起）；③ 前端提示：**"原结算单已推送金蝶，请财务人员在金蝶手工完成旧应付/应收单冲销处理"** |
|
||||
| 3 | 财务 | **在金蝶系统内手工冲销**旧的应付/应收单 | TMS 不参与，这是金蝶侧的人工操作 |
|
||||
| 3 | 财务 | **在金蝶系统内手工冲销**旧的应付/应收单 | TMS 不参与，这是金蝶侧的人工操作；冲销完成后**无需通知 TMS**——正式结算单列表的「金蝶冲销状态」约 10 分钟内自动变为"已冲销"（见 2.4），看到变绿即可回 TMS 重推 |
|
||||
| 4 | 业务 | 回到 TMS，点"重新推送（高危）"并二次确认 | 系统依次：① 硬闸门——按原结算单号去金蝶查旧单，**必须已冲销**（部分冲销也算已冲销），未冲销直接拒绝；② **克隆一张新的正式结算单**（全新 FJS/SJS 单号），把调整应用上去，直接置为审批通过（新单不再走审批流）；③ 用新单号推送金蝶，生成**全新**的财务应付/应收单 + 落锁 + 附件；④ 调整单改挂到新单，回填"已同步 + 金蝶单据号"；⑤ 原单标记"已调整"，原单在金蝶的旧锁解锁 |
|
||||
| 5 | 系统 | — | 完成。此时列表里**新旧两张正式结算单并存**，带标识区分（见第六节） |
|
||||
|
||||
@@ -165,6 +184,7 @@
|
||||
| 部分冲销 | 视同已冲销，放行重推 |
|
||||
| 审批时原单刚好已被推送到金蝶 | 按**当下**状态走场景 B，选单时的预检结论不作数 |
|
||||
| 选单时金蝶超时/不可用 | 预检降级"未校验"，不阻断建单 |
|
||||
| 列表「金蝶冲销状态」与金蝶实际有出入 | 列表为定时同步值，允许滞后约 10 分钟；重推一律以闸门实时校验为准，不影响拦截准确性 |
|
||||
| 重推成功前原单旧锁残留 | 重推成功时统一解锁 |
|
||||
| 应收结算单 | 与应付完全同一套流程，仅接口不同（应收 A302 系 / 应付 A102 系） |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user