Test #1
+13
-5
@@ -2,7 +2,7 @@
|
||||
|
||||
> 版本：V1.0
|
||||
> 日期：2026-08-11
|
||||
> 状态：可进入 Finance 后端实现
|
||||
> 状态：目标契约；以《F1人工财务契约审查与门禁》为开发/联调准入依据
|
||||
> OpenAPI：`openapi/finance-f1-manual-v1.yaml`
|
||||
|
||||
## 1. 首期边界
|
||||
@@ -11,7 +11,7 @@
|
||||
- 平台财务人工填写账单、收款、成本表单并上传凭证。
|
||||
- 客户只读查看本客户账单、收款记录和未收余额。
|
||||
- 出账前账单可改；出账后冻结，只能由平台财务调整或作废重开。
|
||||
- 客户账期按客户配置，默认 30 个自然日；到期日为出账日加账期天数。
|
||||
- 客户账期按客户配置，默认 30 个自然日；账单日期和到期日由服务端按 `billDate + creditDays` 计算。
|
||||
- 一笔收款可分配到多张账单；财务逐张填写分配金额。首期不处理预收、多收、手续费、退款。
|
||||
- 单票成本归属单票；整柜清关、拖车等公共成本按柜内有效票体积分摊。
|
||||
|
||||
@@ -23,6 +23,8 @@
|
||||
- 写请求必须带 `Idempotency-Key`；更新/动作请求必须带 `expectedVersion`。
|
||||
- 客户范围从登录授权上下文取得，服务端忽略请求体中的客户切换字段。
|
||||
- 文件先由 File 服务上传，Finance 接收 `fileId` 引用，不直接接收二进制。
|
||||
- 平台账单列表必须带 `customerId`；收款和成本列表的 `customerId` 为可选筛选。首期接口返回非分页数组，前端分页只能在适配层完成；不得把数组伪装成服务端分页对象。
|
||||
- Finance 对外 DTO 应稳定使用 camelCase；数据库 JDBC `snake_case` 仅限适配层，不能作为长期前后端契约。
|
||||
|
||||
## 3. 对象与状态
|
||||
|
||||
@@ -32,7 +34,7 @@
|
||||
|
||||
账单明细至少保存 `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 收款
|
||||
|
||||
@@ -63,6 +65,8 @@
|
||||
| GET | `/api/platform/finance/v1/receipts` | 查询收款记录 |
|
||||
| POST | `/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. 登记单票成本成功；整柜公共成本按体积分摊，零体积场景要求人工指定。
|
||||
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 服务、客户范围、权限码、编号器、审计、文件引用和幂等表。
|
||||
- Firstleg：已发布费用来源快照和来源版本查询；Finance 不跨库读取。
|
||||
- Admin：平台财务路由和三个写表单。
|
||||
- Client：账单/收款只读查询。
|
||||
|
||||
本契约不要求修改 Firstleg 或 Finance Java；后端实现时以此文档和 OpenAPI 为准。
|
||||
本契约不要求修改 Firstleg 或 Finance Java；后端实现时以此文档、OpenAPI 和门禁审查结论为准。当前 Java 返回的 JDBC `snake_case Map`、非分页数组属于过渡实现，联调前必须由 API 适配层稳定化。
|
||||
|
||||
Reference in New Issue
Block a user