diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..8d1ac99f6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,47 @@
+# 柏悦头程后端项目指引
+
+## 适用范围
+
+- 本文件适用于 `baiyue-firstleg/` 整个 Maven 多模块仓库；进入子模块后同时遵守该模块的 `AGENTS.md`。
+- 开始修改前先读根目录 `README.md`、`pom.xml` 和 `docs/头程项目目录结构与服务说明.md`；业务边界不清时读 `docs/repository-boundary.md`。
+- 本仓只承载国内头程业务。尾程源码、数据库、Redis、Nacos 和内部接口不得并入本仓。
+
+## 模块快速索引
+
+| 模块 | 职责 | 首选入口 |
+|---|---|---|
+| `platform-bom/` | 公共制品版本清单 | `pom.xml` 的 `dependencyManagement` |
+| `common-core/` | 返回模型、错误码、基础实体、MyBatis 配置 | `api/`、`exception/`、`model/`、`mybatis/` |
+| `common-web/` | 全局异常与请求链路标识 | `GlobalExceptionHandler.java`、`CorrelationIdFilter.java` |
+| `common-security/` | JWT、Redis 会话校验、认证上下文、401/403 | `JwtAuthenticationFilter.java`、`RedisAccessTokenSessionValidator.java` |
+| `common-openapi/` | SpringDoc 自动配置 | `BaiyueOpenApiAutoConfiguration.java`、`OpenApiProperties.java` |
+| `common-audit/` | 审计注解、切面、脱敏与发送 | `BusinessAuditAspect.java`、`SensitiveDataSanitizer.java`、`AuditSink.java` |
+| `common-event-contract/` | 跨区域事件信封、类型、标识、哈希与校验 | `EventEnvelope.java`、`EventTypes.java`、`EventEnvelopeValidator.java` |
+| `gateway/` | 路由、CORS、入口安全、访问域隔离 | `config/`、`filter/`、`src/main/resources/application*.yml` |
+| `auth/` | 登录、令牌、注册、账号与密码 | `controller/`、`service/`、`src/main/resources/db/` |
+| `iam/` | 租户、成员、企业资料、RBAC 与授权快照 | `controller/`、`service/`、`README-IAM.md` |
+| `order/` | 订单主数据、状态编排、快照与 Outbox | `controller/`、`OrderApplicationService.java`、`README-ORDER.md` |
+| `firstleg/` | 履约任务、操作分配与分配历史 | `PlatformFulfillmentAssignmentController.java`、`FulfillmentTaskService.java` |
+| `warehouse/` | 仓库、地址、服务能力与往来单位 | `controller/`、`WarehouseApplicationService.java`、`PartnerQueryService.java` |
+| `file/` | 企业资质文件本地存储、预览与鉴权 | `controller/`、`LocalQualificationStorage.java`；元数据表结构尚未接入 |
+| `print/` | 打印中心边界 | 当前为应用、健康检查和 `print/src/main/resources/db/print.sql` 骨架 |
+| `audit-service/` | 审计事件接收与持久化 | `AuditIngestController.java`、`AuditIngestService.java` |
+| `integration-service/` | OCR、Amazon 等第三方适配 | `provider/`、`IntegrationProperties.java` |
+| `event-bridge-service/` | 跨区域事件接收、校验与 Inbox 幂等 | `EventBridgeController.java`、`EventInboxService.java` |
+
+## 配置、数据库与验证入口
+
+- 服务本地配置在各模块 `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。
+- 服务间调用先找调用方 `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`。
+- `reports/`、`target/`、日志、上传文件和本地环境文件不属于源码，检索与提交时排除。
+
+## 通用修改约束
+
+- Controller 只做协议转换，Service 负责编排，Repository/Mapper 负责持久化；不要跨层堆放业务逻辑。
+- 商户数据必须保留租户维度，并由服务端执行租户、访问域、数据范围和按钮权限校验。
+- 修改 SQL、DTO、事件或公共组件时同步检查所有生产者与消费者；优先保持兼容，不能兼容时写清迁移顺序。
+- 密码、令牌、第三方密钥和真实客户数据只能通过环境变量或配置中心密文注入。
diff --git a/audit-service/AGENTS.md b/audit-service/AGENTS.md
new file mode 100644
index 000000000..e6ab1d923
--- /dev/null
+++ b/audit-service/AGENTS.md
@@ -0,0 +1,27 @@
+# Audit Service 模块指引
+
+## 职责边界
+
+- 负责接收 `common-audit` 产生的审计事件并持久化到 `baiyue_audit`。
+- 审计注解、切面、脱敏和发送策略在 `common-audit/`；本服务不复制业务服务的审计采集逻辑。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用入口 | `src/main/java/com/baiyue/audit/BaiyueAuditApplication.java` |
+| 内部接收 API | `controller/AuditIngestController.java`（`/internal/audit/events`） |
+| 内部令牌保护 | `security/InternalServiceTokenGuard.java` |
+| 接收 DTO | `dto/AuditIngestRequest.java` |
+| 入库编排 | `service/AuditIngestService.java` |
+| 持久化 | `entity/AuditLogEntity.java`、`mapper/AuditLogMapper.java`、`repository/AuditEventRepository.java` |
+| 表结构 | `src/main/resources/db/audit.sql` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/audit-service.yml` |
+| 内部令牌测试 | `src/test/java/com/baiyue/audit/security/InternalServiceTokenGuardTest.java` |
+
+## 修改与验证
+
+- 内部接收接口必须受可信服务身份保护；不对前端直接开放。
+- 入库前确保密码、Token、证件等敏感信息已脱敏；新增字段时同步检查 `../common-audit/src/main/java/com/baiyue/common/audit/AuditEvent.java` 与发送实现。
+- 审计链路故障不得阻塞核心交易；保留幂等、超时、容量和留存策略的演进空间。
+- 从父目录运行 `mvn -pl audit-service -am test`，并验证接收、拒绝非法请求和持久化结果。
diff --git a/auth/AGENTS.md b/auth/AGENTS.md
new file mode 100644
index 000000000..be1cae42c
--- /dev/null
+++ b/auth/AGENTS.md
@@ -0,0 +1,29 @@
+# Auth Service 模块指引
+
+## 职责边界
+
+- 负责账号凭据、登录、Access/Refresh Token 生命周期、退出、密码变更及商户注册协作。
+- 租户、成员资料、角色和权限属于 `iam/`；Auth 只通过 IAM 客户端加载授权快照和创建注册结果。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用与安全配置 | `src/main/java/com/baiyue/auth/BaiyueAuthApplication.java`、`config/AuthSecurityConfig.java` |
+| 登录、注册、刷新、退出、改密 API | `controller/AuthController.java`（`/api/auth`） |
+| 内部账号管理 API | `controller/InternalAccountController.java`（`/internal/auth/accounts`） |
+| 认证与令牌编排 | `service/AuthService.java`、`TokenSessionStore.java` |
+| 账号状态、密码重置 | `service/AccountManagementService.java` |
+| 商户注册协作 | `service/MerchantRegistrationService.java` |
+| IAM 调用与授权快照 | `client/IamAuthorizationClient.java`、`IamOnboardingClient.java`、`AuthorizationSnapshot.java` |
+| 账号与 Refresh Token 持久化 | `entity/`、`mapper/`、`repository/` |
+| 请求/响应模型 | `dto/` |
+| 表结构与一期账号 | `src/main/resources/db/auth.sql`、`phase1-admin-accounts.sql` |
+| 配置与测试 | `src/main/resources/application.yml`、`src/test/java/com/baiyue/auth/service/` |
+
+## 修改与验证
+
+- 密码必须安全散列；不得记录密码、Token、密钥或完整敏感 Claim。
+- 修改 Token Claim、会话 Redis Key、过期或撤销逻辑时同步检查 `common-security/`、`gateway/` 和 IAM 授权快照。
+- 注册流程跨 Auth/IAM，失败补偿和幂等必须成对检查；不要跨库写 IAM 表。
+- 从父目录运行 `mvn -pl auth -am test`，认证接口变更再运行相关 `scripts/` 回归。
diff --git a/common-audit/AGENTS.md b/common-audit/AGENTS.md
new file mode 100644
index 000000000..cb0a8e9b8
--- /dev/null
+++ b/common-audit/AGENTS.md
@@ -0,0 +1,24 @@
+# Common Audit 模块指引
+
+## 职责边界
+
+- 负责业务审计事件采集、注解切面、敏感字段脱敏以及日志/HTTP 输出。
+- 审计记录持久化属于 `audit-service/`；本模块不依赖具体业务 Entity 或数据库。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 审计注解与切面 | `src/main/java/com/baiyue/common/audit/BusinessAudit.java`、`BusinessAuditAspect.java` |
+| 事件模型 | `AuditEvent.java` |
+| 输出抽象与实现 | `AuditSink.java`、`LoggingAuditSink.java`、`HttpAuditSink.java` |
+| 敏感数据脱敏 | `SensitiveDataSanitizer.java` |
+| `baiyue.audit` 配置 | `AuditProperties.java` |
+| 自动配置 | `BaiyueAuditAutoConfiguration.java` 与 `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
+| 远程发送鉴权测试 | `src/test/java/com/baiyue/common/audit/HttpAuditSinkTest.java` |
+
+## 修改与验证
+
+- 新增审计字段时先确认不会泄露密码、令牌、证件或客户敏感数据，并检查 `audit-service` 接收 DTO。
+- 审计失败不应破坏核心业务；调整输出策略时保留超时、关闭开关和安全降级。
+- 从父目录运行 `mvn -pl common-audit -am test`，并按影响追加验证 `audit-service`。
diff --git a/common-core/AGENTS.md b/common-core/AGENTS.md
new file mode 100644
index 000000000..e2e5b3bcd
--- /dev/null
+++ b/common-core/AGENTS.md
@@ -0,0 +1,23 @@
+# Common Core 模块指引
+
+## 职责边界
+
+- 提供不依赖具体业务域的返回模型、异常、基础实体和 MyBatis-Plus 通用配置。
+- 不引入订单、仓库、租户等领域实体，不调用业务服务，也不承载 Controller。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 统一响应与分页 | `src/main/java/com/baiyue/common/core/api/ApiResponse.java`、`PageResult.java` |
+| 返回码 | `src/main/java/com/baiyue/common/core/api/ResultCode.java` |
+| 业务异常 | `src/main/java/com/baiyue/common/core/exception/BizException.java` |
+| 通用审计字段 | `src/main/java/com/baiyue/common/core/model/BaseEntity.java` |
+| MyBatis-Plus 与审计人 | `src/main/java/com/baiyue/common/core/mybatis/` |
+| 响应契约测试 | `src/test/java/com/baiyue/common/core/ApiResponseTest.java` |
+
+## 修改与验证
+
+- 公共响应、错误码或基础实体变化会影响所有服务；先检索消费者并保持序列化和数据库兼容。
+- 新能力只有被多个模块稳定复用时才放入本模块。
+- 从父目录运行 `mvn -pl common-core -am test`。
diff --git a/common-event-contract/AGENTS.md b/common-event-contract/AGENTS.md
new file mode 100644
index 000000000..0b00b4c7f
--- /dev/null
+++ b/common-event-contract/AGENTS.md
@@ -0,0 +1,25 @@
+# Common Event Contract 模块指引
+
+## 职责边界
+
+- 维护国内头程与国外尾程之间稳定、可版本化的事件契约。
+- 只放事件信封、类型、区域、标识、规范化、哈希和校验；不放任一侧领域 Entity、数据库模型或发送实现。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 事件信封 | `src/main/java/com/baiyue/common/event/EventEnvelope.java` |
+| 契约校验 | `EventEnvelopeValidator.java` |
+| 事件 ID 与业务键 | `EventIdentifiers.java` |
+| Payload 规范化与哈希 | `EventPayloadCanonicalizer.java`、`EventPayloadHash.java` |
+| 事件类型与区域 | `EventTypes.java`、`RegionCode.java` |
+| 契约说明 | `package-info.java` |
+| 兼容性测试 | `src/test/java/com/baiyue/common/event/EventEnvelopeTest.java` |
+
+## 修改与验证
+
+- 所有字段与事件类型都视为跨仓公共契约；优先新增可选字段和新版本，禁止无迁移直接改名、改语义或删除。
+- 同步检查 `event-bridge-service/`、国内生产者以及固定 BOM 版本的尾程消费者。
+- 哈希算法或规范化规则变化必须保留跨语言、跨版本确定性测试。
+- 从父目录运行 `mvn -pl common-event-contract -am test`。
diff --git a/common-openapi/AGENTS.md b/common-openapi/AGENTS.md
new file mode 100644
index 000000000..e17a16e06
--- /dev/null
+++ b/common-openapi/AGENTS.md
@@ -0,0 +1,20 @@
+# Common OpenAPI 模块指引
+
+## 职责边界
+
+- 为 Spring MVC 服务提供 SpringDoc/OpenAPI 自动配置和统一文档元数据。
+- 不在这里维护具体业务接口契约；服务专属 OpenAPI 文件留在对应服务资源目录。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 自动配置 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` |
+| `baiyue.openapi` 配置项 | `src/main/java/com/baiyue/common/openapi/OpenApiProperties.java` |
+| 自动配置注册 | `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
+
+## 修改与验证
+
+- 调整分组、标题或安全方案时检查所有 MVC 服务的 Swagger 输出；Gateway 的 WebFlux 聚合配置在 `gateway/`。
+- 配置项变化优先保持旧键兼容，并同步 Nacos 模板。
+- 从父目录运行 `mvn -pl common-openapi -am test`。
diff --git a/common-security/AGENTS.md b/common-security/AGENTS.md
new file mode 100644
index 000000000..bddd9f83c
--- /dev/null
+++ b/common-security/AGENTS.md
@@ -0,0 +1,24 @@
+# Common Security 模块指引
+
+## 职责边界
+
+- 提供业务服务通用的 JWT 解码、认证过滤、Redis Access Token 会话校验、认证用户上下文及 401/403 JSON 响应。
+- 角色、权限、租户成员关系由 `iam/` 维护；本模块不实现 RBAC 管理业务。网关的 Reactive 安全链位于 `gateway/`。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 自动配置 | `src/main/java/com/baiyue/common/security/BaiyueSecurityAutoConfiguration.java`、`HmacJwtDecoderAutoConfiguration.java` |
+| JWT 过滤与声明映射 | `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java` |
+| 当前用户与认证对象 | `AuthenticatedUser.java`、`BaiyueJwtAuthenticationToken.java` |
+| Redis 会话校验 | `AccessTokenSessionValidator.java`、`RedisAccessTokenSessionValidator.java`、`RedisTokenKeys.java` |
+| 401/403 响应 | `JsonAuthenticationEntryPoint.java`、`JsonAccessDeniedHandler.java` |
+| 自动配置注册 | `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
+| 安全回归测试 | `src/test/java/com/baiyue/common/security/` |
+
+## 修改与验证
+
+- Token Claim、Redis Key 或认证对象变化必须同步检查 `auth/`、`gateway/` 和所有业务服务。
+- 不降低服务端租户、会话或权限校验；密钥只从配置中心或环境变量读取。
+- 从父目录运行 `mvn -pl common-security -am test`。
diff --git a/common-web/AGENTS.md b/common-web/AGENTS.md
new file mode 100644
index 000000000..ca393fcc5
--- /dev/null
+++ b/common-web/AGENTS.md
@@ -0,0 +1,22 @@
+# Common Web 模块指引
+
+## 职责边界
+
+- 提供 Servlet Web 通用能力：请求链路标识、上下文和统一异常响应。
+- 不放具体业务 Controller、路由或领域异常编排；业务错误通过 `common-core` 的契约表达。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 链路上下文 | `src/main/java/com/baiyue/common/web/CorrelationContext.java` |
+| 请求 ID 过滤器 | `src/main/java/com/baiyue/common/web/CorrelationIdFilter.java` |
+| 全局异常映射 | `src/main/java/com/baiyue/common/web/GlobalExceptionHandler.java` |
+| 过滤器测试 | `src/test/java/com/baiyue/common/web/CorrelationIdFilterTest.java` |
+| 异常响应测试 | `src/test/java/com/baiyue/common/web/GlobalExceptionHandlerTest.java` |
+
+## 修改与验证
+
+- 修改异常响应时同时检查 HTTP 状态、`ApiResponse` 结构、校验错误和安全异常是否仍一致。
+- 修改 Correlation ID 时检查请求头兼容、线程上下文清理和日志链路。
+- 从父目录运行 `mvn -pl common-web -am test`。
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index 2ff360751..2ce1fbb07 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -163,7 +163,7 @@ services:
     <<: *common
     image: ${IMAGE_REPOSITORY}/audit-service:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-audit
