baiyue-firstleg/warehouse/src/main/resources/openapi/supplier-frontend-handoff.md

平台供应商前端接口交接单

接入约定

• Base path：/api/platform/v1/suppliers
• 浏览器请求继续使用 Gateway /api 前缀，不在前端硬编码服务地址。
• 仅平台端账号可访问，供应商固定属于平台公共作用域 tenantId=0。
• 供应商是独立业务档案，不复用或修改往来单位 Partner。
• 所有接口使用统一 ApiResponse<T>：

{
  "code": "200",
  "message": "success",
  "data": {},
  "requestId": null,
  "traceId": null,
  "timestamp": "2026-08-13T03:00:00Z"
}

• 普通业务失败、参数校验失败通常仍返回 HTTP 200，前端必须以 body code === "200" 判断业务成功。认证、网关或基础设施拒绝仍可能返回真实 HTTP 401、403、503。
• Java Long 标识在 JSON 中按字符串消费，包括 id、tenantId、createdBy、updatedBy，不得转成 JavaScript number。

接口清单

功能	方法与路径	权限码
列表	GET /api/platform/v1/suppliers	platform:supplier:list
分类统计	GET /api/platform/v1/suppliers/stats	platform:supplier:list
详情	GET /api/platform/v1/suppliers/{id}?tenantId=0	platform:supplier:list
新增	POST /api/platform/v1/suppliers?tenantId=0	platform:supplier:create
编辑	PUT /api/platform/v1/suppliers/{id}?tenantId=0	platform:supplier:edit
启停	PATCH /api/platform/v1/suppliers/{id}/status?tenantId=0	platform:supplier:status

列表和统计的 tenantId 可省略；传入时只能是 0。详情、新增、编辑、启停当前要求显式传 tenantId=0。

列表查询

查询参数：

参数	类型	必填	说明
tenantId	string	否	只能为 0
page	integer	否	默认 1，最小 1
size	integer	否	默认 20，范围 1..200
category	enum	否	供应商分类
region	string	否	地区精确匹配，最长 80
status	enum	否	合作状态
keyword	string	否	按供应商名称或联系人模糊匹配

分页响应 data：

{
  "records": [],
  "page": 1,
  "size": 20,
  "total": 0,
  "pages": 0
}

records 元素使用下述 Supplier 字段。page/size/total/pages 是整数分页元数据。

Supplier 字段

字段	类型	说明
id	string	供应商 ID
tenantId	string	固定为 0
name	string	供应商名称，平台内唯一
category	enum	分类
region	string	地区
legalRepresentative	string	法人代表
contactName	string	联系人
phone	string	联系电话
email	string/null	电子邮箱
address	string/null	公司地址
businessLicenseNo	string/null	营业执照号/统一社会信用代码
licenseFileId	string/null	File 服务返回的营业执照文件 ID，只允许十进制数字字符串
status	enum	合作状态
settlementPeriod	enum	结算周期
remark	string/null	备注
createdBy	string/null	创建人 ID
createdAt	datetime	创建时间
updatedBy	string/null	最后修改人 ID
updatedAt	datetime	最后修改时间
deleted	boolean	逻辑删除标记；正常响应为 false
version	integer	乐观锁版本

营业执照上传由 File 服务完成。Supplier 新增或编辑只提交 licenseFileId；查看操作使用该 ID获取文件，不把 URL、base64 或文件二进制提交到 Supplier 接口。原型要求营业执照查看由前端使用居中弹框承载。

新增与编辑

新增和编辑使用相同请求体：

{
  "name": "示例供应商有限公司",
  "category": "BOOKING",
  "region": "宁波",
  "legalRepresentative": "张三",
  "contactName": "李经理",
  "phone": "13800000000",
  "email": "supplier@example.com",
  "address": "宁波市示例路 1 号",
  "businessLicenseNo": "91330000XXXXXXXXXX",
  "licenseFileId": "192000000000000001",
  "status": "ACTIVE",
  "settlementPeriod": "MONTHLY_30",
  "remark": ""
}

