baiyue-firstleg/AGENTS.md

柏悦头程后端项目指引

适用范围

• 本文件适用于 baiyue-firstleg/ 整个 Maven 多模块仓库；进入子模块后同时遵守该模块的 AGENTS.md。
• 开始修改前先读根目录 README.md、pom.xml 和 docs/头程项目目录结构与服务说明.md；业务边界以本文件及该说明的“项目定位、主要调用关系、开发和拆分约束”为准。
• 本仓只承载国内头程业务。尾程源码、数据库、Redis、Nacos 和内部接口不得并入本仓。

模块快速索引

模块	职责	首选入口
platform-bom/	公共制品版本清单	pom.xml 的 dependencyManagement
common-core/	返回模型、错误码、基础实体、MyBatis 配置	ApiResponse.java、ResultCode.java、exception/、model/、mybatis/；成功码为字符串 "200"
common-web/	HTTP 200 业务响应、全局异常、请求链路标识、长整型 JSON 字符串序列化	CommonWebAutoConfiguration.java、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/CorrelationIdWebFilter.java、src/main/resources/application*.yml
auth/	登录、令牌、注册、账号、密码与账号归属范围	InternalAccountController.java、AccountManagementService.java、AccountManagementDtos.java、src/main/resources/db/
iam/	租户、商户成员、平台统一用户管理、企业资料/资质、RBAC 与授权快照	PlatformUserManagementController.java、PlatformTenantController.java、ProfileResourceController.java、RbacController.java
order/	订单主数据、租户运单数、持久化幂等、状态编排、快照与 Outbox	PlatformFirstLegOrderController.java、OrderApplicationService.java、TenantOrderCountResponse.java、README-ORDER.md
firstleg/	履约任务分页/详情、操作分配与分配历史	PlatformFulfillmentAssignmentController.java、FulfillmentTaskService.java、src/main/resources/db/phase1-firstleg-task-list-index.sql
warehouse/	仓库、地址、服务能力、往来单位多类型、快递公司与 XLSX 导入	controller/、PlatformPartnerQueryService.java、PartnerImportService.java、ExpressCompanyImportService.java
file/	企业资质文件上传、替换、预览与鉴权	QualificationFileController.java、PlatformQualificationFileController.java、LocalQualificationStorage.java；元数据仍归 IAM，File 自身表结构尚未接入
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

高频业务检索入口

搜索目标	先读
后台用户管理、平台/企业账号、跨租户调动	iam/.../controller/PlatformUserManagementController.java → service/PlatformUserManagementService.java → auth/.../controller/InternalAccountController.java 的 scope 接口
企业客户档案、审核、必填资质	iam/.../controller/PlatformTenantController.java、service/TenantService.java、service/ProfileResourceService.java
客户列表真实运单数	order/.../controller/PlatformFirstLegOrderController.java 的 /tenant-counts；不要在 IAM 查订单表
平台代客户上传或替换资质	file/.../controller/PlatformQualificationFileController.java → client/IamQualificationClient.java → iam/.../controller/InternalTenantController.java 的 /platform-qualifications
往来单位多类型	warehouse/.../service/PlatformPartnerQueryService.java、entity/PartnerTypeEntity.java、src/main/resources/db/warehouse-partner.sql，消费者看 order/.../client/PartnerClient.java
往来单位/快递公司批量导入	warehouse/.../service/PartnerImportService.java、ExpressCompanyImportService.java、两个平台 Controller 的 /import-template 与 /import
HTTP 200、body code、成功码 "200"	docs/统一响应约定改造方案-HTTP200.md、common-core/ResultCode.java、common-web/GlobalExceptionHandler.java
单服务 Jenkins 构建或部署	总控 Jenkinsfile、子 Job Jenkinsfile.service、模块/JAR 映射 deploy/service-map.yml

配置、数据库与验证入口

• 服务本地配置在各模块 src/main/resources/application.yml；Nacos 环境配置集中在 config/nacos/local/ 和 config/nacos/cn/。
• 每个服务的文件日志和滚动策略也在自身 application.yml，统一通过 LOG_PATH 或 LOGGING_* 环境变量覆盖；容器宿主机挂载见 deploy/docker-compose.yml。
• 子模块索引中 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/数据库环境切换说明.md、scripts/local-env.ps1 与 config/nacos/local/；接口契约优先读目标模块 src/main/resources/openapi/ 和 Controller，回归入口在 scripts/，历史资质文件迁移使用 scripts/migrate-local-qualification-file.ps1。
• 平台管理与头程履约补齐的本地数据库只读核验、SQL 清单和回归结果见 docs/2026-07-31平台管理与头程履约补齐回归报告.md。
• IAM 授角、订单主数据、File、Gateway CORS 与文件日志的本轮结果见 docs/2026-07-31-P0-P2问题修复回归报告.md。
• 本轮测试环境数据库增量统一从 deploy/sql/2026-07-31一期回归测试环境增量迁移.sql 执行，执行边界与核验方式见 deploy/sql/README.md。
• CI 总控入口是 Jenkinsfile，负责按变更或勾选项并行调度 11 个独立服务 Job；单服务构建、镜像与部署逻辑在 Jenkinsfile.service。Job 名必须以模块名结尾，公共模块或 deploy/ 变化会触发全部服务。
• 从本目录运行全量校验：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 必须同步声明字符串契约。
• 普通业务成功与失败统一使用 HTTP 200，并以响应体字符串 code 判断；code == "200" 才成功。网关/Servlet Security 的真实 401/403、协议与基础设施错误、Warehouse readiness 503、Audit 202 和 Event Bridge 内部鉴权边界除外；完整约定见 docs/统一响应约定改造方案-HTTP200.md。
• 密码、令牌、第三方密钥和真实客户数据只能通过环境变量或配置中心密文注入。

本地内部服务令牌

• scripts/local-env.ps1 是本地运行时的统一环境入口，Order、Warehouse、IAM 等相互调用的服务必须从同一套 INTERNAL_SERVICE_TOKEN 启动。
• config/nacos/local/baiyue-common.yml 的本地默认令牌必须与该脚本一致；变更后执行 scripts/publish-local-nacos-config.ps1 发布并重启相关服务。