baiyue-firstleg/AGENTS.md

头程与海外仓后端项目指引

适用范围与定位

• 本文件适用于 baiyue-firstleg/ Maven 多模块仓库，包含国内头程与海外区域服务；进入具体服务后继续读取该服务的 AGENTS.md。
• 本层只负责：服务边界、跨服务契约、数据库部署总入口、阶段路由和通用验证。Controller、Service、DTO、SQL 细节以模块级指引为准。
• 普通任务先读本文件和目标模块指引；聚合构建/架构问题再读 README.md、pom.xml、docs/头程项目目录结构与服务说明.md。
• 平台/客户层级与权限公共语义见 ../docs/平台客户层级与权限契约.md；国内/海外 Token、双区域 API 和跨区事件公共契约见 ../docs/跨区域认证与服务通信契约.md。本文件只保留后端执行所需摘要。

不可突破的产品与数据边界

• 当前产品只有“平台—客户”两级。tenant_id=0 是平台技术作用域；tenant_id>0 是客户隔离键，不得新增租户切换、租户选择或租户级 RBAC。
• 公共仓库、往来单位、快递、托盘、库位统一归属 tenant_id=0；订单、文件、费用等客户数据按客户 tenant_id>0 隔离。不得跨库 Join 或信任客户端客户 ID。
• 国内订单交易状态归 order，头程履约/入库状态归 firstleg，财务账期、账单、收款、成本与核销归 finance；全部仓库 ID、类型、状态、地址和能力主档归国内 warehouse，海外 warehouse-overseas-service 只维护引用同一国内 warehouseId 的库位、托盘和资源锁。海外尾程订单、入仓计划、库存业务与海外本土业务归 lastleg-service，海外公网入口归 gateway-overseas。文件对象归 file，第三方适配归 integration-service；跨服务通过内部客户端、DTO、事件和服务令牌协作。
• 普通业务成功/失败使用 HTTP 200 + body code（成功为字符串 "200"）；认证、基础设施和网关拒绝可使用真实 401/403/503。

服务路由（按关键词定位）