必填字段：name、category、region、legalRepresentative、contactName、phone、status、settlementPeriod。订舱供应商不区分国内或国外。

新增成功的 data 是供应商 ID 字符串。编辑成功的 data 为 null。

启停

{ "status": "INACTIVE" }

只接受 ACTIVE 或 INACTIVE。接口不物理删除供应商。

分类统计

GET /stats 的响应 data：

{
  "booking": 8,
  "customs": 5,
  "trucking": 6,
  "certificate": 3
}

枚举

供应商分类：

值	展示文案
BOOKING	订舱
CUSTOMS	报关
TRUCKING	拖车
CERTIFICATE	证书

合作状态：

值	展示文案
ACTIVE	合作中
INACTIVE	停用

结算周期：

值	展示文案
MONTHLY_30	月结30天
MONTHLY_45	月结45天
MONTHLY_60	月结60天
MONTHLY_90	月结90天
PER_TRANSACTION	票结
IMMEDIATE	现结

错误码

code	场景	前端处理建议
200	成功	使用 data
A0400	tenantId 非 0、请求格式或查询参数非法	显示参数错误，不重试
A0401	未登录或登录态失效	进入统一登录失效流程
A0403	非平台用户或缺少对应权限	显示无权限
A0404	供应商不存在	提示记录不存在并刷新列表
A0409	供应商名称重复或并发唯一键冲突	保留表单并提示名称已存在
A0422	字段校验失败	使用 message/data 显示字段错误
S0500	未预期服务异常	展示通用错误并记录 requestId/traceId
S0503	Warehouse 数据库不可用	展示稍后重试并记录 requestId/traceId

校验错误时 data 可能为字段到错误信息的映射，例如：

{
  "code": "A0422",
  "message": "name: must not be blank",
  "data": { "name": "must not be blank" },
  "requestId": "...",
  "traceId": "...",
  "timestamp": "..."
}

契约来源

• OpenAPI：warehouse/src/main/resources/openapi/supplier-v1.yaml
• Controller：warehouse/src/main/java/com/baiyue/warehouse/controller/PlatformSupplierController.java
• DTO：warehouse/src/main/java/com/baiyue/warehouse/dto/SupplierDtos.java

权限码已在接口层冻结，但 IAM 权限初始化不属于本次 warehouse 文件所有权，联调前需确认 IAM 已落库并授予目标平台角色。

初始化与验收

• Warehouse 模块表迁移：warehouse/src/main/resources/db/warehouse-supplier.sql
• IAM 权限迁移：iam/src/main/resources/db/platform-supplier-permissions.sql
• 测试/存量环境唯一执行入口：deploy/sql/头程数据库统一增量-MySQL8.sql
• 权限固定 ID：5103080..5103083，依次对应 list/create/edit/status；PLATFORM_ADMIN 默认获得全部四项权限。
• Admin 测试环境验收模块：scripts/admin-test-env-modules/suppliers.mjs
• 验收模块静态契约：scripts/admin-test-env-modules/suppliers-contract.test.mjs

离线验证：

mvn -pl warehouse,iam -am test
node --test scripts/admin-test-env-modules/suppliers-contract.test.mjs
pwsh scripts/local-db-full-acceptance.ps1 -DryRun

仅在当前对话已明确授权测试环境 API 验收后，才能运行下列命令。该模块会新增一条带本轮 marker 的供应商档案，并在结束时停用；由于供应商契约不提供删除接口，记录会保留为 INACTIVE。

node scripts/admin-test-env-acceptance.mjs --modules suppliers

模块覆盖列表、统计、新增、详情、编辑、启停、重复名称、非法 scope、客户账号权限拒绝、tenantId != 0 和错误响应 requestId/traceId。本轮代码交付不执行该测试环境命令。