From 26e995a97e04a729128e1f271d9a897adf1e3274 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Fri, 18 Sep 2026 11:28:02 +0800
Subject: [PATCH] =?UTF-8?q?feat(changelog):=20=E5=8F=B8=E5=AF=BC=E9=A2=84?=
 =?UTF-8?q?=E6=94=AF=EF=BC=88=E5=8F=B8=E5=AF=BC=E5=80=9F=E6=AC=BE=EF=BC=89?=
 =?UTF-8?q?=E6=94=AF=E4=BB=98=E9=93=BE=E6=8E=A5=E9=80=9A=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E5=87=BA=E7=BA=B3=20ADVANCE=20=E9=A1=B5=E7=AD=BE=20queue/pay?=
 =?UTF-8?q?=20=E7=9C=9F=E5=AE=9E=E6=8E=A5=E9=80=9A=EF=BC=88Epic=20#7901?=
 =?UTF-8?q?=EF=BC=8CPR=20#7902/#7906/#7910=20=E5=B7=B2=E5=90=88=E5=B9=B6?=
 =?UTF-8?q?=20dev-v3=20=E9=83=A8=E7=BD=B2=E6=B5=8B=E8=AF=95=E6=9C=8D=20E2E?=
 =?UTF-8?q?=20=E9=80=9A=E8=BF=87=EF=BC=9B=E5=8E=9F=20598607=20=E7=A9=BA?=
 =?UTF-8?q?=E5=A3=B3=E4=B8=8B=E7=BA=BF=EF=BC=8C=E9=87=91=E9=A2=9D=E9=94=81?=
 =?UTF-8?q?=E6=AD=BB=20598610=EF=BC=8C=E6=96=B0=E5=A2=9E=E9=94=99=E8=AF=AF?=
 =?UTF-8?q?=E7=A0=81=20599500-599505=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...01_司导预支支付链接通-新增接口-管理后台.md | 438 ++++++++++++++++++
 1 file changed, 438 insertions(+)
 create mode 100644 changelogs-v2/2026-09/18_7901_司导预支支付链接通-新增接口-管理后台.md

