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/	全局异常与请求链路标识	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、事件或公共组件时同步检查所有生产者与消费者；优先保持兼容，不能兼容时写清迁移顺序。
• 密码、令牌、第三方密钥和真实客户数据只能通过环境变量或配置中心密文注入。