html/docs

Fork 0

Files

T

ouyangxq 40492cdae8 docs: organize contracts by business domain

2026-09-04 16:44:08 +08:00

6.7 KiB

Raw Blame History

海外仓阶梯费用前端联调说明

更新日期：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 字符

四、请求示例

新增：

{
  "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}
  ]
}

编辑请求结构与新增一致，并增加详情返回的版本号：

{
  "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 结构：

{
  "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 项按钮权限，平台系统管理员默认获得上述权限。唯一数据库增量入口：

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 自动计费流程。

6.7 KiB Raw Blame History Unescape Escape