任务关键词	首选服务	先看入口
登录、Token、密码、注册	auth/	auth/AGENTS.md
客户档案、成员、审核、RBAC、授权快照	iam/	iam/AGENTS.md
客户建档默认尺寸初始化与补偿	iam/、firstleg/	IAM CustomerDimensionRuleInitializationService 持久化意图、CustomerDimensionInitializationRelay 后台投递；Firstleg 内部入口 /internal/firstleg/v1/customer-dimension-configs/defaults，未 READY 不得审核通过
消息中心、站内通知、消息模板、收件箱	iam/	iam/AGENTS.md，再按 src/main/java/com/baiyue/iam/notification/ 定位；业务事件生产者回到所属服务
订单、货物、快照、状态、幂等、Outbox	order/	order/AGENTS.md
履约分配、入库、测量、审核、FBA 计费	firstleg/	firstleg/AGENTS.md
Firstleg 内部模块化与依赖基线	firstleg/	firstleg/docs/firstleg-internal-modularization-baseline.md、firstleg/scripts/analyze-firstleg-dependencies.mjs；价格簿查询和客户统计按端口/适配器切片，不改变服务与数据库边界
Mapper 新增、移动、Bean 缺失与扫描遗漏	目标持久化服务	所有 Mapper 显式 @Mapper，启动类按服务根包注解过滤扫描；先运行 node scripts/mapper-scan-contract.mjs，再按目标模块执行 test-compile/test，不得等部署启动发现
分柜、柜次、智能排柜、预装/装柜清单、PDA	firstleg/	firstleg/AGENTS.md，再按 split/、loading/、outbound/ 定位；预装/正式装柜详情阶段由 /loading-plans/{planId}/lifecycle 按稳定 planId 解析，不从 404 或文案推断
合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除	firstleg/	loading/coload/controller/PlatformColoadGroupController.java、service/ColoadGroupService.java、persistence/ColoadGroupMapper.java、src/main/resources/openapi/coload-groups-v1.yaml；按订单建组并冻结全部可用入仓片段，仅要求同国内仓、同渠道
智能装柜入仓码候选与箱数分配	firstleg/	controller/PlatformSmartLoadingController.java 的 /inbound-candidates、/plans/{planId}/inbound-assignments，业务编排 service/SmartLoadingService.java
订舱、船期、拖车、报关	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
平台操作日志与审计查询	audit-service/	audit-service/AGENTS.md；平台查询接口 /api/platform/v1/audit/logs
资质、导出、测量图片、文件下载	file/	file/AGENTS.md
路由、CORS、JWT 入口、访问域	gateway/	gateway/AGENTS.md
百度/Amazon/OCR/第三方适配	integration-service/	integration-service/AGENTS.md
海外 API 路由、海外 Token、Audience/JWKS	gateway-overseas/	gateway-overseas/AGENTS.md
海外 IAM 状态与权限版本投影	lastleg-service/security/	lastleg-service/AGENTS.md；内部入口 /internal/lastleg/security/v1/events、/validate；消费三类 IAM 安全事件并为海外 Gateway 提供 fail-closed 校验，投影表归 baiyue_lastleg
尾程订单、海外入仓计划、换标、库存、采购、本土卡车	lastleg-service/	lastleg-service/AGENTS.md，再按 inboundplan/、relabel/、inventory/、procurement/、trucking/ 定位
柜级入仓计划进度与整柜转换	lastleg-service/	orders/container-summaries 按 sourceContainerBookingId 跨客户聚合全柜进度与 allPlansReady，详情返回柜内全部订单/入仓码/计划且不受订单分页截断；plannedArrivalAt 只取装柜完成事件 estimatedWarehouseArrivalAt 冻结事实；inbound-plans/convert-container 锁定同柜订单，每票生成独立计划，整批原子且幂等
海外入仓分页、FBA 预约、PDA 柜号签收与入仓	lastleg-service/	平台入口 inboundplan/controller/InboundPlanController.java、InboundPlanQueryMapper.java、InboundFbaAppointmentService.java；PDA 公网入口 inboundplan/pda/controller/ReceivingContainerController.java、ReceivingContainerService.java，旧 planNo/allocationId Controller 已移除
海外仓排车查询、候选与智能预排	lastleg-service/	dispatch/controller/DispatchQueryController.java、SmartDispatchController.java；草稿柜、托盘锁和预排归 dispatch/，只读排车和预排创建独立开关，不自动开放编辑、取消、发车、PDA 出库或派送
客户海外仓贴标、转运、废弃与退货换标	lastleg-service/	relabel/、transfer/、discard/ 的 Merchant Controller/Service；Client 消费端 ../apps/client-web/src/modules/overseas-warehouse/，统一经 gateway-overseas/
海外仓 PDA 盘点、移库、托盘、换标与查询	lastleg-service/、warehouse-overseas-service/	Lastleg pda/stocktake/、pda/move/、pda/warehouse/、palletops/、relabel/pda/；契约 lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml；物理托盘流转与补偿进入 Warehouse InternalPdaPalletTransitionController，设备端入口是否开放以 ../apps/pda-overseas-uniapp/AGENTS.md 为准
国内船节点向海外接柜门禁事件	firstleg/、common-event-contract/、lastleg-service/	Firstleg portschedule/service/CarrierScheduleNodeOutboxService.java 发布 FirstLegContainerShippingNodeRecordedV1；Lastleg shipping/service/ContainerShippingNodeConsumer.java 单调消费，只有实际 PICKUP_READY 及以后节点允许海外 PDA 候选进入可收货
海外仓库目录、海外库位、海外托盘、资源锁	国内仓库目录归 warehouse/，海外资源归 warehouse-overseas-service/	warehouse/AGENTS.md、warehouse-overseas-service/AGENTS.md；海外库只保存国内 warehouseId 引用
Lastleg 内部模块化与依赖基线	lastleg-service/	lastleg-service/docs/lastleg-internal-modularization-baseline.md、lastleg-service/scripts/analyze-lastleg-dependencies.mjs；只用于约束服务内部依赖，不改变服务和数据库边界
PDF 标签、审计、跨区双向事件	print/、audit-service/、event-bridge-service/	事件模型先读 common-event-contract/AGENTS.md；国内真实生产验收 firstleg/.../TaillegRealProducerAcceptanceTest.java、海外真实消费验收 lastleg-service/.../TaillegRealConsumerAcceptanceTest.java；可靠投递与 CN/OVERSEAS 目标路由读 event-bridge-service/AGENTS.md

