# 财务结算接口文档

本文档汇总财务结算相关接口，覆盖供应商/分销商日结、月结费用查询，平台收入查询，结算单创建、审批和记账闭环。

## 通用说明

接口域名: https://dev.opencomputing.cn

金额口径：

- `sales_amount`：销售金额，来源于 `bill.amount`。
- `settlement_amount`：应结算金额。
  - 供应商：当前账本 `bill_detail.subjectname LIKE '待结转%'` 且 `accounting_dir='贷'`。
  - 分销商：当前账本 `bill_detail.subjectname='分销商存放资金'` 且 `accounting_dir='借'`，`participantid=分销商orgid`。
- `platform_income_amount`：平台收入，当前账本 `bill_detail.subjectname IN ('折扣收入', '底价收入')` 且 `accounting_dir='贷'`。
- 所有正式结算金额只统计已记账账单：`bill.bill_state = '1'`。

状态说明：

| 状态 | 含义 |
| --- | --- |
| `draft` | 草稿，已创建结算单但未提交审批 |
| `approving` | 审批中 |
| `approved` | 审批通过，等待或正在记账 |
| `rejected` | 审批拒绝 |
| `settled` | 已完成结算记账 |
| `failed` | 结算记账失败 |
| `cancelled` | 审批撤销 |

推荐调用流程：

```text
summary -> preview -> create -> submit -> apv_callback
```

## 1. 汇总查询

接口：

```text
/bill/finance_settlement_summary.dspy
```

功能：

查询供应商或分销商在指定日结/月结账期内的销售金额、结算金额、平台收入和账单数量。支持按对手方聚合，也支持指定某个供应商或分销商查询。

入参：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
| `counterparty_type` | 是 | string | `supplier` 供应商，`reseller` 分销商 |
| `period_type` | 否 | string | `day` 或 `month`，默认 `day` |
| `start_date` | 是 | string | 查询开始日期，格式 `YYYY-MM-DD` |
| `end_date` | 是 | string | 查询结束日期，格式 `YYYY-MM-DD` |
| `counterparty_orgid` | 否 | string | 指定供应商或分销商机构 ID |
| `current_page` | 否 | number | 页码，默认 `1` |
| `page_size` | 否 | number | 每页数量，默认 `20` |

请求示例：

```json
{
  "accounting_orgid": "org001",
  "counterparty_type": "supplier",
  "period_type": "month",
  "start_date": "2026-06-01",
  "end_date": "2026-06-30",
  "current_page": 1,
  "page_size": 20
}
```

出参：

| 字段 | 说明 |
| --- | --- |
| `data.summary.sales_amount` | 销售金额合计 |
| `data.summary.settlement_amount` | 结算金额合计 |
| `data.summary.platform_income_amount` | 平台收入合计 |
| `data.summary.bill_count` | 账单数量 |
| `data.items[].period` | 账期，日结为 `YYYY-MM-DD`，月结为 `YYYY-MM` |
| `data.items[].counterparty_orgid` | 对手方机构 ID |
| `data.items[].counterparty_name` | 对手方名称 |
| `data.items[].sales_amount` | 当前行销售金额 |
| `data.items[].settlement_amount` | 当前行结算金额 |
| `data.items[].platform_income_amount` | 当前行平台收入 |
| `data.items[].bill_count` | 当前行账单数量 |

返回示例：

```json
{
  "status": true,
  "msg": "ok",
  "data": {
    "accounting_orgid": "org001",
    "counterparty_type": "supplier",
    "period_type": "month",
    "start_date": "2026-06-01",
    "end_date": "2026-06-30",
    "summary": {
      "sales_amount": 1000.0,
      "settlement_amount": 700.0,
      "platform_income_amount": 300.0,
      "bill_count": 10
    },
    "total_count": 1,
    "current_page": 1,
    "page_size": 20,
    "items": []
  }
}
```

## 2. 结算单预览

接口：

```text
/bill/finance_settlement_preview.dspy
```

功能：

创建结算单前预览明细，检查指定账期是否已有结算单，并返回可结算账单明细。

