暂存提交

docs/企业资质文件迁移说明.md

@@ -43,6 +43,14 @@ WHERE deleted = 0
 5. 在单条事务中按 `id + tenant_id + 旧 document_url` 条件更新 IAM 的 `document_url`。受影响行数不是 1 时立即回滚。
 6. 再次通过平台预览接口验收；验收完成前保留旧文件和旧 URL 清单，以便回滚。
 
+容器部署前必须确认 File 实例注册名为 `file-service`，Gateway 路由目标为 `lb://file-service`，并确认 `/data/files` 是持久卷且容器用户 UID 10001 可以实际创建和删除文件。镜像内的目录权限不会覆盖宿主机 bind mount 的属主；使用宿主机目录时，须先创建目录并把所有权授予 UID 10001。旧版本已创建的卷或目录可在维护窗口使用当前 File 镜像一次性修复后重启：
+
+```sh
+docker compose --env-file <环境文件> -f deploy/docker-compose.yml run --rm --user 0 --entrypoint sh file -c 'chown -R 10001:10001 /data/files'
+```
+
+`/actuator/health` 通过后，还应执行一次脱敏图片上传和平台预览，验证 Gateway、Nacos、挂载和 IAM 协作的完整链路。
+
 当前 File 服务使用本地或共享文件目录时，可先运行仓库内脚本生成真实文件、前向 SQL 和回滚 SQL：
 
 ```powershell
@@ -54,7 +62,7 @@ WHERE deleted = 0
   -OldDocumentUrl /phase1-seed/demo-business-license.jpg
 ```
 
-脚本会校验文件大小、JPG/PNG 文件签名和复制前后 SHA-256，并生成带 `id + tenant_id + 旧 URL` 乐观条件的前向 SQL及回滚 SQL。脚本不会连接数据库；执行人员确认文件已落到 File 服务实际挂载目录后，才可人工执行生成的前向 SQL。若受影响行数不是 1，必须回滚并删除本次新增文件。对象存储环境不使用该脚本，应通过 File 上传接口迁移。
+脚本会校验文件大小、JPG/PNG 文件签名和复制前后 SHA-256，并生成带 `id + tenant_id + 旧 URL` 乐观条件的前向 SQL及回滚 SQL。脚本不会连接数据库，也不会在生成的 SQL 中自动提交事务；执行人员确认文件已落到 File 服务实际挂载目录后，才可人工执行前向 SQL，并在 `affected_rows = 1` 且平台预览校验成功后显式 `COMMIT`。否则必须 `ROLLBACK` 并删除本次新增文件。对象存储环境不使用该脚本，应通过 File 上传接口迁移。
 
 数据库更新模板如下，执行时必须替换为经过文件校验的真实值：
 
@@ -67,7 +75,7 @@ WHERE id = :qualification_id
   AND document_url = :expected_old_url
   AND deleted = 0;
 -- 仅当 ROW_COUNT() = 1 且新文件已通过 File 预览校验时提交，否则回滚。
-COMMIT;
+-- 执行人员检查后显式 COMMIT 或 ROLLBACK，模板不自动提交。
 ```
 
 ## 新环境初始化