平台管理与头程履约补齐回归报告

日期：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 跳过

业务模块最终命令：

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/，没有放入临时目录，也没有自动写入本地数据库。

IAM 已有库：依次执行 phase1-admin-rbac.sql、rbac-role-management-v2.sql、phase1-platform-master-data-and-permission-management.sql。
Warehouse 新库：依次执行 warehouse.sql、warehouse-partner.sql、warehouse-express-company.sql、warehouse-seed.sql。
Warehouse 已有库：在基础表脚本后执行 phase1-warehouse-schema-migration.sql，再按需执行种子脚本。
Order 新库执行 order.sql；已有库执行 phase1-order-extension.sql。
Firstleg 新库执行 firstleg.sql；已有库执行 phase1-firstleg-task-list-index.sql。

File 本轮不涉及数据库迁移脚本。非本地环境必须显式配置 FILE_STORAGE_ROOT 并挂载持久化可写目录；Docker 部署保持 /data/files 卷挂载。

以上脚本已在本机开发库按顺序成功执行。其他环境仍需按发布流程独立执行并记录结果，不得以本地执行结果代替环境迁移记录。

六、仍需环境联调

部署后的 Gateway 仍需做浏览器级跨租户 403、停用账号、停用权限即时生效及移动端验收。
PENDING/REJECTED 企业、普通成员和自定义角色需要在专用测试环境准备可回收样本，完成五状态浏览器验收。
远程 test 环境需按第五节执行迁移并部署同一构建版本；本轮没有连接或写入远程 test 数据库。

7.5 KiB Raw Blame History Unescape Escape