docs: organize contracts by business domain
This commit is contained in:
@@ -0,0 +1,171 @@
|
||||
# 海外仓阶梯费用前端联调说明
|
||||
|
||||
> 更新日期：2026-08-05
|
||||
> 后端服务：Warehouse Service
|
||||
> 当前状态：后端 CRUD、Gateway 路由、权限、数据库增量和自动化测试已完成；前端待实现与联调
|
||||
|
||||
## 一、业务边界
|
||||
|
||||
本功能用于平台端按客户维护海外仓仓储费的天数阶梯基础资料。一名客户只能存在一份有效配置，配置包含客户、币种和 1 至 100 组连续的天数阶梯。
|
||||
|
||||
当前只提供基础资料维护，不参与本期入库、FBA 自动计费、费用发送、账单、对账或结算。当前也没有启停、计费单位、生效日期、免租期和版本发布能力，前端不得自行补造这些字段或业务动作。
|
||||
|
||||
## 二、建议页面
|
||||
|
||||
- 页面名称：海外仓阶梯费用
|
||||
- 建议路由：`/customers/overseas-storage-fees`
|
||||
- 列表筛选：客户 ID、客户公司名称关键字
|
||||
- 列表字段：客户、币种、阶梯摘要、版本、创建时间、更新时间
|
||||
- 详情与编辑字段：客户 ID、客户公司名称、币种、阶梯起始天、阶梯结束天、仓储费单价
|
||||
- 操作：查看、新增、编辑、删除
|
||||
|
||||
编辑和删除必须使用详情返回的最新 `version`。发生 409 冲突时应提示“数据已被修改，请刷新后重试”，重新读取详情，不能静默覆盖。
|
||||
|
||||
## 三、接口清单
|
||||
|
||||
统一前缀：`/api/platform/v1/overseas-storage-fees`
|
||||
|
||||
| 方法 | 路径 | 用途 | 权限 |
|
||||
|---|---|---|---|
|
||||
| GET | `/api/platform/v1/overseas-storage-fees` | 分页查询 | `platform:overseas-storage-fee:list` |
|
||||
| GET | `/api/platform/v1/overseas-storage-fees/{id}` | 查询详情 | `platform:overseas-storage-fee:list` |
|
||||
| POST | `/api/platform/v1/overseas-storage-fees` | 新增 | `platform:overseas-storage-fee:create` |
|
||||
| PUT | `/api/platform/v1/overseas-storage-fees/{id}` | 编辑 | `platform:overseas-storage-fee:edit` |
|
||||
| DELETE | `/api/platform/v1/overseas-storage-fees/{id}?version={version}` | 删除 | `platform:overseas-storage-fee:delete` |
|
||||
|
||||
仅允许平台端令牌调用。列表查询参数如下：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `page` | long | 否 | 默认 1，最小 1 |
|
||||
| `size` | long | 否 | 默认 20，范围 1 至 200 |
|
||||
| `customerId` | long | 否 | 客户 ID 精确查询 |
|
||||
| `customerName` | string | 否 | 客户公司名称模糊查询，最多 128 字符 |
|
||||
|
||||
## 四、请求示例
|
||||
|
||||
新增：
|
||||
|
||||
```json
|
||||
{
|
||||
"customerId": "10001",
|
||||
"customerName": "示例客户有限公司",
|
||||
"currency": "USD",
|
||||
"tiers": [
|
||||
{"startDay": 1, "endDay": 7, "unitPrice": 0.5},
|
||||
{"startDay": 8, "endDay": 30, "unitPrice": 0.8},
|
||||
{"startDay": 31, "endDay": 60, "unitPrice": 0.6}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
编辑请求结构与新增一致，并增加详情返回的版本号：
|
||||
|
||||
```json
|
||||
{
|
||||
"customerId": "10001",
|
||||
"customerName": "示例客户有限公司",
|
||||
"currency": "USD",
|
||||
"tiers": [
|
||||
{"startDay": 1, "endDay": 10, "unitPrice": 0.55},
|
||||
{"startDay": 11, "endDay": 30, "unitPrice": 0.8}
|
||||
],
|
||||
"version": 1
|
||||
}
|
||||
```
|
||||
|
||||
说明：Java Long 类型的 ID 在浏览器中统一按字符串保存和传递，避免精度丢失。
|
||||
|
||||
## 五、响应结构
|
||||
|
||||
详情的 `data` 结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "2100000000000000001",
|
||||
"customerId": "10001",
|
||||
"customerName": "示例客户有限公司",
|
||||
"currency": "USD",
|
||||
"tiers": [
|
||||
{
|
||||
"id": "2100000000000000002",
|
||||
"startDay": 1,
|
||||
"endDay": 7,
|
||||
"unitPrice": 0.5,
|
||||
"sortNo": 1
|
||||
}
|
||||
],
|
||||
"version": 0,
|
||||
"createdAt": "2026-08-05T10:00:00",
|
||||
"updatedAt": "2026-08-05T10:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
分页接口的 `data` 包含 `records`、`page`、`size`、`total`、`pages`。新增成功时 `data` 为新增配置 ID；编辑和删除成功时 `data` 为 `null`。
|
||||
|
||||
## 六、校验规则
|
||||
|
||||
- 一个客户只能有一份有效配置。
|
||||
- `customerId` 必须为正数，`customerName` 必填且最多 128 字符。
|
||||
- 币种必须是三位大写字母，例如 `CNY`、`USD`。
|
||||
- 阶梯必须为 1 至 100 组。
|
||||
- 第一组必须从第 1 天开始。
|
||||
- 后一组 `startDay` 必须等于前一组 `endDay + 1`。
|
||||
- 区间不能间断、重叠或倒置。
|
||||
- 起止天数范围为 1 至 36500。
|
||||
- 单价必须大于 0，最多 12 位整数和 6 位小数。
|
||||
|
||||
## 七、错误处理
|
||||
|
||||
| 业务码 | 场景 | 前端处理 |
|
||||
|---|---|---|
|
||||
| `A0403` | 非平台端访问或缺少按钮权限 | 显示无权限，隐藏无权限操作 |
|
||||
| `A0404` | 配置不存在或已删除 | 提示数据不存在并返回列表 |
|
||||
| `A0409` | 客户重复配置、阶梯区间冲突、版本过期或并发修改 | 保留用户提示，刷新列表或详情 |
|
||||
| `A0422` | 参数、币种、阶梯连续性或单价校验失败 | 显示服务端错误信息并定位表单 |
|
||||
| `S0503` | Warehouse 服务不可用或未就绪 | 显示服务暂不可用并允许重试 |
|
||||
|
||||
普通成功响应仍需判断统一响应体 `code === "200"`。
|
||||
|
||||
## 八、数据库与部署
|
||||
|
||||
本功能复用 Warehouse 数据库，未新增微服务或独立数据库。新增表：
|
||||
|
||||
- `wh_overseas_storage_fee_rule`
|
||||
- `wh_overseas_storage_fee_tier`
|
||||
|
||||
同时新增 5 个索引及 4 项按钮权限，平台系统管理员默认获得上述权限。唯一数据库增量入口：
|
||||
|
||||
```text
|
||||
D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql
|
||||
```
|
||||
|
||||
当前已完成 SQL 静态契约校验，但本次功能增量尚未在真实数据库执行。部署或联调前需先在目标库执行统一增量脚本并确认脚本最终输出 `PASS`。
|
||||
|
||||
## 九、Swagger
|
||||
|
||||
- Gateway 聚合文档：`http://127.0.0.1:9000/webjars/swagger-ui/index.html`，选择 Warehouse 平台端分组。
|
||||
- Warehouse 直连文档：`http://127.0.0.1:9204/swagger-ui/index.html`。
|
||||
- Gateway OpenAPI：`/warehouse-service/v3/api-docs/platform`。
|
||||
|
||||
## 十、后端验证结果
|
||||
|
||||
- Warehouse 全量测试：91 项通过。
|
||||
- 海外仓阶梯费用 CRUD 定向测试：6 项通过。
|
||||
- SQL 契约测试：1 项通过。
|
||||
- Gateway 路由契约测试：2 项通过。
|
||||
- Maven 构建：`BUILD SUCCESS`。
|
||||
- SQL 静态校验：存储过程分隔符、预处理语句配对、唯一最终 `PASS` 和危险语句检查均通过。
|
||||
|
||||
## 十一、前端验收清单
|
||||
|
||||
- 有列表权限时可进入页面，无权限时路由、菜单和按钮状态正确。
|
||||
- 客户 ID 和客户名称筛选、分页及空态正确。
|
||||
- 新增后回读详情，ID 全程不转为 JavaScript `Number`。
|
||||
- 同一客户重复新增时正确处理 `A0409`。
|
||||
- 阶梯间断、重叠、倒置、非第 1 天开始和非正单价均不能提交成功。
|
||||
- 编辑使用最新 `version`，过期版本收到 409 后刷新详情。
|
||||
- 删除前二次确认，并携带最新 `version`。
|
||||
- 请求失败、服务不可用、加载态、空态和重复提交均有明确反馈。
|
||||
- 页面不出现启停、生效日期、计费单位、免租期或自动计费开关等未定义字段。
|
||||
- 不将本配置接入当前头程/FBA 自动计费流程。
|
||||
Reference in New Issue
Block a user