96 lines
7.5 KiB
Markdown
96 lines
7.5 KiB
Markdown
# 平台管理与头程履约补齐回归报告
|
||
|
||
日期：2026-07-31
|
||
范围：IAM、Warehouse、Order、Firstleg、File 及共享依赖
|
||
边界：只连接本机开发数据库；已执行项目内可重复迁移和可回收联调数据，未连接远程 test 数据库。服务仅使用 `19100/19101/19104/19105/19106` 测试专用端口，回归结束后全部停止，不占用日常 `9000/920x` 端口。
|
||
|
||
## 一、问题核验结论
|
||
|
||
前端报告中的后端缺口基本属实：平台客户档案、平台快递公司、平台往来单位、权限资源维护、平台代客订单写入和履约任务查询此前均不完整。平台权限快照虽然在说明中出现，但 Controller 和 OpenAPI 曾发生漂移，导致登录后权限初始化存在失败风险。
|
||
|
||
本轮已补齐：
|
||
|
||
- 当前用户有效权限查询，不依赖角色列表权限，按有效成员、有效角色和有效权限实时计算。
|
||
- 平台客户档案分页、详情、编辑、启停，并阻止通过启停接口绕过企业审核。
|
||
- 平台内部用户的成员主键和角色回显，以及新增、编辑、启停、重置密码、角色分配闭环。
|
||
- 权限资源编辑、启停、删除；系统资源、存在子节点或已绑定角色的资源禁止删除。
|
||
- 历史实现曾要求平台快递公司和往来单位的所有读写携带目标租户；该口径已于 2026-08-05 废止，两类主数据现统一归属平台作用域 `0`。
|
||
- 平台代客创建、编辑、提交头程订单；商户端和平台端创建、提交均消费 `Idempotency-Key`。
|
||
- 订单不存在统一返回 HTTP 404；Warehouse 下游不可用统一映射为受控 503。
|
||
- Firstleg 履约任务列表、详情、按订单查询、分配历史和分页查询。
|
||
- File 企业资质上传改为流式落盘，服务启动时校验存储根目录；跨平台默认目录不再硬编码 Windows 路径，磁盘故障统一返回 `S0503` 并记录底层异常。
|
||
- `Long/long` 由 `common-web` 统一序列化为 JSON 字符串，请求继续接受字符串 ID；`common-openapi` 同步把长整型声明为字符串，避免 19 位雪花 ID 被浏览器截断。
|
||
|
||
## 二、本地数据库迁移与核验
|
||
|
||
使用各服务 `application-dev.yml` 的本地连接配置，先读取 `information_schema`，再按第四节顺序执行可重复迁移，最后重新核验关键字段和索引。MySQL 版本为 `8.4.11`。
|
||
|
||
| 数据库 | 关键表结果 | 当前数据量 |
|
||
|---|---|---|
|
||
| `baiyue_iam` | 成员、角色、权限及关联表均存在；`iam_permission.built_in` 已迁移 | 成员 22、角色 15、权限 115、租户 17 |
|
||
| `baiyue_warehouse` | 仓库、地址、能力、往来单位、快递公司表及必需字段均存在 | 仓库 1、地址 1、能力 1、往来单位 1、启用快递公司 1 |
|
||
| `baiyue_order` | 订单快照字段、快递字段和幂等记录表均已迁移 | 原有订单 5；回归订单已精确清理 |
|
||
| `baiyue_firstleg` | 履约任务表和分配历史表均存在 | 两表均为 0 |
|
||
|
||
本地 File 存储目录 `D:\baiyue-firstleg-runtime\uploads` 已存在租户 `10001` 的 UUID 资质图片。使用商户 Token 请求 `/api/merchant/v1/files/qualifications/a1d6caa0-14df-4988-831c-d1a8f5d142ff.png` 返回 HTTP 200、`image/png`、47772 字节。旧 `/phase1-seed/demo-business-license.jpg` 记录状态已是 `SUPERSEDED`，不再作为当前有效资质。
|
||
|
||
关键索引只读核验结果：订单幂等唯一索引、Firstleg 客户隔离任务索引、往来单位和快递公司的兼容作用域编码唯一索引均已存在；后两者当前固定使用平台公共作用域 `0`。
|
||
|
||
迁移实测发现 MySQL 不支持 `ADD COLUMN IF NOT EXISTS`，IAM 与 Warehouse 增量脚本已改为 `information_schema + 动态 SQL` 的可重复写法，并在本地成功执行。远程测试环境部署时仍必须核对迁移版本；健康检查成功不能证明业务表结构已同步。
|
||
|
||
## 三、自动化回归结果
|
||
|
||
为避免多窗口并行构建清理同一 `target`，先安装共享模块快照，再隔离执行四个业务模块的 `clean test`。
|
||
|
||
| 模块 | 测试数 | 结果 |
|
||
|---|---:|---|
|
||
| 共享模块 | 16 | 通过 |
|
||
| IAM | 58 | 通过 |
|
||
| Order | 18 | 通过 |
|
||
| Firstleg | 6 | 通过 |
|
||
| Warehouse | 28 | 通过 |
|
||
| File | 5 | 通过 |
|
||
| 全仓合计 | 169 | 全部通过，0 失败、0 错误、0 跳过 |
|
||
|
||
业务模块最终命令：
|
||
|
||
```powershell
|
||
mvn -o "-Dmaven.repo.local=C:\Users\25137\.m2\repository" clean test
|
||
```
|
||
|
||
最终结果：19 个 Reactor 模块全部构建成功，169 项测试无失败、无错误、无跳过；`git diff --check` 通过。
|
||
|
||
## 四、真实接口回归
|
||
|
||
本地启动 Auth、IAM、Order、Warehouse、File，统一连接本机数据库和 Redis，并使用测试专用端口完成以下验证：
|
||
|
||
- 商户端、平台端统一登录均成功；平台权限快照返回 61 项权限，不依赖角色列表权限。
|
||
- 平台客户分页返回 16 条；内部用户返回 `membershipId` 和 `roleIds`，ID 的 JSON 类型为字符串。
|
||
- 商户仓库、往来单位候选、平台仓库、平台往来单位、平台快递公司均返回真实本地数据；19 位仓库 ID 保持 `190000000000000001`，未发生精度截断。
|
||
- 平台往来单位和快递公司均完成新增、编辑、停用、详情回读；该历史回归当时按客户作用域清理，当前两类主数据已统一归平台公共作用域 `0`。
|
||
- 商户头程订单完成创建草稿、相同 `Idempotency-Key` 重放返回同一订单 ID、提交、相同提交键重放、详情读取和取消；测试订单及子表、Outbox、幂等记录随后精确清理。
|
||
- 不存在订单返回 HTTP 404；Order OpenAPI 已声明必填 `Idempotency-Key`，`OrderEntity.id` 类型为 `string`，平台提交路径正确。
|
||
- 有效资质文件鉴权预览返回 HTTP 200，文件内容与元数据路径一致。
|
||
|
||
服务启动期间 Nacos 本地配置读取出现一次 `MalformedInputException`，但五个服务均正常启动且健康检查为 `UP`。这是本地 Nacos 配置内容编码问题，不影响本轮源码与数据库结论；应单独把 Nacos YAML 统一保存为 UTF-8。
|
||
|
||
## 五、SQL 脚本位置与执行顺序
|
||
|
||
脚本均放在所属服务的 `src/main/resources/db/`，没有放入临时目录，也没有自动写入本地数据库。
|
||
|
||
1. IAM 已有库：依次执行 `phase1-admin-rbac.sql`、`rbac-role-management-v2.sql`、`phase1-platform-master-data-and-permission-management.sql`。
|
||
2. Warehouse 新库：依次执行 `warehouse.sql`、`warehouse-partner.sql`、`warehouse-express-company.sql`、`warehouse-seed.sql`。
|
||
3. Warehouse 已有库：在基础表脚本后执行 `phase1-warehouse-schema-migration.sql`，再按需执行种子脚本。
|
||
4. Order 新库执行 `order.sql`；已有库执行 `phase1-order-extension.sql`。
|
||
5. Firstleg 新库执行 `firstleg.sql`；已有库执行 `phase1-firstleg-task-list-index.sql`。
|
||
|
||
File 本轮不涉及数据库迁移脚本。非本地环境必须显式配置 `FILE_STORAGE_ROOT` 并挂载持久化可写目录；Docker 部署保持 `/data/files` 卷挂载。
|
||
|
||
以上脚本已在本机开发库按顺序成功执行。其他环境仍需按发布流程独立执行并记录结果，不得以本地执行结果代替环境迁移记录。
|
||
|
||
## 六、仍需环境联调
|
||
|
||
- 部署后的 Gateway 仍需做浏览器级跨租户 403、停用账号、停用权限即时生效及移动端验收。
|
||
- PENDING/REJECTED 企业、普通成员和自定义角色需要在专用测试环境准备可回收样本，完成五状态浏览器验收。
|
||
- 远程 test 环境需按第五节执行迁移并部署同一构建版本；本轮没有连接或写入远程 test 数据库。
|