优化

AGENTS.md

@@ -26,6 +26,7 @@
 | 分柜、柜次、智能排柜、预装/装柜清单、PDA | `firstleg/` | `firstleg/AGENTS.md`，再按 `split/`、`loading/`、`outbound/` 定位 |
 | 订舱、船期、拖车、报关 | `firstleg/` | `oceanbooking/`、`portschedule/`、`outbound/dispatch/`、`customs/` |
 | 客户账期、费用池、账单、收款、成本、核销 | `finance/` | `finance/AGENTS.md`；费用来源和柜次成本快照再联查 `firstleg/AGENTS.md`，凭证再联查 `file/AGENTS.md` |
+| 入库/柜次应付、直接已付、付款流水与凭证 | `firstleg/`、`finance/`、`file/` | 业务费用与付款快照见 `firstleg/AGENTS.md` 的 `FeePaymentSnapshotValidator`；`/api/platform/finance/v1/vouchers` 上传凭证，File 按 `FINANCE_VOUCHER` 和客户范围校验 |
 | 仓库、往来单位、快递、托盘、库位 | `warehouse/` | `warehouse/AGENTS.md` |
 | 供应商、国内整柜库存与出入库 | `warehouse/` | `warehouse/AGENTS.md`；OpenAPI `warehouse/src/main/resources/openapi/supplier-v1.yaml`、`domestic-container-v1.yaml` |
 | 客户运营统计、在途柜量 | `firstleg/` | `firstleg/AGENTS.md`；OpenAPI `firstleg/src/main/resources/openapi/customer-statistics-v1.yaml` |
@@ -35,8 +36,21 @@
 | 百度/Amazon/OCR/第三方适配 | `integration-service/` | `integration-service/AGENTS.md` |
 | 海外 API 路由、海外 Token、Audience/JWKS | `gateway-overseas/` | `gateway-overseas/AGENTS.md` |
 | 尾程订单、海外入仓计划、换标、库存、采购、本土卡车 | `lastleg-service/` | `lastleg-service/AGENTS.md`，再按 `inboundplan/`、`relabel/`、`inventory/`、`procurement/`、`trucking/` 定位 |
+| 海外入仓分页、FBA 预约、PDA 卸柜照片 | `lastleg-service/` | `inboundplan/controller/InboundPlanController.java`、`InboundPlanQueryMapper.java`、`InboundFbaAppointmentService.java`、`inboundplan/pda/` |
 | 海外仓库、海外库位、海外托盘、资源锁 | `warehouse-overseas-service/` | `warehouse-overseas-service/AGENTS.md` |
-| PDF 标签、审计、事件 | `print/`、`audit-service/`、`event-bridge-service/` | 各服务指引 |
+| PDF 标签、审计、跨区双向事件 | `print/`、`audit-service/`、`event-bridge-service/` | 事件模型先读 `common-event-contract/AGENTS.md`；可靠投递与 CN/OVERSEAS 目标路由读 `event-bridge-service/AGENTS.md` |
+
+## 公共模块快速索引
+
+| 关键词 | 模块与入口 |
+|---|---|
+| 公共依赖版本 | `platform-bom/pom.xml`；统一管理公共组件版本，不放业务实现 |
+| 通用响应、分页、异常、基础实体与导出契约 | `common-core/`；从 `ApiResponse.java`、`PageResult.java`、`BizException.java`、`ExportContracts.java` 定位 |
+| Web 异常、请求关联 ID、Long ID 序列化 | `common-web/`；从 `GlobalExceptionHandler.java`、`CorrelationIdFilter.java`、`LongIdJacksonConfiguration.java` 定位 |
+| JWT、JWKS、会话校验与认证用户 | `common-security/`；从 `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java`、`AccessTokenSessionValidator.java` 定位 |
+| Springdoc/OpenAPI 自动配置 | `common-openapi/`；从 `BaiyueOpenApiAutoConfiguration.java`、`OpenApiProperties.java` 定位 |
+| 业务审计注解、脱敏、Outbox 与投递 | `common-audit/`；从 `BusinessAudit.java`、`BusinessAuditAspect.java`、`SensitiveDataSanitizer.java`、`AuditOutboxPublisher.java` 定位 |
+| 跨区域事件信封、Payload 与哈希 | `common-event-contract/`；继续读该目录 `AGENTS.md` |
 
 ## 全量验收路由
 
@@ -60,6 +74,7 @@
 - 数据库只访问所属服务库。模块表结构位于 `<module>/src/main/resources/db/`；当前开发阶段直接更新最新模块基线和 `deploy/sql/头程数据库统一增量-MySQL8.sql`，不为历史开发数据新增兼容迁移。已有名称含 `migration` 的脚本仅作现有结构来源和开发追溯，部署说明见 `deploy/sql/README.md`。
 - 通用配置在 `config/nacos/{local,cn}/`；服务日志、上传文件、`target/`、`reports/` 不属于源码。
 - Java 签名变更的最低编译门禁是 `mvn -pl <module> -am test-compile`，它必须在部署前完成并覆盖测试源码；有行为变化时继续运行 `mvn -pl <module> -am test`。`-DskipTests` 可跳过测试执行但仍须保留测试编译，`-Dmaven.test.skip=true` 会跳过测试编译，不得作为签名变更的交付验证。全量验证仍使用 `mvn -DskipTests validate`、`mvn test`；不要在本地启动 Java/Nacos/数据库，除非用户明确要求。
+- `AGENTS.md` 索引维护完成后运行 `./scripts/agents-index-contract.ps1`；脚本只读源码目录和指定指引，验证部署单元、模块覆盖、关键入口与排除目录，不访问 HTTP、数据库或部署环境。
 
 ## 全量 HTTP 验收脚本路由