暂存提交

docs/2026-07-31平台管理与头程履约补齐回归报告.md

@@ -0,0 +1,95 @@
+# 平台管理与头程履约补齐回归报告
+
+日期：2026-07-31  
+范围：IAM、Warehouse、Order、Firstleg、File 及共享依赖  
+边界：只连接本机开发数据库；已执行项目内可重复迁移和可回收联调数据，未连接远程 test 数据库。服务仅使用 `19100/19101/19104/19105/19106` 测试专用端口，回归结束后全部停止，不占用日常 `9000/920x` 端口。
+
+## 一、问题核验结论
+
+前端报告中的后端缺口基本属实：平台客户档案、平台快递公司、平台往来单位、权限资源维护、平台代客订单写入和履约任务查询此前均不完整。平台权限快照虽然在说明中出现，但 Controller 和 OpenAPI 曾发生漂移，导致登录后权限初始化存在失败风险。
+
+本轮已补齐：
+
+- 当前用户有效权限查询，不依赖角色列表权限，按有效成员、有效角色和有效权限实时计算。
+- 平台客户档案分页、详情、编辑、启停，并阻止通过启停接口绕过企业审核。
+- 平台内部用户的成员主键和角色回显，以及新增、编辑、启停、重置密码、角色分配闭环。
+- 权限资源编辑、启停、删除；系统资源、存在子节点或已绑定角色的资源禁止删除。
+- 平台快递公司和往来单位的分页、详情、新增、编辑、启停，所有读写强制携带目标租户。
+- 平台代客创建、编辑、提交头程订单；商户端和平台端创建、提交均消费 `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 租户任务索引、往来单位和快递公司的租户编码唯一索引均已存在。
+
+迁移实测发现 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`，未发生精度截断。
+- 平台往来单位和快递公司均完成新增、编辑、停用、详情回读；测试记录随后按租户和精确 ID 清理。
+- 商户头程订单完成创建草稿、相同 `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 数据库。