暂存提交

AGENTS.md

@@ -20,9 +20,9 @@
 | `gateway/` | 路由、CORS、入口安全、访问域隔离 | `config/`、`filter/`、`src/main/resources/application*.yml` |
 | `auth/` | 登录、令牌、注册、账号与密码 | `InternalAccountController.java`、`AccountManagementService.java`、`src/main/resources/db/` |
 | `iam/` | 租户、商户成员、平台内部用户、企业资料、RBAC 与授权快照 | `ProfileResourceController.java`、`PlatformInternalUserService.java`、`RbacController.java` |
-| `order/` | 订单主数据、状态编排、快照与 Outbox | `controller/`、`OrderApplicationService.java`、`README-ORDER.md` |
-| `firstleg/` | 履约任务、操作分配与分配历史 | `PlatformFulfillmentAssignmentController.java`、`FulfillmentTaskService.java` |
-| `warehouse/` | 仓库、地址、服务能力与往来单位 | `controller/`、`WarehouseApplicationService.java`、`PartnerQueryService.java` |
+| `order/` | 订单主数据、持久化幂等、状态编排、快照与 Outbox | `controller/`、`OrderApplicationService.java`、`OrderIdempotencyRecordEntity.java`、`README-ORDER.md` |
+| `firstleg/` | 履约任务分页/详情、操作分配与分配历史 | `PlatformFulfillmentAssignmentController.java`、`FulfillmentTaskService.java`、`src/main/resources/db/phase1-firstleg-task-list-index.sql` |
+| `warehouse/` | 仓库、地址、服务能力、往来单位与快递公司主数据 | `controller/`、`WarehouseApplicationService.java`、`PlatformPartnerQueryService.java`、`ExpressCompanyQueryService.java` |
 | `file/` | 企业资质文件本地存储、预览与鉴权 | `controller/`、`LocalQualificationStorage.java`；元数据表结构尚未接入 |
 | `print/` | 打印中心边界 | 当前为应用、健康检查和 `print/src/main/resources/db/print.sql` 骨架 |
 | `audit-service/` | 审计事件接收与持久化 | `AuditIngestController.java`、`AuditIngestService.java`；当前接收接口未实现内部令牌保护 |
@@ -34,6 +34,7 @@
 - 服务本地配置在各模块 `src/main/resources/application.yml`；Nacos 环境配置集中在 `config/nacos/local/` 和 `config/nacos/cn/`。
 - 子模块索引中 `controller/`、`service/`、`client/` 等包内简写均从该模块的 `src/main/java/com/baiyue/<domain>/` 起算；资源路径从模块根目录起算。
 - 表结构和增量脚本优先在目标模块 `src/main/resources/db/` 查找；每个服务只能访问自己的数据库，禁止跨库 Join。
+- `CREATE TABLE IF NOT EXISTS` 不会升级既有表；新增字段或索引时必须同时提供可重复执行的增量迁移，并在部署清单中写明执行顺序。
 - 服务间调用先找调用方 `client/`；跨区域数据只使用 `common-event-contract/` 和事件桥，不共享领域 Entity。
 - 本地运行看 `docs/local-runtime.md`；接口联调看 `docs/phase1-local-api.md`；回归入口在 `scripts/`。
 - 从本目录运行全量校验：`mvn -DskipTests validate`、`mvn test`。单模块修改优先运行 `mvn -pl <module> -am test`。

common-web/AGENTS.md

@@ -18,5 +18,6 @@
 ## 修改与验证
 
 - 修改异常响应时同时检查 HTTP 状态、`ApiResponse` 结构、校验错误和安全异常是否仍一致。
+- 查询参数类型转换失败映射为 400，Bean Validation 约束失败映射为 422，禁止落入通用 500。
 - 修改 Correlation ID 时检查请求头兼容、线程上下文清理和日志链路。
 - 从父目录运行 `mvn -pl common-web -am test`。

common-web/src/main/java/com/baiyue/common/web/GlobalExceptionHandler.java

@@ -15,6 +15,7 @@ import org.springframework.validation.FieldError;
 import org.springframework.http.converter.HttpMessageNotReadableException;
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.springframework.web.bind.MissingServletRequestParameterException;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
 
@@ -54,7 +55,8 @@ public class GlobalExceptionHandler {
         return validationResponse(errors, request);
     }
 
-    @ExceptionHandler({HttpMessageNotReadableException.class, MissingServletRequestParameterException.class})
+    @ExceptionHandler({HttpMessageNotReadableException.class, MissingServletRequestParameterException.class,
+            MethodArgumentTypeMismatchException.class})
     public ResponseEntity<ApiResponse<Void>> handleBadRequest(Exception exception, HttpServletRequest request) {
         return failure(ResultCode.BAD_REQUEST, ResultCode.BAD_REQUEST.message(), request);
     }

common-web/src/test/java/com/baiyue/common/web/GlobalExceptionHandlerTest.java

@@ -4,6 +4,10 @@ import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import org.junit.jupiter.api.Test;
 import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.core.MethodParameter;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+
+import java.lang.reflect.Method;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -20,4 +24,21 @@ class GlobalExceptionHandlerTest {
         assertThat(response.getBody().code()).isEqualTo(ResultCode.BUSINESS_ERROR.code());
         assertThat(response.getBody().requestId()).isEqualTo("r1");
     }
+
+    @Test
+    void 查询参数类型错误映射为四百而不是五百() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        Method method = GlobalExceptionHandlerTest.class.getDeclaredMethod("paging", long.class);
+        MethodParameter parameter = new MethodParameter(method, 0);
+        MethodArgumentTypeMismatchException exception = new MethodArgumentTypeMismatchException(
+                "abc", Long.class, "page", parameter, new NumberFormatException("abc"));
+
+        var response = handler.handleBadRequest(exception, request);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(400);
+        assertThat(response.getBody().code()).isEqualTo(ResultCode.BAD_REQUEST.code());
+    }
+
+    private void paging(long page) {
+    }
 }

docs/database-schema.md

@@ -73,6 +73,7 @@ SQL 入口位于各服务的 `src/main/resources/db` 目录。
 | `wh_warehouse_address` | 保存仓库运营、退货等不同用途的地址和可选经纬度。 | `tenant_id`、`warehouse_id`、`address_type` |
 | `wh_service_capability` | 声明仓库可提供的收货、仓储、拣包、退货等服务能力及截单时间。 | `tenant_id`、`warehouse_id`、`capability_code`、`enabled`、`cutoff_time` |
 | `wh_partner` | 仓储域内的租户往来单位配置，供订单选择客户、联系人和地址；商户候选查询强制过滤停用数据。 | `tenant_id`、`partner_code`、`partner_name`、`partner_type`、`contact_name`、`contact_phone`、`address_line`、`status` |
+| `wh_express_company` | 租户维度快递公司主数据，供平台基础资料页分页查询。 | `tenant_id`、`company_code`、`company_name`、`service_phone`、`tracking_url_template`、`status` |
 
 ## 文件中心服务
 

docs/phase1-local-api.md

@@ -9,6 +9,8 @@ Authorization: Bearer <accessToken>
 Content-Type: application/json
 ```
 
+创建订单草稿和提交订单还必须携带 `Idempotency-Key`。同一操作者重试同一请求时复用原值；同一键用于不同请求返回 409，键缺失或长度超过 128 返回 400/422。
+
 普通成功响应：
 
 ```json
@@ -128,6 +130,18 @@ IAM 的商户资质接口只读。旧的 `POST /api/merchant/v1/iam/tenant/quali
 | POST | `/api/platform/v1/iam/reviews/{id}/approve` | `platform:customer:approve` | 审核通过 |
 | POST | `/api/platform/v1/iam/reviews/{id}/reject` | `platform:customer:reject` | 审核驳回 |
 
+平台登录初始化与后台管理：
+
+| 方法 | 路径 | 权限 | 说明 |
+|---|---|---|---|
+| GET | `/api/{platform\|merchant}/v1/iam/authorization/permissions` | 已认证有效成员 | 实时返回当前有效权限，不要求角色管理权限 |
+| GET | `/api/platform/v1/iam/tenants?page=1&size=20` | `platform:customer:list` | 仅分页查询商户企业，支持关键字与状态 |
+| GET | `/api/platform/v1/iam/internal-users` | `platform:user:list` | 返回 `membershipId`、账号资料和 `roleIds` |
+| POST | `/api/platform/v1/iam/internal-users` | `platform:user:create` | 创建或关联平台认证账号 |
+| PUT | `/api/platform/v1/iam/internal-users/{membershipId}` | `platform:user:edit` | 编辑资料与角色 |
+| PUT | `/api/platform/v1/iam/internal-users/{membershipId}/status` | `platform:user:status` | 启用或停用平台用户 |
+| PUT | `/api/platform/v1/iam/internal-users/{membershipId}/password` | `platform:user:reset-password` | 重置密码，密码只转交 Auth |
+
 审核请求：
 
 ```json
