hl-api-changelog/changelogs-v2/2026-09/30_8626_司导往来账账页与明细-新增接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8626	司导往来账账页+明细分页两接口上线：按带团服务人员聚合报账+预支净往来（role 取值含摄影/领队）	admin	yst(GIT)	新增接口	deployed	not_required	implemented	hl-admin	1a337d86d556062cd78daf7a94ba3a42ac310dce	v2.1	2026-09-30	财务往来账新增「司导往来账」两个只读查询接口（/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 上线起即为本文口径，无历史版本。前端无既有调用，纯新对接。前端已交付:statement.js 加司导段(API 层 page→pageNo,字典四 role/两 bizType/三 direction/PAID 分文案);新建 current-account/guide 页内 v-if 双视图(账页 netBalance 三态+明细三选一标识原样带回);hiddenRoute 先行(后端 sys_menu 未下挂,预期 component=finance/current-account/guide)。	2026-09-30	dev-v3

finance：司导往来账账页 + 明细分页（管理后台）

服务: hl-order-service-v3（finance 模块，同进程） PR: wx/HL#8574 （账页初版） + wx/HL#8627 （口径扩摄影/领队） Issue: wx/HL#8555 + wx/HL#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

{
  "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

{
  "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

{ "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：wx/HL#8574
• 口径扩展 PR：wx/HL#8627
• Issue：wx/HL#8555 、wx/HL#8626

13.2 联系人

• 后端 / 财务域：yst(腰苏图)