diff --git a/changelogs-v2/2026-09/18_7901_司导预支支付链接通-新增接口-管理后台.md b/changelogs-v2/2026-09/18_7901_司导预支支付链接通-新增接口-管理后台.md
new file mode 100644
index 00000000..5fdbf31c
--- /dev/null
+++ b/changelogs-v2/2026-09/18_7901_司导预支支付链接通-新增接口-管理后台.md
@@ -0,0 +1,438 @@
+---
+schema: "hl-changelog/v2"
+ticket: "advance-cashier-pay-link"
+title: "司导预支（司导借款）支付链接通——出纳 ADVANCE 页签 queue/pay 两端点真实接通（原 598607 空壳下线）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-18"
+status_note: "财务出纳「司导借款支付」页签（ADVANCE）此前在拆壳合芯 #7855 中为预留空壳，queue/pay 调用一律 598607「预留未接通，前端勿接」。本次 Epic #7901（PR #7902/#7906/#7910，已全部合并 dev-v3 并部署测试服，E2E 验证通过）真实接通：order 域预支审批通过后自动推送生成财务执行单 fin_advance（APPROVED）进入出纳待支付队列；出纳登记付款后记资金流水 OUT、执行单回写 PAID，并事件回写 order 域 order_advance PAID。路径沿用拆壳时已分配的 GET/POST /admin/finance/cashier/advance/{queue,pay}（非 /v3 前缀），入参/出参结构与拆壳契约一致，本次仅把行为从 598607 改为真实业务；付款金额锁死=队列行 amount（598610），前端应禁用金额输入直接回填。"
+updated_at: "2026-09-18"
+base: "dev-v3"
+---
+
+# 司导预支（司导借款）支付链接通（管理后台）
+
+> **服务**: hl-order-service-v3（hl-finance 模块，端口 8086，财务表与 order v3 同库 hl_order_service_v3）
+> **类型**: 预留空壳真实接通（路径/入参/出参字段结构沿用 #7855 拆壳契约不变，行为从 598607 改为真实业务，前端视角等价新增可对接接口）
+> **日期**: 2026-09-18
+> **影响范围**: 管理后台财务域「出纳支付管理 - 司导借款支付（ADVANCE）」页签（原置灰/勿接，现可对接）
+> **覆盖 Epic**: #7901（PR #7902 地基 fin_advance 表+错误码 / PR #7906 审批推送+队列接通 / PR #7910 出纳付款接通+事件回写+菜单）
+
+---
+
+## 一、接口背景
+
+司导预支（司导借款）= 订单执行中司机/导游向公司预借的备用金，从公司资金账户真实出款，属于出纳付款业务。完整链路：
+
+```
+订单详情创建预支（SUBMITTED 待审批）
+  -> 财务审批通过（order 域 order_advance APPROVED）
+    -> 自动推送生成财务执行单 fin_advance（状态 APPROVED，进入出纳 ADVANCE 待支付队列）
+      -> 出纳在「司导借款支付」页签登记付款（记资金流水 OUT）
+        -> fin_advance 回写 PAID；同事务事件回写 order 域 order_advance PAID（队列出队）
+```
+
+关键口径：
+
+- **队列只有一笔状态**：队列内单据 status 恒为 APPROVED（已审批待支付）；付款成功翻 PAID 后自动出队。无草稿/审批中/驳回单，也没有独立复核环节。
+- **金额推送时冻结**：财务执行单金额是审批通过时的快照，出纳付款金额**锁死**（须严格等于队列行 amount，不一致 598610 硬拦），不允许改额。
+- **队列无手续费**：预支线无手续费概念，队列行 fee 恒为 0、actualAmount = amount；付款入参 fee 不传或传 0。
+- **付款成功有最终一致旁路**：order 域预支单状态由事件 AFTER_COMMIT 回写，极端情况下回写失败只告警不影响付款主链（财务侧已 PAID、钱已出账为准）。
+
+此前状态（#7855 拆壳合芯，见 changelog 台账 214）：ADVANCE 页签两个端点是契约占位空壳，调用一律返 **598607「付款类型非法…ADVANCE 司导预支」预留未接通**，前端被要求勿接。**本次起该页签真实可用，598607 不再可能由这两个端点返回。**
+
+---
+
+## 二、变更清单
+
+| # | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|----------|------|
+| 1 | GET | /admin/finance/cashier/advance/queue | 空壳转接通 | 司导预支待付款队列：原一律 598607，现真实返回 fin_advance 中 status=APPROVED 分页 |
+| 2 | POST | /admin/finance/cashier/advance/pay | 空壳转接通 | 司导预支登记付款：原一律 598607，现真实记 OUT 流水 + 回写 PAID + 事件回写 order_advance |
+| 3 | 错误码段位 599500-599599 | 新增 | 预支支付链专属段位（hl-finance），启用 599500/599501/599502/599504/599505（599503 预留） |
+| 4 | 页签标识 ADVANCE | 可启用 | 出纳 8 页签之一；台账接口 bizType=ADVANCE 同步可见（已付款流水） |
+
+> 路径前缀为 /admin/finance/cashier/advance（**无 /v3 版本前缀**，与其余 7 个出纳页签一致，经网关 /admin 路由到 hl-finance）。
+
+---
+
+## 三、接口详情
+
+| 项 | 说明 |
+|---|---|
+| 使用场景 | 管理后台「财务 - 出纳支付管理 - 司导借款支付」页签：拉待支付队列、对单笔预支登记付款 |
+| 认证 | 管理后台 JWT（网关统一鉴权），需出纳付款相关菜单/按钮权限 |
+| 幂等性 | queue 只读幂等。pay 为 APPROVED 到 PAID 条件更新（CAS）：服务端先对单据行 SELECT ... FOR UPDATE 行锁 + 锁内状态校验，重复付款/并发重复提交后到的请求返 **599502**，资金流水随事务回滚不留孤儿流水，重复提交安全 |
+| 限流 | 走网关统一限流，无模块特殊限流 |
+| ID 序列化 | 所有 Long 型 ID（队列行 id、入参 bizId/payAccountId、出参 flowId/bizId）JSON 中均为 **String**，防 JS 精度丢失；前端回传 bizId 时按字符串原样回传即可 |
+| 单据状态机 | APPROVED（已审批待支付，推送即此态，队列内唯一状态）到 PAID（已支付，出纳付款回写，终态） |
+| 排序与分页 | 队列按 advance_id 倒序（最新推送在前），分页 page/pageSize，默认 page=1、pageSize=20 |
+
+---
+
+## 四、接口入参
+
+### 4.1 待付款队列 GET /admin/finance/cashier/advance/queue（Query 参数 CashierQueueFormReqVO）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 | 校验 |
+|------|------|------|------|------|------|
+| page | Integer | 否 | 1 | 页码 | 大于等于 1；兼容别名 pageNo（传 pageNo 等价） |
+| pageSize | Integer | 否 | 20 | 每页条数 | 1-100，超 100 返 400 |
+
+> 无任何业务筛选参数（不按状态/日期/单号筛选），队列固定只捞 APPROVED 单。
+
+### 4.2 登记付款 POST /admin/finance/cashier/advance/pay（JSON body CashierPayFormReqVO）
+
+| 字段 | 类型 | 必填 | 说明 | 校验/联动 |
+|------|------|------|------|-----------|
+| bizId | Long（JSON 字符串） | 是 | 业务单据ID，**取队列行 id**（fin_advance.advance_id） | 非空；不存在/已软删 -> 599500 |
+| payAccountId | Long（JSON 字符串） | 是 | 出账公司账户ID（fin_fund_account，资金账户下拉选择） | 非空；账户不存在/停用 -> 598603 |
+| payMethod | String | 建议必传 | 付款方式，字典 fin_pay_way 码值：CASH 现金 / BANK 银行转账 / THIRD_PARTY 三方支付 | 与 payChannel、账户类型三级联动（见 §六、§九）；不传时跳过方式-账户校验，不建议前端留空 |
+| payChannel | String | 条件必填 | 付款渠道：WXPAY 微信支付 / ALIPAY 支付宝；**仅 payMethod=THIRD_PARTY 时传**，CASH/BANK 不得传 | 最长 20；组合不匹配 -> 598608 |
+| amount | Number | 是 | 付款金额，**必须等于队列行 amount（金额锁死，前端禁用编辑直接回填）** | 非空且大于 0（否则 598605）；与快照不一致 -> 598610 |
+| fee | Number | 否 | 手续费（大于等于 0，挂出账流水）；预支线固定传 0 或不传 | 负数 -> 598605 |
+| voucherNo | String | 否 | 付款凭证号（如银行回单流水号） | - |
+| voucherUrl | String | 否 | 付款凭证影像 URL（OSS 地址） | - |
+| payDate | String | 是 | 付款日期，格式 **yyyy-MM-dd**，可回溯补录（允许选今天以前的日期） | 非空；格式非法 -> 400 |
+
+> 入参里**没有** bizType/payType（路径即类型），也**没有**经办人/operatorName（后端自动取当前登录人快照，前端伪造无效）。
+
+---
+
+## 五、出参字段
+
+### 5.1 队列出参：Result&lt;PageResult&lt;AdvanceQueueRowRespVO&gt;&gt;
+
+外层为统一包装 Result（code/message/data/traceId/success），data 为分页结构 records / total / page / pageSize。
+
+records[] 每行字段（共 10 个）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 单据ID（fin_advance 雪花 ID）。**付款时作为 bizId 原样回传** |
+| bizNo | String | 业务单号 = 预支单号，格式 YZ- + yyyyMMdd + 4 位序号（如 YZ-20260918-0007） |
+| amount | Number | 付款金额（审批通过时快照冻结，**即付款金额锁死基准**） |
+| fee | Number | 手续费，预支线**恒为 0** |
+| actualAmount | Number | 实付 = amount − fee；预支线下恒等于 amount |
+| operatorName | String | 借款对象姓名快照（收款人/司导姓名 payeeName，改名不追溯） |
+| createTime | String | 推送时间，yyyy-MM-dd HH:mm:ss（fin_advance 建单时间，即审批通过推送时间） |
+| occurDate | String | 发生日期（yyyy-MM-dd）；**fin_advance 无来源列，恒返回 null**，前端渲染用「-」兜底即可 |
+| status | String | 单据状态，队列内恒为 APPROVED |
+| remark | String | 备注；**fin_advance 无备注列，恒返回 null** |
+
+> 队列行不返回订单号/借款类型/收款人 ID 等字段（单号 YZ- 与借款对象姓名为页面展示锚点；如需订单号需走 order 域预支详情接口，不在本页签契约内）。
+
+### 5.2 付款出参：Result&lt;CashierPayRespVO&gt;
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| flowId | String | 资金流水ID（fin_fund_flow 雪花 ID） |
+| flowNo | String | 资金流水号，格式 LS + yyyyMMdd + 4 位序号（如 LS202609180012） |
+| balanceAfter | Number | 本笔记完后出账账户结存快照（可用于付款成功提示「账户余额 xxx」） |
+| bizId | String | 业务单据ID（fin_advance.advance_id，已回写 PAID），与入参 bizId 相同 |
+
+---
+
+## 六、枚举 / 数据字典
+
+### 6.1 单据状态 status（队列行出参）
+
+| 值 | 中文 | 是否在队列 |
+|----|------|-----------|
+| APPROVED | 已审批待支付 | 是，队列内唯一值 |
+| PAID | 已支付（终态） | 否，付款后出队 |
+
+### 6.2 付款方式 payMethod（字典 fin_pay_way）
+
+| 值 | 中文 | 渠道约束 | 账户约束 |
+|----|------|----------|----------|
+| CASH | 现金 | 不得传 payChannel | 须选现金类账户 |
+| BANK | 银行转账 | 不得传 payChannel | 须选银行类账户 |
+| THIRD_PARTY | 三方支付 | **必传** payChannel=WXPAY/ALIPAY | 须选对应渠道的商户号账户 |
+
+### 6.3 付款渠道 payChannel
+
+| 值 | 中文 |
+|----|------|
+| WXPAY | 微信支付 |
+| ALIPAY | 支付宝 |
+
+### 6.4 页签标识 ADVANCE
+
+出纳已付款流水台账 GET /admin/finance/cashier/payments/page（8 页签共用，本次契约不变）查本页签已付款流水时传 bizType=ADVANCE；台账中 ADVANCE 单号前缀为 YZ-。
+
+---
+
+## 七、错误码
+
+响应体形态：{"code": 码值, "message": "文案", "traceId": "...", "success": false}，HTTP 状态码通常仍为 200（业务错误码在 body.code）。
+
+### 7.1 预支支付链专属（段位 599500-599599，本次新增）
+
+| code | message | 触发场景 | 前端处理建议 |
+|------|---------|----------|-------------|
+| 599500 | 预支单不存在 | bizId 无效或已被软删（如拿旧队列数据付款） | 提示「预支单不存在」并刷新队列 |
+| 599501 | 预支单非待支付状态 | 单据既不是 APPROVED 也不是 PAID（异常中间态/并发状态漂移） | 提示后刷新队列 |
+| 599502 | 预支单已支付 | 重复付款：单据已 PAID；含并发下 CAS 条件更新 0 行兜底 | 提示「该单已支付，请勿重复付款」并刷新队列（该单应已消失） |
+| 599503 | 预支金额非法 | **预留码，当前付款链路不抛出（勿按此码写分支）**；语义为 amount 为 null 或小于等于 0 的脏数据拦截 | - |
+| 599504 | 预支单已推送过财务 | order 域审批推送侧防重复推送（uk 约束/取号撞号重试耗尽）。**出纳前端正常操作遇不到** | 出现属后端异常，报 traceId |
+| 599505 | 预支推送快照数据非法 | order 域推送入口快照字段缺失/金额小于等于 0 fail-fast。**出纳前端遇不到** | 出现属后端异常，报 traceId |
+
+### 7.2 复用车看出纳通用码（段位 598600-598699）
+
+| code | message | 触发场景 |
+|------|---------|----------|
+| 598603 | 出账账户不存在或已停用 | payAccountId 无效 / 账户被停用（弹窗前请重新拉账户下拉） |
+| 598604 | 账户余额不足且不允许透支 | 出账账户余额不够且未开透支 |
+| 598605 | 付款金额无效（金额须大于0，手续费不得为负） | amount 小于等于 0 / null，或 fee 小于 0（前端锁死回填正常不会触发） |
+| 598608 | 收付方式与收付渠道不匹配（THIRD_PARTY 须传渠道 WXPAY/ALIPAY，其余方式不得传渠道） | THIRD_PARTY 没传/传了非法 payChannel；或 CASH/BANK 带了 payChannel |
+| 598609 | 收付账户与收付方式不匹配（现金方式须选现金账户、银行转账须选银行账户、三方支付须选对应渠道商户号账户） | 付款方式与所选账户类型不一致；THIRD_PARTY 时渠道与账户渠道不一致 |
+| 598610 | 付款金额与单据应付金额不一致（出纳付款须严格按审批应付金额，不得修改） | **金额锁死**：amount 不等于队列行快照金额（含前端误传/用户改额） |
+| 598607 | 付款类型非法（含 ADVANCE 司导预支文案） | **接通后这两个端点不会再返回**；若仍见到 598607 说明打到旧版本后端，先确认部署版本 |
+
+### 7.3 参数校验错误
+
+JSR-303 注解校验失败（bizId/payAccountId/amount/payDate 为空、pageSize 大于 100、payDate 格式错误等）走全局 400 校验响应，字段级 message 为中文（如「业务单据ID不能为空」「付款日期不能为空」）。
+
+---
+
+## 八、示例
+
+### 8.1 典型成功——拉队列 -> 登记银行转账付款
+
+**第 1 步：拉待付款队列**
+
+请求：
+```
+GET /admin/finance/cashier/advance/queue?page=1&pageSize=20
+Authorization: Bearer <管理后台 JWT>
+（无请求体）
+```
+
+响应：
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "id": "1962180000000000101",
+        "bizNo": "YZ-20260918-0007",
+        "amount": 3000.00,
+        "fee": 0,
+        "actualAmount": 3000.00,
+        "operatorName": "布仁",
+        "createTime": "2026-09-18 09:12:35",
+        "occurDate": null,
+        "status": "APPROVED",
+        "remark": null
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 20
+  },
+  "traceId": "a1b2c3d4-e5f6-7890",
+  "success": true
+}
+```
+
+无待支付单时（空态）：
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "traceId": "a1b2c3d5-e5f6-7891",
+  "success": true
+}
+```
+
+**第 2 步：登记付款（金额回填队列 amount，禁用编辑）**
+
+请求：
+```
+POST /admin/finance/cashier/advance/pay
+Authorization: Bearer <管理后台 JWT>
+Content-Type: application/json
+```
+```json
+{
+  "bizId": "1962180000000000101",
+  "payAccountId": "1956000000000000001",
+  "payMethod": "BANK",
+  "amount": 3000.00,
+  "fee": 0,
+  "voucherNo": "TRANS20260918007",
+  "voucherUrl": "https://oss.example.com/voucher/20260918/yz0007.pdf",
+  "payDate": "2026-09-18"
+}
+```
+
+响应：
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "flowId": "1962190000000000202",
+    "flowNo": "LS202609180012",
+    "balanceAfter": 87600.00,
+    "bizId": "1962180000000000101"
+  },
+  "traceId": "b2c3d4e5-f6a7-8901",
+  "success": true
+}
+```
+
+付款成功后该单 fin_advance 已 PAID 并出队；前端刷新队列此单消失，可在已付款流水台账（bizType=ADVANCE）查到 LS202609180012。
+
+### 8.2 边界情况——重复付款被拦截（599502）
+
+**场景**：同一队列行连续点了两次「确认付款」（或两个出纳同时操作）。第一笔成功，第二笔在服务端行锁内见到单据已 PAID。
+
+请求（与 8.1 第 2 步完全相同的报文再发一次）
+
+响应：
+```json
+{
+  "code": 599502,
+  "message": "预支单已支付",
+  "traceId": "c3d4e5f6-a7b8-9012",
+  "success": false
+}
+```
+
+前端处理：提示「该预支单已支付，请勿重复付款」，重新拉队列（该单已不在队列），不要重试原请求。
+
+> 同形态的陈旧数据边界：拿着已过期的队列缓存付款，若单据已支付同样是 599502；若单据被软删则是 599500。
+
+### 8.3 业务失败——付款金额与单据不一致（598610，金额锁死）
+
+**场景**：前端未锁死金额（或被人为改成 2800.00）。
+
+请求：
+```
+POST /admin/finance/cashier/advance/pay
+Authorization: Bearer <管理后台 JWT>
+Content-Type: application/json
+```
+```json
+{
+  "bizId": "1962180000000000101",
+  "payAccountId": "1956000000000000001",
+  "payMethod": "BANK",
+  "amount": 2800.00,
+  "payDate": "2026-09-18"
+}
+```
+
+响应：
+```json
+{
+  "code": 598610,
+  "message": "付款金额与单据应付金额不一致（出纳付款须严格按审批应付金额，不得修改）",
+  "traceId": "d4e5f6a7-b8c9-0123",
+  "success": false
+}
+```
+
+其他高频失败形态（响应结构同上，换 code/message）：
+
+- 三方支付没选渠道：598608「收付方式与收付渠道不匹配…」
+- 现金方式选了银行账户：598609「收付账户与收付方式不匹配…」
+- 账户余额不足：598604「账户余额不足且不允许透支」
+- 必填缺失（如 payDate 未传）：HTTP 400 全局校验响应，message「付款日期不能为空」
+
+---
+
+## 九、业务边界
+
+- **适用**：队列仅展示 status=APPROVED 的预支财务执行单（来源：order 域预支审批通过自动推送）；出纳对其登记付款。
+- **不适用**：
+  - 草稿 / 待审批 / 已驳回的预支不进队列（在 order 域审批链路，出纳看不到）。
+  - 已支付 PAID 单不出现在队列；拿旧 bizId 再付款 -> 599502。
+  - 队列查询不支持按单号/借款人/日期筛选（后端固定捞全量 APPROVED 分页）。
+- **金额锁死（最重要）**：pay.amount 必须与队列行 amount 完全一致（BigDecimal 按数值比较，3000 与 3000.00 视为相等），不一致一律 598610。**前端付款弹窗金额输入框应禁用/只读，打开弹窗时用队列行 amount 回填**，不要给出纳留改额入口。
+- **方式-渠道-账户三级匹配**：THIRD_PARTY 必须带 WXPAY/ALIPAY 且选对应渠道商户号账户（否则 598608/598609）；CASH/BANK 不得带 payChannel。
+- **并发安全**：双人同时付同一单不会重复出款——行锁 + CAS，后到者 599502，资金流水随事务回滚。
+- **余额与透支**：账户余额不足且不允许透支 -> 598604，付款整笔失败，单据仍是 APPROVED 留在队列，可换账户/充值后重试。
+- **payDate 可补录**：允许选历史日期（出纳补登场景），不允许空、格式必须 yyyy-MM-dd。
+- **支付后状态回写有旁路延迟**：财务侧 PAID 与出账为同事务强一致；订单侧 order_advance 状态由事件提交后异步回写，前端「订单详情-预支列表」若短时间仍显示待支付可提示刷新，不影响资金结果。
+
+---
+
+## 十、修改前后对比
+
+### 10.1 行为对比（本次为同路径空壳接通）
+
+| 项 | 接通前（#7855 空壳） | 接通后（#7901，本次） |
+|----|----------------------|----------------------|
+| GET .../advance/queue | 直接抛 598607，无任何数据 | 返回 fin_advance APPROVED 分页（10 字段强类型行） |
+| POST .../advance/pay | 直接抛 598607，不出账 | 行锁校验 -> 金额锁死 -> 记 OUT 流水 -> 回写 PAID -> 事件回写 order_advance |
+| 前端策略 | 页签置灰/不接入（文档明确「勿接」） | **正式对接，放开页签** |
+| 路径 / HTTP 方法 / 入参字段 / 出参字段 | - | **完全不变**（拆壳时已按强类型契约建好） |
+| 页签 bizType=ADVANCE 台账 | 无 ADVANCE 流水 | 付款后可见 LS- 流水（台账接口本身无改动） |
+
+### 10.2 错误码对比
+
+| 场景 | 接通前 | 接通后 |
+|------|--------|--------|
+| 调 queue/pay | 598607（任何入参都抛） | 正常业务响应；失败按原因返 599500/599501/599502/598603/598604/598605/598608/598609/598610 |
+| 重复付款 | 598607 | 599502 预支单已支付 |
+
+> 因字段契约零变化，无字段级增删改；前端此前若已按 #7855 文档预埋了 ADVANCE 类型定义，可直接启用。
+
+---
+
+## 十一、影响评估 / 回滚
+
+### 11.1 影响评估
+
+- **是否破坏向后兼容**：否。路径、方法、入参/出参结构均未变；仅行为从「返 598607」变为真实业务，此前无前端真实调用（空壳期约定勿接）。
+- **前端是否必须同步上线**：否，但需要**主动放开**原被要求置灰/勿接的「司导借款支付」页签并接线；不接线不影响其他 7 个页签。
+- **数据/DDL**：PR-1 新建财务执行单表 fin_advance（Flyway 随 hl-finance 部署），队列与付款只读写该表及 fin_fund_flow；老订单无预支数据时队列自然为空。
+- **部署状态**：3 个 PR 已全部合并 dev-v3 并部署测试服，队列 -> 付款 -> PAID 回写 -> order 域状态回写 E2E 验证通过（2026-09-18）。
+
+### 11.2 回滚方案
+
+- 回滚方式：revert PR #7910（付款接通）/ #7906（队列与推送）即可恢复空壳/停推；纯应用层回滚，已产生的 fin_advance/流水数据保留无害。
+- 回滚后队列端点会重新返回 598607，前端页签重新置灰即可，无数据迁移、无缓存清理。
+
+---
+
+## 十二、注意事项（给前端的落地清单）
+
+1. **金额控件锁死**：付款弹窗 amount 用队列行 amount 回填且只读，fee 固定 0；不要做可编辑金额框（后端 598610 会硬拦，放开输入只会制造失败弹窗）。
+2. **bizId 用队列行 id 字符串**：雪花 ID 全程按字符串处理（列表已序列化为 String，直接回传，不要 Number 化）。
+3. **空字段兜底**：队列行 occurDate、remark 恒为 null，列表列用「-」展示，不要当成异常。
+4. **operatorName = 借款对象（司导姓名）**：列名建议展示为「借款对象」，不是「申请人」。
+5. **付款成功后动作**：关闭弹窗 -> 成功提示（可附带 flowNo 与 balanceAfter）-> 重拉 queue（该单应消失）；不要只在本地列表删行后不刷新。
+6. **599502 是正常业务拦截不是系统错误**：按「重复付款」语义提示并刷新队列；599500/599501 同样提示后刷新。599504/599505 出纳端正常不会出现，出现请带 traceId 找后端。
+7. **若 queue/pay 仍收到 598607**：说明请求落到未部署新代码的旧实例/旧环境，先核对环境版本，不要改前端代码适配。
+8. **页签标识**：ADVANCE；单号前缀 YZ-；已付款流水走共用台账 GET /admin/finance/cashier/payments/page?bizType=ADVANCE（契约沿用出纳台账既有约定）。
+9. **业务上游入口**：预支申请/审批在订单详情（order 域端点 /v3/admin/order/{orderId}/advance、/v3/admin/order/advance/{advanceId}/approve 等），出纳页签只负责付款，不负责申请与审批。
+
+---
+
+## 十三、关联 / 联系人
+
+### 13.1 链接
+
+- **Epic Issue**: [#7901](https://git.1814.love:8443/wx/HL/issues/7901)
+- **PR-1（地基 fin_advance + 错误码 5995xx）**: [#7902](https://git.1814.love:8443/wx/HL/pulls/7902) ｜ merge commit [4d4d69a8](https://git.1814.love:8443/wx/HL/commit/4d4d69a8588c2394b525e33e5073a8cce5df95b2)
+- **PR-2（审批推送 + 出纳队列接通）**: [#7906](https://git.1814.love:8443/wx/HL/pulls/7906) ｜ merge commit [9d54a66e](https://git.1814.love:8443/wx/HL/commit/9d54a66ecf7c03ba4b84fbd20fc5e0a7c2d53eeb)
+- **PR-3（出纳付款接通 + 事件回写 + 菜单）**: [#7910](https://git.1814.love:8443/wx/HL/pulls/7910) ｜ merge commit [4cf4ae73](https://git.1814.love:8443/wx/HL/commit/4cf4ae73f3a5f1a10e7ba35f962bb056a669c667)
+- **前序契约（空壳期）**: PR #7855 出纳支付拆壳合芯 changelog《17_7842_出纳支付接口拆壳合芯-修改接口-管理后台》（ADVANCE 当时标注「预留未接通，前端勿接」）
+
+### 13.2 联系人
+
+- **后端负责人**: @yst（腰苏图）