forked from erp-dev/erp
feat: correct first
This commit is contained in:
257
docs/FINANCE-API-AGENT-HANDOFF.md
Normal file
257
docs/FINANCE-API-AGENT-HANDOFF.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
http://43.139.183.222:18080
|
||||
```
|
||||
|
||||
Authorization header format:
|
||||
|
||||
```http
|
||||
Authorization: <deployment auth secret>
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 本仓库不写入真实鉴权密钥。
|
||||
- 实际值请从目标环境部署配置中的 `auth.secret` 获取。
|
||||
- 当前系统仍然使用固定值鉴权，不是动态 token。
|
||||
|
||||
当前线上固定鉴权值：
|
||||
|
||||
- `Authorization: your-fixed-authorization-secret`
|
||||
|
||||
## Purpose
|
||||
|
||||
该接口用于：
|
||||
|
||||
1. 按客户名称精确抽取该客户的指定财务记录。
|
||||
2. 在会议中快速切换不同记录类型，逐项与财务人员核对。
|
||||
3. 根据需要区分“真实资金变动”和“挂账/欠款调整”。
|
||||
|
||||
## Request Shape
|
||||
|
||||
```http
|
||||
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
|
||||
|
||||
```http
|
||||
GET /api/v1/finance/by-customer?customer_name_b64=<BASE64URL_NAME>&record_types=sale
|
||||
Authorization: <deployment auth secret>
|
||||
```
|
||||
|
||||
### Only Sale Returns
|
||||
|
||||
```http
|
||||
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
|
||||
|
||||
```http
|
||||
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
|
||||
|
||||
```http
|
||||
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
|
||||
|
||||
```http
|
||||
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
|
||||
|
||||
```http
|
||||
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. 如果用户要求复杂统计，必须拒绝，并说明当前只支持原始命中记录查询，以及必要时基于返回结果做简单累计或计数。
|
||||
Reference in New Issue
Block a user