86 lines
4.9 KiB
Markdown
86 lines
4.9 KiB
Markdown
# 企业资质文件迁移说明
|
||
|
||
## 统一接口边界
|
||
|
||
企业资质的唯一真实上传入口是：
|
||
|
||
```http
|
||
POST /api/merchant/v1/files/qualifications
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
表单字段为 `file`，可选字段为 `certificateNo`。File 服务先校验并保存真实图片，再通过内部接口通知 IAM 创建资质和审核记录。IAM 的商户资质接口只负责查询，不再提供 JSON 上传入口。
|
||
|
||
有效的商户预览地址格式为：
|
||
|
||
```text
|
||
/api/merchant/v1/files/qualifications/{uuid}.jpg
|
||
/api/merchant/v1/files/qualifications/{uuid}.png
|
||
```
|
||
|
||
数据库中的 URL 不是文件本身。禁止只生成 UUID 并修改 `document_url`，也禁止用空文件或任意图片冒充营业执照。
|
||
|
||
## 历史数据盘点
|
||
|
||
发布前先以只读方式盘点历史路径：
|
||
|
||
```sql
|
||
SELECT id, tenant_id, qualification_type, document_url, status
|
||
FROM baiyue_iam.iam_tenant_qualification
|
||
WHERE deleted = 0
|
||
AND (document_url IS NULL
|
||
OR document_url NOT REGEXP '^/api/merchant/v1/files/qualifications/[0-9a-fA-F-]{36}\\.(jpg|png)$');
|
||
```
|
||
|
||
盘点结果中的每条记录都必须找到原始图片。找不到原始图片时，将记录标记为“待业务补传”，不得伪造文件，也不得直接改 URL。
|
||
|
||
## 可落地迁移步骤
|
||
|
||
1. 暂停对应资质的替换操作，记录资质 ID、租户 ID、旧 URL 和原文件校验和。
|
||
2. 从可信旧存储取得原始图片，校验文件签名、扩展名和不超过 5 MB 的大小限制。
|
||
3. 使用迁移工具按 File 服务同一规则生成 UUID 文件名，将真实文件写入共享存储的 `qualifications/{tenantId}/` 目录。
|
||
4. 写入完成后，从 File 服务平台预览接口读取新文件并核对 SHA-256；读取失败时不得修改数据库。
|
||
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
|
||
.\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。脚本不会连接数据库，也不会在生成的 SQL 中自动提交事务；执行人员确认文件已落到 File 服务实际挂载目录后，才可人工执行前向 SQL，并在 `affected_rows = 1` 且平台预览校验成功后显式 `COMMIT`。否则必须 `ROLLBACK` 并删除本次新增文件。对象存储环境不使用该脚本，应通过 File 上传接口迁移。
|
||
|
||
数据库更新模板如下，执行时必须替换为经过文件校验的真实值：
|
||
|
||
```sql
|
||
START TRANSACTION;
|
||
UPDATE baiyue_iam.iam_tenant_qualification
|
||
SET document_url = :verified_new_url
|
||
WHERE id = :qualification_id
|
||
AND tenant_id = :tenant_id
|
||
AND document_url = :expected_old_url
|
||
AND deleted = 0;
|
||
-- 仅当 ROW_COUNT() = 1 且新文件已通过 File 预览校验时提交，否则回滚。
|
||
-- 执行人员检查后显式 COMMIT 或 ROLLBACK，模板不自动提交。
|
||
```
|
||
|
||
## 新环境初始化
|
||
|
||
初始化脚本不再创建 `/phase1-seed/...` 虚假资质。测试环境需要可下单的商户时，应使用脱敏但真实存在的 JPG/PNG 文件走 File 上传、平台审核完整流程，使租户达到 `ACTIVE` 且资质达到 `APPROVED`。初始化账号、文件和审核结果应作为一套环境数据验收，不得仅靠 SQL 绕过文件保存。
|
||
|
||
用于联调的样本必须在名称或图片水印中明确标注“仅供测试”，并登记租户 ID、资质 ID、文件 SHA-256 和创建时间。验收结束后按生成的回滚 SQL恢复原元数据并删除本次文件；若样本通过正常上传审核流程产生，应由测试数据清理流程按同一组标识回收，禁止直接删除仍被资质元数据引用的文件。
|