@@ -165,11 +179,11 @@ IAM 的商户资质接口只读。旧的 `POST /api/merchant/v1/iam/tenant/quali
 
 | 方法 | 路径 | 权限 | 说明 |
 |---|---|---|---|
-| POST | `/api/merchant/v1/orders/first-leg` | `merchant:order:create` | 创建草稿，`data` 为订单 ID |
+| POST | `/api/merchant/v1/orders/first-leg` | `merchant:order:create` | 创建草稿，必须携带 `Idempotency-Key`，`data` 为订单 ID |
 | PUT | `/api/merchant/v1/orders/first-leg/{id}` | `merchant:order:edit` | 编辑草稿 |
 | GET | `/api/merchant/v1/orders/first-leg` | 商户身份 | 分页查询自己的订单 |
 | GET | `/api/merchant/v1/orders/first-leg/{id}` | 商户身份 | 查询自己的订单详情 |
-| POST | `/api/merchant/v1/orders/first-leg/{id}/submit` | `merchant:order:submit` | 提交订单 |
+| POST | `/api/merchant/v1/orders/first-leg/{id}/submit` | `merchant:order:submit` | 提交订单，必须携带 `Idempotency-Key` |
 
 列表参数：`keyword,status,customerId,destinationWarehouseId,createdFrom,createdTo,page,size`；`page` 从 1 开始，`size` 为 1 至 200。
 
@@ -251,6 +265,21 @@ IAM 的商户资质接口只读。旧的 `POST /api/merchant/v1/iam/tenant/quali
 | GET | `/api/merchant/v1/partners/candidates` | 当前租户启用往来单位候选 |
 | GET | `/api/merchant/v1/partners/{partnerId}` | 当前租户启用往来单位详情 |
 | GET | `/api/platform/v1/warehouse-admin?tenantId={tenantId}&page=1&size=20` | 平台仓储列表 |
+| GET | `/api/platform/v1/partners?tenantId={tenantId}&page=1&size=20` | 平台往来单位分页，需要 `platform:counterparty:list` |
+| GET | `/api/platform/v1/partners/{id}?tenantId={tenantId}` | 平台往来单位详情，需要 `platform:counterparty:list` |
+| POST | `/api/platform/v1/partners?tenantId={tenantId}` | 新增往来单位，需要 `platform:counterparty:create` |
+| PUT | `/api/platform/v1/partners/{id}?tenantId={tenantId}` | 编辑往来单位，需要 `platform:counterparty:edit` |
+| PATCH | `/api/platform/v1/partners/{id}/status?tenantId={tenantId}` | 启用或停用往来单位，需要 `platform:counterparty:status` |
+| GET | `/api/platform/v1/express-companies?tenantId={tenantId}&page=1&size=20` | 平台快递公司分页，需要 `platform:express:list` |
+| GET | `/api/platform/v1/express-companies/{id}?tenantId={tenantId}` | 平台快递公司详情，需要 `platform:express:list` |
+| POST | `/api/platform/v1/express-companies?tenantId={tenantId}` | 新增快递公司，需要 `platform:express:create` |
+| PUT | `/api/platform/v1/express-companies/{id}?tenantId={tenantId}` | 编辑快递公司，需要 `platform:express:edit` |
+| PATCH | `/api/platform/v1/express-companies/{id}/status?tenantId={tenantId}` | 启用或停用快递公司，需要 `platform:express:status` |
+| GET | `/api/platform/v1/first-leg/tasks?tenantId={tenantId}&page=1&size=20` | 履约任务分页，需要 `platform:firstleg:task:list` |
+| GET | `/api/platform/v1/first-leg/tasks/{taskId}?tenantId={tenantId}` | 履约任务详情，需要 `platform:firstleg:task:view` |
+| GET | `/api/platform/v1/first-leg/tasks/by-order/{orderId}?tenantId={tenantId}` | 按订单查询履约任务，需要 `platform:firstleg:task:view` |
+| GET | `/api/platform/v1/first-leg/tasks/{taskId}/assignment-history?tenantId={tenantId}` | 分配历史，需要 `platform:firstleg:assignment:history` |
+| POST | `/api/platform/v1/first-leg/tasks/{taskId}/assignment?tenantId={tenantId}` | 分配或改派，需要 `platform:firstleg:assignment:assign` |
 | GET | `/api/platform/v1/iam/status` | IAM 网关路由状态 |
 | GET | `/api/platform/v1/orders/status` | Order 网关路由状态 |
 | GET | `/api/platform/v1/first-leg/status` | Firstleg 网关路由状态 |
@@ -260,6 +289,8 @@ IAM 的商户资质接口只读。旧的 `POST /api/merchant/v1/iam/tenant/quali
 
 往来单位由 `warehouse-service` 承载，表为 `baiyue_warehouse.wh_partner`，不是独立服务或独立数据库。仓库和往来单位查询强制执行租户隔离和停用过滤。
 
+部署到既有数据库时，除主建表脚本外还要执行 `firstleg/src/main/resources/db/phase1-firstleg-task-list-index.sql`；该脚本可重复执行，用于补齐履约任务租户时间分页索引。
+
 平台履约可通过 `PUT /api/platform/v1/orders/first-leg/{orderId}/express?tenantId={tenantId}` 写入 `expressCompany,expressTrackingNo`；商户端只能在订单详情读取，不能维护快递公司或调用平台写接口。
 
 ## 8. Swagger 分组

firstleg/AGENTS.md

@@ -10,17 +10,21 @@
 | 功能 | 入口 |
 |---|---|
 | 应用入口 | `src/main/java/com/baiyue/firstleg/BaiyueFirstlegApplication.java` |
-| 平台履约分配 API | `controller/PlatformFulfillmentAssignmentController.java`（`/api/platform/v1/first-leg/tasks`） |
+| 平台履约任务查询与分配 API | `controller/PlatformFulfillmentAssignmentController.java`（`/api/platform/v1/first-leg/tasks`） |
+| 任务列表、详情、按订单查询、分配历史 | `FulfillmentTaskService.java`、`FulfillmentTaskRepository.java`；只读权限码见控制器 `@PreAuthorize` |
 | 服务状态 | `controller/FirstlegHealthController.java` |
-| 分配请求 | `dto/AssignRequest.java` |
+| 查询与分配请求 | `dto/FulfillmentTaskQuery.java`、`dto/AssignRequest.java` |
 | 履约与分配编排 | `service/FulfillmentTaskService.java` |
 | 任务与历史持久化 | `entity/`、`mapper/`、`repository/FulfillmentTaskRepository.java` |
-| 表结构 | `src/main/resources/db/firstleg.sql` |
+| 表结构与查询索引迁移 | `src/main/resources/db/firstleg.sql`、`src/main/resources/db/phase1-firstleg-task-list-index.sql` |
+| OpenAPI 与测试 | `src/main/resources/openapi/firstleg-v1.yaml`、`src/test/java/com/baiyue/firstleg/` |
 | 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/firstleg-service.yml` |
 
 ## 修改与验证
 
 - 任务状态与订单状态保持领域分离；需要联动时使用稳定 DTO 或事件，不共享 Order Entity 或数据库。
 - 分配操作要保留历史、操作者、时间和幂等语义；平台端接口必须执行权限校验。
+- 所有查询必须带目标租户并在仓储层过滤；列表和分配历史使用统一分页响应，详情不存在时统一返回 404。
+- 新建库由 `firstleg.sql` 创建查询索引；既有库必须再执行可重复部署的 `phase1-firstleg-task-list-index.sql`，不能只依赖 `CREATE TABLE IF NOT EXISTS`。
 - 当前模块没有专属自动化测试时，不要为小改动擅自引入新框架；至少运行模块构建并记录接口验证。
 - 从父目录运行 `mvn -pl firstleg -am test`。

firstleg/src/main/java/com/baiyue/firstleg/controller/PlatformFulfillmentAssignmentController.java

@@ -2,10 +2,14 @@ package com.baiyue.firstleg.controller;
 
 import com.baiyue.common.audit.BusinessAudit;
 import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.firstleg.dto.AssignRequest;
+import com.baiyue.firstleg.dto.FulfillmentTaskQuery;
+import com.baiyue.firstleg.entity.AssignmentHistoryEntity;
+import com.baiyue.firstleg.entity.FulfillmentTaskEntity;
 import com.baiyue.firstleg.service.FulfillmentTaskService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
@@ -13,7 +17,11 @@ import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -22,11 +30,11 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 /**
- * 平台端头程履约任务指派接口，在目标租户内完成任务指派或改派并记录指派历史。
+ * 平台端头程履约任务接口，在目标租户内提供任务查询、分配和分配历史查询。
  */
 @Tag(
-    name = "Platform first-leg assignment / 平台头程指派",
-    description = "Platform APIs for assigning tenant-scoped first-leg fulfillment tasks. / 平台端按租户指派头程履约任务的接口。"
+    name = "平台头程履约任务",
+    description = "平台端按目标租户查询和分配头程履约任务。"
 )
 @RestController
 @RequestMapping("/api/platform/v1/first-leg/tasks")
@@ -52,6 +60,7 @@ public class PlatformFulfillmentAssignmentController {
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "Task is closed or concurrently updated / 任务已关闭或发生并发更新")
     })
     @PostMapping("/{taskId}/assignment")
