# 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. 如果用户要求复杂统计，必须拒绝，并说明当前只支持原始命中记录查询，以及必要时基于返回结果做简单累计或计数。