baiyue-firstleg/AGENTS.md

柏悦头程后端项目指引

适用范围

• 本文件适用于 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/	全局异常、请求链路标识、长整型 JSON 字符串序列化	GlobalExceptionHandler.java、CorrelationIdFilter.java、LongIdJacksonConfiguration.java
common-security/	JWT、Redis 会话校验、认证上下文、401/403	JwtAuthenticationFilter.java、RedisAccessTokenSessionValidator.java
common-openapi/	SpringDoc 自动配置与长整型字符串契约	BaiyueOpenApiAutoConfiguration.java、OpenApiProperties.java
common-audit/	审计注解、切面、脱敏与日志/HTTP 发送	BusinessAuditAspect.java、SensitiveDataSanitizer.java、HttpAuditSink.java
common-event-contract/	跨区域事件信封、类型、标识、哈希与校验	EventEnvelope.java、EventTypes.java、EventEnvelopeValidator.java
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、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；启动时校验存储目录，磁盘故障返回 S0503，元数据表结构尚未接入
print/	打印中心边界	当前为应用、健康检查和 print/src/main/resources/db/print.sql 骨架
audit-service/	审计事件接收与持久化	AuditIngestController.java、AuditIngestService.java；当前接收接口未实现内部令牌保护
integration-service/	重量 OCR、百度 OCR、Amazon 等第三方适配	controller/WeightOcrController.java、service/ocr/、provider/ocr/、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。
• CREATE TABLE IF NOT EXISTS 不会升级既有表；新增字段或索引时必须同时提供可重复执行的增量迁移，并在部署清单中写明执行顺序。
• 服务间调用先找调用方 client/；跨区域数据只使用 common-event-contract/ 和事件桥，不共享领域 Entity。
• 本地运行看 docs/local-runtime.md；接口联调看 docs/phase1-local-api.md；回归入口在 scripts/，历史资质文件迁移使用 scripts/migrate-local-qualification-file.ps1。
• 平台管理与头程履约补齐的本地数据库只读核验、SQL 清单和回归结果见 docs/2026-07-31平台管理与头程履约补齐回归报告.md。
• 本轮测试环境数据库增量统一从 deploy/sql/2026-07-31一期回归测试环境增量迁移.sql 执行，执行边界与核验方式见 deploy/sql/README.md。
• 从本目录运行全量校验：mvn -DskipTests validate、mvn test。单模块修改优先运行 mvn -pl <module> -am test。
• reports/、target/、日志、上传文件和本地环境文件不属于源码，检索与提交时排除。

通用修改约束

• Controller 只做协议转换，Service 负责编排，Repository/Mapper 负责持久化；不要跨层堆放业务逻辑。
• 商户数据必须保留租户维度，并由服务端执行租户、访问域、数据范围和按钮权限校验。
• 修改 SQL、DTO、事件或公共组件时同步检查所有生产者与消费者；优先保持兼容，不能兼容时写清迁移顺序。
• 对外 HTTP JSON 中的 Java Long/long 统一输出字符串，请求同时接受字符串 ID；业务模块禁止重复添加局部 ID 转换器，OpenAPI 必须同步声明字符串契约。
• 密码、令牌、第三方密钥和真实客户数据只能通过环境变量或配置中心密文注入。