暂存提交
This commit is contained in:
@@ -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 数据库。
|
||||
@@ -289,6 +289,8 @@ IAM 的商户资质接口只读。旧的 `POST /api/merchant/v1/iam/tenant/quali
|
||||
|
||||
往来单位由 `warehouse-service` 承载，表为 `baiyue_warehouse.wh_partner`，不是独立服务或独立数据库。仓库和往来单位查询强制执行租户隔离和停用过滤。
|
||||
|
||||
平台往来单位和快递公司均为目标商户租户下的主数据，因此所有平台管理接口都必须显式传入 `tenantId`，缺失或小于 1 返回参数错误。`/api/platform/v1/warehouses/status` 会实际探测仓库、地址、服务能力、往来单位和快递公司表的必需字段；缺表或缺列返回 HTTP 503 且状态为 `DEGRADED`。业务查询遇到数据源不可用或结构漂移时统一返回 `S0503`，不再用 `S0500` 隐藏迁移问题。
|
||||
|
||||
部署到既有数据库时，除主建表脚本外还要执行 `firstleg/src/main/resources/db/phase1-firstleg-task-list-index.sql`；该脚本可重复执行，用于补齐履约任务租户时间分页索引。
|
||||
|
||||
平台履约可通过 `PUT /api/platform/v1/orders/first-leg/{orderId}/express?tenantId={tenantId}` 写入 `expressCompany,expressTrackingNo`；商户端只能在订单详情读取，不能维护快递公司或调用平台写接口。
|
||||
|
||||
@@ -43,6 +43,19 @@ WHERE deleted = 0
|
||||
5. 在单条事务中按 `id + tenant_id + 旧 document_url` 条件更新 IAM 的 `document_url`。受影响行数不是 1 时立即回滚。
|
||||
6. 再次通过平台预览接口验收；验收完成前保留旧文件和旧 URL 清单，以便回滚。
|
||||
|
||||
当前 File 服务使用本地或共享文件目录时，可先运行仓库内脚本生成真实文件、前向 SQL 和回滚 SQL：
|
||||
|
||||
```powershell
|
||||
.\scripts\migrate-local-qualification-file.ps1 `
|
||||
-ImagePath D:\test-data\脱敏营业执照.png `
|
||||
-StorageRoot D:\baiyue-firstleg-runtime\uploads `
|
||||
-TenantId 10001 `
|
||||
-QualificationId 资质ID `
|
||||
-OldDocumentUrl /phase1-seed/demo-business-license.jpg
|
||||
```
|
||||
|
||||
脚本会校验文件大小、JPG/PNG 文件签名和复制前后 SHA-256，并生成带 `id + tenant_id + 旧 URL` 乐观条件的前向 SQL及回滚 SQL。脚本不会连接数据库；执行人员确认文件已落到 File 服务实际挂载目录后，才可人工执行生成的前向 SQL。若受影响行数不是 1，必须回滚并删除本次新增文件。对象存储环境不使用该脚本，应通过 File 上传接口迁移。
|
||||
|
||||
数据库更新模板如下，执行时必须替换为经过文件校验的真实值：
|
||||
|
||||
```sql
|
||||
@@ -60,3 +73,5 @@ COMMIT;
|
||||
## 新环境初始化
|
||||
|
||||
初始化脚本不再创建 `/phase1-seed/...` 虚假资质。测试环境需要可下单的商户时，应使用脱敏但真实存在的 JPG/PNG 文件走 File 上传、平台审核完整流程，使租户达到 `ACTIVE` 且资质达到 `APPROVED`。初始化账号、文件和审核结果应作为一套环境数据验收，不得仅靠 SQL 绕过文件保存。
|
||||
|
||||
用于联调的样本必须在名称或图片水印中明确标注“仅供测试”，并登记租户 ID、资质 ID、文件 SHA-256 和创建时间。验收结束后按生成的回滚 SQL恢复原元数据并删除本次文件；若样本通过正常上传审核流程产生，应由测试数据清理流程按同一组标识回收，禁止直接删除仍被资质元数据引用的文件。
|
||||
|
||||
Reference in New Issue
Block a user