html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-08-11 10:46:15 +08:00
parent 6041a6d976
commit 953a3b0ed9
1 changed files with 13 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
财务管理/F1人工账单收款成本接口契约.md
+13 -5
View File
@@ -2,7 +2,7 @@
> 版本：V1.0 > 版本：V1.0
> 日期：2026-08-11 > 日期：2026-08-11
> 状态：可进入 Finance 后端实现 > 状态：目标契约；以《F1人工财务契约审查与门禁》为开发/联调准入依据
> OpenAPI：`openapi/finance-f1-manual-v1.yaml` > OpenAPI：`openapi/finance-f1-manual-v1.yaml`
## 1. 首期边界 ## 1. 首期边界
@@ -11,7 +11,7 @@
- 平台财务人工填写账单、收款、成本表单并上传凭证。 - 平台财务人工填写账单、收款、成本表单并上传凭证。
- 客户只读查看本客户账单、收款记录和未收余额。 - 客户只读查看本客户账单、收款记录和未收余额。
- 出账前账单可改；出账后冻结，只能由平台财务调整或作废重开。 - 出账前账单可改；出账后冻结，只能由平台财务调整或作废重开。
- 客户账期按客户配置，默认 30 个自然日；到期日为出账日加账期天数。 - 客户账期按客户配置，默认 30 个自然日；账单日期和到期日由服务端按 `billDate + creditDays` 计算。
- 一笔收款可分配到多张账单；财务逐张填写分配金额。首期不处理预收、多收、手续费、退款。 - 一笔收款可分配到多张账单；财务逐张填写分配金额。首期不处理预收、多收、手续费、退款。
- 单票成本归属单票；整柜清关、拖车等公共成本按柜内有效票体积分摊。 - 单票成本归属单票；整柜清关、拖车等公共成本按柜内有效票体积分摊。
@@ -23,6 +23,8 @@
- 写请求必须带 `Idempotency-Key`；更新/动作请求必须带 `expectedVersion`。 - 写请求必须带 `Idempotency-Key`；更新/动作请求必须带 `expectedVersion`。
- 客户范围从登录授权上下文取得，服务端忽略请求体中的客户切换字段。 - 客户范围从登录授权上下文取得，服务端忽略请求体中的客户切换字段。
- 文件先由 File 服务上传，Finance 接收 `fileId` 引用，不直接接收二进制。 - 文件先由 File 服务上传，Finance 接收 `fileId` 引用，不直接接收二进制。
- 平台账单列表必须带 `customerId`；收款和成本列表的 `customerId` 为可选筛选。首期接口返回非分页数组，前端分页只能在适配层完成；不得把数组伪装成服务端分页对象。
- Finance 对外 DTO 应稳定使用 camelCase；数据库 JDBC `snake_case` 仅限适配层，不能作为长期前后端契约。
## 3. 对象与状态 ## 3. 对象与状态
@@ -32,7 +34,7 @@
账单明细至少保存 `sourceFeeId`、`sourceFeeVersion`、`orderId`/`inboundId`、费用项目快照、数量、单价和金额。多笔订单分别出账；同一账单可包含多个费用项。 账单明细至少保存 `sourceFeeId`、`sourceFeeVersion`、`orderId`/`inboundId`、费用项目快照、数量、单价和金额。多笔订单分别出账；同一账单可包含多个费用项。
状态：`DRAFT → ISSUED → PARTIALLY_PAID → PAID`；`ISSUED/PARTIALLY_PAID/PAID → VOIDED`。`DRAFT` 可编辑，其他状态金额不可覆盖。 状态：`DRAFT → ISSUED → PARTIALLY_PAID → PAID`；未发生收款时允许 `DRAFT/ISSUED → VOIDED`。`DRAFT` 可编辑，已出账账单不得原地无痕覆盖金额；调整必须形成可追溯的新版本/修订记录，或走作废后重开。
### 3.2 收款 ### 3.2 收款
@@ -63,6 +65,8 @@
| GET | `/api/platform/finance/v1/receipts` | 查询收款记录 | | GET | `/api/platform/finance/v1/receipts` | 查询收款记录 |
| POST | `/api/platform/finance/v1/cost-entries` | 人工登记单票/整柜成本 | | POST | `/api/platform/finance/v1/cost-entries` | 人工登记单票/整柜成本 |
| GET | `/api/platform/finance/v1/cost-entries` | 查询成本记录 | | GET | `/api/platform/finance/v1/cost-entries` | 查询成本记录 |
| GET | `/api/platform/finance/v1/customers/{tenantId}/terms` | 查询客户账期（`tenantId` 为兼容字段，产品语义为客户） |
| PUT | `/api/platform/finance/v1/customers/{tenantId}/terms` | 保存客户账期，默认 30 天 |
### 客户只读 ### 客户只读
@@ -105,11 +109,15 @@
9. 登记单票成本成功；整柜公共成本按体积分摊，零体积场景要求人工指定。 9. 登记单票成本成功；整柜公共成本按体积分摊，零体积场景要求人工指定。
10. 重复 `Idempotency-Key` 返回原结果；同键不同请求返回 `FIN-AR-010`。 10. 重复 `Idempotency-Key` 返回原结果；同键不同请求返回 `FIN-AR-010`。
## 7. 实现依赖 ## 7. 权限矩阵
平台写入由 `platform:finance:*` 权限控制：账单 `view/create/update/issue/adjust/void`，收款 `view/create`，成本 `view/create`，客户账期 `view/update`。客户仅有 `merchant:finance:statement:list/view`，服务端从登录上下文确定客户范围。
## 8. 实现依赖
- F0：Finance 服务、客户范围、权限码、编号器、审计、文件引用和幂等表。 - F0：Finance 服务、客户范围、权限码、编号器、审计、文件引用和幂等表。
- Firstleg：已发布费用来源快照和来源版本查询；Finance 不跨库读取。 - Firstleg：已发布费用来源快照和来源版本查询；Finance 不跨库读取。
- Admin：平台财务路由和三个写表单。 - Admin：平台财务路由和三个写表单。
- Client：账单/收款只读查询。 - Client：账单/收款只读查询。
本契约不要求修改 Firstleg 或 Finance Java；后端实现时以此文档和 OpenAPI 为准。 本契约不要求修改 Firstleg 或 Finance Java；后端实现时以此文档、OpenAPI 和门禁审查结论为准。当前 Java 返回的 JDBC `snake_case Map`、非分页数组属于过渡实现，联调前必须由 API 适配层稳定化。