docs(finance): 司导往来账账页+明细两接口上线 changelog（#8626）

新增 /admin/finance/statements/guide-ledger/page + /entries 两接口，按带团服务人员（导游/司机/摄影/领队）聚合报账+预支现算净往来。关联 PR #8574（初版）+ #8627（口径扩摄影/领队），Issue #8555 + #8626。
2026-09-30 10:04:41 +08:00
@@ -0,0 +1,256 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8626"
+title: "司导往来账账页+明细分页两接口上线：按带团服务人员聚合报账+预支净往来（role 取值含摄影/领队）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "财务往来账新增「司导往来账」两个只读查询接口（/admin/finance/statements/guide-ledger/page 账页 + /entries 明细），按带团服务人员（司导）聚合其报账单+预支单现算净往来，纯查询零 DDL、不动 fin_statement_entry、不接上游流水钩子。口径要点：①司导=带团服务人员（导游 GUIDE/司机 DRIVER/摄影 PHOTOGRAPHER/领队 LEADER，均非内部员工），员工借款 fin_staff_loan 不纳入；②净往来只算已生效报账单（排除 PENDING 未批准/RETURNED 已退回），预支算 APPROVED/PAID；③聚合键=报账人/收款人姓名快照（reporterAssignmentId 与 payeeStaffId 分属两套 ID 空间无法 join）；④netBalance 正=司导欠公司、负=公司欠司导。两接口入参/出参/枚举/错误码自 2026-09-30 上线起即为本文口径，无历史版本。前端无既有调用，纯新对接。"
+updated_at: "2026-09-30"
+base: "dev-v3"
+---
+
+# finance：司导往来账账页 + 明细分页（管理后台）
+
+**服务**: hl-order-service-v3（finance 模块，同进程）
+**PR**: https://git.1814.love/wx/HL/pulls/8574 （账页初版） + https://git.1814.love/wx/HL/pulls/8627 （口径扩摄影/领队）
+**Issue**: https://git.1814.love/wx/HL/issues/8555 + https://git.1814.love/wx/HL/issues/8626
+
+---
+
+## 一、接口背景
+
+管理后台「财务 → 往来账」需要一本**司导往来账**：以「带团服务人员（司导）」为单位，把该人的**报账单**（多退少补结算净额）和**预支单**（借款挂账）合并，现算出他当前与公司的净往来余额（谁欠谁、欠多少），并能下钻看每一笔单据。
+
+此前往来账只有供应商一本（`fin_statement_entry`），且只接通应付/预付源；司导/员工的报账、预支走的是另一套表（`fin_reimburse` / `fin_advance`），没有按人聚合的账页。本期新增两个只读接口补齐，**纯查询聚合、零 DDL、不改任何既有账表**。
+
+---
+
+## 二、变更清单
+
+| 项 | 变更 |
+|---|---|
+| `GET /admin/finance/statements/guide-ledger/page` | **新增**：司导往来账账页分页（按人聚合） |
+| `GET /admin/finance/statements/guide-ledger/entries` | **新增**：司导往来明细分页（报账+预支合并，按日期倒序） |
+| 出参 `role` 取值集合 | 司导角色快照，取值 ∈ `GUIDE/DRIVER/PHOTOGRAPHER/LEADER`（带团服务人员） |
+| 数据库表 | 零 DDL |
+
+> 这两个接口是**首次上线**，前端无既有调用，按新对接处理即可。
+
+---
+
+## 三、接口详情
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/admin/finance/statements/guide-ledger/page` | GET | 账页：每个司导一行，聚合其报账净额 + 预支挂账，现算净往来余额 |
+| `/admin/finance/statements/guide-ledger/entries` | GET | 明细：某个司导名下的报账单+预支单逐笔列出，按单据日期倒序 |
+
+---
+
+## 四、接口入参
+
+### 4.1 `GET /page`（`GuideLedgerPageReqVO`）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `pageNo` | int | ✅ | 页码，从 1 开始 |
+| `pageSize` | int | ✅ | 每页条数 |
+| `keyword` | string | ❌ | 司导姓名（模糊，匹配报账人/收款人姓名快照）；空=不限 |
+| `onlyOutstanding` | boolean | ❌ | true=只看有往来的司导（净往来≠0 或有未结清单据）；默认 false |
+
+> 账页**暂无 role 过滤入参**（角色只在出参 `role` 体现）；如需按角色过滤，前端可本地过滤或后续提需求加参。
+
+### 4.2 `GET /entries`（`GuideLedgerEntryReqVO`）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `pageNo` | int | ✅ | 页码 |
+| `pageSize` | int | ✅ | 每页条数 |
+| `reporterAssignmentId` | long | 三选一 | 报账人人员分配 ID（账页行 `reporterAssignmentId` 原样带回） |
+| `payeeStaffId` | long | 三选一 | 收款人员工 ID（账页行 `payeeStaffId` 原样带回） |
+| `reporterName` | string | 三选一 | 司导姓名（账页行 `staffName` 原样带回，精确匹配） |
+| `bizType` | string | ❌ | 单据类型过滤：`REIMBURSE` 只看报账 / `ADVANCE` 只看预支；空=两者都要 |
+
+> **司导标识三选一必填**（`reporterAssignmentId` / `payeeStaffId` / `reporterName` 至少填一个，全空 → 596010）。由前端从账页行**原样带回**；匹配规则：ID 精确 或 姓名精确，任一命中即归属该司导。
+
+---
+
+## 五、接口出参
+
+### 5.1 账页行（`GuideLedgerRowRespVO`，`data.records[]`）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `reporterAssignmentId` | long(string) | 报账人人员分配 ID 快照（明细下钻回传用；可空） |
+| `payeeStaffId` | long(string) | 收款人员工 ID 快照（预支线，明细下钻回传用；可空） |
+| `staffName` | string | 司导姓名（聚合键） |
+| `role` | string | 角色快照（`GUIDE` 导游 / `DRIVER` 司机 / `PHOTOGRAPHER` 摄影 / `LEADER` 领队；同一人多角色取任一非空；纯预支无报账可空） |
+| `reimburseReceivableTotal` | number | 报账应收合计（RECEIVABLE 方向净额合计，司导欠公司） |
+| `reimbursePayableTotal` | number | 报账应付合计（PAYABLE 方向净额绝对值合计，公司欠司导） |
+| `advanceTotal` | number | 预支挂账合计（APPROVED/PAID 预支金额合计，多退少补待核单轧差） |
+| `netBalance` | number | **净往来余额（正=司导欠公司 / 负=公司欠司导 / 0=两清）** |
+| `outstandingCount` | int | 未结清单据数（报账未两清终态单数 + 预支在途单数） |
+
+### 5.2 明细行（`GuideLedgerEntryRespVO`，`data.records[]`）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | long(string) | 单据 ID（REIMBURSE=reimburse_id / ADVANCE=advance_id） |
+| `bizType` | string | 单据类型：`REIMBURSE` 报账 / `ADVANCE` 预支 |
+| `bizNo` | string | 单号（报账单号 BZ- / 预支单号 YZ-） |
+| `orderNo` | string | 团号（订单号快照；可空） |
+| `amount` | number | 金额（报账=结算金额 \|净额\|，预支=预支金额，恒正） |
+| `direction` | string | 方向：`PAYABLE` 公司欠司导 / `RECEIVABLE` 司导欠公司 / `BALANCED` 两清（预支恒 RECEIVABLE） |
+| `status` | string | 单据状态（报账 PENDING/APPROVED/PARTIAL_RECEIVED/PAID/RECEIVED/CLOSED；预支 APPROVED/PAID） |
+| `bizDate` | datetime | 单据日期（推送生成时间） |
+
+> 分页结构：`data.records[]` + `data.total` + `data.page` + `data.pageSize`（PageResult，**注意是 `records` 不是 `list`**）。
+> 长整型 ID（`reporterAssignmentId`/`payeeStaffId`/`id`）JSON 序列化为字符串，前端按字符串处理防精度丢失。
+
+---
+
+## 六、枚举 / 数据字典
+
+### role 司导角色（快照值，非字典）
+`GUIDE` 导游 / `DRIVER` 司机 / `PHOTOGRAPHER` 摄影师 / `LEADER` 领队
+> 口径：带团服务人员，**均非内部员工**；其余角色（含内部员工）不进司导往来账。员工借款 fin_staff_loan 不纳入。
+
+### bizType 单据类型
+`REIMBURSE` 报账 / `ADVANCE` 预支
+
+### direction 方向
+`PAYABLE` 公司欠司导 / `RECEIVABLE` 司导欠公司 / `BALANCED` 两清
+
+### status 单据状态（状态机枚举，各源不同）
+- 报账：`PENDING` 待复核 / `APPROVED` 已批准 / `PARTIAL_RECEIVED` 部分回款 / `PAID` 已付讫 / `RECEIVED` 已回款 / `CLOSED` 已两清（`RETURNED` 已退回不计入往来）
+- 预支：`APPROVED` 已批准 / `PAID` 已付款
+
+---
+
+## 七、错误码
+
+| 码 | 含义 |
+|---|---|
+| 596010 | 司导标识缺失（entries 三选一全空） |
+
+---
+
+## 八、示例
+
+### 8.1 账页（典型）
+
+```
+GET /admin/finance/statements/guide-ledger/page?pageNo=1&pageSize=10
+```
+
+```json
+{
+  "code": 200,
+  "data": {
+    "records": [
+      {
+        "reporterAssignmentId": null,
+        "payeeStaffId": "2100747615736897537",
+        "staffName": "刘大山",
+        "role": null,
+        "reimburseReceivableTotal": 0,
+        "reimbursePayableTotal": 0,
+        "advanceTotal": 260.00,
+        "netBalance": 260.00,
+        "outstandingCount": 1
+      }
+    ],
+    "total": 1, "page": 1, "pageSize": 10
+  }
+}
+```
+
+### 8.2 明细分页（按收款人 ID 下钻）
+
+```
+GET /admin/finance/statements/guide-ledger/entries?pageNo=1&pageSize=10&payeeStaffId=2100747615736897537
+```
+
+```json
+{
+  "code": 200,
+  "data": {
+    "records": [
+      { "id": "2201...", "bizType": "ADVANCE", "bizNo": "YZ-202609290001",
+        "orderNo": null, "amount": 260.0, "direction": "RECEIVABLE",
+        "status": "APPROVED", "bizDate": "2026-09-29T10:00:00" }
+    ],
+    "total": 1, "page": 1, "pageSize": 10
+  }
+}
+```
+
+### 8.3 业务失败（entries 三选一全空 → 596010）
+
+```
+GET /admin/finance/statements/guide-ledger/entries?pageNo=1&pageSize=10
+```
+
+```json
+{ "code": 596010, "message": "司导标识缺失" }
+```
+
+---
+
+## 九、业务边界
+
+- **纯查询聚合**：两接口只读，不写任何表、不改 fin_statement_entry、不接上游流水钩子；净往来为现算不落列。
+- **只算生效单**：报账单排除 PENDING（未批准不生效）与 RETURNED（已退回，由 version_no+1 新单承接防双算）；预支算 APPROVED/PAID。
+- **聚合键=姓名快照**：reporterAssignmentId（order 域人员分配 ID）与 payeeStaffId（员工 ID）分属两套 ID 空间无法 join，故按报账人/收款人姓名快照聚合；姓名缺失时退化按 ID 单列。
+- **净额方向**：netBalance 正=司导欠公司、负=公司欠司导、0=两清。报账 PAYABLE 方向（公司欠司导）取净额绝对值计入 reimbursePayableTotal。
+- **不含员工借款**：司导/摄影/领队均非内部员工，fin_staff_loan 不纳入。
+
+---
+
+## 十、修改前后对比
+
+新增接口，无修改前版本。
+
+| 维度 | 说明 |
+|---|---|
+| 接口 | 首次上线，前端无既有调用 |
+| role 取值 | 上线即为 4 角色（GUIDE/DRIVER/PHOTOGRAPHER/LEADER），无历史 2 角色版本对外暴露 |
+
+---
+
+## 十一、影响评估 / 回滚
+
+- 后端：新增两个只读端点，零 DDL、零既有逻辑改动；回滚=下线两接口（前端无依赖）。
+- 前端：纯新对接，无回归面。
+- 数据库：无变更。
+
+---
+
+## 十二、注意事项
+
+- 分页结构是 `data.records[]`（PageResult），**不是 `list`**，前端取数组时注意。
+- 长整型 ID 序列化为字符串，按字符串处理。
+- entries 下钻时，账页行的 `reporterAssignmentId`/`payeeStaffId`/`staffName` **原样带回**即可（三选一，无需自己拼）。
+- `role` 可能为 null（纯预支无报账的司导），前端渲染时对 null 做兜底（显示「-」或留空），不要假设非空。
+
+---
+
+## 十三、关联 / 联系人
+
+### 13.1 链接
+
+- 账页初版 PR：https://git.1814.love/wx/HL/pulls/8574
+- 口径扩展 PR：https://git.1814.love/wx/HL/pulls/8627
+- Issue：https://git.1814.love/wx/HL/issues/8555 、https://git.1814.love/wx/HL/issues/8626
+
+### 13.2 联系人
+
+- 后端 / 财务域：yst(腰苏图)