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

## 接入约定

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

```json
{
  "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`：

```json
{
  "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 接口。原型要求营业执照查看由前端使用居中弹框承载。

## 新增与编辑

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

```json
{
  "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`。

## 启停

```json
{ "status": "INACTIVE" }
```

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

## 分类统计

`GET /stats` 的响应 `data`：

```json
{
  "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` 可能为字段到错误信息的映射，例如：

```json
{
  "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`

离线验证：

```powershell
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`。

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

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