+    @PreAuthorize("hasAuthority('platform:firstleg:assignment:assign')")
     public ApiResponse<Void> assign(
         @AuthenticationPrincipal AuthenticatedUser user,
         @Parameter(description = "Target tenant ID / 目标租户 ID", example = "10001", required = true)
@@ -72,17 +81,84 @@ public class PlatformFulfillmentAssignmentController {
         return ApiResponse.success(null);
     }
 
+    @Operation(summary = "查询履约任务列表", description = "在指定租户内按条件分页查询头程履约任务。")
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "无查询权限")
+    })
+    @GetMapping
+    @PreAuthorize("hasAuthority('platform:firstleg:task:list')")
+    public ApiResponse<PageResult<FulfillmentTaskEntity>> page(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam long tenantId,
+        @Valid FulfillmentTaskQuery query) {
+        requirePlatform(user);
+        requireTenant(tenantId);
+        return ApiResponse.success(service.page(tenantId, query));
+    }
+
+    @Operation(summary = "查询履约任务详情", description = "查询指定租户内的头程履约任务详情。")
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "无查看权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "任务不存在")
+    })
+    @GetMapping("/{taskId}")
+    @PreAuthorize("hasAuthority('platform:firstleg:task:view')")
+    public ApiResponse<FulfillmentTaskEntity> detail(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam long tenantId,
+        @PathVariable long taskId) {
+        requirePlatform(user);
+        requireTenant(tenantId);
+        return ApiResponse.success(service.detail(tenantId, taskId));
+    }
+
+    @Operation(summary = "按订单查询履约任务", description = "使用订单逻辑ID查询指定租户内唯一的履约任务。")
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "无查看权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "任务不存在")
+    })
+    @GetMapping("/by-order/{orderId}")
+    @PreAuthorize("hasAuthority('platform:firstleg:task:view')")
+    public ApiResponse<FulfillmentTaskEntity> byOrder(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam long tenantId,
+        @PathVariable long orderId) {
+        requirePlatform(user);
+        requireTenant(tenantId);
+        return ApiResponse.success(service.byOrder(tenantId, orderId));
+    }
+
+    @Operation(summary = "查询分配历史", description = "分页查询指定履约任务不可变的分配历史。")
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "无历史查看权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "任务不存在")
+    })
+    @GetMapping("/{taskId}/assignment-history")
+    @PreAuthorize("hasAuthority('platform:firstleg:assignment:history')")
+    public ApiResponse<PageResult<AssignmentHistoryEntity>> assignmentHistory(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam long tenantId,
+        @PathVariable long taskId,
+        @RequestParam(defaultValue = "1") @Min(1) long page,
+        @RequestParam(defaultValue = "20") @Min(1) @Max(200) long size) {
+        requirePlatform(user);
+        requireTenant(tenantId);
+        return ApiResponse.success(service.assignmentHistory(tenantId, taskId, page, size));
+    }
+
     private static void requirePlatform(AuthenticatedUser user) {
         if (user == null || !"PLATFORM".equals(user.appCode())) {
-            throw new BizException(ResultCode.FORBIDDEN,
-                "Platform application required / 仅允许平台端访问");
+            throw new BizException(ResultCode.FORBIDDEN, "仅允许平台端访问");
         }
     }
 
     private static void requireTenant(long tenantId) {
         if (tenantId <= 0) {
-            throw new BizException(ResultCode.BAD_REQUEST,
-                "Target tenant is required / 必须指定有效目标租户");
+            throw new BizException(ResultCode.BAD_REQUEST, "必须指定有效目标租户");
         }
     }
 }

firstleg/src/main/java/com/baiyue/firstleg/repository/FulfillmentTaskRepository.java

@@ -1,11 +1,15 @@
 package com.baiyue.firstleg.repository;
 
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.firstleg.dto.FulfillmentTaskQuery;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import com.baiyue.firstleg.entity.AssignmentHistoryEntity;
 import com.baiyue.firstleg.entity.FulfillmentTaskEntity;
 import com.baiyue.firstleg.mapper.AssignmentHistoryMapper;
 import com.baiyue.firstleg.mapper.FulfillmentTaskMapper;
 import org.springframework.stereotype.Repository;