公共模块快速索引

关键词	模块与入口
公共依赖版本	platform-bom/pom.xml；统一管理公共组件版本，不放业务实现
通用响应、分页、异常、基础实体与导出契约	common-core/；从 ApiResponse.java、PageResult.java、BizException.java、ExportContracts.java 定位
Web 异常、请求关联/Trace、同步出站传播、Long ID 序列化	common-web/；从 GlobalExceptionHandler.java、CorrelationIdFilter.java、TraceParent.java、FeignTraceRequestInterceptor.java、RestClientTraceInterceptor.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

全量验收路由

• 当前一期、二期、三期及财务统一进入全量验收；按本次链路读取对应阶段/专题文档，不以历史阶段终点阻断跨服务联调或回归。
• auth、iam、warehouse、order、firstleg、file、finance、integration-service 及出仓相关能力按各自模块契约协作；状态、权限、数据库和 OpenAPI 以当前实现及已确认契约为准。

国内头程与海外仓协同

• 国内头程 Auth 是唯一用户账号和 Token 签发方；Admin/Client 共用一套前端和用户体系，海外仓不得另建登录或权限模型。
• 统一使用 RS256/JWKS。国内登录/刷新时由 Auth 同时签发国内 Token 和短时海外 Token；前端统一认证层按国内/海外 API Base 自动选择。国内服务叠加 Redis 会话校验，海外服务不得访问国内 Redis，只按限定 Audience 的海外 Token Claims 完成本地认证和授权；海外业务请求不得经国内 Gateway 中转。
• 头程装柜完成向海外建尾程单、海外 PDA 卸柜完成向国内回写货柜报空事实，以及后续费用来源和财务回传，统一走 MQ Outbox/Inbox 事件链；事件不携带用户 JWT，服务身份由 MQ TLS/ACL 或内部服务令牌负责。跨区事件契约、幂等和死信分别查 common-event-contract/、event-bridge-service/ 与目标消费者。
• 海外浏览器请求只进入 gateway-overseas/，由其路由到 lastleg-service/、warehouse-overseas-service/ 及海外部署的公共服务；不得经国内 gateway/ 中转。lastleg-service 不读取头程数据库，warehouse-overseas-service 不读取尾程订单库。

契约、数据库与验证入口

