java-project/baiyue-firstleg
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6a2075fe4bb5ae2d69dc499e13f0a9d282ba63a6
baiyue-firstleg/iam/src/main/resources/openapi/iam-v1.yaml
T

1722 lines
84 KiB
YAML
Raw Normal View History

暂存提交
2026-07-30 18:01:36 +08:00
openapi: 3.0.3
info:
title: Baiyue IAM API / 百悦身份与权限 API
优化
2026-08-05 16:26:10 +08:00
description: Customer master data, members, roles, menus, pages, buttons and API permissions for the current single-tenant product. Historical tenant-named paths, schemas and fields are retained for compatibility; tenantId > 0 currently means customer ID, while 0 is technical scope for platform identities, RBAC, and public warehouse resources. / 当前单租户产品的客户主档、成员、角色、菜单、页面、按钮和 API 权限管理。tenant 命名的路径、模型和字段仅为历史兼容；tenantId 大于 0 当前表示客户 ID，0 表示平台身份、RBAC 和公共仓储资源技术作用域。
暂存提交
2026-07-30 18:01:36 +08:00
version: 1.0.1
servers:
- url: /
security:
- bearerAuth: []
tags:
- name: Platform Tenant / 平台租户
优化
2026-08-05 16:26:10 +08:00
description: Historical tag for platform customer administration; it does not represent a real tenant layer. / 历史兼容标签，实际用于平台客户管理，不表示真实租户层。
暂存提交
2026-07-30 18:01:36 +08:00
- name: Merchant Tenant / 商户企业
优化
2026-08-05 16:26:10 +08:00
description: Current customer profile and members; tenant naming is retained for compatibility. / 当前客户企业资料与成员；tenant 命名仅为兼容。
暂存提交
2026-07-30 18:01:36 +08:00
- name: IAM Resources / IAM 资源
description: Internal users, addresses and qualifications / 内部用户、地址与资质
- name: RBAC
description: Platform and merchant role-permission management / 平台端与商户端角色权限管理
paths:
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
/api/merchant/v1/iam/profile:
get:
tags: [Merchant Tenant / 商户企业]
summary: 查看当前登录用户个人资料
responses:
'200':
description: 查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/PersonalProfileApiResponse'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
put:
tags: [Merchant Tenant / 商户企业]
summary: 修改当前登录用户普通资料
description: 仅修改显示名称和邮箱；用户名、手机号必须走敏感标识接口。
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdatePersonalProfileRequest'}
responses:
'200':
description: 修改成功
content:
application/json:
schema: {$ref: '#/components/schemas/PersonalProfileApiResponse'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
/api/merchant/v1/iam/profile/login-identifiers:
put:
tags: [Merchant Tenant / 商户企业]
summary: 修改当前登录用户的用户名和手机号
description: 仅允许当前非代登录用户修改本人标识，必须用当前密码重新认证；成功后全部 Token 和会话失效，需重新登录。权限为已认证客户本人，无额外权限码。
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ChangeLoginIdentifiersRequest'}
responses:
'200':
description: 修改成功并已吊销会话
content:
application/json:
schema: {$ref: '#/components/schemas/PersonalProfileApiResponse'}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
'409': {$ref: '#/components/responses/Conflict'}
优化
2026-09-02 10:04:18 +08:00
/api/platform/v1/iam/tenants/administrator-phone-availability:
优化
2026-08-07 14:46:55 +08:00
get:
tags: [Platform Tenant / 平台租户]
优化
2026-09-02 10:04:18 +08:00
summary: 校验首个管理员登录手机号唯一性
description: 仅在创建客户前校验 Auth 登录手机号；公司联系电话不要求跨企业唯一。
优化
2026-08-07 14:46:55 +08:00
parameters:
优化
2026-09-02 10:04:18 +08:00
- {name: phone, in: query, required: true, schema: {type: string, pattern: '^1[3-9]\d{9}$'}}
优化
2026-08-07 14:46:55 +08:00
responses:
'200':
优化
2026-09-02 10:04:18 +08:00
description: 返回手机号是否可作为首个管理员登录手机号
优化
2026-08-07 14:46:55 +08:00
content:
application/json:
schema:
type: object
properties:
code: {type: string}
message: {type: string}
data: {type: boolean}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/platform/v1/iam/tenants:
暂存提交
2026-07-31 14:55:34 +08:00
get:
tags: [Platform Tenant / 平台租户]
暂存提交
2026-07-31 16:53:07 +08:00
summary: 查询企业客户列表
暂存提交
2026-08-03 12:43:30 +08:00
description: 分页查询商户企业客户，需要 `platform:customer:list` 权限；联系电话和邮箱仅返回脱敏摘要。
暂存提交
2026-07-31 14:55:34 +08:00
parameters:
- {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
- {name: size, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
优化
2026-08-14 12:50:37 +08:00
- {name: keyword, in: query, required: false, schema: {type: string}, description: 客户名称关键字，不支持客户编号、信用代码或联系人搜索}
优化
2026-09-11 16:17:16 +08:00
- {name: status, in: query, required: false, schema: {type: string, enum: [PROFILE_REQUIRED, PENDING, ACTIVE, REJECTED, DISABLED]}}
暂存提交
2026-07-31 14:55:34 +08:00
responses:
'200':
description: 企业客户分页查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/TenantPageApiResponse'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 14:55:34 +08:00
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'422': {$ref: '#/components/responses/UnprocessableEntity'}
暂存提交
2026-07-30 18:01:36 +08:00
post:
tags: [Platform Tenant / 平台租户]
优化
2026-08-03 14:16:10 +08:00
summary: Register enterprise tenant / 创建企业客户草稿
优化
2026-08-25 15:08:34 +08:00
description: Create a `PROFILE_REQUIRED` enterprise draft and its OWNER account, returning one-time credentials. Customer creation succeeds after IAM commits; default dimensions initialize reliably in background and are exposed as `PENDING/READY/FAILED`. / 创建待完善企业客户草稿及 OWNER 账号并返回一次性凭据；IAM 提交即代表客户创建成功，默认尺寸在后台可靠初始化并显式返回 PENDING/READY/FAILED。
暂存提交
2026-07-30 18:01:36 +08:00
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/RegisterRequest'}
responses:
优化
2026-08-08 10:31:44 +08:00
'200': {$ref: '#/components/responses/TenantCreationSuccess'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-31 14:55:34 +08:00
/api/platform/v1/iam/authorization/permissions:
get:
tags: [IAM Resources / IAM 资源]
暂存提交
2026-07-31 16:53:07 +08:00
summary: 查询当前用户有效权限
优化
2026-09-09 12:57:59 +08:00
description: 返回当前有效平台成员权限编码；只要求有效 PLATFORM JWT，不依赖 `platform:role:list`。入库单扣货与解除扣货返回独立写权限 `platform:firstleg:inbound:hold`，不会由 `platform:firstleg:inbound:list` 查看权限自动获得。资金账户充值审核与手工调账分别返回 `platform:finance:recharge:review`、`platform:finance:customer-account:adjust`，并与 `platform:finance:customer-account:list` 只读权限分离。海外仓返回 `platform:overseas-warehouse:dispatch:list`、`platform:overseas-warehouse:dispatch:edit`、`platform:overseas-warehouse:dispatch:cancel`、`platform:overseas-warehouse:dispatch:transfer-delivery`、`platform:overseas-warehouse:outbound:list`、`platform:overseas-warehouse:outbound:create`、`platform:overseas-warehouse:outbound:cancel`、`platform:overseas-warehouse:delivery:list`、`platform:overseas-warehouse:delivery:return`、`platform:overseas-warehouse:delivery:status`、`platform:overseas-warehouse:delivery:documents`、`platform:overseas-warehouse:exception-order:list`、`platform:overseas-warehouse:exception-order:create`、`platform:overseas-warehouse:exception-order:process`、`platform:overseas-warehouse:customer-visit:list`、`platform:overseas-warehouse:customer-visit:edit`；海外 PDA 盘点、移库、换标和现场查询统一返回 `lastleg:pda:operate`，且仅限 `OVERSEAS_WAREHOUSE_PDA_OPERATOR`。货柜双工作台以 `platform:firstleg:container:list/create/edit` 维护国内送柜报关，国外清关提柜独立返回 `platform:firstleg:terminal-drayage:list`、`platform:firstleg:terminal-drayage:document:edit`、`platform:firstleg:terminal-drayage:fleet:edit`、`platform:firstleg:terminal-drayage:pickup-appointment:edit`、`platform:firstleg:terminal-drayage:pickup:confirm`、`platform:firstleg:terminal-drayage:empty-return:confirm`，不以 `container:list/edit` 兼容放行国外操作。派送三类资料管理使用独立写权限 `platform:overseas-warehouse:delivery:documents`；读取和下载仍使用 `platform:overseas-warehouse:delivery:list`。列表权限包含详情和只读辅助接口，写操作独立授权。
暂存提交
2026-07-31 14:55:34 +08:00
responses:
'200':
description: 当前平台成员权限查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/PermissionCodesApiResponse'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-07-31 16:53:07 +08:00
/api/platform/v1/iam/tenants/{tenantId}:
parameters:
- {$ref: '#/components/parameters/TenantId'}
get:
tags: [Platform Tenant / 平台租户]
summary: 查询企业客户档案
优化
2026-08-13 12:22:31 +08:00
description: 需要 `platform:customer:list` 权限，返回完整联系方式。
暂存提交
2026-07-31 16:53:07 +08:00
responses:
暂存提交
2026-08-03 12:43:30 +08:00
'200': {$ref: '#/components/responses/TenantSuccess'}
暂存提交
2026-07-31 16:53:07 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
暂存提交
2026-07-31 16:53:07 +08:00
put:
tags: [Platform Tenant / 平台租户]
summary: 编辑企业客户档案
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdateTenantRequest'}
responses:
暂存提交
2026-08-03 12:43:30 +08:00
'200': {$ref: '#/components/responses/TenantSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 16:53:07 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
优化
2026-08-07 09:06:19 +08:00
/api/platform/v1/iam/tenants/{tenantId}/members:
parameters:
- {$ref: '#/components/parameters/TenantId'}
get:
tags: [Platform Tenant / 平台租户]
summary: 查询企业客户成员及账号
优化
2026-08-13 12:22:31 +08:00
description: 平台只读查询指定客户的全部企业成员，包含 OWNER 企业管理员并返回登录账号；需要 `platform:customer:list` 权限。
优化
2026-08-07 09:06:19 +08:00
responses:
'200':
description: 企业成员查询成功
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformCustomerMembersApiResponse'
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
优化
2026-08-25 15:08:34 +08:00
/api/platform/v1/iam/tenants/{tenantId}/dimension-initialization:
parameters:
- {$ref: '#/components/parameters/TenantId'}
get:
tags: [Platform Tenant / 平台租户]
summary: 查询客户默认尺寸初始化诊断
description: 返回任务状态、尝试次数、下次重试时间和最后失败原因；不会把远端失败转换为空数据或成功。
responses:
'200':
description: 初始化诊断查询成功
content:
application/json:
schema:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/CustomerDimensionInitializationStatus'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
/api/platform/v1/iam/tenants/{tenantId}/dimension-initialization/retry:
parameters:
- {$ref: '#/components/parameters/TenantId'}
post:
tags: [Platform Tenant / 平台租户]
summary: 人工重试失败的客户默认尺寸初始化
description: 只允许 FAILED 任务重新进入 PENDING；稳定 initializationKey 不变。
responses:
'200': {$ref: '#/components/responses/TenantSuccess'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
优化
2026-08-03 14:16:10 +08:00
/api/platform/v1/iam/tenants/{tenantId}/submit-review:
parameters:
- {$ref: '#/components/parameters/TenantId'}
post:
tags: [Platform Tenant / 平台租户]
summary: 提交企业客户审核
优化
2026-09-02 10:04:18 +08:00
description: 校验营业执照和统一社会信用代码后创建审核单，并把客户状态改为 `PENDING`；法人身份证选填，保存资料和上传文件均不会自动调用本接口。
优化
2026-08-03 14:16:10 +08:00
responses:
'200': {$ref: '#/components/responses/TenantSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-08-03 12:43:30 +08:00
/api/platform/v1/iam/tenants/{tenantId}/addresses:
parameters:
- {$ref: '#/components/parameters/TenantId'}
get:
tags: [Platform Tenant / 平台租户]
summary: 查询企业客户地址
优化
2026-08-13 12:22:31 +08:00
description: 需要 `platform:customer:list` 权限；只读接口，不提供平台端地址写入。
暂存提交
2026-08-03 12:43:30 +08:00
responses:
'200':
description: 企业客户地址查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/TenantAddressListApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
/api/platform/v1/iam/tenants/{tenantId}/qualifications:
parameters:
- {$ref: '#/components/parameters/TenantId'}
get:
tags: [Platform Tenant / 平台租户]
summary: 查询企业客户资质
优化
2026-08-13 12:22:31 +08:00
description: 需要 `platform:customer:list` 权限；只读查询资质元数据，不授予审核权限。
暂存提交
2026-08-03 12:43:30 +08:00
responses:
'200':
description: 企业客户资质查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/TenantQualificationListApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
优化
2026-09-11 16:17:16 +08:00
/api/platform/v1/iam/tenants/{tenantId}/qualifications/{qualificationId}:
parameters:
- {$ref: '#/components/parameters/TenantId'}
- {name: qualificationId, in: path, required: true, schema: {type: integer, format: int64}}
get:
tags: [Platform Tenant / 平台租户]
summary: 查询企业客户资质详情
description: 需要 `platform:customer:list` 权限，并同时校验客户与资质归属。
responses:
'200':
description: 企业客户资质详情查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/TenantQualificationApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
暂存提交
2026-07-31 16:53:07 +08:00
/api/platform/v1/iam/tenants/{tenantId}/status:
parameters:
- {$ref: '#/components/parameters/TenantId'}
put:
tags: [Platform Tenant / 平台租户]
summary: 启停企业客户
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ChangeTenantStatusRequest'}
responses:
暂存提交
2026-08-03 12:43:30 +08:00
'200': {$ref: '#/components/responses/TenantSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 16:53:07 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
优化
2026-08-08 09:17:42 +08:00
/api/platform/v1/iam/tenants/{tenantId}/owner/password:
parameters:
- {$ref: '#/components/parameters/TenantId'}
put:
tags: [Platform Tenant / 平台租户]
summary: 重置客户企业管理员密码
description: 仅重置指定客户 OWNER 的认证密码；密码不写入审计快照并撤销该账号现有会话。
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ResetCustomerOwnerPasswordRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'400': {$ref: '#/components/responses/BadRequest'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'503': {$ref: '#/components/responses/ServiceUnavailable'}
/api/platform/v1/iam/tenants/{tenantId}/archive:
parameters:
- {$ref: '#/components/parameters/TenantId'}
post:
tags: [Platform Tenant / 平台租户]
summary: 逻辑归档客户
description: 仅停用客户及其认证账号，保留业务历史数据；重复归档幂等返回当前客户。
security: [{bearerAuth: []}]
responses:
'200': {$ref: '#/components/responses/TenantSuccess'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
'503': {$ref: '#/components/responses/ServiceUnavailable'}
/api/platform/v1/iam/tenants/{tenantId}/impersonation:
parameters:
- {$ref: '#/components/parameters/TenantId'}
post:
tags: [Platform Tenant / 平台租户]
summary: 创建客户代登录授权码
description: 创建 60 秒有效、只能兑换一次且不包含刷新令牌的客户 OWNER 代登录授权码。
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CustomerImpersonationRequest'}
responses:
'200':
description: 授权码创建成功
content:
application/json:
schema: {$ref: '#/components/schemas/CustomerImpersonationApiResponse'}
'400': {$ref: '#/components/responses/BadRequest'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
'503': {$ref: '#/components/responses/ServiceUnavailable'}
暂存提交
2026-07-31 14:55:34 +08:00
/api/merchant/v1/iam/authorization/permissions:
get:
tags: [IAM Resources / IAM 资源]
暂存提交
2026-07-31 16:53:07 +08:00
summary: 查询当前用户有效权限
feat(finance): add customer wallet recharge flow
2026-09-05 08:34:40 +08:00
description: 返回当前有效客户成员权限编码。资金账户和流水只读返回 `merchant:finance:account:view`，提交充值申请返回 `merchant:finance:recharge:create`，两者独立授权。海外采购、本土卡、本土散板和海外入库订单分别返回 `merchant:cross-border:procurement`、`merchant:cross-border:domestic-trucking`、`merchant:cross-border:pallet-shipping`、`merchant:warehouse:inbound:list`；客户派送返回 `merchant:warehouse:delivery:list` 和 `merchant:warehouse:delivery:create`。列表权限包含详情只读，创建权限独立授权。
暂存提交
2026-07-31 14:55:34 +08:00
responses:
'200':
description: 当前商户成员权限查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/PermissionCodesApiResponse'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/platform/v1/iam/reviews:
get:
tags: [Platform Tenant / 平台租户]
summary: List pending tenant reviews / 查询待审核企业
description: Return enterprise registrations waiting for a platform decision. / 返回等待平台处理的企业注册审核记录。
responses:
优化
2026-08-17 19:13:08 +08:00
'200':
description: 待审核企业及客户摘要查询成功
content:
application/json:
schema: {$ref: '#/components/schemas/PendingEnterpriseReviewListApiResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
/api/platform/v1/iam/reviews/{id}/approve:
post:
tags: [Platform Tenant / 平台租户]
summary: Approve enterprise registration / 审核通过企业注册
优化
2026-08-04 09:05:28 +08:00
description: Approve and activate the tenant. Client registrations keep the registration account as administrator. Only platform-created tenants without an owner receive a generated administrator and one-time credentials. / 审核通过并激活企业；客户端注册账号继续作为企业管理员，仅平台代建且没有所有者的企业自动创建管理员并返回一次性凭据。
暂存提交
2026-07-30 18:01:36 +08:00
parameters:
- {$ref: '#/components/parameters/Id'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ReviewRequest'}
responses:
优化
2026-08-04 09:05:28 +08:00
'200':
description: 审核通过；data 返回开户结果及一次性初始凭据
content:
application/json:
schema: {$ref: '#/components/schemas/TenantApprovalApiResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/platform/v1/iam/reviews/{id}/reject:
post:
tags: [Platform Tenant / 平台租户]
summary: Reject enterprise registration / 驳回企业注册
description: Reject a pending registration and save the review comment. / 驳回待审核注册申请并保存审核意见。
parameters:
- {$ref: '#/components/parameters/Id'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ReviewRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
优化
2026-08-03 13:16:19 +08:00
/api/platform/v1/iam/users:
get:
tags: [IAM Resources / IAM 资源]
优化
2026-08-04 13:32:24 +08:00
summary: 分页查询平台内部用户
parameters:
- {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
- {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
- {name: keyword, in: query, schema: {type: string}, description: 匹配姓名、手机号、邮箱或成员编号}
- {name: status, in: query, schema: {type: string, enum: [ACTIVE, DISABLED]}}
优化
2026-08-03 13:16:19 +08:00
responses:
优化
2026-08-04 13:32:24 +08:00
'200':
description: 仅返回 tenant_id=0 的平台内部用户分页
content:
application/json:
schema: {$ref: '#/components/schemas/PlatformManagedUserPageApiResponse'}
优化
2026-08-03 13:16:19 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
post:
tags: [IAM Resources / IAM 资源]
优化
2026-08-04 13:32:24 +08:00
summary: 新增平台内部用户
优化
2026-08-03 13:16:19 +08:00
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreatePlatformManagedUserRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
/api/platform/v1/iam/users/options:
get:
tags: [IAM Resources / IAM 资源]
优化
2026-08-05 16:26:10 +08:00
summary: 查询平台技术作用域和 PLATFORM 角色选项
优化
2026-08-03 13:16:19 +08:00
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
/api/platform/v1/iam/users/{membershipId}:
parameters:
- {$ref: '#/components/parameters/MembershipId'}
put:
tags: [IAM Resources / IAM 资源]
优化
2026-08-04 13:32:24 +08:00
summary: 编辑平台内部用户资料及角色
优化
2026-08-03 13:16:19 +08:00
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdatePlatformManagedUserRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
/api/platform/v1/iam/users/{membershipId}/status:
parameters:
- {$ref: '#/components/parameters/MembershipId'}
put:
tags: [IAM Resources / IAM 资源]
优化
2026-08-04 13:32:24 +08:00
summary: 启用或停用平台内部用户
优化
2026-08-03 13:16:19 +08:00
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ChangeInternalUserStatusRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
/api/platform/v1/iam/users/{membershipId}/password:
parameters:
- {$ref: '#/components/parameters/MembershipId'}
put:
tags: [IAM Resources / IAM 资源]
优化
2026-08-04 13:32:24 +08:00
summary: 重置平台内部用户密码
优化
2026-08-03 13:16:19 +08:00
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ResetInternalUserPasswordRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/platform/v1/iam/internal-users:
get:
tags: [IAM Resources / IAM 资源]
暂存提交
2026-07-31 13:52:35 +08:00
summary: 查询平台内部用户
暂存提交
2026-07-30 18:01:36 +08:00
responses:
暂存提交
2026-07-31 14:55:34 +08:00
'200':
description: 平台内部用户查询成功，公开主键为 membershipId 并回显 roleIds
content:
application/json:
schema: {$ref: '#/components/schemas/InternalUserListApiResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
post:
tags: [IAM Resources / IAM 资源]
暂存提交
2026-07-31 13:52:35 +08:00
summary: 新增平台内部用户
description: 创建完整的 Auth/IAM 平台账号，也兼容通过 authUserId 关联已有账号。
暂存提交
2026-07-30 18:01:36 +08:00
requestBody:
required: true
content:
application/json:
暂存提交
2026-07-31 13:52:35 +08:00
schema: {$ref: '#/components/schemas/CreateInternalUserRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-31 13:52:35 +08:00
/api/platform/v1/iam/internal-users/{membershipId}:
parameters:
- {$ref: '#/components/parameters/MembershipId'}
put:
tags: [IAM Resources / IAM 资源]
summary: 编辑平台内部用户
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdateInternalUserRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 13:52:35 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-31 13:52:35 +08:00
/api/platform/v1/iam/internal-users/{membershipId}/status:
parameters:
- {$ref: '#/components/parameters/MembershipId'}
put:
tags: [IAM Resources / IAM 资源]
summary: 启用或停用平台内部用户
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ChangeInternalUserStatusRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 13:52:35 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
暂存提交
2026-07-31 13:52:35 +08:00
/api/platform/v1/iam/internal-users/{membershipId}/password:
parameters:
- {$ref: '#/components/parameters/MembershipId'}
put:
tags: [IAM Resources / IAM 资源]
summary: 重置平台内部用户密码
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ResetInternalUserPasswordRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 13:52:35 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
暂存提交
2026-07-31 16:53:07 +08:00
/api/platform/v1/iam/internal-users/{membershipId}/roles:
parameters:
- {$ref: '#/components/parameters/MembershipId'}
put:
tags: [IAM 资源]
summary: 全量分配平台内部用户角色
优化
2026-08-05 16:26:10 +08:00
description: 仅允许分配平台技术作用域（tenant_id=0）下已启用的平台端角色；空集合表示清空角色。
暂存提交
2026-07-31 16:53:07 +08:00
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/AssignInternalUserRolesRequest'}
responses:
'200':
description: 角色分配成功并返回最新内部用户模型
content:
application/json:
schema: {$ref: '#/components/schemas/InternalUserApiResponse'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 16:53:07 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/merchant/v1/iam/tenant/profile:
get:
tags: [Merchant Tenant / 商户企业]
summary: Get current tenant profile / 查询当前企业资料
优化
2026-08-05 16:26:10 +08:00
description: The compatibility field tenant ID comes only from the verified JWT and currently identifies the customer. / 客户隔离兼容字段 tenant ID 仅取自已验证 JWT，当前表示登录客户 ID。
暂存提交
2026-07-30 18:01:36 +08:00
responses:
'200': {$ref: '#/components/responses/Success'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
暂存提交
2026-07-30 18:01:36 +08:00
put:
tags: [Merchant Tenant / 商户企业]
summary: Update current tenant profile / 更新当前企业资料
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdateProfileRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'404': {$ref: '#/components/responses/NotFound'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/merchant/v1/iam/members:
get:
tags: [Merchant Tenant / 商户企业]
summary: List enterprise members / 查询企业成员
responses:
优化
2026-08-17 19:51:54 +08:00
'200':
description: 企业成员列表，包含真实登录账号与最后登录时间
content:
application/json:
schema: {$ref: '#/components/schemas/MerchantMemberListApiResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
post:
tags: [Merchant Tenant / 商户企业]
summary: Add enterprise member / 新增企业成员
暂存提交
2026-08-03 12:43:30 +08:00
description: 新增基础资料需要 merchant:member:create；roleIds 非空时还必须具有 merchant:member:grant-role，否则返回 403/A0403。空数组表示不分配角色。
暂存提交
2026-07-30 18:01:36 +08:00
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreateMemberRequest'}
responses:
优化
2026-08-17 19:51:54 +08:00
'200':
description: 新增后的企业成员
content:
application/json:
schema: {$ref: '#/components/schemas/MerchantMemberApiResponse'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
/api/merchant/v1/iam/members/{membershipId}:
parameters:
- name: membershipId
in: path
required: true
description: 当前租户内的成员关系 ID
schema: {type: string, pattern: '^\d+$'}
get:
tags: [Merchant Tenant / 商户企业]
summary: 查询成员详情及当前角色
优化
2026-08-05 16:26:10 +08:00
description: 返回当前客户成员资料，roleIds 为服务端实时查询的当前角色集合；跨客户成员按不存在处理。
暂存提交
2026-08-03 12:43:30 +08:00
responses:
优化
2026-08-17 19:51:54 +08:00
'200':
description: 企业成员详情
content:
application/json:
schema: {$ref: '#/components/schemas/MerchantMemberApiResponse'}
暂存提交
2026-08-03 12:43:30 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
put:
tags: [Merchant Tenant / 商户企业]
summary: 编辑成员资料及角色
description: 基础资料编辑需要 merchant:member:edit。仅当 roleIds 与当前角色集合实际不同时额外要求 merchant:member:grant-role；传空数组清空角色也属于角色变更。角色集合未变化时不误拒绝。
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdateMemberRequest'}
responses:
优化
2026-08-17 19:51:54 +08:00
'200':
description: 更新后的企业成员
content:
application/json:
schema: {$ref: '#/components/schemas/MerchantMemberApiResponse'}
暂存提交
2026-08-03 12:43:30 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/merchant/v1/iam/tenant/addresses:
get:
tags: [IAM Resources / IAM 资源]
summary: List tenant addresses / 查询企业地址
responses:
优化
2026-08-17 19:51:54 +08:00
'200':
description: 角色列表及各角色实时成员数
content:
application/json:
schema: {$ref: '#/components/schemas/RoleListApiResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
post:
tags: [IAM Resources / IAM 资源]
summary: Add tenant address / 新增企业地址
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/AddressRequest'}
responses:
优化
2026-08-17 19:51:54 +08:00
'200':
description: 新增后的角色及实时成员数
content:
application/json:
schema: {$ref: '#/components/schemas/RoleApiResponse'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
/api/merchant/v1/iam/tenant/qualifications:
get:
tags: [IAM Resources / IAM 资源]
summary: List tenant qualifications / 查询企业资质
responses:
优化
2026-09-11 16:17:16 +08:00
'200':
description: 当前客户资质列表
content:
application/json:
schema: {$ref: '#/components/schemas/TenantQualificationListApiResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
优化
2026-09-11 16:17:16 +08:00
/api/merchant/v1/iam/tenant/qualifications/{qualificationId}:
parameters:
- {name: qualificationId, in: path, required: true, schema: {type: integer, format: int64}}
get:
tags: [IAM Resources / IAM 资源]
summary: 查询当前客户资质详情
description: 需要 `merchant:profile:view` 权限；客户范围来自 JWT，跨客户资质按不存在处理。
responses:
'200':
description: 当前客户资质详情
content:
application/json:
schema: {$ref: '#/components/schemas/TenantQualificationApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
delete:
tags: [IAM Resources / IAM 资源]
summary: 删除送审前企业资质
description: 需要 `merchant:qualification:upload` 权限；仅客户状态为 `PROFILE_REQUIRED` 或 `REJECTED` 时允许，`PENDING`、`ACTIVE` 等提交审核后的状态由服务端拒绝。客户范围来自 JWT；重复删除或跨客户 ID 返回相同幂等结果，不泄露归属。
responses:
'200':
description: 删除成功或目标已不存在
content:
application/json:
schema: {$ref: '#/components/schemas/QualificationDeletionApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
'409': {$ref: '#/components/responses/Conflict'}
优化
2026-08-03 18:28:35 +08:00
/api/merchant/v1/iam/tenant/qualifications/submit-review:
post:
tags: [IAM Resources / IAM 资源]
summary: Submit enterprise qualifications for review / 提交企业资质审核
优化
2026-09-02 10:04:18 +08:00
description: Uploading or replacing a qualification keeps the tenant in draft state. This endpoint requires only the business license and unified social credit code; legal-person ID, freight-forwarder certificate and bank account license are optional. / 上传或替换资质不会自动送审；本接口只要求营业执照和统一社会信用代码，法人身份证、货代资质证书和银行开户许可证选填。
优化
2026-08-03 18:28:35 +08:00
responses:
'200': {$ref: '#/components/responses/TenantSuccess'}
'400': {$ref: '#/components/responses/BadRequest'}
'403': {$ref: '#/components/responses/Forbidden'}
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/{app}/v1/iam/roles:
parameters:
- {$ref: '#/components/parameters/App'}
get:
tags: [RBAC]
summary: List roles / 查询角色
优化
2026-08-28 10:38:58 +08:00
description: List roles in the selected application and current customer or platform technical scope. Domestic first-leg PDA and overseas warehouse PDA operators are separate, mutually exclusive roles. / 查询指定应用及当前客户范围或平台技术作用域内的角色；国内头程 PDA 作业员与海外仓 PDA 作业员是两批独立人员，对应角色互斥且权限不交叉。
暂存提交
2026-07-30 18:01:36 +08:00
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
post:
tags: [RBAC]
summary: Create role / 新增角色
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreateRoleRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/{app}/v1/iam/members/roles:
put:
tags: [RBAC]
summary: Assign roles to member / 设置成员角色
feat(iam): 初始化三期仓库作业角色
2026-08-10 11:54:58 +08:00
description: Replace member role assignments in the same tenant and application. Platform administrators can assign the built-in warehouse roles to active internal-user memberships; the API does not create accounts or fixed credentials. / 在同一客户和应用域内替换成员角色；平台管理员可将内置仓库角色分配给已启用的内部用户成员，本接口不会创建账号或固定密码。
暂存提交
2026-07-30 18:01:36 +08:00
parameters:
- {$ref: '#/components/parameters/App'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/AssignRolesRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
/api/{app}/v1/iam/permissions:
parameters:
- {$ref: '#/components/parameters/App'}
get:
tags: [RBAC]
summary: List menu, page, button and API permissions / 查询菜单、页面、按钮和 API 权限
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
post:
tags: [RBAC]
summary: Create permission / 新增权限
description: Create a MENU, PAGE, BUTTON or API permission node. / 创建 MENU、PAGE、BUTTON 或 API 权限节点。
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreatePermissionRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-30 18:01:36 +08:00
/api/{app}/v1/iam/roles/permissions:
put:
tags: [RBAC]
summary: Grant permissions to role / 设置角色权限
优化
2026-08-05 16:26:10 +08:00
description: Replace role permissions; cross-customer and cross-application grants are rejected. / 替换角色权限，拒绝跨客户和跨应用授权。
暂存提交
2026-07-30 18:01:36 +08:00
parameters:
- {$ref: '#/components/parameters/App'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/GrantPermissionsRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-30 18:01:36 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-07-31 16:53:07 +08:00
/api/{app}/v1/iam/permissions/{permissionId}:
parameters:
- {$ref: '#/components/parameters/App'}
- {$ref: '#/components/parameters/PermissionId'}
put:
tags: [RBAC]
summary: 编辑自定义权限资源
description: 权限编码和类型不可变更，系统预置资源不可修改。
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/UpdatePermissionRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 16:53:07 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-31 16:53:07 +08:00
delete:
tags: [RBAC]
summary: 删除未绑定的自定义权限资源
description: 系统预置资源、存在子资源或已绑定角色的资源不可删除。
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
暂存提交
2026-07-31 16:53:07 +08:00
/api/{app}/v1/iam/permissions/{permissionId}/status:
parameters:
- {$ref: '#/components/parameters/App'}
- {$ref: '#/components/parameters/PermissionId'}
put:
tags: [RBAC]
summary: 启停自定义权限资源
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ChangePermissionStatusRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
暂存提交
2026-08-03 12:43:30 +08:00
'400': {$ref: '#/components/responses/BadRequest'}
暂存提交
2026-07-31 16:53:07 +08:00
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-08-03 12:43:30 +08:00
'409': {$ref: '#/components/responses/Conflict'}
优化
2026-09-11 16:17:16 +08:00
/internal/iam/merchant-registrations/{authUserId}:
get:
tags: [IAM Resources / IAM 资源]
summary: 查询已创建的企业注册状态
description: 仅供 Auth Service 对相同账号、手机号和密码的注册重试进行幂等确认，不创建或修改企业资料。
security: []
parameters:
- {$ref: '#/components/parameters/InternalServiceToken'}
- {name: authUserId, in: path, required: true, schema: {type: integer, format: int64}}
responses:
'200':
description: 注册状态查询成功
content:
application/json:
schema:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: object
required: [tenantId, membershipId, tenantStatus, dimensionInitializationStatus]
properties:
tenantId: {type: integer, format: int64}
membershipId: {type: integer, format: int64}
tenantStatus: {type: string, enum: [PROFILE_REQUIRED, PENDING, ACTIVE, REJECTED, DISABLED, ARCHIVED]}
dimensionInitializationStatus: {type: string, enum: [PENDING, READY, FAILED]}
'403': {$ref: '#/components/responses/Forbidden'}
'404': {$ref: '#/components/responses/NotFound'}
/internal/iam/qualifications:
post:
tags: [IAM Resources / IAM 资源]
summary: 登记客户单个选填资质
description: 仅供 File Service 调用；原始文件名必须由上传请求传入，不得从存储 URL 推断。
security: []
parameters:
- {$ref: '#/components/parameters/InternalServiceToken'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/QualificationSubmissionRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
'409': {$ref: '#/components/responses/Conflict'}
/internal/iam/platform-qualifications:
post:
tags: [IAM Resources / IAM 资源]
summary: 平台代客户登记单个选填资质
description: 仅供 File Service 调用；原始文件名必须由上传请求传入，不得从存储 URL 推断。
security: []
parameters:
- {$ref: '#/components/parameters/InternalServiceToken'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/QualificationSubmissionRequest'}
responses:
'200': {$ref: '#/components/responses/Success'}
'403': {$ref: '#/components/responses/Forbidden'}
'409': {$ref: '#/components/responses/Conflict'}
优化
2026-08-05 09:11:26 +08:00
/internal/iam/required-qualification-packages:
post:
tags: [IAM Resources / IAM 资源]
优化
2026-09-02 10:04:18 +08:00
summary: 商户营业执照资质包登记
description: 仅供 File Service 调用；在一个 IAM 事务中登记必填营业执照与统一社会信用代码，法人身份证可选。
优化
2026-08-05 09:11:26 +08:00
security: []
parameters:
- {$ref: '#/components/parameters/InternalServiceToken'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/RequiredQualificationPackageRequest'}
responses:
'200':
description: 统一响应；仅 data 非空且 code 为 200 表示资质包已完整登记
content:
application/json:
schema: {$ref: '#/components/schemas/RequiredQualificationPackageApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
/internal/iam/platform-required-qualification-packages:
post:
tags: [IAM Resources / IAM 资源]
优化
2026-09-02 10:04:18 +08:00
summary: 平台代客户登记营业执照资质包
description: 仅供 File Service 调用；与商户入口使用相同规则，营业执照与统一社会信用代码必填，法人身份证可选。
优化
2026-08-05 09:11:26 +08:00
security: []
parameters:
- {$ref: '#/components/parameters/InternalServiceToken'}
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/RequiredQualificationPackageRequest'}
responses:
'200':
description: 统一响应；仅 data 非空且 code 为 200 表示资质包已完整登记
content:
application/json:
schema: {$ref: '#/components/schemas/RequiredQualificationPackageApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
优化
2026-08-14 12:50:37 +08:00
/internal/iam/finance-customers:
get:
tags: [IAM Resources / IAM 资源]
summary: 提供财务客户主数据摘要
description: 仅供 Finance Service 调用；只返回正常/停用客户及财务账户所需的客户编号、名称和联系方式，不依赖财务表是否已有记录。
security: []
parameters:
- {$ref: '#/components/parameters/InternalServiceToken'}
- {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
- {name: size, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
- {name: keyword, in: query, required: false, schema: {type: string}}
- {name: status, in: query, required: false, schema: {type: string, enum: [ACTIVE, DISABLED]}}
- {name: customerId, in: query, required: false, schema: {type: integer, format: int64, minimum: 1}}
responses:
'200':
description: 财务客户主数据分页摘要
content:
application/json:
schema:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: object
required: [records, page, size, total, pages]
properties:
records: {type: array, items: {$ref: '#/components/schemas/FinanceCustomerSummary'}}
page: {type: integer}
size: {type: integer}
total: {type: integer, format: int64}
pages: {type: integer}
'403': {$ref: '#/components/responses/Forbidden'}
优化
2026-08-04 09:05:28 +08:00
/internal/exports/v1/CUSTOMER_LIST/batches:
post:
tags: [Internal Export Provider]
summary: 分批提供企业客户导出数据
description: 仅供 File Service 调用；按平台访问域、签名最大 ID 快照和游标只读查询商户客户。
security: []
parameters:
- name: X-Internal-Service-Token
in: header
required: true
schema: {type: string}
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [taskId, tenantId, appCode, requestedBy, dispatchVersion, parameters, limit]
properties:
taskId: {type: string, pattern: '^\d+$'}
tenantId: {type: string, pattern: '^\d+$'}
appCode: {type: string, enum: [PLATFORM]}
requestedBy: {type: string, pattern: '^\d+$'}
dispatchVersion: {type: integer, minimum: 1}
parameters: {type: object}
cursor: {type: string, nullable: true}
snapshotToken: {type: string, nullable: true, maxLength: 512}
limit: {type: integer, minimum: 1, maximum: 500}
responses:
'200':
description: 统一响应；data 为 ExportBatchResponse，Long 值以字符串传输
content:
application/json:
schema: {$ref: '#/components/schemas/ApiResponse'}
'403': {$ref: '#/components/responses/Forbidden'}
暂存提交
2026-07-30 18:01:36 +08:00
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
优化
2026-08-05 09:11:26 +08:00
InternalServiceToken:
name: X-Internal-Service-Token
in: header
required: true
schema: {type: string}
暂存提交
2026-07-30 18:01:36 +08:00
Id:
name: id
in: path
required: true
description: Resource ID / 资源 ID
schema: {type: integer, format: int64}
example: 190000000000000001
App:
name: app
in: path
required: true
description: Application domain / 应用域
schema: {type: string, enum: [platform, merchant]}
example: platform
暂存提交
2026-07-31 13:52:35 +08:00
MembershipId:
name: membershipId
in: path
required: true
暂存提交
2026-07-31 16:53:07 +08:00
description: 平台成员关系 ID
schema: {type: integer, format: int64}
TenantId:
name: tenantId
in: path
required: true
优化
2026-08-05 16:26:10 +08:00
description: 企业客户 ID；tenantId 为历史兼容参数名
暂存提交
2026-08-03 12:43:30 +08:00
schema: {type: string, pattern: '^\d+$'}
暂存提交
2026-07-31 16:53:07 +08:00
PermissionId:
name: permissionId
in: path
required: true
description: 权限资源 ID
暂存提交
2026-07-31 13:52:35 +08:00
schema: {type: integer, format: int64}
暂存提交
2026-07-30 18:01:36 +08:00
responses:
Success: {description: Operation succeeded / 操作成功, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
暂存提交
2026-08-03 12:43:30 +08:00
TenantSuccess: {description: Enterprise tenant returned / 返回企业客户档案, content: {application/json: {schema: {$ref: '#/components/schemas/TenantApiResponse'}}}}
优化
2026-08-08 10:31:44 +08:00
TenantCreationSuccess: {description: Enterprise tenant and one-time owner credentials returned / 返回企业客户及一次性管理员凭据, content: {application/json: {schema: {$ref: '#/components/schemas/TenantCreationApiResponse'}}}}
暂存提交
2026-08-03 12:43:30 +08:00
BadRequest: {description: Invalid request / 请求参数错误, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
暂存提交
2026-07-30 18:01:36 +08:00
Unauthorized: {description: Authentication required / 需要登录, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
优化
2026-08-25 12:27:47 +08:00
Forbidden: {description: 'Permission, customer scope or platform technical scope rejected / 权限、客户范围或平台技术作用域不匹配', content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
暂存提交
2026-08-03 12:43:30 +08:00
NotFound: {description: Resource not found / 资源不存在, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
Conflict: {description: Resource conflict / 资源冲突, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
优化
2026-08-08 09:17:42 +08:00
ServiceUnavailable: {description: Authentication service unavailable / 认证服务不可用, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
暂存提交
2026-08-03 12:43:30 +08:00
UnprocessableEntity: {description: 参数校验失败, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
暂存提交
2026-07-30 18:01:36 +08:00
schemas:
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
PersonalProfileResponse:
type: object
required: [userId, authUserId, username, displayName, phone]
properties:
userId: {type: string, pattern: '^\d+$'}
authUserId: {type: string, pattern: '^\d+$'}
username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'}
displayName: {type: string, maxLength: 64}
fix(auth): reject placeholder mobile numbers
2026-09-01 19:27:46 +08:00
phone: {type: string, pattern: '^1[3-9]\d{9}$'}
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
email: {type: string, format: email, nullable: true}
UpdatePersonalProfileRequest:
type: object
required: [displayName]
properties:
displayName: {type: string, minLength: 1, maxLength: 64}
email: {type: string, format: email, maxLength: 128, nullable: true}
ChangeLoginIdentifiersRequest:
type: object
required: [username, phone, currentPassword]
properties:
username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'}
fix(auth): reject placeholder mobile numbers
2026-09-01 19:27:46 +08:00
phone: {type: string, pattern: '^1[3-9]\d{9}$'}
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
currentPassword: {type: string, format: password, writeOnly: true}
PersonalProfileApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/PersonalProfileResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
ApiResponse:
type: object
required: [code, message, timestamp]
properties:
暂存提交
2026-08-03 12:43:30 +08:00
code: {type: string, example: '00000'}
暂存提交
2026-07-30 18:01:36 +08:00
message: {type: string, example: Success}
data: {}
requestId: {type: string}
traceId: {type: string}
timestamp: {type: string, format: date-time}
暂存提交
2026-07-31 14:55:34 +08:00
PermissionCodesApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: array
uniqueItems: true
items: {type: string}
优化
2026-08-17 19:51:54 +08:00
MerchantMemberResponse:
type: object
required: [membershipId, userId, authUserId, username, displayName, memberType, status, lastLoginAt, roleIds]
properties:
membershipId: {type: string, pattern: '^\d+$'}
userId: {type: string, pattern: '^\d+$'}
authUserId: {type: string, pattern: '^\d+$'}
username: {type: string, description: 统一认证登录账号}
displayName: {type: string}
phone: {type: string, nullable: true}
email: {type: string, format: email, nullable: true}
memberType: {type: string, enum: [OWNER, EMPLOYEE]}
memberNo: {type: string, nullable: true, description: 企业内部成员编号，不作为登录账号}
status: {type: string, enum: [ACTIVE, DISABLED]}
lastLoginAt: {type: string, format: date-time, nullable: true, description: 从 Auth 账号事实返回；null 表示从未登录}
roleIds: {type: array, items: {type: string, pattern: '^\d+$'}}
MerchantMemberListApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {type: array, items: {$ref: '#/components/schemas/MerchantMemberResponse'}}
MerchantMemberApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/MerchantMemberResponse'}
RoleResponse:
type: object
required: [id, tenantId, appCode, roleCode, roleName, roleType, status, memberCount, permissionIds]
properties:
id: {type: string, pattern: '^\d+$'}
tenantId: {type: string, pattern: '^\d+$'}
appCode: {type: string, enum: [PLATFORM, MERCHANT]}
roleCode: {type: string}
roleName: {type: string}
roleType: {type: string, enum: [SYSTEM, CUSTOM]}
status: {type: string, enum: [ACTIVE, DISABLED]}
description: {type: string, nullable: true}
memberCount: {type: integer, format: int64, minimum: 0, description: 当前客户及应用域内分配该角色的成员数}
permissionIds: {type: array, uniqueItems: true, items: {type: string, pattern: '^\d+$'}}
RoleListApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {type: array, items: {$ref: '#/components/schemas/RoleResponse'}}
RoleApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/RoleResponse'}
暂存提交
2026-07-31 14:55:34 +08:00
TenantPageApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: object
required: [records, page, size, total, pages]
properties:
records: {type: array, items: {$ref: '#/components/schemas/TenantResponse'}}
page: {type: integer, format: int64, minimum: 1}
size: {type: integer, format: int64, minimum: 1}
total: {type: integer, format: int64, minimum: 0}
pages: {type: integer, format: int64, minimum: 0}
优化
2026-08-04 09:05:28 +08:00
TenantApprovalApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/TenantApprovalResponse'}
优化
2026-08-17 19:13:08 +08:00
PendingEnterpriseReviewListApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: array
items: {$ref: '#/components/schemas/PendingEnterpriseReviewResponse'}
PendingEnterpriseReviewResponse:
type: object
required: [id, tenantId, reviewType, status, tenantName, tenantCode, contactName, submittedAt]
properties:
id: {type: string, pattern: '^\d+$', description: 审核单 ID}
tenantId: {type: string, pattern: '^\d+$', description: 客户 ID}
reviewType: {type: string, example: REGISTER}
status: {type: string, enum: [PENDING]}
tenantName: {type: string, description: 客户名称}
优化
2026-09-11 11:51:26 +08:00
tenantCode: {type: string, pattern: '^\d{5}$', example: '00001', description: 五位客户编号}
优化
2026-08-17 19:13:08 +08:00
contactName: {type: string, description: 联系人}
contactPhone: {type: string, nullable: true, description: 联系电话}
contactEmail: {type: string, format: email, nullable: true, description: 联系邮箱}
submittedAt: {type: string, format: date-time, description: 提交审核时间}
reviewComment: {type: string, nullable: true, description: 审核意见}
优化
2026-08-08 10:31:44 +08:00
TenantCreationApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/TenantCreationResponse'}
TenantCreationResponse:
type: object
required: [tenant, administratorUsername, temporaryPassword]
properties:
tenant: {$ref: '#/components/schemas/TenantResponse'}
administratorUsername: {type: string, example: '13800138000'}
temporaryPassword: {type: string, format: password, description: 一次性初始密码，仅本次创建响应返回}
优化
2026-08-04 09:05:28 +08:00
TenantApprovalResponse:
type: object
required: [tenantId, administratorCreated]
properties:
tenantId: {type: string, pattern: '^\d+$', example: '190000000000000001'}
administratorCreated: {type: boolean, description: 本次审核是否新建企业管理员}
优化
2026-08-07 14:46:55 +08:00
administratorUsername: {type: string, nullable: true, example: '13800138000'}
优化
2026-08-04 09:05:28 +08:00
temporaryPassword: {type: string, format: password, nullable: true, description: 一次性初始密码，仅新建管理员时返回}
暂存提交
2026-08-03 12:43:30 +08:00
TenantApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/TenantResponse'}
暂存提交
2026-07-31 14:55:34 +08:00
InternalUserListApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {type: array, items: {$ref: '#/components/schemas/InternalUserResponse'}}
暂存提交
2026-07-31 16:53:07 +08:00
InternalUserApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/InternalUserResponse'}
优化
2026-08-07 09:06:19 +08:00
PlatformCustomerMemberResponse:
type: object
required: [membershipId, userId, authUserId, username, displayName, memberType, status, roleIds, roleNames]
properties:
membershipId: {type: string, pattern: '^\d+$'}
userId: {type: string, pattern: '^\d+$'}
authUserId: {type: string, pattern: '^\d+$'}
username: {type: string}
displayName: {type: string}
phone: {type: string}
email: {type: string, format: email}
memberType: {type: string, enum: [OWNER, EMPLOYEE]}
memberNo: {type: string}
status: {type: string, enum: [ACTIVE, DISABLED]}
roleIds: {type: array, items: {type: string, pattern: '^\d+$'}}
roleNames: {type: array, items: {type: string}}
PlatformCustomerMembersApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {type: array, items: {$ref: '#/components/schemas/PlatformCustomerMemberResponse'}}
优化
2026-08-04 13:32:24 +08:00
PlatformManagedUserPageApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: object
required: [records, page, size, total, pages]
properties:
records: {type: array, items: {$ref: '#/components/schemas/PlatformManagedUserResponse'}}
page: {type: integer, minimum: 1}
size: {type: integer, minimum: 1}
total: {type: integer, minimum: 0}
pages: {type: integer, minimum: 0}
暂存提交
2026-07-31 14:55:34 +08:00
TenantResponse:
type: object
优化
2026-09-14 15:33:29 +08:00
required: [id, tenantCode, tenantName, customerNickname, status, dimensionInitializationStatus, servicePackage]
暂存提交
2026-07-31 14:55:34 +08:00
properties:
暂存提交
2026-08-03 12:43:30 +08:00
id: {type: string, pattern: '^\d+$', example: '190000000000000001'}
优化
2026-09-11 11:51:26 +08:00
tenantCode: {type: string, pattern: '^\d{5}$', example: '00001'}
暂存提交
2026-07-31 14:55:34 +08:00
tenantName: {type: string}
fix(iam): scope customer nickname to customer management
2026-09-14 15:38:29 +08:00
customerNickname: {type: string, maxLength: 32, description: 客户昵称}
优化
2026-08-14 16:06:27 +08:00
status: {type: string, enum: [PROFILE_REQUIRED, PENDING, ACTIVE, REJECTED, DISABLED, ARCHIVED]}
优化
2026-08-25 15:08:34 +08:00
dimensionInitializationStatus: {type: string, enum: [PENDING, READY, FAILED], description: 客户默认尺寸初始化状态；未 READY 时依赖该配置的业务失败关闭}
暂存提交
2026-07-31 14:55:34 +08:00
legalName: {type: string}
优化
2026-09-11 16:17:16 +08:00
legalRepresentative: {type: string, maxLength: 64, nullable: true}
暂存提交
2026-07-31 14:55:34 +08:00
unifiedSocialCreditCode: {type: string}
contactName: {type: string}
contactPhone: {type: string}
contactEmail: {type: string, format: email}
暂存提交
2026-08-03 12:43:30 +08:00
contactWechat: {type: string, maxLength: 64}
优化
2026-08-03 14:16:10 +08:00
servicePackage: {type: string, maxLength: 64}
暂存提交
2026-08-03 12:43:30 +08:00
salesOwnerName: {type: string, maxLength: 64}
paymentTermDays: {type: integer, minimum: 0, maximum: 365}
enterpriseType: {type: string, maxLength: 64}
establishedDate: {type: string, format: date}
registeredCapital: {type: number, format: decimal, minimum: 0}
registeredCapitalCurrency: {type: string, pattern: '^[A-Z]{3}$', example: CNY}
registeredAddress: {type: string, maxLength: 500}
internalRemark: {type: string, maxLength: 1000, description: 仅平台端可见}
createdAt: {type: string, format: date-time, description: 入驻时间}
approvedAt: {type: string, format: date-time, description: 审批通过时间}
优化
2026-08-25 15:08:34 +08:00
CustomerDimensionInitializationStatus:
type: object
required: [tenantId, status, attemptCount, nextRetryAt, updatedAt]
properties:
tenantId: {type: string, pattern: '^\d+$'}
status: {type: string, enum: [PENDING, SENDING, READY, FAILED, CANCELLED]}
attemptCount: {type: integer, minimum: 0}
nextRetryAt: {type: string, format: date-time}
lastErrorCode: {type: string, nullable: true}
lastErrorMessage: {type: string, nullable: true, description: 已清洗且截断的最后失败诊断}
updatedAt: {type: string, format: date-time}
优化
2026-08-14 12:50:37 +08:00
FinanceCustomerSummary:
type: object
fix(iam): scope customer nickname to customer management
2026-09-14 15:38:29 +08:00
required: [id, tenantCode, tenantName, status]
优化
2026-08-14 12:50:37 +08:00
properties:
id: {type: string, pattern: '^\d+$'}
优化
2026-09-11 11:51:26 +08:00
tenantCode: {type: string, pattern: '^\d{5}$', example: '00001'}
优化
2026-08-14 12:50:37 +08:00
tenantName: {type: string}
status: {type: string, enum: [ACTIVE, DISABLED]}
contactName: {type: string, nullable: true}
contactPhone: {type: string, nullable: true}
暂存提交
2026-08-03 12:43:30 +08:00
TenantAddressListApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: array
items: {$ref: '#/components/schemas/TenantAddress'}
TenantQualificationListApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: array
items: {$ref: '#/components/schemas/TenantQualification'}
优化
2026-09-11 16:17:16 +08:00
TenantQualificationApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/TenantQualification'}
QualificationDeletionApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: object
required: [qualificationId]
properties:
qualificationId: {type: string, pattern: '^\d+$'}
deletedDocumentUrl: {type: string, nullable: true, description: 首次删除时返回，供 File Service 回收文件；重复删除为空}
暂存提交
2026-08-03 12:43:30 +08:00
TenantAddress:
type: object
properties:
id: {type: string, pattern: '^\d+$'}
tenantId: {type: string, pattern: '^\d+$'}
addressType: {type: string}
countryCode: {type: string}
province: {type: string}
city: {type: string}
district: {type: string}
detail: {type: string}
postalCode: {type: string}
isDefault: {type: boolean}
TenantQualification:
type: object
优化
2026-09-11 16:17:16 +08:00
required: [id, tenantId, qualificationType, documentUrl, originalFileName, status, createdAt, updatedAt]
暂存提交
2026-08-03 12:43:30 +08:00
properties:
id: {type: string, pattern: '^\d+$'}
tenantId: {type: string, pattern: '^\d+$'}
优化
2026-08-03 14:16:10 +08:00
qualificationType: {type: string, enum: [BUSINESS_LICENSE, LEGAL_PERSON_ID, FREIGHT_FORWARDER_CERTIFICATE, BANK_ACCOUNT_LICENSE]}
暂存提交
2026-08-03 12:43:30 +08:00
certificateNo: {type: string}
documentUrl: {type: string}
优化
2026-09-11 16:17:16 +08:00
originalFileName: {type: string, description: 上传时原始文件名；前端不得从 URL 或内部 ID 推断}
暂存提交
2026-08-03 12:43:30 +08:00
validFrom: {type: string, format: date}
优化
2026-08-03 14:16:10 +08:00
validTo: {type: string, format: date, nullable: true}
优化
2026-08-03 18:28:35 +08:00
status: {type: string, enum: [PENDING, APPROVED, REJECTED, SUPERSEDED]}
暂存提交
2026-08-03 12:43:30 +08:00
reviewComment: {type: string}
优化
2026-09-11 16:17:16 +08:00
createdAt: {type: string, format: date-time}
updatedAt: {type: string, format: date-time}
QualificationSubmissionRequest:
type: object
required: [tenantId, qualificationType, documentUrl, originalFileName, replace]
properties:
tenantId: {type: string, pattern: '^\d+$'}
qualificationType: {type: string, enum: [LEGAL_PERSON_ID, FREIGHT_FORWARDER_CERTIFICATE, BANK_ACCOUNT_LICENSE]}
certificateNo: {type: string, nullable: true}
documentUrl: {type: string, minLength: 1}
originalFileName: {type: string, minLength: 1, maxLength: 255}
validTo: {type: string, format: date, nullable: true}
replace: {type: boolean}
优化
2026-08-05 09:11:26 +08:00
RequiredQualificationPackageRequest:
type: object
优化
2026-09-11 16:17:16 +08:00
required: [tenantId, unifiedSocialCreditCode, businessLicenseDocumentUrl, businessLicenseOriginalFileName, replaceBusinessLicense]
优化
2026-08-05 09:11:26 +08:00
properties:
tenantId: {type: string, pattern: '^\d+$'}
unifiedSocialCreditCode: {type: string, pattern: '^[0-9A-Za-z]{18}$'}
businessLicenseDocumentUrl: {type: string, minLength: 1}
优化
2026-09-11 16:17:16 +08:00
businessLicenseOriginalFileName: {type: string, minLength: 1, maxLength: 255}
优化
2026-08-05 09:11:26 +08:00
businessLicenseValidTo: {type: string, format: date, nullable: true}
replaceBusinessLicense: {type: boolean}
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
legalPersonIdDocumentUrl: {type: string, minLength: 1, nullable: true, description: 法人身份证选填}
优化
2026-09-11 16:17:16 +08:00
legalPersonIdOriginalFileName: {type: string, maxLength: 255, nullable: true, description: 上传法人身份证时必传}
优化
2026-08-05 09:11:26 +08:00
legalPersonIdValidTo: {type: string, format: date, nullable: true}
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
replaceLegalPersonId: {type: boolean, nullable: true, default: false}
优化
2026-08-05 09:11:26 +08:00
RequiredQualificationPackageResponse:
type: object
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
required: [businessLicenseQualificationId, tenantStatus]
优化
2026-08-05 09:11:26 +08:00
properties:
businessLicenseQualificationId: {type: string, pattern: '^\d+$'}
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
legalPersonIdQualificationId: {type: string, pattern: '^\d+$', nullable: true}
优化
2026-08-05 09:11:26 +08:00
tenantStatus: {type: string, enum: [PROFILE_REQUIRED, REJECTED]}
replacedBusinessLicenseDocumentUrl: {type: string, nullable: true}
replacedLegalPersonIdDocumentUrl: {type: string, nullable: true}
RequiredQualificationPackageApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data: {$ref: '#/components/schemas/RequiredQualificationPackageResponse'}
暂存提交
2026-07-30 18:01:36 +08:00
RegisterRequest:
type: object
优化
2026-09-11 16:17:16 +08:00
required: [tenantName, legalName, contactName, contactPhone, servicePackage]
暂存提交
2026-07-30 18:01:36 +08:00
properties:
tenantName: {type: string, example: 深圳虫虫出海科技有限公司}
优化
2026-09-14 15:33:29 +08:00
customerNickname: {type: string, maxLength: 32, example: SZWL, description: 选填；不填时默认取公司名称各中文字符的拼音大写首字母，没有中文时取首个非空字符并转大写}
优化
2026-08-04 09:05:28 +08:00
legalName: {type: string, example: 深圳虫虫出海科技有限公司}
优化
2026-09-11 16:17:16 +08:00
legalRepresentative: {type: string, maxLength: 64, nullable: true, example: 张三, description: 选填}
暂存提交
2026-07-30 18:01:36 +08:00
contactName: {type: string, example: 李四}
优化
2026-09-02 10:04:18 +08:00
contactPhone: {type: string, pattern: '^1[3-9]\d{9}$', example: '13800138000', description: 创建时同时初始化公司联系电话与首个管理员登录手机号；创建后二者独立维护}
暂存提交
2026-07-30 18:01:36 +08:00
contactEmail: {type: string, format: email, example: contact@example.com}
暂存提交
2026-08-03 12:43:30 +08:00
contactWechat: {type: string, maxLength: 64}
优化
2026-08-03 14:16:10 +08:00
servicePackage: {type: string, maxLength: 64, example: 基础版}
暂存提交
2026-08-03 12:43:30 +08:00
salesOwnerName: {type: string, maxLength: 64}
paymentTermDays: {type: integer, minimum: 0, maximum: 365}
enterpriseType: {type: string, maxLength: 64}
establishedDate: {type: string, format: date}
registeredCapital: {type: number, format: decimal, minimum: 0}
registeredCapitalCurrency: {type: string, pattern: '^[A-Z]{3}$', example: CNY}
registeredAddress: {type: string, maxLength: 500}
internalRemark: {type: string, maxLength: 1000}
暂存提交
2026-07-30 18:01:36 +08:00
UpdateProfileRequest:
type: object
优化
2026-09-11 16:17:16 +08:00
required: [tenantName, legalName, contactName, contactPhone]
暂存提交
2026-07-30 18:01:36 +08:00
properties:
tenantName: {type: string}
legalName: {type: string}
优化
2026-09-11 16:17:16 +08:00
legalRepresentative: {type: string, maxLength: 64, nullable: true, description: 选填}
暂存提交
2026-07-30 18:01:36 +08:00
contactName: {type: string}
优化
2026-09-02 10:04:18 +08:00
contactPhone: {type: string, pattern: '^[0-9-]{4,32}$', description: 公司联系电话，不作为登录标识且不要求跨企业唯一}
暂存提交
2026-07-30 18:01:36 +08:00
contactEmail: {type: string, format: email}
暂存提交
2026-07-31 16:53:07 +08:00
UpdateTenantRequest:
type: object
优化
2026-09-14 15:33:29 +08:00
required: [tenantName, customerNickname, legalName, contactName, contactPhone]
暂存提交
2026-07-31 16:53:07 +08:00
properties:
tenantName: {type: string}
fix(iam): scope customer nickname to customer management
2026-09-14 15:38:29 +08:00
customerNickname: {type: string, maxLength: 32, description: 客户昵称}
暂存提交
2026-07-31 16:53:07 +08:00
legalName: {type: string}
优化
2026-09-11 16:17:16 +08:00
legalRepresentative: {type: string, maxLength: 64, nullable: true, description: 选填}
暂存提交
2026-07-31 16:53:07 +08:00
contactName: {type: string}
优化
2026-09-02 10:04:18 +08:00
contactPhone: {type: string, pattern: '^[0-9-]{4,32}$', description: 公司联系电话，与管理员及成员登录手机号独立且不要求跨企业唯一}
暂存提交
2026-07-31 16:53:07 +08:00
contactEmail: {type: string, format: email}
暂存提交
2026-08-03 12:43:30 +08:00
contactWechat: {type: string, maxLength: 64}
优化
2026-08-03 14:16:10 +08:00
servicePackage: {type: string, maxLength: 64, example: 基础版}
暂存提交
2026-08-03 12:43:30 +08:00
salesOwnerName: {type: string, maxLength: 64}
paymentTermDays: {type: integer, minimum: 0, maximum: 365}
enterpriseType: {type: string, maxLength: 64}
establishedDate: {type: string, format: date}
registeredCapital: {type: number, format: decimal, minimum: 0}
registeredCapitalCurrency: {type: string, pattern: '^[A-Z]{3}$'}
registeredAddress: {type: string, maxLength: 500}
internalRemark: {type: string, maxLength: 1000}
暂存提交
2026-07-31 16:53:07 +08:00
ChangeTenantStatusRequest:
type: object
required: [status]
properties:
status: {type: string, enum: [ACTIVE, DISABLED]}
优化
2026-08-08 09:17:42 +08:00
ResetCustomerOwnerPasswordRequest:
type: object
required: [newPassword]
properties:
newPassword: {type: string, format: password, minLength: 8, maxLength: 64, writeOnly: true}
forceChangePassword: {type: boolean, default: true}
CustomerImpersonationRequest:
type: object
required: [reason]
properties:
reason: {type: string, minLength: 5, maxLength: 500}
CustomerImpersonationApiResponse:
allOf:
- {$ref: '#/components/schemas/ApiResponse'}
- type: object
properties:
data:
type: object
required: [code, ticketId, expiresIn]
properties:
code: {type: string, writeOnly: true}
ticketId: {type: string, format: uuid}
expiresIn: {type: integer, example: 60}
暂存提交
2026-07-30 18:01:36 +08:00
ReviewRequest:
type: object
properties:
refactor(api): 统一 HTTP 200 响应契约
2026-08-01 10:17:20 +08:00
comment: {type: string, maxLength: 500, description: Review comment or rejection reason / 审核意见或驳回原因}
优化
2026-08-03 13:16:19 +08:00
CreatePlatformManagedUserRequest:
type: object
required: [username, displayName, phone, tenantId, roleIds, password, status]
properties:
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'}
优化
2026-08-03 13:16:19 +08:00
displayName: {type: string, maxLength: 64}
优化
2026-09-02 10:04:18 +08:00
phone: {type: string, pattern: '^1[3-9]\\d{9}$', description: 平台账号登录手机号；修改时同步 Auth、撤销该账号会话并审计}
优化
2026-08-03 13:16:19 +08:00
email: {type: string, format: email, maxLength: 128}
优化
2026-08-05 16:26:10 +08:00
tenantId: {type: integer, format: int64, enum: [0], description: 保留的兼容字段，只允许平台技术作用域 0}
优化
2026-08-03 13:16:19 +08:00
roleIds: {type: array, minItems: 1, items: {type: integer, format: int64}}
优化
2026-08-28 10:38:58 +08:00
overseasWarehouseId: {type: integer, format: int64, nullable: true, description: 选择 OVERSEAS_WAREHOUSE_PDA_OPERATOR 时必填且只能绑定一个实际海外仓；CN_FIRSTLEG_PDA_OPERATOR 与其他角色必须为空；两个 PDA 角色不能同时分配}
优化
2026-08-03 13:16:19 +08:00
password: {type: string, format: password, minLength: 8, maxLength: 64, writeOnly: true}
status: {type: string, enum: [ACTIVE, DISABLED]}
UpdatePlatformManagedUserRequest:
type: object
required: [displayName, phone, tenantId, roleIds]
properties:
displayName: {type: string, maxLength: 64}
优化
2026-09-02 10:04:18 +08:00
phone: {type: string, pattern: '^1[3-9]\\d{9}$', description: 平台账号登录手机号；与任何企业联系电话无关}
优化
2026-08-03 13:16:19 +08:00
email: {type: string, format: email, maxLength: 128}
优化
2026-08-05 16:26:10 +08:00
tenantId: {type: integer, format: int64, enum: [0], description: 保留的兼容字段，只允许平台技术作用域 0}
优化
2026-08-03 13:16:19 +08:00
roleIds: {type: array, minItems: 1, items: {type: integer, format: int64}}
优化
2026-08-28 10:38:58 +08:00
overseasWarehouseId: {type: integer, format: int64, nullable: true, description: 选择 OVERSEAS_WAREHOUSE_PDA_OPERATOR 时必填且只能绑定一个实际海外仓；CN_FIRSTLEG_PDA_OPERATOR 与其他角色必须为空；两个 PDA 角色不能同时分配}
暂存提交
2026-07-31 13:52:35 +08:00
CreateInternalUserRequest:
暂存提交
2026-07-30 18:01:36 +08:00
type: object
暂存提交
2026-07-31 13:52:35 +08:00
required: [displayName]
暂存提交
2026-07-30 18:01:36 +08:00
properties:
暂存提交
2026-07-31 13:52:35 +08:00
authUserId: {type: integer, format: int64, description: 兼容旧接口；填写后关联已有认证账号}
userType: {type: string, enum: [INTERNAL, PLATFORM], description: 兼容旧接口，可省略}
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'}
暂存提交
2026-07-31 13:52:35 +08:00
password: {type: string, format: password, minLength: 8, maxLength: 64, writeOnly: true}
displayName: {type: string, maxLength: 64}
优化
2026-09-02 10:04:18 +08:00
phone: {type: string, pattern: '^1[3-9]\d{9}$', description: 企业成员登录手机号；修改时同步 Auth、撤销该账号会话并审计}
暂存提交
2026-07-31 13:52:35 +08:00
email: {type: string, format: email, maxLength: 128}
memberNo: {type: string, maxLength: 64}
roleIds: {type: array, items: {type: integer, format: int64}}
UpdateInternalUserRequest:
type: object
required: [displayName, memberNo, roleIds]
properties:
displayName: {type: string, maxLength: 64}
优化
2026-09-02 10:04:18 +08:00
phone: {type: string, pattern: '^1[3-9]\d{9}$', description: 企业成员登录手机号；与公司联系电话无关}
暂存提交
2026-07-31 13:52:35 +08:00
email: {type: string, format: email, maxLength: 128}
memberNo: {type: string, maxLength: 64}
roleIds: {type: array, items: {type: integer, format: int64}}
ChangeInternalUserStatusRequest:
type: object
required: [status]
properties:
status: {type: string, enum: [ACTIVE, DISABLED]}
ResetInternalUserPasswordRequest:
type: object
required: [newPassword]
properties:
newPassword: {type: string, format: password, minLength: 8, maxLength: 64, writeOnly: true}
暂存提交
2026-07-31 16:53:07 +08:00
AssignInternalUserRolesRequest:
type: object
required: [roleIds]
properties:
roleIds: {type: array, items: {type: integer, format: int64}}
暂存提交
2026-07-31 13:52:35 +08:00
InternalUserResponse:
type: object
required: [membershipId, userId, authUserId, username, displayName, memberType, status, roleIds]
properties:
membershipId: {type: integer, format: int64}
userId: {type: integer, format: int64}
暂存提交
2026-07-30 18:01:36 +08:00
authUserId: {type: integer, format: int64}
暂存提交
2026-07-31 13:52:35 +08:00
username: {type: string}
暂存提交
2026-07-30 18:01:36 +08:00
displayName: {type: string}
phone: {type: string}
email: {type: string, format: email}
暂存提交
2026-07-31 13:52:35 +08:00
memberType: {type: string, enum: [EMPLOYEE]}
memberNo: {type: string}
status: {type: string, enum: [ACTIVE, DISABLED]}
roleIds: {type: array, items: {type: integer, format: int64}}
优化
2026-08-04 13:32:24 +08:00
PlatformManagedUserResponse:
type: object
required: [membershipId, userId, authUserId, username, displayName, tenantId, tenantName, memberType, status, roleIds, roleNames, protectedAccount]
properties:
membershipId: {type: string, pattern: '^\d+$'}
userId: {type: string, pattern: '^\d+$'}
authUserId: {type: string, pattern: '^\d+$'}
username: {type: string}
displayName: {type: string}
phone: {type: string}
email: {type: string, format: email}
tenantId: {type: string, enum: ['0']}
tenantName: {type: string, enum: [平台]}
memberType: {type: string, enum: [EMPLOYEE]}
memberNo: {type: string}
status: {type: string, enum: [ACTIVE, DISABLED]}
roleIds: {type: array, items: {type: string, pattern: '^\d+$'}}
roleNames: {type: array, items: {type: string}}
lastLoginAt: {type: string, format: date-time, nullable: true}
protectedAccount: {type: boolean}
fix: bind overseas receiving to shared warehouse
2026-08-24 21:46:19 +08:00
overseasWarehouseId: {type: string, pattern: '^\d+$', nullable: true, description: 海外仓PDA操作员绑定的唯一实际海外仓ID}
暂存提交
2026-07-30 18:01:36 +08:00
CreateMemberRequest:
type: object
required: [username, password, displayName, memberType]
properties:
feat(auth): support username or phone login
2026-09-01 19:15:32 +08:00
username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'}
暂存提交
2026-07-30 18:01:36 +08:00
password: {type: string, format: password, minLength: 8, maxLength: 64}
displayName: {type: string, maxLength: 64}
fix(auth): reject placeholder mobile numbers
2026-09-01 19:27:46 +08:00
phone: {type: string, pattern: '^1[3-9]\d{9}$'}
暂存提交
2026-07-30 18:01:36 +08:00
email: {type: string, format: email, maxLength: 128}
暂存提交
2026-08-03 12:43:30 +08:00
memberType: {type: string, enum: [EMPLOYEE]}
暂存提交
2026-07-30 18:01:36 +08:00
memberNo: {type: string}
暂存提交
2026-08-03 12:43:30 +08:00
roleIds:
type: array
description: 初始角色 ID；非空时额外要求 merchant:member:grant-role
items: {type: string, pattern: '^\d+$'}
UpdateMemberRequest:
type: object
required: [displayName, memberType]
properties:
displayName: {type: string, maxLength: 64}
fix(auth): reject placeholder mobile numbers
2026-09-01 19:27:46 +08:00
phone: {type: string, pattern: '^1[3-9]\d{9}$'}
暂存提交
2026-08-03 12:43:30 +08:00
email: {type: string, format: email, maxLength: 128}
memberType: {type: string, enum: [EMPLOYEE]}
memberNo: {type: string, maxLength: 64}
roleIds:
type: array
description: 完整目标角色集合；空数组表示清空，集合变化时额外要求 merchant:member:grant-role
items: {type: string, pattern: '^\d+$'}
暂存提交
2026-07-30 18:01:36 +08:00
AddressRequest:
type: object
required: [addressType, detail]
properties:
addressType: {type: string, enum: [OPERATING, BILLING, RETURN]}
countryCode: {type: string, example: CN}
province: {type: string}
city: {type: string}
district: {type: string}
detail: {type: string}
postalCode: {type: string}
isDefault: {type: boolean}
CreateRoleRequest:
type: object
required: [roleCode, roleName]
properties:
roleCode: {type: string, example: ORDER_OPERATOR}
roleName: {type: string, example: 订单操作员}
description: {type: string}
CreatePermissionRequest:
type: object
required: [type, code, name]
properties:
type: {type: string, enum: [MENU, PAGE, BUTTON, API], example: BUTTON}
code: {type: string, example: 'order:firstleg:submit'}
name: {type: string, example: 提交头程订单}
parentId: {type: integer, format: int64, example: 0}
routePath: {type: string}
httpMethod: {type: string, enum: [GET, POST, PUT, PATCH, DELETE]}
sortNo: {type: integer, example: 10}
暂存提交
2026-07-31 16:53:07 +08:00
UpdatePermissionRequest:
type: object
required: [name]
properties:
name: {type: string}
parentId: {type: integer, format: int64}
routePath: {type: string}
httpMethod: {type: string, enum: [GET, POST, PUT, PATCH, DELETE]}
sortNo: {type: integer}
ChangePermissionStatusRequest:
type: object
required: [status]
properties:
status: {type: string, enum: [ACTIVE, DISABLED]}
暂存提交
2026-07-30 18:01:36 +08:00
AssignRolesRequest:
type: object
required: [membershipId, roleIds]
properties:
membershipId: {type: integer, format: int64}
roleIds: {type: array, items: {type: integer, format: int64}}
GrantPermissionsRequest:
type: object
required: [roleId, permissionIds]
properties:
roleId: {type: integer, format: int64}
permissionIds: {type: array, items: {type: integer, format: int64}}
Reference in New Issue Copy Permalink