+import org.springframework.util.StringUtils;
 
 /**
  * 头程履约任务仓储，按租户查询和更新任务，并持久化每次指派历史。
@@ -26,6 +30,31 @@ public class FulfillmentTaskRepository {
             .eq(FulfillmentTaskEntity::getId, taskId));
     }
 
+    public FulfillmentTaskEntity findByOrder(long tenantId, long orderId) {
+        return tasks.selectOne(new LambdaQueryWrapper<FulfillmentTaskEntity>()
+            .eq(FulfillmentTaskEntity::getTenantId, tenantId)
+            .eq(FulfillmentTaskEntity::getOrderId, orderId));
+    }
+
+    public PageResult<FulfillmentTaskEntity> page(long tenantId, FulfillmentTaskQuery query) {
+        LambdaQueryWrapper<FulfillmentTaskEntity> wrapper = new LambdaQueryWrapper<FulfillmentTaskEntity>()
+            .eq(FulfillmentTaskEntity::getTenantId, tenantId)
+            .eq(StringUtils.hasText(query.status()), FulfillmentTaskEntity::getStatus, query.status())
+            .eq(query.assigneeId() != null, FulfillmentTaskEntity::getAssigneeId, query.assigneeId())
+            .like(StringUtils.hasText(query.keyword()), FulfillmentTaskEntity::getOrderNo, query.keyword())
+            .orderByDesc(FulfillmentTaskEntity::getCreatedAt);
+        return PageResult.from(tasks.selectPage(new Page<>(query.page(), query.size()), wrapper));
+    }
+
+    public PageResult<AssignmentHistoryEntity> pageHistory(
+        long tenantId, long taskId, long page, long size) {
+        LambdaQueryWrapper<AssignmentHistoryEntity> wrapper = new LambdaQueryWrapper<AssignmentHistoryEntity>()
+            .eq(AssignmentHistoryEntity::getTenantId, tenantId)
+            .eq(AssignmentHistoryEntity::getTaskId, taskId)
+            .orderByDesc(AssignmentHistoryEntity::getCreatedAt);
+        return PageResult.from(histories.selectPage(new Page<>(page, size), wrapper));
+    }
+
     public boolean update(FulfillmentTaskEntity task) {
         return tasks.updateById(task) == 1;
     }

firstleg/src/main/java/com/baiyue/firstleg/service/FulfillmentTaskService.java

@@ -2,6 +2,8 @@ package com.baiyue.firstleg.service;
 import jakarta.annotation.Resource;
 
 import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.firstleg.dto.FulfillmentTaskQuery;
 import com.baiyue.common.core.exception.BizException;
 import com.baiyue.firstleg.entity.AssignmentHistoryEntity;
 import com.baiyue.firstleg.entity.FulfillmentTaskEntity;
@@ -23,11 +25,7 @@ public class FulfillmentTaskService {
     @Transactional
     public void assign(long tenantId, long operatorId, long taskId,
                        long assigneeId, String assigneeName, String reason) {
-        FulfillmentTaskEntity task = repository.findOwned(tenantId, taskId);
-        if (task == null) {
-            throw new BizException(ResultCode.NOT_FOUND,
-                "Fulfillment task not found / 头程履约任务不存在");
-        }
+        FulfillmentTaskEntity task = requireTask(tenantId, taskId);
         if ("COMPLETED".equals(task.getStatus()) || "CANCELLED".equals(task.getStatus())) {
             throw new BizException(ResultCode.CONFLICT,
                 "Closed task cannot be assigned / 已关闭任务不能再次指派");
@@ -55,4 +53,38 @@ public class FulfillmentTaskService {
         history.setCreatedAt(LocalDateTime.now());
         repository.insertHistory(history);
     }
+
+    public PageResult<FulfillmentTaskEntity> page(long tenantId, FulfillmentTaskQuery query) {
+        return repository.page(tenantId, query);
+    }
+
+    public FulfillmentTaskEntity detail(long tenantId, long taskId) {
+        return requireTask(tenantId, taskId);
+    }
+
+    public FulfillmentTaskEntity byOrder(long tenantId, long orderId) {
+        FulfillmentTaskEntity task = repository.findByOrder(tenantId, orderId);
+        if (task == null) {
+            throw notFound();
+        }
+        return task;
+    }
+
+    public PageResult<AssignmentHistoryEntity> assignmentHistory(
+        long tenantId, long taskId, long page, long size) {
+        requireTask(tenantId, taskId);
+        return repository.pageHistory(tenantId, taskId, page, size);
+    }
+
+    private FulfillmentTaskEntity requireTask(long tenantId, long taskId) {
+        FulfillmentTaskEntity task = repository.findOwned(tenantId, taskId);
+        if (task == null) {
+            throw notFound();
+        }
+        return task;
+    }
+
+    private BizException notFound() {
+        return new BizException(ResultCode.NOT_FOUND, "头程履约任务不存在");
+    }
 }

firstleg/src/main/resources/db/firstleg.sql

@@ -23,6 +23,7 @@ CREATE TABLE IF NOT EXISTS fl_fulfillment_task (
   version INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
   PRIMARY KEY (id),
   UNIQUE KEY uk_task_tenant_order (tenant_id, order_id),
+  KEY idx_task_tenant_created (tenant_id, created_at),
   KEY idx_task_assignee_status (tenant_id, assignee_id, status, created_at)
 ) ENGINE=InnoDB COMMENT='头程履约任务表：接收订单事件后形成独立履约任务，管理指派、执行和完成状态';
 

iam/AGENTS.md

@@ -14,10 +14,12 @@
 | 商户个人与企业资料 | `controller/MerchantTenantController.java` | `PersonalProfileService.java`、`TenantService.java` |
 | 商户成员增改、启停、重置密码 | `MerchantTenantController.java` | `MemberService.java`，账号协作看 `client/AuthAccountClient.java` |
 | 平台创建企业与入驻审核 | `controller/PlatformTenantController.java` | `MerchantOnboardingService.java`、`TenantService.java` |
+| 平台企业客户分页 | `controller/PlatformTenantController.java` | `TenantService.pageMerchants`、`TenantRepository.pageMerchants`；仅返回 `tenant_type=MERCHANT` |
 | 平台内部用户 | `controller/ProfileResourceController.java` | `PlatformInternalUserService.java`；账号创建、显示名、启停和重置密码经 `AuthAccountClient` 编排 |
 | 企业地址与资质元数据 | `controller/ProfileResourceController.java` | `ProfileResourceService.java`、`ProfileResourceRepository.java` |
 | 角色、权限、成员角色、角色授权 | `controller/RbacController.java` | `RbacService.java`、`RbacRepository.java` |
 | Auth/Order 内部授权与资格查询 | `InternalAuthorizationController.java`、`InternalTenantController.java` | `AuthorizationSnapshotService.java`、`TenantGuard.java` |
+| 当前登录成员有效权限 | `controller/AuthorizationController.java` | `AuthorizationSnapshotService.currentPermissions`；实时按有效成员、角色和权限资源计算，不依赖角色管理权限 |
 | DTO | `src/main/java/com/baiyue/iam/dto/` | 按 Authorization、Member、Onboarding、Profile、Rbac、Tenant 分类 |
 | 持久化 | `entity/`、`mapper/`、`repository/` | 租户、成员、角色、权限、地址、资质与审核模型 |
 | 数据库 | `src/main/resources/db/` | 主结构 `iam.sql`，一期与 RBAC 增量脚本同目录 |
@@ -28,6 +30,8 @@
 
 - `tenant_id` 是商户数据隔离核心；平台端与商户端访问域、角色和权限不可混用。
 - 按钮隐藏不能代替后端 permission code / permissionIds 校验；权限快照变化需同步检查 Auth 与 Gateway Claim 消费。
+- `/api/{app}/v1/iam/authorization/permissions` 是登录初始化接口，只校验已认证应用域和有效成员身份；禁止增加 `role:list` 等业务权限前置条件。
+- 平台企业客户分页仅查询商户租户；分页参数类型错误返回 400，范围或状态约束错误返回 422。
 - 成员账号操作跨 IAM/Auth，保持幂等与补偿；资质上传跨 IAM/File，IAM 不保存文件内容。
 - 平台内部用户的公开主键是 `membershipId`；列表必须回显 `roleIds`，密码只允许通过 DTO 转交 Auth，禁止进入 IAM 实体、日志或审计快照。
 - SQL 增量保持可重复部署顺序，修改 Entity 时同步检查 Mapper、Repository、DTO 与种子数据。

iam/src/main/java/com/baiyue/iam/controller/PlatformTenantController.java

@@ -16,6 +16,7 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.Pattern;
 import jakarta.validation.Valid;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -39,15 +40,18 @@ public class PlatformTenantController {
     @PreAuthorize("hasAuthority('platform:customer:list')")
     @Operation(summary = "List enterprise tenants / 查询企业列表", description = "Returns paged merchant enterprise tenants for platform operators. / 平台端分页查询商户企业，支持企业名称、统一社会信用代码、联系人和状态筛选。")
     @ApiResponses({
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Tenant list returned / 企业列表查询成功"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid paging parameters / 分页参数无效"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Platform scope required / 需要平台端权限")
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "企业列表查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "分页参数类型无效"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "需要登录"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "需要平台端权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "422", description = "分页范围或状态无效")
     })
     public ApiResponse<PageResult<TenantResponse>> page(
             @RequestParam(defaultValue = "1") @Min(1) long page,
             @RequestParam(defaultValue = "20") @Min(1) @Max(200) long size,
             @RequestParam(required = false) String keyword,
-            @RequestParam(required = false) String status,
+            @RequestParam(required = false)
+            @Pattern(regexp = "PROFILE_REQUIRED|PENDING|ACTIVE|REJECTED|DISABLED") String status,
             @AuthenticationPrincipal AuthenticatedUser user) {
         TenantGuard.tenant(user, "PLATFORM");
         return ApiResponse.success(service.pageMerchants(page, size, keyword, status));

iam/src/main/java/com/baiyue/iam/mapper/AuthorizationQueryMapper.java

@@ -55,7 +55,7 @@ public interface AuthorizationQueryMapper {
           AND (r.tenant_id = 0 OR r.tenant_id = #{tenantId})
           AND r.app_code = #{appCode} AND r.status = 'ACTIVE' AND r.deleted = 0
           AND (p.tenant_id = 0 OR p.tenant_id = #{tenantId})
-          AND p.app_code = #{appCode} AND p.status = 'ACTIVE'
+          AND p.app_code = #{appCode} AND p.status = 'ACTIVE' AND p.deleted = 0
         ORDER BY p.permission_code
         """)
     List<String> findPermissions(@Param("userId") long userId,

iam/src/main/java/com/baiyue/iam/service/AuthorizationSnapshotService.java

@@ -6,10 +6,12 @@ import com.baiyue.common.core.exception.BizException;
 import com.baiyue.iam.dto.AuthorizationDtos.SnapshotRequest;
 import com.baiyue.iam.dto.AuthorizationDtos.SnapshotResponse;
 import com.baiyue.iam.mapper.AuthorizationQueryMapper;
+import com.baiyue.common.security.AuthenticatedUser;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
 import java.util.LinkedHashSet;
+import java.util.List;
 import java.util.Set;
 
 /**
@@ -24,6 +26,7 @@ public class AuthorizationSnapshotService {
 
     @Transactional(readOnly = true)
     public SnapshotResponse load(SnapshotRequest request) {
+        requireRequest(request);
         String appCode = request.getAppCode().trim().toUpperCase(java.util.Locale.ROOT);
         if (!APPS.contains(appCode)) {
             throw new BizException(ResultCode.FORBIDDEN, "未知的应用身份域");
@@ -38,11 +41,40 @@ public class AuthorizationSnapshotService {
             throw new BizException(ResultCode.FORBIDDEN, "IAM 用户或成员身份无效");
         }
 
-        Set<String> roles = new LinkedHashSet<>(mapper.findRoles(
+        Set<String> roles = normalizedSet(mapper.findRoles(
                 request.getUserId(), request.getTenantId(), request.getMembershipId(), appCode));
-        Set<String> permissions = new LinkedHashSet<>(mapper.findPermissions(
+        Set<String> permissions = normalizedSet(mapper.findPermissions(
                 request.getUserId(), request.getTenantId(), request.getMembershipId(), appCode));
         return new SnapshotResponse(request.getUserId(), request.getTenantId(), request.getMembershipId(),
                 appCode, appCode, Set.copyOf(roles), Set.copyOf(permissions));
     }
+
+    /**
+     * 根据已认证请求主体重新计算有效权限，而不是复用 JWT 中可能已经过期的权限声明。
+     */
+    @Transactional(readOnly = true)
+    public Set<String> currentPermissions(AuthenticatedUser user, String appCode) {
+        if (user == null || user.userId() == null || user.tenantId() == null || user.membershipId() == null) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "Authentication identity is incomplete / 登录身份不完整");
+        }
+        return load(new SnapshotRequest(user.userId(), user.tenantId(), user.membershipId(), appCode))
+                .getPermissions();
+    }
+
+    private void requireRequest(SnapshotRequest request) {
+        if (request == null || request.getUserId() == null || request.getTenantId() == null
+                || request.getMembershipId() == null || request.getAppCode() == null
+                || request.getAppCode().isBlank()) {
+            throw new BizException(ResultCode.FORBIDDEN, "Authorization identity is incomplete / 授权身份不完整");
+        }
+    }
+
+    private Set<String> normalizedSet(List<String> values) {
+        if (values == null || values.isEmpty()) {
+            return Set.of();
+        }
+        LinkedHashSet<String> normalized = new LinkedHashSet<>();
+        values.stream().filter(java.util.Objects::nonNull).forEach(normalized::add);
+        return Set.copyOf(normalized);
+    }
 }

iam/src/main/resources/db/phase1-admin-rbac.sql