• 跨服务修改先检查调用方 client/、被调用方 Controller/DTO、src/main/resources/openapi/ 和双方契约测试；禁止共享领域 Entity。
• 修改 Java 方法、构造器、Controller、Client、DTO 或 Mapper 参数签名时，先用 rg 定向查找符号及旧参数形态，并同步更新 src/main/、src/test/、Mock、Fixture、契约测试和脚本中的全部调用点。新增可选参数也必须补齐旧测试调用，不能因生产调用已更新就视为完成。
• 所有生产 MyBatis Mapper 接口必须显式标记 @Mapper；每个持久化服务只允许在启动类使用一次服务根包 @MapperScan(..., annotationClass = Mapper.class)，不得新增子域包白名单或分散的 *MapperConfiguration。新增或移动 Mapper 后先运行 node scripts/mapper-scan-contract.mjs，全量后端回归也会在 Maven 前执行该门禁。
• 平台后台存在正式列表页时，*:list 同时授权列表、详情及只读辅助接口；create、edit、delete、status、approve、review、export、upload、complete 等操作保持独立。当前未上线，不兼容旧独立 *:view，Controller 不得使用 hasAnyAuthority(list, view)，OpenAPI 和角色初始化只保留 *:list。
• 供应商查询接口固定只使用 platform:supplier:list；IAM 中 platform:supplier:list 是正式菜单资源，platform:supplier:view 必须停用/移除，不得重新提升或兼容。
• 权限语义变更必须同步 Controller @PreAuthorize、OpenAPI、模块权限 SQL、IAM 菜单资源、统一增量脚本和契约测试。并行模块任务不得覆盖菜单与权限总控已写入共享 SQL 或权限契约的改动。
• 数据库只访问所属服务库。模块表结构位于 <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；脚本只读源码目录和指定指引，验证根快速表唯一性、部署单元、Client active 路由、四期范围漂移、仓库主档唯一权威、订舱关联候选与柜量语义、整柜出仓与船节点单调性、海外 Gateway 覆盖、PDA 运行配置/独立更新/语言预留、人工分段验收链、Lastleg 海外安全投影、同步 Trace、模块覆盖、关键入口与排除目录，不访问 HTTP、数据库或部署环境。
• Mapper 注册静态合同为 scripts/mapper-scan-contract.mjs、mapper-scan-contract.test.mjs：自动发现聚合模块、生产 *Mapper 接口、服务启动类和分散扫描配置，不启动 Spring、不连接数据库；遗漏注解、扫描根漂移或重新引入子域扫描时直接失败并输出类与文件路径。
• 单服务镜像构建/部署从 Jenkinsfile.service、deploy/docker/Dockerfile、deploy/scripts/deploy-built-service.sh 进入；新镜像启动失败或健康检查失败时只允许回滚到同服务先前镜像，并保持任务失败，离线合同见 scripts/deploy-built-service-rollback.test.mjs。实际部署仍须当前对话明确授权。

全量 HTTP 验收脚本路由

• 全量验收唯一指向测试环境 HTTP：平台端执行 scripts/admin-test-env-acceptance.mjs，客户端执行 scripts/client-test-env-acceptance.mjs；二期专项场景才单独执行 scripts/client-phase2-test-env-acceptance.mjs，不替代客户端全量入口。
• Admin 总入口默认按模块列表覆盖平台全链路；需要定位单个业务时使用 --modules <name>，模块名称和静态合同先查 scripts/admin-test-env-modules/README.md。
• 这些脚本会创建、更新或最终停用测试数据，必须在当前对话明确授权测试环境验收后执行，并保存 JSON 报告；未授权不得请求 Gateway。
• 后端 Maven、前端 pnpm test/typecheck、PDA node --test 和数据库 Dry-run 都是本地质量检查，不属于全量 HTTP 验收。
• Java 模块、OpenAPI 覆盖、JaCoCo 与 SpotBugs 聚合摘要使用 node scripts/java-quality-summary.mjs；默认仅报告存量缺口，是否阻断由显式 --require-* 参数决定，输出位于 target/ 时不得作为业务事实或提交物。
• HTTP 全量通过后，才进入 Admin/Client 真实页面调用、浏览器样式和 PDA 页面/设备验收；自动化 HTTP 通过不代表视觉验收完成。

阶段文档入口

• 一期：../docs/一期/README.md、../docs/一期/一期头程订单闭环设计.md
• 二期：../docs/二期/README.md、../docs/二期/二期需求优化版-v2-测量计费入库主流程.md、需求确认清单及联调报告
• 三期：../docs/三期/README.md、../docs/三期/三期开工门禁.md、../docs/三期/三期开发规划.md、../docs/三期/三期需求确认表.md、页面与原型清单
• 四期：../docs/四期/README.md；海外入口 gateway-overseas/，尾程与入仓库存 lastleg-service/，海外仓储资源 warehouse-overseas-service/
• 财务：../docs/财务管理/README.md 中已确认的范围、对象、状态和接口约束

全量验收任务再读取对应阶段进度表、验收报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。