当前主体模型：业务单租户，产品只包含“平台—客户”两级。现有 tenant_id > 0、tenantId 和 Tenant* 是历史兼容命名，当前承载客户归属与隔离；tenant_id = 0 是平台账号、平台 RBAC 和平台公共主数据的技术作用域，不是可管理租户。平台公共仓库、往来单位、快递公司、托盘、库位等归属 0，客户订单、文件和费用归属客户 ID。未经过独立迁移设计，不得新增真实租户层或把现有客户隔离字段改义为上级租户。

模块

gateway：四端统一 API 入口。
finance：财务账单、费用、充值、授信与资金核销。
auth：统一登录、令牌签发与刷新。
iam：客户主档、用户、企业成员、角色、菜单、按钮权限和数据范围；部分路径、表和类保留 tenant 历史命名。
order：订单主数据及订单状态编排。
firstleg：头程揽收、入仓、装载、发运和交接。
warehouse：国内仓储能力。
file、print、audit-service、integration-service：国内公共业务能力；Print 调用方接入见 print/README.md。
lastleg-service、warehouse-overseas-service：海外尾程/入仓/出库/派送和海外仓储资源，统一会话鉴权。
common-*、common-event-contract：由本仓维护并以 com.baiyue.shared 发布的公共制品。
platform-bom：统一管理仓库内公共依赖版本。

本地构建

# 日常按受影响模块检查；跨服务变更显式列入消费者。
.\scripts\backend-check.ps1 -Modules order -Mode Compile
.\scripts\backend-check.ps1 -Modules order
# 根构建/拓扑变化等全量触发条件见 AGENTS.md。
.\scripts\local-check.ps1 -Command @('node', '--test', 'scripts/java-topology-contract.test.mjs')
.\scripts\backend-full-regression.ps1

开发中可通过 backend-check.ps1 -Mode Focused -Modules <模块> -Tests <精确测试类名> 快速反馈；参数、DryRun 和结果边界见后端分层检查。单服务修改收尾执行模块回归，不默认执行上面的全仓命令。

GitLab 在独立 Node 镜像中自动执行拓扑合同，随后才允许服务制品打包。Maven verify 会为执行过测试且产生覆盖率数据的模块生成 target/site/jacoco/index.html 与 jacoco.xml；当前只生成报告，不设置覆盖率阈值，也不改变测试选择。Jenkins 的 java-builder 尚未在仓库中声明 Node 运行时，因此暂不重复执行该 Node 合同，以 GitLab 门禁和上述本地命令为准。

2026-07-30 订单与客户前端联调缺口已完成真实回归：19 个 Reactor 项目构建成功，75 项单元及组件测试、68 项认证与 IAM 真实 API、37 项订单与仓库真实 API 全部通过。详细证据见 docs/phase1-business-maturity-regression-report.md。

唯一发布配置为 deploy/docker-compose.yml、deploy/env/.env.test.example 和 config/nacos/test/；所有保留服务共用实际 Namespace ID、Auth/Redis 会话和单机内部网络，各服务 Schema 保留。往来单位由 warehouse-service 承载并保存到 baiyue_warehouse.wh_partner。发布、健康检查和失败恢复见 deploy/TEST单机部署执行清单.md。真实凭据不得提交；本地编译不代表另有开发环境。

容器日志

所有服务只向标准输出和标准错误写日志，不在容器内生成应用日志文件，也不把应用日志目录挂载到宿主机。统一业务及基础设施 Compose 默认使用宝塔可见的 Docker json-file 日志驱动，并设置强制轮转；仍可通过 docker logs 排查。文件服务的 /data/files 是业务文件目录，不属于日志目录，必须继续持久化。

单容器默认保留 50m × 3，可在 TEST 部署变量中覆盖：

环境	`DOCKER_LOG_DRIVER`	`DOCKER_LOG_MAX_SIZE`	`DOCKER_LOG_MAX_FILE`	长期留存
测试	`json-file`	`50m`	`3`	不要求

当前优先保证宝塔可观测性，因此不启用 json-file 压缩或非阻塞投递，避免面板无法读取轮转文件或在日志压力下静默丢弃。接入集中日志系统后，可通过 DOCKER_LOG_DRIVER 切换驱动，并由集中系统承担长期检索与留存。

调整日志策略后必须重新创建容器；只重启既有容器不会改变其日志驱动。历史 /data/logs/baiyue-firstleg 文件和旧容器日志不自动删除，确认无需保留后再单独清理。

网关跨域配置

本地默认允许商户端和后台端从 localhost/127.0.0.1 的 5173/5174 端口访问网关。部署到 TEST 时，必须通过 CORS_ALLOWED_ORIGINS 配置两个前端的明确地址，多个地址用英文逗号分隔，例如：

CORS_ALLOWED_ORIGINS=https://merchant.example.com,https://admin.example.com

当前登录态通过 Bearer Token 传递，CORS_ALLOW_CREDENTIALS 默认关闭。禁止把允许来源配置成 *；如果以后改为 Cookie 登录，必须使用 HTTPS 明确域名，并审查 Cookie 的 SameSite 和 Secure 设置。

仓库边界

仓库结构入口见 docs/头程项目目录结构与服务说明.md。服务保持数据归属、禁止跨库直接查询其他服务业务表；同机可共用 MySQL 实例、Redis 和 Nacos。内部调用不通过公网，部署及通信规则以新的两份主契约为准。

前端 phase4 定向离线检查入口为 apps/admin-web/scripts/phase4-test-frontend-acceptance.mjs（工作区相对路径），由 Admin 的 pnpm test:phase4:test 使用 vitest.phase4-test.config.ts 执行；不替代真实HTTP、页面或PDA验收。

README.md Unescape Escape

柏悦头程平台

模块

本地构建

容器日志

网关跨域配置

仓库边界

README.md