erpnew/docs/FINANCE-API-AGENT-HANDOFF.md

Customer Finance API Handoff For AI Agent

本文档面向会中协作的 AI agent，用于通过当前 API 配合财务人员核实指定客户的销售、销退、收款、退款数据。

Scope

当前只使用这一个接口：

• GET /api/v1/finance/by-customer

当前业务口径已经固定：

• 销售：只认 dbo.I_Sale 中 DanType = 成品销售单
• 销退：只认 dbo.I_Sale 中 DanType = 客户退货单
• 收款：只认 dbo.F_Skd 中 BianHaoID LIKE 'XS%'
• 退款：只认 dbo.F_Skd 中 BianHaoID LIKE 'XT%'

Access

Base URL:

http://43.139.183.222:18080

Authorization header format:

Authorization: <deployment auth secret>

说明：

• 本仓库不写入真实鉴权密钥。
• 实际值请从目标环境部署配置中的 auth.secret 获取。
• 当前系统仍然使用固定值鉴权，不是动态 token。

当前线上固定鉴权值：

• Authorization: your-fixed-authorization-secret

Purpose

该接口用于：

1. 按客户名称精确抽取该客户的指定财务记录。
2. 在会议中快速切换不同记录类型，逐项与财务人员核对。
3. 根据需要区分“真实资金变动”和“挂账/欠款调整”。

Request Shape

GET /api/v1/finance/by-customer?customer_name_b64=...&record_types=...&include_cash_movement=...&include_adjustments=...

参数：

• customer_name_b64: 必填，客户名称的 Base64URL 编码。
• record_types: 可选，逗号分隔，支持 sale、sale_return、receipt、refund。
• include_cash_movement: 可选，布尔值，默认 true。
• include_adjustments: 可选，布尔值，默认 false。

Current Semantics

0. 用户可以查询哪些财务数据

当前支持查询的记录类型只有 4 类：

• sale：销售记录
• sale_return：销退 / 客户退货记录
• receipt：收款 / 回款记录
• refund：退款记录

说明：

• 可以单选一种类型，例如只查 sale_return
• 也可以多选多种类型，例如 sale,receipt
• 如果用户问的是“这个客户有哪些财务记录”这类宽泛问题，可以查询四类全部数据
• 但会中更建议显式指定类型，避免一次返回过多记录

1. record_types

可选值：

• sale
• sale_return
• receipt
• refund

示例：

• 只查销售：record_types=sale
• 只查销退：record_types=sale_return
• 只查收款：record_types=receipt
• 只查退款：record_types=refund
• 同时查销售和收款：record_types=sale,receipt

注意：

• 如果不传 record_types，当前实现会默认查询四类全部数据。
• 因为返回的是“当前条件命中的全部记录”，会中使用时建议始终显式传 record_types，避免一次取太多数据。

2. include_cash_movement

控制是否包含真实资金变动记录。

对 receipt：

• true 时取 FkJinE > 0

对 refund：

• true 时取 FkJinE < 0

3. include_adjustments

控制是否包含挂账/欠款调整记录。

对 receipt 和 refund：

• true 时额外包含 FkJinE = 0

典型含义：

• FkJinE > 0：客户真实收款
• FkJinE < 0：客户真实退款
• FkJinE = 0：挂账、欠款、非现金调整

Recommended Meeting Flow

建议会中按以下顺序核实：

1. 先查销售：确认该客户近期销售单是否齐全。
2. 再查销退：确认是否存在退货单以及备注原因。
3. 再查收款：先只看真实资金流入。
4. 再查退款：先只看真实资金流出。
5. 如果财务提到“这笔不是付款，是挂账冲减”，再打开 include_adjustments=true 复核。

Ready-To-Use Examples

Only Sales

GET /api/v1/finance/by-customer?customer_name_b64=<BASE64URL_NAME>&record_types=sale
Authorization: <deployment auth secret>

Only Sale Returns

GET /api/v1/finance/by-customer?customer_name_b64=<BASE64URL_NAME>&record_types=sale_return
Authorization: <deployment auth secret>

Only Receipts With Real Cash Movement

GET /api/v1/finance/by-customer?customer_name_b64=<BASE64URL_NAME>&record_types=receipt&include_cash_movement=true&include_adjustments=false
Authorization: <deployment auth secret>

Only Refunds With Real Cash Movement

GET /api/v1/finance/by-customer?customer_name_b64=<BASE64URL_NAME>&record_types=refund&include_cash_movement=true&include_adjustments=false
Authorization: <deployment auth secret>

Only Refund Adjustments

GET /api/v1/finance/by-customer?customer_name_b64=<BASE64URL_NAME>&record_types=refund&include_cash_movement=false&include_adjustments=true
Authorization: <deployment auth secret>

Sales And Receipts Together

GET /api/v1/finance/by-customer?customer_name_b64=<BASE64URL_NAME>&record_types=sale,receipt&include_cash_movement=true&include_adjustments=false
Authorization: <deployment auth secret>

Response Reading Guide

关键字段：

• customer_name
• customer_ids
• record_types
• include_cash_movement
• include_adjustments
• total_count
• sales_count
• sale_returns_count
• receipts_count
• refunds_count
• sales
• sale_returns
• receipts
• refunds

注意：

• 返回结构按类别拆分，不是一个混合数组。
• 只请求某一类时，其它类别通常为 null 或计数为 0。
• 当前不会做按单聚合，返回的是原始命中记录。

Known Limitations

当前接口只支持以下过滤维度：

1. 客户名称
2. 财务记录类型
3. 是否包含真实资金变动
4. 是否包含挂账/欠款调整

当前不支持：

1. 时间范围过滤
2. 分页
3. 排序参数
4. 数量限制
5. 写入、修改、删除、审批、纠正财务数据
6. 非简单累计之外的统计分析
7. 按季度、按月、按年等时间维度汇总
8. 环比、同比、趋势分析、占比分析、分组统计
9. 筛选后的分组累计、小计、分类汇总

因此，当前返回的是“指定客户 + 指定类型 + 指定资金口径”下的全部命中数据。

这里的“允许的简单累计”仅指：

• 对当前 API 已返回的同类记录做直接求和或直接计数

不允许的情况包括：

• 先按额外条件切片后再做累计
• 先按季度/月度分桶后再汇总
• 任何需要派生统计口径的复杂计算

What To Tell Finance In The Meeting

可以直接这样解释：

1. 现在可以按客户名只查销售，或只查销退，或只查收款，或只查退款。
2. 收款和退款还可以区分成“真实资金变动”和“挂账调整”。
3. 但当前还不能按时间截取，也不能分页，所以结果是当前条件下的全量命中集。

Practical Advice For The Agent

1. 会中尽量显式传 record_types，不要依赖默认全量。
2. 查收款/退款时，先用 include_cash_movement=true&include_adjustments=false，先看真实收付款。
3. 只有在财务明确提到“挂账”“冲减”“欠款”时，再补查 include_adjustments=true。
4. 如果返回 not_found，先不要直接下结论，优先确认客户名称是否与主数据 B_Khzl.KhName 完全一致。
5. 如果用户问“可以查哪些财务数据”，应明确回答当前支持：销售、销退、收款、退款，并说明可以单选也可以多选。
6. 如果用户要求写入财务数据，必须拒绝，并说明当前 API 只支持查询。
7. 如果用户要求复杂统计，必须拒绝，并说明当前只支持原始命中记录查询，以及必要时基于返回结果做简单累计或计数。