openapi: 3.0.3 info: title: Baiyue IAM API / 百悦身份与权限 API 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 和公共仓储资源技术作用域。 version: 1.0.1 servers: - url: / security: - bearerAuth: [] tags: - name: Platform Tenant / 平台租户 description: Historical tag for platform customer administration; it does not represent a real tenant layer. / 历史兼容标签，实际用于平台客户管理，不表示真实租户层。 - name: Merchant Tenant / 商户企业 description: Current customer profile and members; tenant naming is retained for compatibility. / 当前客户企业资料与成员；tenant 命名仅为兼容。 - name: IAM Resources / IAM 资源 description: Internal users, addresses and qualifications / 内部用户、地址与资质 - name: RBAC description: Platform and merchant role-permission management / 平台端与商户端角色权限管理 paths: /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'} /api/platform/v1/iam/tenants/administrator-phone-availability: get: tags: [Platform Tenant / 平台租户] summary: 校验首个管理员登录手机号唯一性 description: 仅在创建客户前校验 Auth 登录手机号；公司联系电话不要求跨企业唯一。 parameters: - {name: phone, in: query, required: true, schema: {type: string, pattern: '^1[3-9]\d{9}$'}} responses: '200': description: 返回手机号是否可作为首个管理员登录手机号 content: application/json: schema: type: object properties: code: {type: string} message: {type: string} data: {type: boolean} '403': {$ref: '#/components/responses/Forbidden'} /api/platform/v1/iam/tenants: get: tags: [Platform Tenant / 平台租户] summary: 查询企业客户列表 description: 分页查询商户企业客户，需要 `platform:customer:list` 权限；联系电话和邮箱仅返回脱敏摘要。 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}} - {name: keyword, in: query, required: false, schema: {type: string}, description: 客户名称关键字，不支持客户编号、信用代码或联系人搜索} - {name: status, in: query, required: false, schema: {type: string, enum: [PROFILE_REQUIRED, PENDING, ACTIVE, REJECTED, DISABLED]}} responses: '200': description: 企业客户分页查询成功 content: application/json: schema: {$ref: '#/components/schemas/TenantPageApiResponse'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '422': {$ref: '#/components/responses/UnprocessableEntity'} post: tags: [Platform Tenant / 平台租户] summary: Register enterprise tenant / 创建企业客户草稿 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。 requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/RegisterRequest'} responses: '200': {$ref: '#/components/responses/TenantCreationSuccess'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} /api/platform/v1/iam/authorization/permissions: get: tags: [IAM Resources / IAM 资源] summary: 查询当前用户有效权限 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`。列表权限包含详情和只读辅助接口，写操作独立授权。 responses: '200': description: 当前平台成员权限查询成功 content: application/json: schema: {$ref: '#/components/schemas/PermissionCodesApiResponse'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} /api/platform/v1/iam/tenants/{tenantId}: parameters: - {$ref: '#/components/parameters/TenantId'} get: tags: [Platform Tenant / 平台租户] summary: 查询企业客户档案 description: 需要 `platform:customer:list` 权限，返回完整联系方式。 responses: '200': {$ref: '#/components/responses/TenantSuccess'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} put: tags: [Platform Tenant / 平台租户] summary: 编辑企业客户档案 requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/UpdateTenantRequest'} responses: '200': {$ref: '#/components/responses/TenantSuccess'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /api/platform/v1/iam/tenants/{tenantId}/members: parameters: - {$ref: '#/components/parameters/TenantId'} get: tags: [Platform Tenant / 平台租户] summary: 查询企业客户成员及账号 description: 平台只读查询指定客户的全部企业成员，包含 OWNER 企业管理员并返回登录账号；需要 `platform:customer:list` 权限。 responses: '200': description: 企业成员查询成功 content: application/json: schema: $ref: '#/components/schemas/PlatformCustomerMembersApiResponse' '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /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'} /api/platform/v1/iam/tenants/{tenantId}/submit-review: parameters: - {$ref: '#/components/parameters/TenantId'} post: tags: [Platform Tenant / 平台租户] summary: 提交企业客户审核 description: 校验营业执照和统一社会信用代码后创建审核单，并把客户状态改为 `PENDING`；法人身份证选填，保存资料和上传文件均不会自动调用本接口。 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'} /api/platform/v1/iam/tenants/{tenantId}/addresses: parameters: - {$ref: '#/components/parameters/TenantId'} get: tags: [Platform Tenant / 平台租户] summary: 查询企业客户地址 description: 需要 `platform:customer:list` 权限；只读接口，不提供平台端地址写入。 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: 查询企业客户资质 description: 需要 `platform:customer:list` 权限；只读查询资质元数据，不授予审核权限。 responses: '200': description: 企业客户资质查询成功 content: application/json: schema: {$ref: '#/components/schemas/TenantQualificationListApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /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'} /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: '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'} /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'} /api/merchant/v1/iam/authorization/permissions: get: tags: [IAM Resources / IAM 资源] summary: 查询当前用户有效权限 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`。列表权限包含详情只读，创建权限独立授权。 responses: '200': description: 当前商户成员权限查询成功 content: application/json: schema: {$ref: '#/components/schemas/PermissionCodesApiResponse'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} /api/platform/v1/iam/reviews: get: tags: [Platform Tenant / 平台租户] summary: List pending tenant reviews / 查询待审核企业 description: Return enterprise registrations waiting for a platform decision. / 返回等待平台处理的企业注册审核记录。 responses: '200': description: 待审核企业及客户摘要查询成功 content: application/json: schema: {$ref: '#/components/schemas/PendingEnterpriseReviewListApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} /api/platform/v1/iam/reviews/{id}/approve: post: tags: [Platform Tenant / 平台租户] summary: Approve enterprise registration / 审核通过企业注册 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. / 审核通过并激活企业；客户端注册账号继续作为企业管理员，仅平台代建且没有所有者的企业自动创建管理员并返回一次性凭据。 parameters: - {$ref: '#/components/parameters/Id'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/ReviewRequest'} responses: '200': description: 审核通过；data 返回开户结果及一次性初始凭据 content: application/json: schema: {$ref: '#/components/schemas/TenantApprovalApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': {$ref: '#/components/responses/Conflict'} /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'} '404': {$ref: '#/components/responses/NotFound'} '409': {$ref: '#/components/responses/Conflict'} /api/platform/v1/iam/users: get: tags: [IAM Resources / IAM 资源] 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]}} responses: '200': description: 仅返回 tenant_id=0 的平台内部用户分页 content: application/json: schema: {$ref: '#/components/schemas/PlatformManagedUserPageApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [IAM Resources / IAM 资源] summary: 新增平台内部用户 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 资源] summary: 查询平台技术作用域和 PLATFORM 角色选项 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 资源] summary: 编辑平台内部用户资料及角色 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 资源] summary: 启用或停用平台内部用户 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 资源] summary: 重置平台内部用户密码 requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/ResetInternalUserPasswordRequest'} responses: '200': {$ref: '#/components/responses/Success'} '403': {$ref: '#/components/responses/Forbidden'} /api/platform/v1/iam/internal-users: get: tags: [IAM Resources / IAM 资源] summary: 查询平台内部用户 responses: '200': description: 平台内部用户查询成功，公开主键为 membershipId 并回显 roleIds content: application/json: schema: {$ref: '#/components/schemas/InternalUserListApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [IAM Resources / IAM 资源] summary: 新增平台内部用户 description: 创建完整的 Auth/IAM 平台账号，也兼容通过 authUserId 关联已有账号。 requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreateInternalUserRequest'} responses: '200': {$ref: '#/components/responses/Success'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} /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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': {$ref: '#/components/responses/Conflict'} /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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /api/platform/v1/iam/internal-users/{membershipId}/roles: parameters: - {$ref: '#/components/parameters/MembershipId'} put: tags: [IAM 资源] summary: 全量分配平台内部用户角色 description: 仅允许分配平台技术作用域（tenant_id=0）下已启用的平台端角色；空集合表示清空角色。 requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AssignInternalUserRolesRequest'} responses: '200': description: 角色分配成功并返回最新内部用户模型 content: application/json: schema: {$ref: '#/components/schemas/InternalUserApiResponse'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /api/merchant/v1/iam/tenant/profile: get: tags: [Merchant Tenant / 商户企业] summary: Get current tenant profile / 查询当前企业资料 description: The compatibility field tenant ID comes only from the verified JWT and currently identifies the customer. / 客户隔离兼容字段 tenant ID 仅取自已验证 JWT，当前表示登录客户 ID。 responses: '200': {$ref: '#/components/responses/Success'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} 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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /api/merchant/v1/iam/members: get: tags: [Merchant Tenant / 商户企业] summary: List enterprise members / 查询企业成员 responses: '200': description: 企业成员列表，包含真实登录账号与最后登录时间 content: application/json: schema: {$ref: '#/components/schemas/MerchantMemberListApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [Merchant Tenant / 商户企业] summary: Add enterprise member / 新增企业成员 description: 新增基础资料需要 merchant:member:create；roleIds 非空时还必须具有 merchant:member:grant-role，否则返回 403/A0403。空数组表示不分配角色。 requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreateMemberRequest'} responses: '200': description: 新增后的企业成员 content: application/json: schema: {$ref: '#/components/schemas/MerchantMemberApiResponse'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '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: 查询成员详情及当前角色 description: 返回当前客户成员资料，roleIds 为服务端实时查询的当前角色集合；跨客户成员按不存在处理。 responses: '200': description: 企业成员详情 content: application/json: schema: {$ref: '#/components/schemas/MerchantMemberApiResponse'} '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: '200': description: 更新后的企业成员 content: application/json: schema: {$ref: '#/components/schemas/MerchantMemberApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': {$ref: '#/components/responses/Conflict'} /api/merchant/v1/iam/tenant/addresses: get: tags: [IAM Resources / IAM 资源] summary: List tenant addresses / 查询企业地址 responses: '200': description: 角色列表及各角色实时成员数 content: application/json: schema: {$ref: '#/components/schemas/RoleListApiResponse'} '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: '200': description: 新增后的角色及实时成员数 content: application/json: schema: {$ref: '#/components/schemas/RoleApiResponse'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} /api/merchant/v1/iam/tenant/qualifications: get: tags: [IAM Resources / IAM 资源] summary: List tenant qualifications / 查询企业资质 responses: '200': description: 当前客户资质列表 content: application/json: schema: {$ref: '#/components/schemas/TenantQualificationListApiResponse'} '403': {$ref: '#/components/responses/Forbidden'} /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'} /api/merchant/v1/iam/tenant/qualifications/submit-review: post: tags: [IAM Resources / IAM 资源] summary: Submit enterprise qualifications for review / 提交企业资质审核 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. / 上传或替换资质不会自动送审；本接口只要求营业执照和统一社会信用代码，法人身份证、货代资质证书和银行开户许可证选填。 responses: '200': {$ref: '#/components/responses/TenantSuccess'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} /api/{app}/v1/iam/roles: parameters: - {$ref: '#/components/parameters/App'} get: tags: [RBAC] summary: List roles / 查询角色 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 作业员是两批独立人员，对应角色互斥且权限不交叉。 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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} /api/{app}/v1/iam/members/roles: put: tags: [RBAC] summary: Assign roles to member / 设置成员角色 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. / 在同一客户和应用域内替换成员角色；平台管理员可将内置仓库角色分配给已启用的内部用户成员，本接口不会创建账号或固定密码。 parameters: - {$ref: '#/components/parameters/App'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AssignRolesRequest'} responses: '200': {$ref: '#/components/responses/Success'} '400': {$ref: '#/components/responses/BadRequest'} '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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} /api/{app}/v1/iam/roles/permissions: put: tags: [RBAC] summary: Grant permissions to role / 设置角色权限 description: Replace role permissions; cross-customer and cross-application grants are rejected. / 替换角色权限，拒绝跨客户和跨应用授权。 parameters: - {$ref: '#/components/parameters/App'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/GrantPermissionsRequest'} responses: '200': {$ref: '#/components/responses/Success'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} /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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} delete: tags: [RBAC] summary: 删除未绑定的自定义权限资源 description: 系统预置资源、存在子资源或已绑定角色的资源不可删除。 responses: '200': {$ref: '#/components/responses/Success'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} /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'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '409': {$ref: '#/components/responses/Conflict'} /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'} /internal/iam/required-qualification-packages: post: tags: [IAM Resources / IAM 资源] summary: 商户营业执照资质包登记 description: 仅供 File Service 调用；在一个 IAM 事务中登记必填营业执照与统一社会信用代码，法人身份证可选。 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 资源] summary: 平台代客户登记营业执照资质包 description: 仅供 File Service 调用；与商户入口使用相同规则，营业执照与统一社会信用代码必填，法人身份证可选。 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/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'} /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'} components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT parameters: InternalServiceToken: name: X-Internal-Service-Token in: header required: true schema: {type: string} 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 MembershipId: name: membershipId in: path required: true description: 平台成员关系 ID schema: {type: integer, format: int64} TenantId: name: tenantId in: path required: true description: 企业客户 ID；tenantId 为历史兼容参数名 schema: {type: string, pattern: '^\d+$'} PermissionId: name: permissionId in: path required: true description: 权限资源 ID schema: {type: integer, format: int64} responses: Success: {description: Operation succeeded / 操作成功, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}} TenantSuccess: {description: Enterprise tenant returned / 返回企业客户档案, content: {application/json: {schema: {$ref: '#/components/schemas/TenantApiResponse'}}}} TenantCreationSuccess: {description: Enterprise tenant and one-time owner credentials returned / 返回企业客户及一次性管理员凭据, content: {application/json: {schema: {$ref: '#/components/schemas/TenantCreationApiResponse'}}}} BadRequest: {description: Invalid request / 请求参数错误, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}} Unauthorized: {description: Authentication required / 需要登录, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}} Forbidden: {description: 'Permission, customer scope or platform technical scope rejected / 权限、客户范围或平台技术作用域不匹配', content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}} 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'}}}} ServiceUnavailable: {description: Authentication service unavailable / 认证服务不可用, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}} UnprocessableEntity: {description: 参数校验失败, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}} schemas: 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} phone: {type: string, pattern: '^1[3-9]\d{9}$'} 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}$'} phone: {type: string, pattern: '^1[3-9]\d{9}$'} currentPassword: {type: string, format: password, writeOnly: true} PersonalProfileApiResponse: allOf: - {$ref: '#/components/schemas/ApiResponse'} - type: object properties: data: {$ref: '#/components/schemas/PersonalProfileResponse'} ApiResponse: type: object required: [code, message, timestamp] properties: code: {type: string, example: '00000'} message: {type: string, example: Success} data: {} requestId: {type: string} traceId: {type: string} timestamp: {type: string, format: date-time} PermissionCodesApiResponse: allOf: - {$ref: '#/components/schemas/ApiResponse'} - type: object properties: data: type: array uniqueItems: true items: {type: string} 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'} 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} TenantApprovalApiResponse: allOf: - {$ref: '#/components/schemas/ApiResponse'} - type: object properties: data: {$ref: '#/components/schemas/TenantApprovalResponse'} 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: 客户名称} tenantCode: {type: string, pattern: '^\d{5}$', example: '00001', description: 五位客户编号} 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: 审核意见} 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: 一次性初始密码，仅本次创建响应返回} TenantApprovalResponse: type: object required: [tenantId, administratorCreated] properties: tenantId: {type: string, pattern: '^\d+$', example: '190000000000000001'} administratorCreated: {type: boolean, description: 本次审核是否新建企业管理员} administratorUsername: {type: string, nullable: true, example: '13800138000'} temporaryPassword: {type: string, format: password, nullable: true, description: 一次性初始密码，仅新建管理员时返回} TenantApiResponse: allOf: - {$ref: '#/components/schemas/ApiResponse'} - type: object properties: data: {$ref: '#/components/schemas/TenantResponse'} InternalUserListApiResponse: allOf: - {$ref: '#/components/schemas/ApiResponse'} - type: object properties: data: {type: array, items: {$ref: '#/components/schemas/InternalUserResponse'}} InternalUserApiResponse: allOf: - {$ref: '#/components/schemas/ApiResponse'} - type: object properties: data: {$ref: '#/components/schemas/InternalUserResponse'} 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'}} 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} TenantResponse: type: object required: [id, tenantCode, tenantName, status, dimensionInitializationStatus, servicePackage] properties: id: {type: string, pattern: '^\d+$', example: '190000000000000001'} tenantCode: {type: string, pattern: '^\d{5}$', example: '00001'} tenantName: {type: string} status: {type: string, enum: [PROFILE_REQUIRED, PENDING, ACTIVE, REJECTED, DISABLED, ARCHIVED]} dimensionInitializationStatus: {type: string, enum: [PENDING, READY, FAILED], description: 客户默认尺寸初始化状态；未 READY 时依赖该配置的业务失败关闭} legalName: {type: string} legalRepresentative: {type: string, maxLength: 64, nullable: true} unifiedSocialCreditCode: {type: string} contactName: {type: string} contactPhone: {type: string} contactEmail: {type: string, format: email} contactWechat: {type: string, maxLength: 64} servicePackage: {type: string, maxLength: 64} 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: 审批通过时间} 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} FinanceCustomerSummary: type: object required: [id, tenantCode, tenantName, status] properties: id: {type: string, pattern: '^\d+$'} tenantCode: {type: string, pattern: '^\d{5}$', example: '00001'} tenantName: {type: string} status: {type: string, enum: [ACTIVE, DISABLED]} contactName: {type: string, nullable: true} contactPhone: {type: string, nullable: true} 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'} 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 回收文件；重复删除为空} 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 required: [id, tenantId, qualificationType, documentUrl, originalFileName, status, createdAt, updatedAt] properties: id: {type: string, pattern: '^\d+$'} tenantId: {type: string, pattern: '^\d+$'} qualificationType: {type: string, enum: [BUSINESS_LICENSE, LEGAL_PERSON_ID, FREIGHT_FORWARDER_CERTIFICATE, BANK_ACCOUNT_LICENSE]} certificateNo: {type: string} documentUrl: {type: string} originalFileName: {type: string, description: 上传时原始文件名；前端不得从 URL 或内部 ID 推断} validFrom: {type: string, format: date} validTo: {type: string, format: date, nullable: true} status: {type: string, enum: [PENDING, APPROVED, REJECTED, SUPERSEDED]} reviewComment: {type: string} 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} RequiredQualificationPackageRequest: type: object required: [tenantId, unifiedSocialCreditCode, businessLicenseDocumentUrl, businessLicenseOriginalFileName, replaceBusinessLicense] properties: tenantId: {type: string, pattern: '^\d+$'} unifiedSocialCreditCode: {type: string, pattern: '^[0-9A-Za-z]{18}$'} businessLicenseDocumentUrl: {type: string, minLength: 1} businessLicenseOriginalFileName: {type: string, minLength: 1, maxLength: 255} businessLicenseValidTo: {type: string, format: date, nullable: true} replaceBusinessLicense: {type: boolean} legalPersonIdDocumentUrl: {type: string, minLength: 1, nullable: true, description: 法人身份证选填} legalPersonIdOriginalFileName: {type: string, maxLength: 255, nullable: true, description: 上传法人身份证时必传} legalPersonIdValidTo: {type: string, format: date, nullable: true} replaceLegalPersonId: {type: boolean, nullable: true, default: false} RequiredQualificationPackageResponse: type: object required: [businessLicenseQualificationId, tenantStatus] properties: businessLicenseQualificationId: {type: string, pattern: '^\d+$'} legalPersonIdQualificationId: {type: string, pattern: '^\d+$', nullable: true} 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'} RegisterRequest: type: object required: [tenantName, legalName, contactName, contactPhone, servicePackage] properties: tenantName: {type: string, example: 深圳虫虫出海科技有限公司} legalName: {type: string, example: 深圳虫虫出海科技有限公司} legalRepresentative: {type: string, maxLength: 64, nullable: true, example: 张三, description: 选填} contactName: {type: string, example: 李四} contactPhone: {type: string, pattern: '^1[3-9]\d{9}$', example: '13800138000', description: 创建时同时初始化公司联系电话与首个管理员登录手机号；创建后二者独立维护} contactEmail: {type: string, format: email, example: contact@example.com} contactWechat: {type: string, maxLength: 64} servicePackage: {type: string, maxLength: 64, example: 基础版} 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} UpdateProfileRequest: type: object required: [tenantName, legalName, contactName, contactPhone] properties: tenantName: {type: string} legalName: {type: string} legalRepresentative: {type: string, maxLength: 64, nullable: true, description: 选填} contactName: {type: string} contactPhone: {type: string, pattern: '^[0-9-]{4,32}$', description: 公司联系电话，不作为登录标识且不要求跨企业唯一} contactEmail: {type: string, format: email} UpdateTenantRequest: type: object required: [tenantName, legalName, contactName, contactPhone] properties: tenantName: {type: string} legalName: {type: string} legalRepresentative: {type: string, maxLength: 64, nullable: true, description: 选填} contactName: {type: string} contactPhone: {type: string, pattern: '^[0-9-]{4,32}$', description: 公司联系电话，与管理员及成员登录手机号独立且不要求跨企业唯一} contactEmail: {type: string, format: email} contactWechat: {type: string, maxLength: 64} servicePackage: {type: string, maxLength: 64, example: 基础版} 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} ChangeTenantStatusRequest: type: object required: [status] properties: status: {type: string, enum: [ACTIVE, DISABLED]} 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} ReviewRequest: type: object properties: comment: {type: string, maxLength: 500, description: Review comment or rejection reason / 审核意见或驳回原因} CreatePlatformManagedUserRequest: type: object required: [username, displayName, phone, tenantId, roleIds, password, status] properties: username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'} displayName: {type: string, maxLength: 64} phone: {type: string, pattern: '^1[3-9]\\d{9}$', description: 平台账号登录手机号；修改时同步 Auth、撤销该账号会话并审计} email: {type: string, format: email, maxLength: 128} tenantId: {type: integer, format: int64, enum: [0], description: 保留的兼容字段，只允许平台技术作用域 0} roleIds: {type: array, minItems: 1, items: {type: integer, format: int64}} overseasWarehouseId: {type: integer, format: int64, nullable: true, description: 选择 OVERSEAS_WAREHOUSE_PDA_OPERATOR 时必填且只能绑定一个实际海外仓；CN_FIRSTLEG_PDA_OPERATOR 与其他角色必须为空；两个 PDA 角色不能同时分配} 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} phone: {type: string, pattern: '^1[3-9]\\d{9}$', description: 平台账号登录手机号；与任何企业联系电话无关} email: {type: string, format: email, maxLength: 128} tenantId: {type: integer, format: int64, enum: [0], description: 保留的兼容字段，只允许平台技术作用域 0} roleIds: {type: array, minItems: 1, items: {type: integer, format: int64}} overseasWarehouseId: {type: integer, format: int64, nullable: true, description: 选择 OVERSEAS_WAREHOUSE_PDA_OPERATOR 时必填且只能绑定一个实际海外仓；CN_FIRSTLEG_PDA_OPERATOR 与其他角色必须为空；两个 PDA 角色不能同时分配} CreateInternalUserRequest: type: object required: [displayName] properties: authUserId: {type: integer, format: int64, description: 兼容旧接口；填写后关联已有认证账号} userType: {type: string, enum: [INTERNAL, PLATFORM], description: 兼容旧接口，可省略} username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'} password: {type: string, format: password, minLength: 8, maxLength: 64, writeOnly: true} displayName: {type: string, maxLength: 64} phone: {type: string, pattern: '^1[3-9]\d{9}$', description: 企业成员登录手机号；修改时同步 Auth、撤销该账号会话并审计} 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} phone: {type: string, pattern: '^1[3-9]\d{9}$', description: 企业成员登录手机号；与公司联系电话无关} 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} AssignInternalUserRolesRequest: type: object required: [roleIds] properties: roleIds: {type: array, items: {type: integer, format: int64}} InternalUserResponse: type: object required: [membershipId, userId, authUserId, username, displayName, memberType, status, roleIds] properties: membershipId: {type: integer, format: int64} userId: {type: integer, format: int64} authUserId: {type: integer, format: int64} username: {type: string} displayName: {type: string} phone: {type: string} email: {type: string, format: email} memberType: {type: string, enum: [EMPLOYEE]} memberNo: {type: string} status: {type: string, enum: [ACTIVE, DISABLED]} roleIds: {type: array, items: {type: integer, format: int64}} 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} overseasWarehouseId: {type: string, pattern: '^\d+$', nullable: true, description: 海外仓PDA操作员绑定的唯一实际海外仓ID} CreateMemberRequest: type: object required: [username, password, displayName, memberType] properties: username: {type: string, pattern: '^[A-Za-z][A-Za-z0-9_.@-]{3,63}$'} password: {type: string, format: password, minLength: 8, maxLength: 64} displayName: {type: string, maxLength: 64} phone: {type: string, pattern: '^1[3-9]\d{9}$'} email: {type: string, format: email, maxLength: 128} memberType: {type: string, enum: [EMPLOYEE]} memberNo: {type: string} 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} phone: {type: string, pattern: '^1[3-9]\d{9}$'} 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+$'} 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} 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]} 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}}