入参：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
| `counterparty_type` | 是 | string | `supplier` 或 `reseller` |
| `counterparty_orgid` | 是 | string | 供应商或分销商机构 ID |
| `period_type` | 否 | string | `day` 或 `month`，默认 `day` |
| `period_start` | 是 | string | 账期开始日期 |
| `period_end` | 是 | string | 账期结束日期 |
| `current_page` | 否 | number | 页码，默认 `1` |
| `page_size` | 否 | number | 每页数量，默认 `50` |

请求示例：

```json
{
  "accounting_orgid": "org001",
  "counterparty_type": "reseller",
  "counterparty_orgid": "reseller001",
  "period_type": "month",
  "period_start": "2026-06-01",
  "period_end": "2026-06-30"
}
```

出参：

| 字段 | 说明 |
| --- | --- |
| `data.can_create` | 是否可以创建结算单 |
| `data.existing_settlement` | 已存在结算单信息，没有则为 `null` |
| `data.summary` | 汇总金额 |
| `data.items[]` | 账单明细 |
| `data.items[].bill_id` | 账单 ID |
| `data.items[].order_id` | 订单 ID |
| `data.items[].bill_date` | 账单日期 |
| `data.items[].sale_mode` | 销售模式，`0` 折扣，`1` 代付费，`2` 底价 |
| `data.items[].sales_amount` | 销售金额 |
| `data.items[].settlement_amount` | 结算金额 |
| `data.items[].platform_income_amount` | 平台收入 |

## 3. 创建结算单

接口：

```text
/bill/finance_settlement_create.dspy
```

功能：

创建结算单主表和明细快照。创建后状态为 `draft`。同一账本机构、对手方、账期不能重复创建。

入参：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
| `counterparty_type` | 是 | string | `supplier` 或 `reseller` |
| `counterparty_orgid` | 是 | string | 供应商或分销商机构 ID |
| `period_type` | 否 | string | `day` 或 `month`，默认 `day` |
| `period_start` | 是 | string | 账期开始日期 |
| `period_end` | 是 | string | 账期结束日期 |
| `userid` | 否 | string | 当前操作用户 ID |

请求示例：

```json
{
  "accounting_orgid": "org001",
  "counterparty_type": "supplier",
  "counterparty_orgid": "supplier001",
  "period_type": "day",
  "period_start": "2026-06-01",
  "period_end": "2026-06-01",
  "userid": "user001"
}
```

出参：

| 字段 | 说明 |
| --- | --- |
| `data.settlement_id` | 结算单 ID |
| `data.settlement_no` | 结算单号 |
| `data.status` | 初始状态，固定为 `draft` |
| `data.summary` | 创建时锁定的汇总金额 |

## 4. 结算单列表

接口：

```text
/bill/finance_settlement_list.dspy
```

功能：

分页查询结算单主表数据。

入参：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `accounting_orgid` | 是 | string | 当前账本机构 ID |
| `counterparty_type` | 否 | string | `supplier` 或 `reseller` |
| `counterparty_orgid` | 否 | string | 对手方机构 ID |
| `status` | 否 | string | 结算单状态 |
| `period_type` | 否 | string | `day` 或 `month` |
| `start_date` | 否 | string | 账期范围开始 |
| `end_date` | 否 | string | 账期范围结束 |
| `current_page` | 否 | number | 页码，默认 `1` |
| `page_size` | 否 | number | 每页数量，默认 `20` |

出参：

| 字段 | 说明 |
| --- | --- |
| `data.total_count` | 总数 |
| `data.current_page` | 当前页 |
| `data.page_size` | 每页数量 |
| `data.items[]` | 结算单列表 |

`items[]` 中主要字段：

| 字段 | 说明 |
| --- | --- |
| `id` | 结算单 ID |
| `settlement_no` | 结算单号 |
| `counterparty_type` | 对手方类型 |
| `counterparty_orgid` | 对手方机构 ID |
| `counterparty_name` | 对手方名称 |
| `period_start` | 账期开始 |
| `period_end` | 账期结束 |
| `sales_amount` | 销售金额 |
| `settlement_amount` | 结算金额 |
| `platform_income_amount` | 平台收入 |
| `status` | 结算单状态 |
| `approval_id` | 审批 ID |

