49 lines
4.1 KiB
Markdown
49 lines
4.1 KiB
Markdown
# 柏悦头程平台
|
|
|
|
本仓库承载国内头程与海外仓后端，包含统一认证、国内订单与履约、国内外仓储资源、海外尾程与入仓业务，以及跨区域事件桥和公共能力。国内、海外仍保持独立数据库、Nacos 命名空间与部署边界，通过版本化跨区域事件协作。
|
|
|
|
> 当前主体模型：业务单租户，产品只包含“平台—客户”两级。现有 `tenant_id > 0`、`tenantId` 和 `Tenant*` 是历史兼容命名，当前承载客户归属与隔离；`tenant_id = 0` 是平台账号、平台 RBAC 和平台公共主数据的技术作用域，不是可管理租户。平台公共仓库、往来单位、快递公司、托盘、库位等归属 `0`，客户订单、文件和费用归属客户 ID。未经过独立迁移设计，不得新增真实租户层或把现有客户隔离字段改义为上级租户。
|
|
|
|
## 模块
|
|
|
|
- `auth`：统一登录、令牌签发与刷新。
|
|
- `iam`：客户主档、用户、企业成员、角色、菜单、按钮权限和数据范围；部分路径、表和类保留 `tenant` 历史命名。
|
|
- `order`：订单主数据及订单状态编排。
|
|
- `firstleg`：头程揽收、入仓、装载、发运和交接。
|
|
- `warehouse`：国内仓储能力。
|
|
- `file`、`print`、`audit-service`、`integration-service`：国内公共业务能力；Print 调用方接入见 `print/README.md`。
|
|
- `gateway-overseas`、`lastleg-service`、`warehouse-overseas-service`、`overseas-security-service`：海外公网入口、海外尾程与入仓业务、海外仓储资源及 IAM 安全投影。
|
|
- `event-bridge-service`：按国内、海外双实例部署的跨区域事件桥。
|
|
- `common-*`、`common-event-contract`：由本仓维护并以 `com.baiyue.shared` 发布的公共制品。
|
|
- `platform-bom`：统一管理仓库内公共依赖版本。
|
|
|
|
## 本地构建
|
|
|
|
```powershell
|
|
mvn -DskipTests validate
|
|
node --test scripts/java-topology-contract.test.mjs
|
|
mvn test
|
|
```
|
|
|
|
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`。
|
|
|
|
国内本地联调启动顺序为：IAM、Auth、Firstleg、Order、Warehouse、File、Print，最后启动 Gateway。往来单位不是独立服务，由 `warehouse-service` 承载并保存到 `baiyue_warehouse.wh_partner`。海外服务通过独立 Compose 与 Nacos 配置启动，不与国内服务共享数据库或配置命名空间。
|
|
|
|
国内 Nacos 配置位于 `config/nacos/cn`。数据库、Redis、Nacos 和 RocketMQ 的生产密码必须通过环境变量或配置中心密文注入，禁止提交明文密码。
|
|
|
|
## 网关跨域配置
|
|
|
|
本地默认允许商户端和后台端从 `localhost/127.0.0.1` 的 `5173/5174` 端口访问网关。部署到测试或生产环境时，必须通过 `CORS_ALLOWED_ORIGINS` 配置两个前端的明确地址，多个地址用英文逗号分隔，例如：
|
|
|
|
```text
|
|
CORS_ALLOWED_ORIGINS=https://merchant.example.com,https://admin.example.com
|
|
```
|
|
|
|
当前登录态通过 Bearer Token 传递，`CORS_ALLOW_CREDENTIALS` 默认关闭。禁止把允许来源配置成 `*`；如果以后改为 Cookie 登录，必须使用 HTTPS 明确域名，并审查 Cookie 的 `SameSite` 和 `Secure` 设置。
|
|
|
|
## 仓库边界
|
|
|
|
仓库边界、服务调用和拆分规则见 `docs/头程项目目录结构与服务说明.md` 的“项目定位”“主要调用关系”和“开发和拆分约束”。国内与海外服务不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。
|