# API 对齐数据库迁移运行手册

## 适用迁移

- MessageService：`20260909000100_ApiAlignmentFixes`
- GroupService：`20260909000200_ApiAlignmentFixes`
- FileService：`20260909000300_AsyncUploadResult`

## 发布前检查

先完成三个库的可恢复备份，并在对应数据库执行：

```sql
-- GroupService：新增 Id 唯一索引前必须无重复。
SELECT Id, COUNT(*) AS duplicate_count
FROM group_join_requests
GROUP BY Id
HAVING COUNT(*) > 1;

-- FileService：收紧 longtext 前检查历史最大长度。
SELECT
  MAX(CHAR_LENGTH(FileName)) AS max_file_name,
  MAX(CHAR_LENGTH(ContentType)) AS max_content_type,
  MAX(CHAR_LENGTH(checksum_algorithm)) AS max_checksum_algorithm,
  MAX(CHAR_LENGTH(checksum_value)) AS max_checksum_value,
  MAX(CHAR_LENGTH(storage_provider)) AS max_storage_provider,
  MAX(CHAR_LENGTH(storage_bucket)) AS max_storage_bucket,
  MAX(CHAR_LENGTH(storage_key)) AS max_storage_key,
  MAX(CHAR_LENGTH(storage_region)) AS max_storage_region
FROM upload_files;
```

上面的长度必须分别不超过 `255/255/16/128/64/255/1024/128`。对 `upload_tasks` 执行同样检查。超长值应先人工确认和修正，不要依赖数据库静默截断。

## 执行迁移

在仓库根目录设置目标数据库连接字符串后执行。不要把真实密码写入仓库或命令记录。

```powershell
$env:DefaultDB_ConnStr = '<MessageService MySQL connection string>'
dotnet ef database update --project MessageService.Infrastructure --startup-project MessageService.WebApi --context MessageDbContext

$env:DefaultDB_ConnStr = '<GroupService MySQL connection string>'
dotnet ef database update --project GroupService.Infrastructure --startup-project GroupService.WebApi --context GroupDbContext

$env:DefaultDB_ConnStr = '<FileService MySQL connection string>'
dotnet ef database update --project FileService.Infrastructure --startup-project FileService.WebApi --context FileDbContext
```

建议顺序为 Message → Group → File，随后发布后端，再发布最终前端包。

## 数据兼容说明

- 所有新业务列均可空或有安全默认值，不删除历史记录。
- 历史文件的 `IsPublic` 默认 `false`，无法确认作用域的旧文件因此只允许所有者读取。
- 新上传文件会写入 `SourceTaskId/ChatType/TargetId/ResultFileId`；不要批量猜测旧文件作用域。
- 群退出、群解散和会话隐藏使用软删除。

## 回滚

只有在已经回滚依赖新字段/接口的前后端版本后，才允许回滚数据库迁移：

```powershell
$env:DefaultDB_ConnStr = '<MessageService MySQL connection string>'
dotnet ef database update 20260423115234_InitMessageDb --project MessageService.Infrastructure --startup-project MessageService.WebApi --context MessageDbContext

$env:DefaultDB_ConnStr = '<GroupService MySQL connection string>'
dotnet ef database update 20260429103435_removeGroupRequestOperatorProfile --project GroupService.Infrastructure --startup-project GroupService.WebApi --context GroupDbContext

$env:DefaultDB_ConnStr = '<FileService MySQL connection string>'
dotnet ef database update 20260509073447_InitFileDb --project FileService.Infrastructure --startup-project FileService.WebApi --context FileDbContext
```

FileService 回滚会删除新作用域和任务结果列，并把收紧的字符串列恢复为 `longtext`；回滚前应另行导出这些新列的数据。