-    ports: ["${AUDIT_PORT:-9700}:9700"]
+    expose: ["9700"]
     environment:
       <<: *common-environment
       SERVER_PORT: 9700
diff --git a/event-bridge-service/AGENTS.md b/event-bridge-service/AGENTS.md
new file mode 100644
index 000000000..387ea82f7
--- /dev/null
+++ b/event-bridge-service/AGENTS.md
@@ -0,0 +1,30 @@
+# Event Bridge Service 模块指引
+
+## 职责边界
+
+- 负责跨区域事件接收、内部令牌保护、契约校验和 Inbox 幂等持久化。
+- 事件模型来自 `common-event-contract/`；本服务不共享国内/国外业务数据库，也不承载头程或尾程领域逻辑。
+- 真实跨区发送、重试调度和死信补投仍需按需求继续完善，不把当前接收骨架描述为完整消息平台。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用入口 | `src/main/java/com/baiyue/eventbridge/EventBridgeApplication.java` |
+| 事件接收与状态 API | `controller/EventBridgeController.java`（`/internal/event-bridge`） |
+| 接收结果与状态 DTO | `dto/EventReceiveResult.java`、`BridgeStatus.java` |
+| 校验与 Inbox 编排 | `service/EventInboxService.java` |
+| Inbox 抽象与 MyBatis 实现 | `service/InboxStore.java`、`MybatisInboxStore.java` |
+| Inbox 数据模型 | `domain/BridgeInbox.java`、`mapper/BridgeInboxMapper.java` |
+| 内部服务令牌 | `security/InternalServiceTokenGuard.java` |
+| 表结构 | `src/main/resources/db/event-bridge.sql` |
+| 测试 | `src/test/java/com/baiyue/eventbridge/security/`、`service/` |
+| 架构边界 | `../docs/two-repository-split.md`、`../docs/repository-boundary.md` |
+
+## 修改与验证
+
+- 先使用 `common-event-contract` 校验事件 ID、区域、版本、业务键、时间与 Payload 哈希，再执行幂等入库。
+- 重复事件应返回稳定结果且不重复产生副作用；数据库唯一约束与应用幂等逻辑要同步。
+- 跨区域接口必须鉴权、限流并最小化载荷，禁止携带密钥或非必要客户敏感数据。
+- 契约变化先遵守 `../common-event-contract/AGENTS.md` 的兼容规则，并检查国内外消费者。
+- 从父目录运行 `mvn -pl event-bridge-service -am test`。
diff --git a/file/AGENTS.md b/file/AGENTS.md
new file mode 100644
index 000000000..7130c7f70
--- /dev/null
+++ b/file/AGENTS.md
@@ -0,0 +1,27 @@
+# File Service 模块指引
+
+## 职责边界
+
+- 负责企业资质文件的上传、存储、读取和访问鉴权；当前实现只使用本地磁盘，文件内容不进入 Git。
+- `src/main/resources/db/file.sql` 是文件元数据、下载令牌和下载日志的目标表结构，当前代码尚未接入 Entity、Mapper 或 Repository，不能据此判断元数据持久化已实现。
+- 企业资质审核状态和元数据归 `iam/`；本模块通过 IAM 客户端校验访问权限，不跨库读取 IAM 数据。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 商户资质上传与读取 | `src/main/java/com/baiyue/file/controller/QualificationFileController.java` |
+| 平台资质查看 | `controller/PlatformQualificationFileController.java` |
+| 服务状态 | `controller/FileHealthController.java` |
+| 当前本地磁盘实现 | `service/LocalQualificationStorage.java` |
+| IAM 权限协作 | `client/IamQualificationClient.java` |
+| 目标表结构（尚未接入） | `src/main/resources/db/file.sql` |
+| 存储边界测试 | `src/test/java/com/baiyue/file/service/LocalQualificationStorageTest.java` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/file-service.yml` |
+
+## 修改与验证
+
+- 严格校验租户、文件名/路径、大小、类型和读取权限，防止目录穿越、越权访问和任意文件上传。
+- 生产存储应使用对象存储或共享文件存储；容器本地目录仅适合当前本地实现，不得硬编码环境路径。
+- 接入元数据持久化时需同时实现 Entity、Mapper、Repository、事务和迁移验证，并同步检查 IAM 资质流程及平台/商户 Controller。
+- 从父目录运行 `mvn -pl file -am test`，并按接口影响验证上传、预览、无权限和非法文件场景。
diff --git a/firstleg/AGENTS.md b/firstleg/AGENTS.md
new file mode 100644
index 000000000..4438d9516
--- /dev/null
+++ b/firstleg/AGENTS.md
@@ -0,0 +1,26 @@
+# Firstleg Service 模块指引
+
+## 职责边界
+
+- 负责订单提交后的国内头程履约任务、操作分配和分配历史。
+- 订单主单、商户草稿和交易状态属于 `order/`；不要把订单模型复制进本服务。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用入口 | `src/main/java/com/baiyue/firstleg/BaiyueFirstlegApplication.java` |
+| 平台履约分配 API | `controller/PlatformFulfillmentAssignmentController.java`（`/api/platform/v1/first-leg/tasks`） |
+| 服务状态 | `controller/FirstlegHealthController.java` |
+| 分配请求 | `dto/AssignRequest.java` |
+| 履约与分配编排 | `service/FulfillmentTaskService.java` |
+| 任务与历史持久化 | `entity/`、`mapper/`、`repository/FulfillmentTaskRepository.java` |
+| 表结构 | `src/main/resources/db/firstleg.sql` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/firstleg-service.yml` |
+
+## 修改与验证
+
+- 任务状态与订单状态保持领域分离；需要联动时使用稳定 DTO 或事件，不共享 Order Entity 或数据库。
+- 分配操作要保留历史、操作者、时间和幂等语义；平台端接口必须执行权限校验。
+- 当前模块没有专属自动化测试时，不要为小改动擅自引入新框架；至少运行模块构建并记录接口验证。
+- 从父目录运行 `mvn -pl firstleg -am test`。
diff --git a/gateway/AGENTS.md b/gateway/AGENTS.md
new file mode 100644
index 000000000..8a6d0162d
--- /dev/null
+++ b/gateway/AGENTS.md
@@ -0,0 +1,28 @@
+# Gateway 模块指引
+
+## 职责边界
+
+- 统一承接前端流量，负责服务路由、CORS、JWT/Redis 会话校验、商户端与平台端访问域隔离及 Swagger 聚合。
+- 网关完成入口认证，但业务服务仍必须执行租户、数据范围和权限校验；业务编排不得写入网关。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用入口 | `src/main/java/com/baiyue/gateway/BaiyueGatewayApplication.java` |
+| Security WebFilterChain | `config/GatewaySecurityConfig.java` |
+| 商户/平台访问域 | `config/AppScopeAuthorizationManager.java` |
+| JWT 与安全配置项 | `config/GatewaySecurityProperties.java` |
+| Redis 会话过滤 | `config/RedisTokenSessionWebFilter.java` |
+| CORS | `config/GatewayCorsConfiguration.java`、`GatewayCorsProperties.java` |
+| 可信身份头清理/注入 | `filter/TrustedIdentityHeaderFilter.java` |
+| 本地路由 | `src/main/resources/application.yml` |
+| 国内环境与 Swagger 聚合 | `src/main/resources/application-cn.yml`、`../config/nacos/{local,cn}/gateway.yml` |
+| 访问域与 CORS 测试 | `src/test/java/com/baiyue/gateway/config/` |
+
+## 修改与验证
+
+- 新增服务路由时同步检查本地与 Nacos 配置、访问域、公开路径和 Swagger 聚合；前端只访问网关。
+- 禁止信任客户端自行传入的身份头；Token Claim、Redis Key 变化要与 `auth/`、`common-security/` 同步。
+- CORS 生产来源必须为明确 HTTPS 域名，不能放宽为 `*`。
+- 从父目录运行 `mvn -pl gateway -am test`。
diff --git a/iam/AGENTS.md b/iam/AGENTS.md
new file mode 100644
index 000000000..c88be2c4c
--- /dev/null
+++ b/iam/AGENTS.md
@@ -0,0 +1,30 @@
+# IAM Service 模块指引
+
+## 职责边界
+
+- 负责租户、用户、成员关系、企业资料与审核、角色、权限、数据范围、个人资料和授权快照。
+- 账号凭据与 Token 属于 `auth/`；资质文件内容属于 `file/`。IAM 只维护业务元数据和跨服务协作。
+
+## 功能快速索引
+
+| 功能 | Controller | Service / 数据入口 |
+|---|---|---|
+| 商户个人与企业资料 | `controller/MerchantTenantController.java` | `PersonalProfileService.java`、`TenantService.java` |
+| 商户成员增改、启停、重置密码 | `MerchantTenantController.java` | `MemberService.java`，账号协作看 `client/AuthAccountClient.java` |
+| 平台创建企业与入驻审核 | `controller/PlatformTenantController.java` | `MerchantOnboardingService.java`、`TenantService.java` |
+| 平台内部用户、企业地址与资质元数据 | `controller/ProfileResourceController.java` | `ProfileResourceService.java`、`ProfileResourceRepository.java` |
+| 角色、权限、成员角色、角色授权 | `controller/RbacController.java` | `RbacService.java`、`RbacRepository.java` |
+| Auth/Order 内部授权与资格查询 | `InternalAuthorizationController.java`、`InternalTenantController.java` | `AuthorizationSnapshotService.java`、`TenantGuard.java` |
+| DTO | `src/main/java/com/baiyue/iam/dto/` | 按 Authorization、Member、Onboarding、Profile、Rbac、Tenant 分类 |
+| 持久化 | `entity/`、`mapper/`、`repository/` | 租户、成员、角色、权限、地址、资质与审核模型 |
+| 数据库 | `src/main/resources/db/` | 主结构 `iam.sql`，一期与 RBAC 增量脚本同目录 |
+| OpenAPI 与说明 | `src/main/resources/openapi/iam-v1.yaml`、`README-IAM.md` | 修改接口契约时同步更新 |
+| 测试 | `src/test/java/com/baiyue/iam/` | Controller 路由、授权快照、成员、资料和 RBAC 测试 |
+
+## 修改与验证
+
+- `tenant_id` 是商户数据隔离核心；平台端与商户端访问域、角色和权限不可混用。
+- 按钮隐藏不能代替后端 permission code / permissionIds 校验；权限快照变化需同步检查 Auth 与 Gateway Claim 消费。
+- 成员账号操作跨 IAM/Auth，保持幂等与补偿；资质上传跨 IAM/File，IAM 不保存文件内容。
+- SQL 增量保持可重复部署顺序，修改 Entity 时同步检查 Mapper、Repository、DTO 与种子数据。
+- 从父目录运行 `mvn -pl iam -am test`，再按影响执行一期认证/IAM API 回归。
diff --git a/integration-service/AGENTS.md b/integration-service/AGENTS.md
new file mode 100644
index 000000000..49d6b752d
--- /dev/null
+++ b/integration-service/AGENTS.md
@@ -0,0 +1,28 @@
+# Integration Service 模块指引
+
+## 职责边界
+
+- 集中承载百度 OCR、Amazon Logistics/SP-API 等第三方适配器和能力启停状态。
+- 不保存业务主数据，不把第三方 DTO 泄漏为内部领域模型；真实外部调用默认关闭，密钥仅从安全配置注入。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用与配置扫描 | `src/main/java/com/baiyue/integration/IntegrationServiceApplication.java` |
+| `baiyue.integration` 配置 | `config/IntegrationProperties.java` |
+| 内部供应商状态 API | `controller/IntegrationProviderController.java` |
+| 能力状态模型与服务 | `dto/ProviderStatus.java`、`service/ProviderStatusService.java` |
+| 适配器抽象 | `provider/IntegrationProviderAdapter.java` |
+| 百度 OCR | `provider/BaiduOcrAdapter.java` |
+| Amazon | `provider/AmazonLogisticsAdapter.java` |
+| 内部服务令牌 | `security/InternalServiceTokenGuard.java` |
+| 配置测试 | `src/test/java/com/baiyue/integration/config/IntegrationPropertiesTest.java` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/integration-service.yml` |
+
+## 修改与验证
+
+- 第三方密钥、Token、请求原文和客户敏感数据不得写入源码或日志；配置应支持按供应商独立关闭。
+- 适配器负责外部协议转换、超时、错误归一化和安全降级；业务编排留在调用方服务。
+- 启用真实调用前补齐超时、重试边界、限流、幂等和可观测性，并避免在测试中访问真实供应商。
+- 从父目录运行 `mvn -pl integration-service -am test`。
diff --git a/order/AGENTS.md b/order/AGENTS.md
new file mode 100644
index 000000000..ea6ed86ba
--- /dev/null
+++ b/order/AGENTS.md
@@ -0,0 +1,31 @@
+# Order Service 模块指引
+
+## 职责边界
+
+- 负责头程订单主数据、草稿、提交、平台处理状态、货物、参与方快照、状态历史、内部备注和 Outbox。
+- 履约作业与分配属于 `firstleg/`；仓库和往来单位主数据属于 `warehouse/`；订单只保存必要业务快照。
+
+## 功能快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 商户订单创建、编辑、列表、详情、提交、取消 | `controller/MerchantFirstLegOrderController.java` |
+| 平台订单列表、详情、审核、接单、开始、完成、取消 | `controller/PlatformFirstLegOrderController.java` |
+| 内部备注与快递信息 | `PlatformFirstLegOrderController.java` |
+| 核心编排与状态机 | `service/OrderApplicationService.java`、`entity/OrderStatus.java` |
+| 企业下单资格 | `service/OrderEligibilityGuard.java`、`client/TenantEligibilityClient.java` |
+| 仓库/往来单位有效性 | `service/OrderMasterDataGuard.java`、`client/WarehouseClient.java`、`PartnerClient.java` |
+| 租户与访问范围 | `service/OrderScopeGuard.java` |
+| 请求与详情响应 | `dto/OrderRequests.java`、`OrderDetailResponse.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/` |
+
+## 修改与验证
+
+- 所有商户查询和写入必须执行租户/访问范围校验；平台操作必须验证权限及合法状态迁移。
+- 已提交订单中的仓库、往来单位等快照不能随主数据修改而变化。
+- 跨服务只通过 `client/` 或事件演进，不跨库查询 IAM/Warehouse；跨域通知优先使用 Outbox。
+- 新增状态或动作时同步修改 Controller、Service 状态机、历史记录、DTO、SQL、前端消费者和测试。
+- 从父目录运行 `mvn -pl order -am test`，再运行 `scripts/order-warehouse-real-api-regression.ps1` 或对应一期回归。
diff --git a/platform-bom/AGENTS.md b/platform-bom/AGENTS.md
new file mode 100644
index 000000000..052a3daa0
--- /dev/null
+++ b/platform-bom/AGENTS.md
@@ -0,0 +1,20 @@
+# Platform BOM 模块指引
+
+## 职责边界
+
+- 本模块只通过 `pom.xml` 的 `dependencyManagement` 发布 `baiyue-platform-bom`，统一管理本仓公共制品版本。
+- 不在这里放 Java 业务代码、服务配置或具体依赖实现；第三方技术栈版本仍优先由父 `pom.xml` 管理。
+
+## 快速索引
+
+| 修改目标 | 文件位置 |
+|---|---|
+| BOM 坐标与版本 | `pom.xml` 顶部 `artifactId`、`version` |
+| 公共组件版本 | `pom.xml` 的 `dependencyManagement/dependencies` |
+| 当前纳管制品 | `baiyue-common-core`、`common-web`、`common-security`、`common-openapi`、`common-audit`、`common-event-contract` |
+
+## 修改与验证
+
+- 新增条目前先确认制品确实需要被其他仓库按固定版本消费；业务服务依赖不要放入 BOM。
+- 版本变化会影响所有 BOM 消费者，并可能需要尾程仓同步升级；保持已发布坐标兼容。
+- 从父目录运行 `mvn -pl platform-bom -am validate`。
diff --git a/print/AGENTS.md b/print/AGENTS.md
new file mode 100644
index 000000000..2129aaecb
--- /dev/null
+++ b/print/AGENTS.md
@@ -0,0 +1,21 @@
+# Print Service 模块指引
+
+## 职责边界
+
+- 本模块定义打印中心独立服务边界；当前只包含应用入口、状态接口、配置和数据库骨架。
+- 打印模板版本、任务状态机、PDF/标签生成、重试和幂等尚未完整实现；开始扩展前必须先核对阶段需求，不从原型自动扩大范围。
+
+## 快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 应用入口 | `src/main/java/com/baiyue/print/PrintServiceApplication.java` |
+| 当前状态 API | `controller/PrintHealthController.java`（`/api/platform/v1/print/status`） |
+| 数据库骨架 | `src/main/resources/db/print.sql` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/print-service.yml` |
+
+## 修改与验证
+
+- 订单服务只应提交打印请求，不自行生成面单或操作打印机；生成文件通过 File 服务引用。
+- 新增任务处理时设计明确的状态机、幂等键、失败重试、模板版本与权限边界。
+- 当前无专属测试时，不为小改动引入整套新测试框架；至少从父目录运行 `mvn -pl print -am test` 并记录接口验证。
diff --git a/warehouse/AGENTS.md b/warehouse/AGENTS.md
new file mode 100644
index 000000000..f709f5027
--- /dev/null
+++ b/warehouse/AGENTS.md
@@ -0,0 +1,29 @@
+# Warehouse Service 模块指引
+
+## 职责边界
+
+- 负责国内收货仓、仓库地址、服务能力、启停校验和往来单位主数据。
+- 往来单位保存在 `baiyue_warehouse.wh_partner`，不是独立服务；订单只通过内部接口校验并保存快照。
+
+## 功能快速索引
+
+| 功能 | 入口 |
+|---|---|
+| 商户可用仓库列表与详情 | `controller/MerchantWarehouseController.java` |
+| 平台仓库增改查与启停 | `controller/PlatformWarehouseController.java` |
+| 内部仓库有效性校验 | `controller/InternalWarehouseController.java` |
+| 商户往来单位候选与详情 | `controller/MerchantPartnerController.java` |
+| 内部往来单位有效性校验 | `controller/InternalPartnerController.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` |
+| 测试 | `src/test/java/com/baiyue/warehouse/` |
+
+## 修改与验证
+
+- 商户只看到可用且符合租户/服务范围的数据；平台启停必须检查业务约束，不能只改状态字段。
+- 往来单位与仓库查询供 Order 使用，DTO 或有效性语义变化需同步检查 `order/client/` 和订单快照逻辑。
+- 数据表、Entity、Mapper、Repository 与种子数据必须同步；历史订单不随主数据更新。
+- 从父目录运行 `mvn -pl warehouse -am test`，再运行 `scripts/order-warehouse-real-api-regression.ps1`。