@@ -84,6 +84,7 @@ VALUES
   (5101020, 0, 'PLATFORM', 'MENU', 5101000, 'platform:role:list', '角色管理', '/system/roles', NULL, 20, 'ACTIVE', 0),
   (5101030, 0, 'PLATFORM', 'MENU', 5101000, 'platform:permission:list', '菜单按钮', '/system/permissions', NULL, 30, 'ACTIVE', 0),
   (5102010, 0, 'PLATFORM', 'MENU', 5102000, 'platform:order:list', '订单列表', '/first-leg-orders/list', NULL, 10, 'ACTIVE', 0),
+  (5102020, 0, 'PLATFORM', 'MENU', 5102000, 'platform:firstleg:task:list', '履约任务', '/first-leg-tasks/list', NULL, 20, 'ACTIVE', 0),
   (5103010, 0, 'PLATFORM', 'MENU', 5103000, 'platform:warehouse:list', '国内仓/FBA仓', '/master-data/warehouses', NULL, 10, 'ACTIVE', 0),
   (5103020, 0, 'PLATFORM', 'MENU', 5103000, 'platform:express:list', '快递公司', '/master-data/express', NULL, 20, 'ACTIVE', 0),
   (5103030, 0, 'PLATFORM', 'MENU', 5103000, 'platform:counterparty:list', '往来单位', '/master-data/counterparties', NULL, 30, 'ACTIVE', 0),
@@ -103,9 +104,18 @@ VALUES
   (5102016, 0, 'PLATFORM', 'BUTTON', 5102010, 'platform:order:cancel', '取消订单', NULL, NULL, 60, 'ACTIVE', 0),
   (5102017, 0, 'PLATFORM', 'BUTTON', 5102010, 'platform:order:note', '内部备注', NULL, NULL, 70, 'ACTIVE', 0),
   (5102018, 0, 'PLATFORM', 'BUTTON', 5102010, 'platform:order:fulfillment', '登记履约快递', NULL, NULL, 80, 'ACTIVE', 0),
+  (5102021, 0, 'PLATFORM', 'BUTTON', 5102020, 'platform:firstleg:task:view', '查看履约任务', NULL, NULL, 10, 'ACTIVE', 0),
+  (5102022, 0, 'PLATFORM', 'BUTTON', 5102020, 'platform:firstleg:assignment:history', '查看分配历史', NULL, NULL, 20, 'ACTIVE', 0),
+  (5102023, 0, 'PLATFORM', 'BUTTON', 5102020, 'platform:firstleg:assignment:assign', '分配履约任务', NULL, NULL, 30, 'ACTIVE', 0),
   (5103011, 0, 'PLATFORM', 'BUTTON', 5103010, 'platform:warehouse:create', '新增仓库', NULL, NULL, 10, 'ACTIVE', 0),
   (5103012, 0, 'PLATFORM', 'BUTTON', 5103010, 'platform:warehouse:edit', '编辑仓库', NULL, NULL, 20, 'ACTIVE', 0),
-  (5103013, 0, 'PLATFORM', 'BUTTON', 5103010, 'platform:warehouse:status', '启用停用', NULL, NULL, 30, 'ACTIVE', 0)
+  (5103013, 0, 'PLATFORM', 'BUTTON', 5103010, 'platform:warehouse:status', '启用停用', NULL, NULL, 30, 'ACTIVE', 0),
+  (5103021, 0, 'PLATFORM', 'BUTTON', 5103020, 'platform:express:create', '新增快递公司', NULL, NULL, 10, 'ACTIVE', 0),
+  (5103022, 0, 'PLATFORM', 'BUTTON', 5103020, 'platform:express:edit', '编辑快递公司', NULL, NULL, 20, 'ACTIVE', 0),
+  (5103023, 0, 'PLATFORM', 'BUTTON', 5103020, 'platform:express:status', '启用停用快递公司', NULL, NULL, 30, 'ACTIVE', 0),
+  (5103031, 0, 'PLATFORM', 'BUTTON', 5103030, 'platform:counterparty:create', '新增往来单位', NULL, NULL, 10, 'ACTIVE', 0),
+  (5103032, 0, 'PLATFORM', 'BUTTON', 5103030, 'platform:counterparty:edit', '编辑往来单位', NULL, NULL, 20, 'ACTIVE', 0),
+  (5103033, 0, 'PLATFORM', 'BUTTON', 5103030, 'platform:counterparty:status', '启用停用往来单位', NULL, NULL, 30, 'ACTIVE', 0)
 ON DUPLICATE KEY UPDATE
   permission_type = VALUES(permission_type), parent_id = VALUES(parent_id),
   permission_name = VALUES(permission_name), route_path = VALUES(route_path),
@@ -168,7 +178,7 @@ ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
 
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
 SELECT 4000003, id, 0 FROM iam_permission
-WHERE permission_code LIKE 'platform:order%'
+WHERE permission_code LIKE 'platform:order%' OR permission_code LIKE 'platform:firstleg%'
 ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);
 
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)

iam/src/main/resources/openapi/iam-v1.yaml

@@ -18,6 +18,25 @@ tags:
     description: Platform and merchant role-permission management / 平台端与商户端角色权限管理
 paths:
   /api/platform/v1/iam/tenants:
