diff --git a/财务管理/F1人工账单收款成本接口契约.md b/财务管理/F1人工账单收款成本接口契约.md index ef5e051..9e7d156 100644 --- a/财务管理/F1人工账单收款成本接口契约.md +++ b/财务管理/F1人工账单收款成本接口契约.md @@ -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 适配层稳定化。