## 5. 结算单详情

接口：

```text
/bill/finance_settlement_detail.dspy
```

功能：

查询结算单主表和明细快照。

入参：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `settlement_id` | 是 | string | 结算单 ID |
| `current_page` | 否 | number | 明细页码，默认 `1` |
| `page_size` | 否 | number | 明细每页数量，默认 `100` |

出参：

| 字段 | 说明 |
| --- | --- |
| `data.settlement` | 结算单主表 |
| `data.detail_total_count` | 明细总数 |
| `data.items[]` | 结算明细快照 |

## 6. 提交审批

接口：

```text
/bill/finance_settlement_submit.dspy
```

功能：

将 `draft`、`rejected`、`failed` 状态的结算单提交审批。提交成功后状态更新为 `approving`，并写入 `approval_id`。

入参：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `settlement_id` | 是 | string | 结算单 ID |
| `userid` | 是 | string | 当前操作用户 ID |
| `business_name` | 否 | string | 审批业务名，默认 `财务结算` |

请求示例：

```json
{
  "settlement_id": "settlement001",
  "userid": "user001",
  "business_name": "财务结算"
}
```

出参：

| 字段 | 说明 |
| --- | --- |
| `data.settlement_id` | 结算单 ID |
| `data.approval_id` | 审批实例 ID |
| `data.status` | `approving` |

注意：

- `apv_business` 表中需要存在 `business_name='财务结算'` 的审批业务配置。
- 当前账本机构下需要存在角色为 `财务` 的审批用户。

## 7. 审批回调

接口：

```text
/bill/finance_settlement_apv_callback.dspy
```

功能：

处理审批回调。审批通过后自动结算记账：

- 供应商结算：调用现有 `SettleAccounting`。
- 分销商结算：写入 `bill`、`bill_detail`、`accounting_log`、`acc_detail`、`acc_balance`。

入参：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `apv_id` | 是 | string | 审批实例 ID，也可传 `approval_id` |
| `status` | 是 | string | 审批状态 |

`status` 支持：

| 值 | 说明 |
| --- | --- |
| `start` | 审批中 |
| `agree` | 审批通过，执行结算记账 |
| `refuse` | 审批拒绝 |
| `terminate` | 审批撤销 |

请求示例：

```json
{
  "apv_id": "approval001",
  "status": "agree"
}
```

出参：

| 字段 | 说明 |
| --- | --- |
| `data[].settlement_id` | 结算单 ID |
| `data[].status` | 处理后的状态 |
| `data[].failure_reason` | 失败原因，仅失败时返回 |

返回示例：

```json
{
  "status": true,
  "msg": "ok",
  "data": [
    {
      "settlement_id": "settlement001",
      "status": "settled"
    }
  ]
}
```

## 8. 数据库迁移 SQL

文件：

```text
b/bill/finance_settlement_migration.sql
```

用途：

- 创建 `finance_settlement`。
- 创建 `finance_settlement_detail`。
- 已建表场景下补齐 `sale_mode` 字段。
- 提供分销商结算前账户检查 SQL 模板。

## 9. 页面

文件：

```text
finaace_settlement.html
```

用途：

浅色科技风财务结算页面，包含：

- 汇总查询
- 平台收入展示
- 结算单预览
- 创建结算单
- 结算单列表
- 结算单详情
- 提交审批
- 审批回调

## 10. 常见错误

### 查询失败：`unsupported format character`

原因：

SQL 中包含 `%` 通配符时，运行环境可能再次进行 Python 字符串格式化。

处理：

在 `.dspy` SQL 字符串中使用：

```sql
LIKE '待结转%%'
```

不要写成：

```sql
LIKE '待结转%'
```

### 分销商结算失败：找不到分销商存放资金账户

原因：

分销商结算需要以下账户存在：

- `accounting_orgid = 上级机构`
- `orgid = 分销商机构`
- `subjectname = 分销商存放资金`

以及：

- `accounting_orgid = 上级机构`
- `orgid = 上级机构`
- `subjectname = 资金账号`

处理：

执行 `b/bill/finance_settlement_migration.sql` 中附带的检查 SQL，确认账户已开通。