+    get:
+      tags: [Platform Tenant / 平台租户]
+      summary: List enterprise tenants / 查询企业客户列表
+      description: Returns paged merchant tenants. Requires `platform:customer:list`. / 分页查询商户企业客户，需要 `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 / 创建企业租户
@@ -32,6 +51,32 @@ paths:
         '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: Get current effective permissions / 查询当前用户有效权限
+      description: Returns the current active platform membership's permission codes. It only requires a valid PLATFORM JWT and does not require `platform:role:list`. / 返回当前有效平台成员权限编码；只要求有效 PLATFORM JWT，不依赖 `platform:role:list`。
+      responses:
+        '200':
+          description: 当前平台成员权限查询成功
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/PermissionCodesApiResponse'}
+        '401': {$ref: '#/components/responses/Unauthorized'}
+        '403': {$ref: '#/components/responses/Forbidden'}
+  /api/merchant/v1/iam/authorization/permissions:
+    get:
+      tags: [IAM Resources / IAM 资源]
+      summary: Get current effective permissions / 查询当前用户有效权限
+      description: Returns the current active merchant membership's permission codes. / 返回当前有效商户成员权限编码。
+      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 / 平台租户]
@@ -79,7 +124,11 @@ paths:
       tags: [IAM Resources / IAM 资源]
       summary: 查询平台内部用户
       responses:
-        '200': {$ref: '#/components/responses/Success'}
+        '200':
+          description: 平台内部用户查询成功，公开主键为 membershipId 并回显 roleIds
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/InternalUserListApiResponse'}
         '403': {$ref: '#/components/responses/Forbidden'}
     post:
       tags: [IAM Resources / IAM 资源]
@@ -326,6 +375,7 @@ components:
     Forbidden: {description: Permission or tenant 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'}}}}
+    UnprocessableEntity: {description: 参数校验失败, content: {application/json: {schema: {$ref: '#/components/schemas/ApiResponse'}}}}
   schemas:
     ApiResponse:
       type: object
@@ -337,6 +387,48 @@ components:
         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}
+    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}
+    InternalUserListApiResponse:
+      allOf:
+        - {$ref: '#/components/schemas/ApiResponse'}
+        - type: object
+          properties:
+            data: {type: array, items: {$ref: '#/components/schemas/InternalUserResponse'}}
+    TenantResponse:
+      type: object
+      required: [id, tenantCode, tenantName, status]
+      properties:
+        id: {type: integer, format: int64}
+        tenantCode: {type: string}
+        tenantName: {type: string}
+        status: {type: string, enum: [PROFILE_REQUIRED, PENDING, ACTIVE, REJECTED, DISABLED]}
+        legalName: {type: string}
+        unifiedSocialCreditCode: {type: string}
+        contactName: {type: string}
+        contactPhone: {type: string}
+        contactEmail: {type: string, format: email}
     RegisterRequest:
       type: object
       required: [tenantName, legalName, unifiedSocialCreditCode, contactName, contactPhone]

iam/src/test/java/com/baiyue/iam/service/AuthorizationSnapshotServiceTest.java

@@ -3,6 +3,7 @@ package com.baiyue.iam.service;
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import com.baiyue.iam.dto.AuthorizationDtos.SnapshotRequest;
+import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.iam.mapper.AuthorizationQueryMapper;
 import org.junit.jupiter.api.Test;
 import org.springframework.test.util.ReflectionTestUtils;
@@ -56,6 +57,43 @@ class AuthorizationSnapshotServiceTest {
         verify(mapper).countActiveIdentity(42L, 7L, 9L);
     }
 
+    @Test
+    void loadsCurrentPlatformPermissionsWithoutRoleManagementPermission() {
+        AuthorizationQueryMapper mapper = mock(AuthorizationQueryMapper.class);
+        when(mapper.countActiveIdentity(42L, 0L, 9L)).thenReturn(1);
+        when(mapper.findRoles(42L, 0L, 9L, "PLATFORM")).thenReturn(List.of("ORDER_OPERATOR"));
+        when(mapper.findPermissions(42L, 0L, 9L, "PLATFORM"))
+                .thenReturn(List.of("platform:order:list"));
+
+        var result = service(mapper).currentPermissions(new AuthenticatedUser(42L, 0L, 0L, 9L,
+                "operator", "PLATFORM", "PLATFORM", java.util.Set.of()), "PLATFORM");
+
+        assertThat(result).containsExactly("platform:order:list");
+        verify(mapper).findPermissions(42L, 0L, 9L, "PLATFORM");
+    }
+
+    @Test
+    void rejectsIncompleteCurrentIdentityAsBusinessError() {
+        assertThatThrownBy(() -> service(mock(AuthorizationQueryMapper.class))
+                .currentPermissions(new AuthenticatedUser(42L, 0L, 0L, null,
+                        "operator", "PLATFORM", "PLATFORM", java.util.Set.of()), "PLATFORM"))
+                .isInstanceOfSatisfying(BizException.class,
+                        exception -> assertThat(exception.getResultCode()).isEqualTo(ResultCode.UNAUTHORIZED));
+    }
+
+    @Test
+    void 空角色和权限查询结果不应触发五百错误() {
+        AuthorizationQueryMapper mapper = mock(AuthorizationQueryMapper.class);
+        when(mapper.countActiveIdentity(42L, 0L, 9L)).thenReturn(1);
+        when(mapper.findRoles(42L, 0L, 9L, "PLATFORM")).thenReturn(null);
+        when(mapper.findPermissions(42L, 0L, 9L, "PLATFORM")).thenReturn(null);
+
+        var result = service(mapper).currentPermissions(new AuthenticatedUser(42L, 0L, 0L, 9L,
+                "operator", "PLATFORM", "PLATFORM", java.util.Set.of()), "PLATFORM");
+
+        assertThat(result).isEmpty();
+    }
+
     private AuthorizationSnapshotService service(AuthorizationQueryMapper mapper) {
         AuthorizationSnapshotService service = new AuthorizationSnapshotService();
         ReflectionTestUtils.setField(service, "mapper", mapper);

order/AGENTS.md

@@ -17,7 +17,7 @@
 | 仓库/往来单位有效性 | `service/OrderMasterDataGuard.java`、`client/WarehouseClient.java`、`PartnerClient.java` |
 | 租户与访问范围 | `service/OrderScopeGuard.java` |
 | 请求与详情响应 | `dto/OrderRequests.java`、`OrderDetailResponse.java` |
-| 主单、货物、参与方、历史、备注、Outbox | `entity/`、`mapper/`、`repository/OrderRepository.java` |
+| 主单、货物、参与方、历史、备注、Outbox、幂等记录 | `entity/`、`mapper/`、`repository/OrderRepository.java` |
 | 表结构与一期扩展 | `src/main/resources/db/order.sql`、`phase1-masterdata-extension.sql`、`phase1-order-extension.sql` |
 | 模块说明 | `README-ORDER.md` |
 | 状态、主数据与接口权限测试 | `src/test/java/com/baiyue/order/service/`、`src/test/java/com/baiyue/order/controller/` |
@@ -29,4 +29,5 @@
 - 已提交订单中的仓库、往来单位等快照不能随主数据修改而变化。
 - 跨服务只通过 `client/` 或事件演进，不跨库查询 IAM/Warehouse；跨域通知优先使用 Outbox。
 - 新增状态或动作时同步修改 Controller、Service 状态机、历史记录、DTO、SQL、前端消费者和测试。
+- 创建草稿和提交订单必须接收 `Idempotency-Key`；幂等范围按租户、操作者和操作隔离，请求指纹包含资源，并由数据库唯一键保证并发安全。
 - 从父目录运行 `mvn -pl order -am test`，再运行 `scripts/order-warehouse-real-api-regression.ps1` 或对应一期回归。

order/src/main/java/com/baiyue/order/controller/MerchantFirstLegOrderController.java

@@ -23,6 +23,7 @@ import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
@@ -45,13 +46,18 @@ public class MerchantFirstLegOrderController {
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Draft created / 草稿创建成功"),
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid order data / 订单数据无效"),
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "Authentication required / 需要登录"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Merchant scope required / 需要商户端权限")
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Merchant scope required / 需要商户端权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "幂等键冲突或请求仍在处理中"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "503", description = "主数据下游服务暂时不可用")
     })
     @PostMapping
     @PreAuthorize("hasAuthority('merchant:order:create')")
     public ApiResponse<Long> create(@AuthenticationPrincipal AuthenticatedUser user,
+                                    @Parameter(description = "幂等键，同一操作者的同一请求重试时必须保持不变", required = true)
+                                    @RequestHeader("Idempotency-Key") String idempotencyKey,
                                     @Valid @RequestBody OrderRequests.SaveRequest request) {
-        return ApiResponse.success(service.createDraft(OrderScopeGuard.merchant(user), user.userId(), request));
+        return ApiResponse.success(service.createDraft(
+            OrderScopeGuard.merchant(user), user.userId(), request, idempotencyKey));
     }
 
     @BusinessAudit(event = "ORDER_UPDATE", resourceType = "FIRST_LEG_ORDER", resourceId = "#id", description = "Update draft / 修改草稿")
@@ -104,15 +110,20 @@ public class MerchantFirstLegOrderController {
     @Operation(summary = "Submit / 提交", description = "Submits a draft order for platform review and records status history. / 提交订单草稿进入平台审核，并记录状态历史。")
     @ApiResponses({
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Order submitted / 订单提交成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "缺少或使用了无效幂等键"),
         @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "Order not found / 订单不存在"),
-        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "Invalid status transition / 状态流转无效")
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "Invalid status transition / 状态流转或幂等键冲突"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "503", description = "主数据下游服务暂时不可用")
     })
     @PostMapping("/{id}/submit")
     @PreAuthorize("hasAuthority('merchant:order:submit')")
     public ApiResponse<Void> submit(
         @AuthenticationPrincipal AuthenticatedUser user,
-        @Parameter(description = "Order ID / 订单 ID", example = "190000000000000001", required = true) @PathVariable long id) {
-        return transit(user, id, OrderStatus.SUBMITTED, null);
+        @Parameter(description = "Order ID / 订单 ID", example = "190000000000000001", required = true) @PathVariable long id,
+        @Parameter(description = "幂等键，同一操作者的同一请求重试时必须保持不变", required = true)
+        @RequestHeader("Idempotency-Key") String idempotencyKey) {
+        service.submit(OrderScopeGuard.merchant(user), user.userId(), user.username(), id, idempotencyKey);
+        return ApiResponse.success(null);
     }
 
     @BusinessAudit(event = "ORDER_CANCEL", resourceType = "FIRST_LEG_ORDER", resourceId = "#id", description = "Cancel order / 取消订单")

order/src/main/java/com/baiyue/order/repository/OrderRepository.java

@@ -24,10 +24,12 @@ public class OrderRepository {
     private final OrderStatusHistoryMapper historyMapper;
     private final OutboxEventMapper outboxMapper;
     private final OrderChildPurgeMapper childPurgeMapper;
+    private final OrderIdempotencyRecordMapper idempotencyMapper;
 
     public OrderRepository(OrderMapper orderMapper, OrderCargoMapper cargoMapper, OrderPartyMapper partyMapper,
                            OrderInternalNoteMapper noteMapper, OrderStatusHistoryMapper historyMapper,
-                           OutboxEventMapper outboxMapper, OrderChildPurgeMapper childPurgeMapper) {
+                           OutboxEventMapper outboxMapper, OrderChildPurgeMapper childPurgeMapper,
+                           OrderIdempotencyRecordMapper idempotencyMapper) {
         this.orderMapper = orderMapper;
         this.cargoMapper = cargoMapper;
         this.partyMapper = partyMapper;
@@ -35,6 +37,7 @@ public class OrderRepository {
         this.historyMapper = historyMapper;
         this.outboxMapper = outboxMapper;
         this.childPurgeMapper = childPurgeMapper;
+        this.idempotencyMapper = idempotencyMapper;
     }
 
     public void insertOrder(OrderEntity order) { orderMapper.insert(order); }
@@ -44,6 +47,23 @@ public class OrderRepository {
     public void insertNote(OrderInternalNoteEntity note) { noteMapper.insert(note); }
     public void insertHistory(OrderStatusHistoryEntity history) { historyMapper.insert(history); }
     public void insertOutbox(OutboxEventEntity event) { outboxMapper.insert(event); }
+    public void insertIdempotency(OrderIdempotencyRecordEntity record) { idempotencyMapper.insert(record); }
+
+    public OrderIdempotencyRecordEntity findIdempotency(
+        long tenantId, long operatorId, String operation, String idempotencyKey) {
+        return idempotencyMapper.selectOne(new LambdaQueryWrapper<OrderIdempotencyRecordEntity>()
+            .eq(OrderIdempotencyRecordEntity::getTenantId, tenantId)
+            .eq(OrderIdempotencyRecordEntity::getOperatorId, operatorId)
+            .eq(OrderIdempotencyRecordEntity::getOperation, operation)
+            .eq(OrderIdempotencyRecordEntity::getIdempotencyKey, idempotencyKey));
+    }
+
+    public int completeIdempotency(OrderIdempotencyRecordEntity record, Long resultOrderId) {
+        record.setStatus("COMPLETED");
+        record.setResultOrderId(resultOrderId);
+        record.setCompletedAt(java.time.LocalDateTime.now());
+        return idempotencyMapper.updateById(record);
+    }
 
     public OrderEntity findOwned(long tenantId, long orderId) {
         return orderMapper.selectOne(new LambdaQueryWrapper<OrderEntity>()

order/src/main/java/com/baiyue/order/service/OrderApplicationService.java

@@ -10,11 +10,15 @@ import com.baomidou.mybatisplus.core.toolkit.IdWorker;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.annotation.Resource;
+import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.util.StringUtils;
 
 import java.time.LocalDateTime;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
@@ -26,8 +30,20 @@ public class OrderApplicationService {
     @Resource private OrderEligibilityGuard eligibilityGuard;
     @Resource private OrderMasterDataGuard masterDataGuard;
 
+    /** 创建草稿时使用数据库唯一键保证请求幂等。 */
     @Transactional
-    public Long createDraft(long tenantId, long userId, OrderRequests.SaveRequest request) {
+    public Long createDraft(long tenantId, long userId, OrderRequests.SaveRequest request, String idempotencyKey) {
+        IdempotencyContext idempotency = beginIdempotency(tenantId, userId, "CREATE_DRAFT", 0L, idempotencyKey,
+            requestHash("CREATE_DRAFT", request));
+        if (idempotency.replayed()) {
+            return idempotency.record().getResultOrderId();
+        }
+        Long orderId = createDraftInternal(tenantId, userId, request);
+        completeIdempotency(idempotency, orderId);
+        return orderId;
+    }
+
+    private Long createDraftInternal(long tenantId, long userId, OrderRequests.SaveRequest request) {
         eligibilityGuard.requireApproved(tenantId);
         validatePrototypeFields(request);
         var snapshots = masterDataGuard.validate(tenantId, request);
@@ -43,10 +59,10 @@ public class OrderApplicationService {
 
     @Transactional
     public void updateDraft(long tenantId, long userId, long id, OrderRequests.SaveRequest request) {
+        OrderEntity order = require(tenantId, id);
         eligibilityGuard.requireApproved(tenantId);
         validatePrototypeFields(request);
         var snapshots = masterDataGuard.validate(tenantId, request);
-        OrderEntity order = require(tenantId, id);
         if (order.getStatus() != OrderStatus.DRAFT && order.getStatus() != OrderStatus.REJECTED) {
             throw new BizException("Only draft or rejected orders can be edited");
         }
@@ -58,8 +74,8 @@ public class OrderApplicationService {
 
     @Transactional
     public void transit(long tenantId, long userId, String username, long id, OrderStatus target, String reason) {
-        if (target == OrderStatus.SUBMITTED) eligibilityGuard.requireApproved(tenantId);
         OrderEntity order = require(tenantId, id);
+        if (target == OrderStatus.SUBMITTED) eligibilityGuard.requireApproved(tenantId);
         OrderStatus from = order.getStatus();
         if (!allowed(from, target)) throw new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
             from == target ? "该操作已完成，请勿重复提交" : "订单状态不允许当前操作: " + from + " -> " + target);
@@ -79,6 +95,18 @@ public class OrderApplicationService {
         if (target == OrderStatus.APPROVED || target == OrderStatus.CANCELLED) writeOutbox(order, target);
     }
 
+    /** 提交订单的幂等入口。 */
+    @Transactional
+    public void submit(long tenantId, long userId, String username, long id, String idempotencyKey) {
+        IdempotencyContext idempotency = beginIdempotency(tenantId, userId, "SUBMIT_ORDER", id, idempotencyKey,
+            requestHash("SUBMIT_ORDER", Map.of("orderId", id)));
+        if (idempotency.replayed()) {
+            return;
+        }
+        transit(tenantId, userId, username, id, OrderStatus.SUBMITTED, null);
+        completeIdempotency(idempotency, id);
+    }
+
     public PageResult<OrderEntity> page(long tenantId, OrderRequests.QueryRequest query) { return repository.page(tenantId, query); }
     public OrderDetailResponse detail(long tenantId, long id) {
         OrderEntity order = require(tenantId, id);
@@ -149,9 +177,83 @@ public class OrderApplicationService {
 
     private OrderEntity require(long tenantId, long id) {
         OrderEntity order = repository.findOwned(tenantId, id);
-        if (order == null) throw new BizException("Order not found");
+        if (order == null) throw new BizException(com.baiyue.common.core.api.ResultCode.NOT_FOUND, "Order not found");
         return order;
     }
+
+    private IdempotencyContext beginIdempotency(long tenantId, long operatorId, String operation, long resourceId,
+                                                String rawKey, String requestHash) {
+        if (!StringUtils.hasText(rawKey)) {
+            throw new BizException(com.baiyue.common.core.api.ResultCode.BAD_REQUEST,
+                "必须提供 Idempotency-Key");
+        }
+        String key = rawKey.trim();
+        if (key.length() > 128) {
+            throw new BizException(com.baiyue.common.core.api.ResultCode.VALIDATION_FAILED,
+                "Idempotency-Key length must not exceed 128");
+        }
+        OrderIdempotencyRecordEntity record = new OrderIdempotencyRecordEntity();
+        record.setId(IdWorker.getId());
+        record.setTenantId(tenantId);
+        record.setOperatorId(operatorId);
+        record.setOperation(operation);
+        record.setResourceId(resourceId);
+        record.setIdempotencyKey(key);
+        record.setRequestHash(requestHash);
+        record.setStatus("PROCESSING");
+        record.setCreatedAt(LocalDateTime.now());
+        record.setUpdatedAt(LocalDateTime.now());
+        try {
+            repository.insertIdempotency(record);
+            return IdempotencyContext.created(record);
+        } catch (DuplicateKeyException duplicate) {
+            OrderIdempotencyRecordEntity existing = repository.findIdempotency(
+                tenantId, operatorId, operation, key);
+            if (existing == null || !requestHash.equals(existing.getRequestHash())) {
+                throw new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
+                    "Idempotency-Key conflicts with a different request");
+            }
+            if (!"COMPLETED".equals(existing.getStatus())) {
+                throw new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
+                    "The idempotent request is still being processed");
+            }
+            return IdempotencyContext.replayed(existing);
+        }
+    }
+
+    private void completeIdempotency(IdempotencyContext context, Long resultOrderId) {
+        if (context.enabled() && !context.replayed()) {
+            if (repository.completeIdempotency(context.record(), resultOrderId) != 1) {
+                throw new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
+                    "幂等记录已被并发修改");
+            }
+        }
+    }
+
+    private String requestHash(String operation, Object request) {
+        try {
+            byte[] source = (operation + ":" + json.writeValueAsString(request)).getBytes(StandardCharsets.UTF_8);
+            byte[] digest = MessageDigest.getInstance("SHA-256").digest(source);
+            StringBuilder result = new StringBuilder(64);
+            for (byte value : digest) {
+                result.append(String.format("%02x", value));
+            }
+            return result.toString();
+        } catch (JsonProcessingException | NoSuchAlgorithmException exception) {
+            throw new BizException(com.baiyue.common.core.api.ResultCode.INTERNAL_ERROR,
+                "Cannot create idempotency request fingerprint");
+        }
+    }
+
+    private record IdempotencyContext(OrderIdempotencyRecordEntity record, boolean enabled, boolean replayed) {
+        static IdempotencyContext disabled() { return new IdempotencyContext(null, false, false); }
+        static IdempotencyContext created(OrderIdempotencyRecordEntity record) {
+            return new IdempotencyContext(record, true, false);
+        }
+        static IdempotencyContext replayed(OrderIdempotencyRecordEntity record) {
+            return new IdempotencyContext(record, true, true);
+        }
+    }
     private boolean allowed(OrderStatus from, OrderStatus target) {
         return switch (from) {
             case DRAFT -> target == OrderStatus.SUBMITTED || target == OrderStatus.CANCELLED;

order/src/main/java/com/baiyue/order/service/OrderMasterDataGuard.java

@@ -40,6 +40,10 @@ public class OrderMasterDataGuard {
             throw new BizException(ResultCode.NOT_FOUND,"往来单位或仓库不存在、已停用或不属于当前企业");
         } catch (FeignException exception) {
             throw unavailable("主数据");
+        } catch (BizException exception) {
+            throw exception;
+        } catch (RuntimeException exception) {
+            throw unavailable("主数据");
         }
     }
     public void validatePersisted(long tenantId, Long partnerId, Long receivingWarehouseId, Long destinationWarehouseId) {
@@ -51,7 +55,13 @@ public class OrderMasterDataGuard {
             if (destinationWarehouseId!=null) loadWarehouse(tenantId,destinationWarehouseId,"目的仓库");
         } catch (FeignException.NotFound exception) {
             throw new BizException(ResultCode.NOT_FOUND,"往来单位或仓库已停用、越权或不存在");
-        } catch (FeignException exception) { throw unavailable("主数据"); }
+        } catch (FeignException exception) {
+            throw unavailable("主数据");
+        } catch (BizException exception) {
+            throw exception;
+        } catch (RuntimeException exception) {
+            throw unavailable("主数据");
+        }
     }
     private PartnerClient.Partner loadPartner(long tenantId,long id) {
         var response=partners.active(token,tenantId,id);

order/src/main/resources/db/order.sql

@@ -161,3 +161,21 @@ CREATE TABLE IF NOT EXISTS ord_outbox_event (
   PRIMARY KEY (id),
   KEY idx_outbox_publish (publish_status, next_retry_at, created_at)
 ) ENGINE=InnoDB COMMENT='订单事务Outbox表：与订单业务变更在同一本地事务写入，供后台发布器可靠投递RocketMQ，保证数据库状态与领域事件最终一致；不是普通操作日志';
+
+CREATE TABLE IF NOT EXISTS ord_idempotency_record (
+  id BIGINT UNSIGNED NOT NULL COMMENT '幂等记录ID',
+  tenant_id BIGINT UNSIGNED NOT NULL COMMENT '租户ID',
+  operator_id BIGINT UNSIGNED NOT NULL COMMENT '操作者ID',
+  operation VARCHAR(32) NOT NULL COMMENT '幂等操作类型',
+  resource_id BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '资源ID，创建草稿时为0',
+  idempotency_key VARCHAR(128) NOT NULL COMMENT '客户端幂等键',
+  request_hash CHAR(64) NOT NULL COMMENT '请求内容SHA-256摘要',
+  status VARCHAR(16) NOT NULL COMMENT '处理状态：PROCESSING或COMPLETED',
+  result_order_id BIGINT UNSIGNED NULL COMMENT '成功结果订单ID',
+  completed_at DATETIME(3) NULL COMMENT '处理完成时间',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_order_idempotency_scope (tenant_id, operator_id, operation, idempotency_key),
+  KEY idx_order_idempotency_created (created_at)
+) ENGINE=InnoDB COMMENT='订单写接口持久化幂等记录：唯一键保证同租户同操作者并发请求只执行一次';

order/src/test/java/com/baiyue/order/service/OrderMasterDataGuardTest.java

@@ -59,6 +59,16 @@ class OrderMasterDataGuardTest {
             .isEqualTo(ResultCode.SERVICE_UNAVAILABLE);
         verifyNoInteractions(warehouses);
     }
+    @Test
+    void 下游非Feign运行时异常映射为服务不可用() {
+        WarehouseClient warehouses=mock(WarehouseClient.class); PartnerClient partners=mock(PartnerClient.class);
+        when(partners.active("token",10001,7)).thenThrow(new IllegalStateException("解码失败"));
+
+        assertThatThrownBy(() -> new OrderMasterDataGuard(warehouses,partners,"token").validate(10001,request(7L,8L)))
+            .isInstanceOf(BizException.class)
+            .extracting(exception -> ((BizException) exception).getResultCode())
+            .isEqualTo(ResultCode.SERVICE_UNAVAILABLE);
+    }
     private OrderRequests.SaveRequest request(Long partner,Long warehouse) {
         var party=new OrderRequests.Party("公司","联系人","13800138000",null,"CN",null,"深圳",null,"地址",null);
         var cargo=new OrderRequests.Cargo("货物",null,"CARTON",1,BigDecimal.ONE,BigDecimal.ONE,

warehouse/AGENTS.md

@@ -14,11 +14,13 @@
 | 内部仓库有效性校验 | `controller/InternalWarehouseController.java` |
 | 商户往来单位候选与详情 | `controller/MerchantPartnerController.java` |
 | 内部往来单位有效性校验 | `controller/InternalPartnerController.java` |
+| 平台往来单位增改查与启停 | `controller/PlatformPartnerController.java`、`service/PlatformPartnerQueryService.java` |
+| 平台快递公司增改查与启停 | `controller/PlatformExpressCompanyController.java`、`service/ExpressCompanyQueryService.java` |
 | 仓库业务编排 | `service/WarehouseApplicationService.java` |
 | 往来单位查询与停用过滤 | `service/PartnerQueryService.java` |
-| 请求与详情 DTO | `dto/WarehouseRequests.java`、`WarehouseDetailResponse.java` |
-| 仓库、地址、能力、伙伴持久化 | `entity/`、`mapper/`、`repository/` |
-| 表结构、伙伴与种子数据 | `src/main/resources/db/warehouse.sql`、`warehouse-partner.sql`、`warehouse-seed.sql` |
+| 请求与详情 DTO | `dto/WarehouseRequests.java`、`WarehouseDetailResponse.java`、`MasterDataQueries.java` |
+| 仓库、地址、能力、往来单位与快递公司持久化 | `entity/`、`mapper/`、`repository/` |
+| 表结构、伙伴、快递公司与种子数据 | `src/main/resources/db/warehouse.sql`、`warehouse-partner.sql`、`warehouse-express-company.sql`、`warehouse-seed.sql` |
 | 测试 | `src/test/java/com/baiyue/warehouse/` |
 
 ## 修改与验证

warehouse/src/main/java/com/baiyue/warehouse/repository/PartnerRepository.java

@@ -1,6 +1,9 @@
 package com.baiyue.warehouse.repository;
 
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.warehouse.dto.MasterDataQueries.PartnerPageQuery;
 import com.baiyue.warehouse.entity.PartnerEntity;
 import com.baiyue.warehouse.mapper.PartnerMapper;
 import org.springframework.stereotype.Repository;
@@ -24,4 +27,40 @@ public class PartnerRepository {
             .eq(PartnerEntity::getTenantId, tenantId).eq(PartnerEntity::getId, id)
             .eq(PartnerEntity::getStatus, "ACTIVE"));
     }
+
+    public PageResult<PartnerEntity> page(long tenantId, PartnerPageQuery request) {
+        LambdaQueryWrapper<PartnerEntity> wrapper = new LambdaQueryWrapper<PartnerEntity>()
+            .eq(PartnerEntity::getTenantId, tenantId)
+            .eq(StringUtils.hasText(request.type()), PartnerEntity::getPartnerType, request.type())
+            .eq(StringUtils.hasText(request.status()), PartnerEntity::getStatus, request.status())
+            .and(StringUtils.hasText(request.keyword()), query -> query
+                .like(PartnerEntity::getPartnerCode, request.keyword())
+                .or().like(PartnerEntity::getPartnerName, request.keyword())
+                .or().like(PartnerEntity::getContactName, request.keyword())
+                .or().like(PartnerEntity::getContactPhone, request.keyword()))
+            .orderByAsc(PartnerEntity::getPartnerName)
+            .orderByAsc(PartnerEntity::getId);
+        return PageResult.from(mapper.selectPage(new Page<>(request.page(), request.size()), wrapper));
+    }
+
+    public PartnerEntity findOwned(long tenantId, long id) {
+        return mapper.selectOne(new LambdaQueryWrapper<PartnerEntity>()
+            .eq(PartnerEntity::getTenantId, tenantId)
+            .eq(PartnerEntity::getId, id));
+    }
+
+    public boolean existsCode(long tenantId, String code, Long excludedId) {
+        return mapper.selectCount(new LambdaQueryWrapper<PartnerEntity>()
+            .eq(PartnerEntity::getTenantId, tenantId)
+            .eq(PartnerEntity::getPartnerCode, code)
+            .ne(excludedId != null, PartnerEntity::getId, excludedId)) > 0;
+    }
+
+    public void insert(PartnerEntity entity) {
+        mapper.insert(entity);
+    }
+
+    public void save(PartnerEntity entity) {
+        mapper.updateById(entity);
+    }
 }

warehouse/src/test/java/com/baiyue/warehouse/repository/PartnerRepositoryTest.java

@@ -10,6 +10,8 @@ import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
 import org.apache.ibatis.builder.MapperBuilderAssistant;
 import org.apache.ibatis.session.Configuration;
 import java.util.List;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baiyue.warehouse.dto.MasterDataQueries.PartnerPageQuery;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.*;
@@ -32,4 +34,19 @@ class PartnerRepositoryTest {
         verify(mapper).selectOne(c.capture()); c.getValue().getSqlSegment();
         assertThat(c.getValue().getParamNameValuePairs().values()).contains(10002L,9L,"ACTIVE");
     }
+
+    @Test void 平台分页强制租户并支持筛选() {
+        PartnerMapper mapper=mock(PartnerMapper.class);
+        when(mapper.selectPage(any(Page.class), any())).thenAnswer(invocation -> invocation.getArgument(0));
+
+        new PartnerRepository(mapper).page(10001L,
+            new PartnerPageQuery(1, 20, "示例", "CUSTOMER", "ACTIVE"));
+
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<LambdaQueryWrapper<PartnerEntity>> wrapper=ArgumentCaptor.forClass(LambdaQueryWrapper.class);
+        verify(mapper).selectPage(any(Page.class), wrapper.capture());
+        wrapper.getValue().getSqlSegment();
+        assertThat(wrapper.getValue().getParamNameValuePairs().values())
+            .contains(10001L, "CUSTOMER", "ACTIVE", "%示例%");
+    }
 }