kboss/finance_settlement - 副本.md

财务结算接口文档

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

通用说明

接口域名: 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	审批撤销

推荐调用流程：

summary -> preview -> create -> submit -> apv_callback

1. 汇总查询

接口：

/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

请求示例：

{
  "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	当前行账单数量

返回示例：

{
  "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. 结算单预览

接口：

/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

请求示例：

{
  "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. 创建结算单

接口：

/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

请求示例：

{
  "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. 结算单列表

接口：

/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. 结算单详情

接口：

/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. 提交审批

接口：

/bill/finance_settlement_submit.dspy

功能：

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

入参：

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

请求示例：

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

出参：

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

注意：

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

7. 审批回调

接口：

/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	审批撤销

请求示例：

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

出参：

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

返回示例：

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

8. 数据库迁移 SQL

文件：

b/bill/finance_settlement_migration.sql

用途：

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

9. 页面

文件：

finaace_settlement.html

用途：

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

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

10. 常见错误

查询失败：unsupported format character

原因：

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

处理：

在 .dspy SQL 字符串中使用：

LIKE '待结转%%'

不要写成：

LIKE '待结转%'

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

原因：

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

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

以及：

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

处理：

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