docs: 补充 P0-P2 回归报告

2026-07-31 18:26:55 +08:00
parent b1d4ef39e2
commit 564ac8b320
1 changed files with 90 additions and 0 deletions
@@ -0,0 +1,90 @@
+# P0-P2 问题修复回归报告
+
+日期：2026-07-31
+正式仓库：`D:\baiyue-firstleg`
+范围：IAM 成员授权、Order/Warehouse 主数据链路、File 资质存储、Gateway CORS、服务文件日志。
+测试边界：未连接或写入测试数据库，未启动业务服务，未占用业务端口。
+
+## 1. 验证结论
+
+本轮报告中的问题均属实，已完成代码、配置和自动化测试修复。目标模块自动化回归全部通过；测试环境是否达到最终业务验收，还需要发布 Nacos 配置、重新部署对应实例并执行真实接口联调，不能用单元测试结果替代环境验收。
+
+## 2. P0 修复
+
+### 2.1 成员越权授予角色
+
+- 新增成员携带非空 `roleIds` 时，除 `merchant:member:create` 外还必须具有 `merchant:member:grant-role`。
+- 编辑成员时，仅当角色集合实际变化时要求 `merchant:member:grant-role`；空集合清空已有角色也属于角色变更。
+- 只编辑姓名、联系方式等资料且角色集合不变时，不额外要求授角权限。
+- 跨租户成员先按当前租户查询并返回 404，不在确认租户归属前读取角色关系。
+
+### 2.2 订单草稿主数据链路
+
+- `config/nacos/local/order-service.yml` 和 `config/nacos/cn/order-service.yml` 的 Warehouse URL 默认值统一为空。
+- 默认由 OpenFeign 使用注册名 `warehouse-service` 通过 Nacos 调用；只有隔离端口回归时才显式设置 `WAREHOUSE_SERVICE_URL`。
+- 修复了容器内默认访问 `127.0.0.1:9205`、实际回环到 Order 容器自身的问题。
+- Warehouse 内部接口统一返回：不存在或跨租户为 404，已停用为 409；Order 分别转换为业务不存在和业务冲突，下游 5xx、解码失败或内部令牌不一致转换为 `S0503`。
+
+## 3. P1 修复
+
+### 3.1 File 服务与资质文件
+
+- File 启动时不仅检查目录属性，还会在存储根目录真实创建、写入并删除随机探针文件；挂载不可写时直接启动失败，不再出现实例看似存活、首次上传才报错。
+- `config/nacos/cn/file-service.yml` 删除当前代码未实现的 OSS 假配置，改为显式读取 `FILE_STORAGE_ROOT`。
+- 运行期文件写入异常保持返回 `S0503`，避免把磁盘或挂载故障包装成普通业务错误。
+- 历史资质迁移脚本生成的前向和回滚 SQL 不再自动 `COMMIT`；执行人员必须核对 `affected_rows=1` 和真实文件预览后显式提交，否则回滚。
+- Gateway 的 File 路由契约已通过测试确认指向 `lb://file-service`。
+
+宿主机 bind mount 不会继承镜像内目录属主。发布前必须保证 File 上传目录和各服务日志目录由容器用户 UID 10001 可写；历史 `/phase1-seed/...` 记录必须在取得真实脱敏文件后按《企业资质文件迁移说明》迁移，不能只改 URL。
+
+## 4. P2 修复
+
+- Gateway 继续只允许明确配置的 CORS 来源，禁止通配符 `*`。
+- 精确覆盖 `OPTIONS /api/auth/login`、`Origin: http://localhost:5174`，预检无需 Token 并返回允许来源、方法和请求头。
+- 新增响应式请求标识过滤器，预检成功、拒绝来源和安全失败响应均携带 `X-Request-Id`。
+- 非白名单来源仍返回 403，不会因为放行 `OPTIONS` 而绕过 CORS 白名单。
+
+## 5. 文件日志
+
+Gateway、Auth、IAM、Firstleg、Order、Warehouse、File、Print、Integration、Event Bridge、Audit 共 11 个服务均在自己的 `src/main/resources/application.yml` 配置日志文件和滚动策略。
+
+- 默认本地路径：`./logs/{spring.application.name}.log`
+- 容器路径：由 `LOG_PATH=/app/logs` 覆盖，并使用现有 Docker Compose 宿主机挂载。
+- 默认单文件上限：100 MB
+- 默认保留：30 天
+- 默认总容量上限：5 GB
+- 所有值均可通过 `LOGGING_*` 环境变量覆盖。
+
+## 6. 自动化回归
+
+正式仓串行执行：
+
+```powershell
+mvn -o "-Dmaven.repo.local=C:\Users\25137\.m2\repository" -pl iam,warehouse,order,file,gateway -am clean test
+```
+
+结果：11 个 Reactor 模块全部 `SUCCESS`，总耗时 59.223 秒。
+
+| 目标模块 | 测试数 | 失败 | 错误 | 跳过 |
+|---|---:|---:|---:|---:|
+| Gateway | 9 | 0 | 0 | 0 |
+| IAM | 64 | 0 | 0 | 0 |
+| Order | 24 | 0 | 0 | 0 |
+| Warehouse | 32 | 0 | 0 | 0 |
+| File | 5 | 0 | 0 | 0 |
+| 合计 | 134 | 0 | 0 | 0 |
+
+`git diff --check` 通过。测试只使用单元测试和随机端口测试上下文，没有启动固定业务端口，也没有访问数据库。
+
+## 7. 测试环境最终验收清单
+
+1. 发布更新后的 `local/cn` Nacos 配置并重新部署 Order、Warehouse、File、Gateway、IAM。
+2. 在宿主机预建 File 上传目录和 11 个日志目录，确认 UID 10001 可以创建和删除文件。
+3. 确认 Nacos 中只有当前版本实例，并验证 Gateway 到 `file-service`、`warehouse-service` 的负载均衡路由。
+4. 使用受限商户成员重放新增和编辑成员请求：携带角色但无授角权限必须返回 403；角色不变的资料编辑必须成功。
+5. 使用启用仓库、启用往来单位创建头程草稿；再分别验证不存在、跨租户、停用和重复提交。
+6. 上传一张脱敏营业执照并完成商户、平台预览；不得继续使用 `/phase1-seed/...` 路径。
+7. 从 `http://localhost:5174` 直连 Gateway 验证登录预检、登录、401、403 和非白名单来源。
+8. 检查宿主机固定日志目录，确认每个服务产生独立日志文件并按策略滚动。
+
+完成以上环境联调后，才能把本轮状态从“代码级回归通过”提升为“测试环境业务成熟验收通过”。