# 百悦物流尾程业务平台

本项目是海外尾程业务的独立 Maven 聚合工程草案，根坐标为 `com.baiyue.lastleg:baiyue-lastleg-platform:1.0.0-SNAPSHOT`。项目不包含登录、租户、用户、角色、菜单、按钮权限、国内订单和头程履约源码，也不允许直接查询国内数据库。

## 项目模块

| 模块 | 职责 |
|---|---|
| `gateway` | 海外统一入口、JWKS 验签、双端访问范围校验和显式路由 |
| `lastleg` | 到港、清关、拆柜、海外仓入库、派送和签收 |
| `warehouse` | 海外仓库存、库位和出入库作业 |
| `file` | 海外文件元数据和对象存储适配骨架 |
| `print` | 海外标签、面单和打印任务 |
| `audit-service` | 海外本地操作审计 |
| `integration-service` | 海外仓、承运商、清关和平台渠道适配 |
| `event-bridge-service` | 国内与海外之间的可靠事件收发、幂等和重试 |

## 登录与权限边界

登录、账号、租户、角色以及按钮权限的唯一写入口在头程项目。尾程项目不部署这类服务，按以下方式完成认证和授权：

1. 用户在国内统一入口登录，获得使用非对称算法签名的短时效 JWT。
2. JWT 包含用户、租户、应用端、角色、按钮权限和权限版本等快照信息。
3. 海外网关通过 `JWT_JWK_SET_URI` 获取并缓存公钥，只负责验签、签发方、有效期和应用端校验，不保存签名私钥。
4. 尾程业务服务通过公共安全组件读取权限快照并执行接口、按钮和租户边界校验，不在每次请求时跨区查询国内权限数据。
5. 用户停用、租户冻结和权限版本变化通过跨区事件同步到海外本地投影；高风险操作可依据本地冻结投影立即拒绝。

海外服务不得依赖国内 Redis 中的登录会话。正式上线前，头程公共安全制品必须完成 JWKS 解码器和本地权限快照校验改造。

## 公共制品依赖

本仓库不复制 `common-*` 源码。公共组件由头程仓发布到 Maven 私有仓库，本项目通过以下制品导入版本：

```text
com.baiyue.shared:baiyue-platform-bom:1.0.0-SNAPSHOT
com.baiyue.shared:baiyue-common-core
com.baiyue.shared:baiyue-common-web
com.baiyue.shared:baiyue-common-security
com.baiyue.shared:baiyue-common-openapi
com.baiyue.shared:baiyue-common-audit
com.baiyue.shared:common-event-contract
```

公共制品必须先发布或安装，本仓库才能进行完整 Maven 构建。

## 数据边界

| 服务 | 独立数据库 |
|---|---|
| `lastleg-service` | `baiyue_lastleg` |
| `warehouse-service` | `baiyue_warehouse` |
| `file-service` | `baiyue_file` |
| `print-service` | `baiyue_print` |
| `audit-service` | `baiyue_audit` |
| `event-bridge-service` | `baiyue_event_bridge` |

服务之间不得跨库查询。国内订单和头程事实通过版本化事件进入尾程本地投影，尾程状态和签收事实也通过事件回传国内。

## 文件服务说明

原工程中企业资质上传后同步调用国内权限服务的链路已从尾程仓移除。海外文件中心当前只保留基础骨架；提单、装箱单、清关文件和签收证明的对象存储、授权下载、病毒扫描及保留期限策略属于后续必做能力。

## 配置与构建

海外 Nacos 配置位于 `config/nacos`，环境变量模板位于 `env.example`。网关默认启用 `overseas` 配置，服务发现自动路由关闭，只允许 `application-overseas.yml` 中声明的尾程服务路由。

公共制品安装完成后执行：

```powershell
.\scripts\build.ps1
```

仅检查仓库边界和 POM 结构时执行：

```powershell
.\scripts\check-boundary.ps1
```

详细仓库边界见 [仓库边界说明](docs/repository-boundary.md)。

头程装柜完成后按实装入仓单批量生成尾程订单的事件契约、幂等规则和开发窗口拆分，见 [头程装柜完成生成尾程订单实施基线](docs/firstleg-loading-to-lastleg-orders.md)。