java-project/baiyue-firstleg
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
704cb15ccf17ffa45546f1ea6e00a9908ff15fa1
baiyue-firstleg/docs/phase1-local-api.md
T

305 lines
14 KiB
Markdown
Raw Normal View History

暂存提交
2026-07-30 18:01:36 +08:00
# 一期本地联调 API 文档
## 1. 通用约定
统一基地址：`http://127.0.0.1:9000`；局域网前端使用 `http://192.168.110.149:9000`。除登录、注册、刷新和 Swagger 外，接口均携带：
```http
Authorization: Bearer <accessToken>
Content-Type: application/json
```
暂存提交
2026-07-31 14:55:34 +08:00
创建订单草稿和提交订单还必须携带 `Idempotency-Key`。同一操作者重试同一请求时复用原值；同一键用于不同请求返回 409，键缺失或长度超过 128 返回 400/422。
暂存提交
2026-07-30 18:01:36 +08:00
普通成功响应：
```json
{
"code": "0",
"message": "success",
"data": {},
"requestId": null,
"traceId": null,
"timestamp": "2026-07-30T12:00:00"
}
```
分页数据：
```json
{"records": [], "page": 1, "size": 20, "total": 0, "pages": 0}
```
常用业务错误码：`A0400` 参数错误、`A0401` 未登录、`A0403` 无权限、`A0404` 不存在、`A0409` 冲突、`A0422` 业务校验失败、`A0429` 请求过多、`B0001` 业务失败、`S0500` 服务异常、`S0503` 服务不可用。
## 2. 认证接口
| 方法 | 路径 | 登录要求 | 说明 |
|---|---|---|---|
| POST | `/api/auth/register` | 匿名 | 注册商户及租户 |
| POST | `/api/auth/login` | 匿名 | 平台、商户统一登录 |
| POST | `/api/auth/refresh` | 匿名 | 刷新令牌 |
| POST | `/api/auth/logout` | Access Token | 注销刷新令牌 |
注册请求：
```json
{
"username": "merchant_demo",
"password": "ChangeMe123!",
"displayName": "张三",
"companyName": "深圳示例贸易有限公司",
"legalPerson": "张三",
"legalPhone": "13800138000",
"contactEmail": "demo@example.com",
"countryCode": "CN",
"address": "广东省深圳市南山区测试路1号"
}
```
用户名为 4 至 64 位字母、数字或下划线，密码为 8 至 72 位。注册响应 `data`：`accountId,tenantId,membershipId,tenantStatus,nextStep`。
登录请求：
```json
{"username":"merchant_admin","password":"ChangeMe123!"}
```
登录/刷新响应 `data`：`tokenType,accessToken,expiresIn,refreshToken,refreshExpiresIn`。刷新和退出请求均为：
```json
{"refreshToken":"<refreshToken>"}
```
## 3. IAM 商户端
| 方法 | 路径 | 请求/响应 |
|---|---|---|
| GET | `/api/merchant/v1/iam/tenant/profile` | 返回当前 JWT 租户资料 |
| PUT | `/api/merchant/v1/iam/tenant/profile` | 更新当前租户资料 |
| GET | `/api/merchant/v1/iam/tenant/qualifications` | 返回当前租户资质列表 |
暂存提交
2026-07-31 13:52:35 +08:00
IAM 的商户资质接口只读。旧的 `POST /api/merchant/v1/iam/tenant/qualifications` 已移除，上传必须使用 File 服务的 multipart 接口，避免数据库出现没有真实文件支撑的 URL。
暂存提交
2026-07-30 18:01:36 +08:00
个人资料与修改密码：
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/merchant/v1/iam/profile` | 查询当前登录成员资料 |
| PUT | `/api/merchant/v1/iam/profile` | 编辑姓名、电话和邮箱 |
| PUT | `/api/auth/password` | 校验旧密码并修改本人密码，成功后撤销全部旧会话 |
成员与角色：
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET/POST | `/api/merchant/v1/iam/members` | 成员列表、创建成员和认证账号 |
| GET/PUT | `/api/merchant/v1/iam/members/{membershipId}` | 成员详情、编辑资料和角色 |
| PUT | `/api/merchant/v1/iam/members/{membershipId}/status` | 启用或停用普通成员 |
| PUT | `/api/merchant/v1/iam/members/{membershipId}/password` | 管理员重置成员密码 |
| GET/POST | `/api/merchant/v1/iam/roles` | 角色列表、新建角色 |
| GET/PUT/DELETE | `/api/merchant/v1/iam/roles/{roleId}` | 角色详情、编辑、删除 |
| PUT | `/api/merchant/v1/iam/roles/{roleId}/status` | 启用或停用自定义角色 |
| GET | `/api/merchant/v1/iam/permissions` | 查询去重后的权限资源 |
| PUT | `/api/merchant/v1/iam/roles/permissions` | 全量保存角色权限 |
| GET | `/api/merchant/v1/iam/members/{membershipId}/roles` | 查询成员当前角色 |
| PUT | `/api/merchant/v1/iam/members/roles` | 全量保存或清空成员角色 |
成员列表和详情均返回 `displayName,phone,email,roleIds`；角色列表和详情均返回 `permissionIds`。企业所有者和系统角色受保护，已分配成员的自定义角色不能删除。
资料更新请求：
```json
{
"tenantName": "深圳示例贸易有限公司",
"legalName": "深圳示例贸易有限公司",
"contactName": "李四",
"contactPhone": "13900139000",
"contactEmail": "service@example.com"
}
```
资料响应字段：`id,tenantCode,tenantName,status,legalName,unifiedSocialCreditCode,contactName,contactPhone,contactEmail`。
## 4. IAM 平台审核
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | `/api/platform/v1/iam/reviews` | 平台身份 | 待审核记录 |
| GET | `/api/platform/v1/iam/tenants/{tenantId}/qualifications` | `platform:customer:review` | 指定租户资质 |
| POST | `/api/platform/v1/iam/reviews/{id}/approve` | `platform:customer:approve` | 审核通过 |
| POST | `/api/platform/v1/iam/reviews/{id}/reject` | `platform:customer:reject` | 审核驳回 |
暂存提交
2026-07-31 14:55:34 +08:00
平台登录初始化与后台管理：
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | `/api/{platform\|merchant}/v1/iam/authorization/permissions` | 已认证有效成员 | 实时返回当前有效权限，不要求角色管理权限 |
| GET | `/api/platform/v1/iam/tenants?page=1&size=20` | `platform:customer:list` | 仅分页查询商户企业，支持关键字与状态 |
| GET | `/api/platform/v1/iam/internal-users` | `platform:user:list` | 返回 `membershipId`、账号资料和 `roleIds` |
| POST | `/api/platform/v1/iam/internal-users` | `platform:user:create` | 创建或关联平台认证账号 |
| PUT | `/api/platform/v1/iam/internal-users/{membershipId}` | `platform:user:edit` | 编辑资料与角色 |
| PUT | `/api/platform/v1/iam/internal-users/{membershipId}/status` | `platform:user:status` | 启用或停用平台用户 |
| PUT | `/api/platform/v1/iam/internal-users/{membershipId}/password` | `platform:user:reset-password` | 重置密码，密码只转交 Auth |
暂存提交
2026-07-30 18:01:36 +08:00
审核请求：
```json
{"comment":"资料完整，审核通过"}
```
审核通过后租户状态为 `ACTIVE`、资质为 `APPROVED`；驳回后租户和资质为 `REJECTED`。
## 5. 资质文件
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/merchant/v1/files/qualifications` | 上传当前租户营业执照 |
| GET | `/api/merchant/v1/files/qualifications/{fileName}` | 商户下载自己的资质 |
| GET | `/api/platform/v1/files/qualifications/{tenantId}/{fileName}` | 平台查看指定租户资质 |
暂存提交
2026-07-31 13:52:35 +08:00
历史 `/phase1-seed/...` 路径不符合 File 服务契约，不能直接改成不存在的 UUID。处理步骤见 `docs/企业资质文件迁移说明.md`。
暂存提交
2026-07-30 18:01:36 +08:00
上传采用 `multipart/form-data`：`file` 必填，`certificateNo` 可选。只接受文件内容真实为 JPG/PNG 的图片，最大 5MB。上传成功 `data`：
```json
{
"qualificationId": 1,
"reviewId": 1,
"tenantStatus": "PENDING",
"documentUrl": "/api/merchant/v1/files/qualifications/文件名.png"
}
```
下载接口直接返回图片二进制，不使用统一 JSON 包装。
## 6. 商户头程订单
基路径：`/api/merchant/v1/orders/first-leg`。
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
暂存提交
2026-07-31 14:55:34 +08:00
| POST | `/api/merchant/v1/orders/first-leg` | `merchant:order:create` | 创建草稿，必须携带 `Idempotency-Key`，`data` 为订单 ID |
暂存提交
2026-07-30 18:01:36 +08:00
| PUT | `/api/merchant/v1/orders/first-leg/{id}` | `merchant:order:edit` | 编辑草稿 |
| GET | `/api/merchant/v1/orders/first-leg` | 商户身份 | 分页查询自己的订单 |
| GET | `/api/merchant/v1/orders/first-leg/{id}` | 商户身份 | 查询自己的订单详情 |
暂存提交
2026-07-31 14:55:34 +08:00
| POST | `/api/merchant/v1/orders/first-leg/{id}/submit` | `merchant:order:submit` | 提交订单，必须携带 `Idempotency-Key` |
暂存提交
2026-07-30 18:01:36 +08:00
列表参数：`keyword,status,customerId,destinationWarehouseId,createdFrom,createdTo,page,size`；`page` 从 1 开始，`size` 为 1 至 200。
创建/编辑请求示例：
```json
{
"customerId": 10001,
"customerName": "深圳示例贸易有限公司",
"transportMode": "SEA",
"tradeTerm": "FOB",
"destinationCountryCode": "US",
"destinationWarehouseId": 1001,
"destinationWarehouseName": "ONT8",
"expectedShipDate": "2026-08-15",
"customerRemark": "提货前联系",
"pickupMethod": "PICKUP",
"receivingWarehouseId": 2001,
"receivingWarehouseName": "深圳收货仓",
"channelCode": "SEA-US-FBA",
"channelName": "美国海运渠道",
"taxMode": "BUY_DECLARATION",
"containerMode": "LCL",
"customsInspection": false,
"destinationType": "FBA",
"amazonWarehouseCode": "ONT8",
"shipmentId": "FBA20260730001",
"referenceId": "REF20260730001",
"sender": {
"companyName": "深圳示例贸易有限公司",
"contactName": "张三",
"phone": "13800138000",
"email": "sender@example.com",
"countryCode": "CN",
"province": "广东",
"city": "深圳",
"district": "南山",
"addressLine": "测试路1号",
"postalCode": "518000"
},
"receiver": {
"companyName": "Amazon",
"contactName": "ONT8",
"phone": "1234567890",
"email": "ont8@example.com",
"countryCode": "US",
"province": "CA",
"city": "Moreno Valley",
"district": "Riverside",
"addressLine": "24300 Nandina Ave",
"postalCode": "92551"
},
"cargoes": [{
"cargoName": "蓝牙音箱",
"hsCode": "8518210000",
"packageType": "CARTON",
"packageCount": 2,
"grossWeightKg": 20.5,
"volumeCbm": 0.2,
"declaredValue": 200,
"currency": "USD",
"dangerousGoods": false,
"totalQuantity": 20,
"netWeightKg": 18
}]
}
```
枚举约束：`transportMode=SEA|AIR|RAIL|TRUCK`；`pickupMethod=SELF_EXPRESS|PICKUP|SELF_TRUCK`；`taxMode=BUY_DECLARATION|TAX_REFUND`；`containerMode=FULL_CONTAINER|LCL`；`destinationType=FBA|OVERSEAS|PRIVATE`。
订单详情 `data` 包含 `order,cargoes,parties,internalNotes,statusHistory`。商户详情的 `internalNotes` 固定为空；平台内部备注不得向商户展示。企业必须为 `ACTIVE` 且至少有一项 `APPROVED` 资质，才能创建和提交订单。
## 7. 一期相关查询接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/merchant/v1/warehouses?page=1&size=20` | 商户仓库列表 |
| GET | `/api/merchant/v1/warehouses/{warehouseId}` | 启用仓库详情、地址、能力和收货截单时间 |
| GET | `/api/merchant/v1/partners/candidates` | 当前租户启用往来单位候选 |
| GET | `/api/merchant/v1/partners/{partnerId}` | 当前租户启用往来单位详情 |
| GET | `/api/platform/v1/warehouse-admin?tenantId={tenantId}&page=1&size=20` | 平台仓储列表 |
暂存提交
2026-07-31 14:55:34 +08:00
| GET | `/api/platform/v1/partners?tenantId={tenantId}&page=1&size=20` | 平台往来单位分页，需要 `platform:counterparty:list` |
| GET | `/api/platform/v1/partners/{id}?tenantId={tenantId}` | 平台往来单位详情，需要 `platform:counterparty:list` |
| POST | `/api/platform/v1/partners?tenantId={tenantId}` | 新增往来单位，需要 `platform:counterparty:create` |
| PUT | `/api/platform/v1/partners/{id}?tenantId={tenantId}` | 编辑往来单位，需要 `platform:counterparty:edit` |
| PATCH | `/api/platform/v1/partners/{id}/status?tenantId={tenantId}` | 启用或停用往来单位，需要 `platform:counterparty:status` |
| GET | `/api/platform/v1/express-companies?tenantId={tenantId}&page=1&size=20` | 平台快递公司分页，需要 `platform:express:list` |
| GET | `/api/platform/v1/express-companies/{id}?tenantId={tenantId}` | 平台快递公司详情，需要 `platform:express:list` |
| POST | `/api/platform/v1/express-companies?tenantId={tenantId}` | 新增快递公司，需要 `platform:express:create` |
| PUT | `/api/platform/v1/express-companies/{id}?tenantId={tenantId}` | 编辑快递公司，需要 `platform:express:edit` |
| PATCH | `/api/platform/v1/express-companies/{id}/status?tenantId={tenantId}` | 启用或停用快递公司，需要 `platform:express:status` |
| GET | `/api/platform/v1/first-leg/tasks?tenantId={tenantId}&page=1&size=20` | 履约任务分页，需要 `platform:firstleg:task:list` |
| GET | `/api/platform/v1/first-leg/tasks/{taskId}?tenantId={tenantId}` | 履约任务详情，需要 `platform:firstleg:task:view` |
| GET | `/api/platform/v1/first-leg/tasks/by-order/{orderId}?tenantId={tenantId}` | 按订单查询履约任务，需要 `platform:firstleg:task:view` |
| GET | `/api/platform/v1/first-leg/tasks/{taskId}/assignment-history?tenantId={tenantId}` | 分配历史，需要 `platform:firstleg:assignment:history` |
| POST | `/api/platform/v1/first-leg/tasks/{taskId}/assignment?tenantId={tenantId}` | 分配或改派，需要 `platform:firstleg:assignment:assign` |
暂存提交
2026-07-30 18:01:36 +08:00
| GET | `/api/platform/v1/iam/status` | IAM 网关路由状态 |
| GET | `/api/platform/v1/orders/status` | Order 网关路由状态 |
| GET | `/api/platform/v1/first-leg/status` | Firstleg 网关路由状态 |
| GET | `/api/platform/v1/warehouses/status` | Warehouse 网关路由状态 |
| GET | `/api/platform/v1/files/status` | File 网关路由状态 |
| GET | `/api/platform/v1/print/status` | Print 网关路由状态 |
往来单位由 `warehouse-service` 承载，表为 `baiyue_warehouse.wh_partner`，不是独立服务或独立数据库。仓库和往来单位查询强制执行租户隔离和停用过滤。
暂存提交
2026-07-31 16:53:07 +08:00
平台往来单位和快递公司均为目标商户租户下的主数据，因此所有平台管理接口都必须显式传入 `tenantId`，缺失或小于 1 返回参数错误。`/api/platform/v1/warehouses/status` 会实际探测仓库、地址、服务能力、往来单位和快递公司表的必需字段；缺表或缺列返回 HTTP 503 且状态为 `DEGRADED`。业务查询遇到数据源不可用或结构漂移时统一返回 `S0503`，不再用 `S0500` 隐藏迁移问题。
暂存提交
2026-07-31 14:55:34 +08:00
部署到既有数据库时，除主建表脚本外还要执行 `firstleg/src/main/resources/db/phase1-firstleg-task-list-index.sql`；该脚本可重复执行，用于补齐履约任务租户时间分页索引。
暂存提交
2026-07-30 18:01:36 +08:00
平台履约可通过 `PUT /api/platform/v1/orders/first-leg/{orderId}/express?tenantId={tenantId}` 写入 `expressCompany,expressTrackingNo`；商户端只能在订单详情读取，不能维护快递公司或调用平台写接口。
## 8. Swagger 分组
入口：`http://127.0.0.1:9000/swagger-ui.html`。当前可用分组：Auth 平台、IAM 平台/商户、Order 平台/商户、Firstleg 平台、Warehouse 平台/商户、File 平台/商户、Print 平台。
## 9. 一期明确不纳入
订单平台审核、受理、履约、完成、取消；尾程业务；跨区域事件通知；测试/生产部署，均不属于本地一期前端联调验收范围。
Reference in New Issue Copy Permalink