# 垃圾资源清理机制实现计划

## Context

当前系统所有上传文件（图标、图片、视频、Logo 等）一旦上传到 COS/本地存储，就永远不会被删除。即使用户取消表单、替换文件、或删除实体，存储中的文件仍然残留，形成垃圾资源。本方案通过三层防御彻底解决此问题：

1. **前端即时清理**：取消表单时删除本次上传的文件；替换文件时立即删除旧的上传
2. **后端保存时清理**：更新实体时如果文件 URL 变化，删除旧文件
3. **后端 GC 兜底**：PendingUploads 表 + 定时任务，24 小时后清理未消费的孤立文件（应对浏览器关闭/刷新等极端情况）

## 关键架构决策（基于代码验证）

### 决策 1：不修改各 Service 的存储格式
经代码验证，当前有两类存储格式：
- **存对象键**：ProjectService（CoverImage/VideoUrl 调 ExtractKey）、ContentService（Banner.Image/Partner.Logo 调 ExtractKey）
- **存签名URL/原值**：ProjectService（Category.Icon/Platform.Icon/Tag.Icon 直接赋值）、UserService（Avatar）、AuthService（Avatar）、SystemService（Logo 直接存值）

`FileStorageService.ExtractKey` 是幂等的：传入签名URL→提取key，传入key→原样返回，传入本地URL→去前导斜杠。因此**在清理/消费时调用 ExtractKey 即可归一化**，无需修改存储格式。修改存储格式会破坏前端读取路径（如 GetCategoriesAsync 返回 Icon 原值，前端 `<img :src>` 直接渲染），风险过大。

### 决策 2：DELETE 端点只删 pending 文件
为防止前端误删已被实体引用的文件，DELETE `/api/system/upload` 只删除 `ConsumedAt == null` 的 PendingUpload 记录对应文件。已被消费（保存到实体）的文件通过 Service 层 Update 方法在替换时删除。

### 决策 3：前端通过 key 跟踪上传
`UploadResultDto` 返回 `{ Url, Key }`。当前 IconUpload/VideoUpload 只用 Url，丢弃 Key。改造后捕获 Key，传给 `useUploadSession` 进行跟踪。DELETE 端点接收 key 参数。

## 垃圾场景覆盖

| 场景 | 前端 | 后端 | GC 兜底 |
|------|------|------|---------|
| 新建上传→取消弹窗 | `cleanupPending()` 调 DELETE key 删除文件 | — | 24h 后 GC |
| 编辑上传新文件→取消弹窗 | `cleanupPending()` 删除新文件（旧文件不受影响） | — | 24h 后 GC |
| 上传 A→上传 B 替换 | `deleteByUrl(A)` 立即调 DELETE 删 A | — | — |
| 上传→关闭浏览器 | 无法处理 | — | 24h 后 GC |
| 保存时替换文件 | `clear()` 不删文件 | Update 对比新旧，ExtractKey(old)≠ExtractKey(new) 则删旧文件 | — |
| 保存新增文件 | `clear()` 不删文件 | ConsumeAsync(ExtractKey(new)) 标记消费 | — |
| 删除实体（软删除） | — | 保留文件（支持恢复） | — |

## 后端实现

### 1. 新增实体 PendingUpload（`backend/MilliSim.Api/Common/Entities/Entities.cs` 末尾）

```csharp
/// <summary>
/// 待消费上传文件记录（用于垃圾资源清理跟踪）
/// </summary>
public class PendingUpload : BaseEntity
{
    /// <summary>COS 对象键或本地访问 URL</summary>
    [Required, StringLength(500)]
    public string ObjectKey { get; set; } = string.Empty;

    /// <summary>上传目录（icons/videos/logos/packages 等）</summary>
    [StringLength(50)]
    public string Folder { get; set; } = string.Empty;

    /// <summary>上传者用户 ID</summary>
    public long? UploadedBy { get; set; }

    /// <summary>上传时间</summary>
    public DateTime UploadedAt { get; set; } = DateTime.Now;

    /// <summary>消费时间（null=待消费，非null=已保存到实体）</summary>
    public DateTime? ConsumedAt { get; set; }
}
```

> 注意：用 `ConsumedAt` 是否为 null 区分状态。BaseEntity 的全局软删除过滤器不影响（IsDeleted 始终为 false）。

### 2. DbContext 注册（`backend/MilliSim.Api/Data/MilliSimDbContext.cs`）

- L32 附近添加：`public DbSet<PendingUpload> PendingUploads => Set<PendingUpload>();`
- OnModelCreating 中添加索引：
```csharp
modelBuilder.Entity<PendingUpload>().HasIndex(p => p.ObjectKey);
modelBuilder.Entity<PendingUpload>().HasIndex(p => p.ConsumedAt);
```

### 3. DbSeeder 建表补丁（`backend/MilliSim.Api/Data/DbSeeder.cs` 的 `PatchDatabaseSchemaAsync`）

在 try 块末尾添加 PendingUploads 表检测建表（EnsureCreated 不更新已有库结构，需手动建表）：

```csharp
// ===== PendingUploads 表：垃圾资源清理跟踪 =====
var pendingTableExists = await db.Database.SqlQueryRaw<string>(
    "SELECT TABLE_NAME AS `Value` FROM INFORMATION_SCHEMA.TABLES " +
    "WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'PendingUploads'"
).FirstOrDefaultAsync();

if (pendingTableExists == null)
{
    await db.Database.ExecuteSqlRawAsync(@"
        CREATE TABLE `PendingUploads` (
            `Id` BIGINT NOT NULL AUTO_INCREMENT,
            `ObjectKey` VARCHAR(500) NOT NULL,
            `Folder` VARCHAR(50) NOT NULL DEFAULT '',
            `UploadedBy` BIGINT NULL,
            `UploadedAt` DATETIME NOT NULL,
            `ConsumedAt` DATETIME NULL,
            `CreatedAt` DATETIME NOT NULL,
            `UpdatedAt` DATETIME NOT NULL,
            `IsDeleted` BIT NOT NULL DEFAULT 0,
            PRIMARY KEY (`Id`),
            INDEX `IX_PendingUploads_ObjectKey` (`ObjectKey`),
            INDEX `IX_PendingUploads_ConsumedAt` (`ConsumedAt`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");
}
```

### 4. 新增 UploadTrackingService（`backend/MilliSim.Api/Services/Infrastructure/UploadTrackingService.cs`）

```csharp
public interface IUploadTrackingService
{
    Task RegisterAsync(string objectKey, string folder, long? uploadedBy);
    Task ConsumeAsync(string objectKey);
    Task<bool> DeletePendingAsync(string objectKey);  // 返回是否实际删除（仅删 pending）
    Task<int> CleanupExpiredAsync(int expireHours = 24);
}

public class UploadTrackingService : IUploadTrackingService
{
    // RegisterAsync: 插入 PendingUpload 记录（ObjectKey, Folder, UploadedBy, UploadedAt=now, ConsumedAt=null）
    // ConsumeAsync: 按 ObjectKey 查找 ConsumedAt==null 的记录，设 ConsumedAt=now；找不到则静默跳过
    // DeletePendingAsync: 查 ConsumedAt==null && ObjectKey==key 的记录，调 _fileStorage.DeleteAsync(key) 删文件 + 删记录；找不到返回 false
    // CleanupExpiredAsync: 查 ConsumedAt==null && UploadedAt < now-expireHours，逐条删文件 + 删记录，返回清理数量
}
```

依赖注入：`MilliSimDbContext`、`IFileStorageService`、`ILogger<UploadTrackingService>`。

### 5. 修改 SystemController（`backend/MilliSim.Api/Controllers/SystemController.cs`）

**构造函数**：注入 `IUploadTrackingService`、`ICurrentUserService`。

**Upload 方法**（L147-175）：上传成功后注册 PendingUpload：
```csharp
var fileUrl = await _fileStorage.UploadAsync(file, folder);
var signedUrl = _fileStorage.GetSignedUrl(fileUrl);
// 注册到 PendingUpload 跟踪表
await _uploadTracking.RegisterAsync(fileUrl, folder, _currentUser.UserId);
return ApiResponse<UploadResultDto>.Success(new UploadResultDto { Url = signedUrl, Key = fileUrl });
```

**新增 DELETE 端点**（在 Upload 方法后）：
```csharp
[HttpDelete("upload")]
[Authorize(Policy = "Staff")]
public async Task<ApiResponse> DeleteUpload([FromQuery] string key)
{
    if (string.IsNullOrWhiteSpace(key))
        return ApiResponse.Fail("文件 key 不能为空");
    var deleted = await _uploadTracking.DeletePendingAsync(key);
    return ApiResponse.Success(deleted ? "已删除" : "文件不存在或已使用");
}
```

### 6. 修改各业务 Service（消费 + 旧文件删除）

**核心模式**：每个 Service 注入 `IUploadTrackingService`。Create 方法保存后调 `ConsumeAsync(ExtractKey(fileValue))`；Update 方法先记录旧值，保存后对比新旧，不同则删旧文件 + 消费新文件。

> `ExtractKey` 幂等：签名URL→key，key→key。因此无论存储格式如何都能正确归一化。

| Service | 方法 | 文件字段 | 处理 |
|---------|------|---------|------|
| `ProjectService` | CreateProjectAsync L128 | CoverImage, VideoUrl | 保存后 ConsumeAsync(ExtractKey(CoverImage))、ConsumeAsync(ExtractKey(VideoUrl)) |
| `ProjectService` | UpdateProjectAsync L157 | CoverImage, VideoUrl | 记录旧 CoverImage/VideoUrl；保存后 ExtractKey(旧)≠ExtractKey(新) 则 DeleteAsync(旧)；ConsumeAsync(新)。VideoUrl 跳过 `/api/projects/` 代理 URL |
| `ProjectService` | CreateCategoryAsync L449 | Icon | 保存后 ConsumeAsync(ExtractKey(Icon)) |
| `ProjectService` | UpdateCategoryAsync L467 | Icon | 记录旧 Icon；保存后 ExtractKey(旧)≠ExtractKey(新) 则 DeleteAsync(ExtractKey(旧))；ConsumeAsync(ExtractKey(新)) |
| `ProjectService` | Create/UpdatePlatformAsync | Icon | 同 Category |
| `ProjectService` | Create/UpdateTagAsync | Icon | 同 Category |
| `ContentService` | CreateBannerAsync L63 | Image | 保存后 ConsumeAsync(ExtractKey(Image)) |
| `ContentService` | UpdateBannerAsync L89 | Image | 记录旧 Image；ExtractKey(旧)≠ExtractKey(新) 则 DeleteAsync；ConsumeAsync(新) |
| `ContentService` | Create/UpdatePartnerAsync | Logo | 同 Banner |
| `UserService` | CreateUserAsync L139 | Avatar | 保存后 ConsumeAsync(ExtractKey(Avatar)) |
| `UserService` | UpdateUserAsync L199 | Avatar | 记录旧 Avatar；ExtractKey(旧)≠ExtractKey(新) 则 DeleteAsync；ConsumeAsync(新) |
| `AuthService` | UpdateProfileAsync L140 | Avatar | 注入 IFileStorageService + IUploadTrackingService；同 UpdateUserAsync |
| `SystemService` | UpdateSettingsAsync L54 | Logo* 五项 | 查旧值→保存→对比 LogoFrontend/LogoBackend/LogoFavicon/LogoLogin/LogoFooter，不同则删旧+消费新 |

**SystemService.UpdateSettingsAsync 特殊处理**（Logo 五项）：
```csharp
// 保存前查询旧 Logo 值
var logoKeys = new[] { "LogoFrontend", "LogoBackend", "LogoFavicon", "LogoLogin", "LogoFooter" };
var oldLogos = await _db.SystemSettings
    .Where(s => logoKeys.Contains(s.Key))
    .ToDictionaryAsync(s => s.Key, s => s.Value);

// ... 原有保存逻辑 ...

// 保存后对比 Logo 变化
foreach (var logoKey in logoKeys)
{
    if (request.Settings.TryGetValue(logoKey, out var newValue))
    {
        var oldKey = _fileStorage.ExtractKey(oldLogos.GetValueOrDefault(logoKey) ?? "");
        var newKey = _fileStorage.ExtractKey(newValue);
        if (!string.IsNullOrEmpty(oldKey) && oldKey != newKey)
        {
            await _fileStorage.DeleteAsync(oldKey);
        }
        if (!string.IsNullOrEmpty(newKey))
        {
            await _uploadTracking.ConsumeAsync(newKey);
        }
    }
}
```

### 7. 新增 GC 后台任务（`backend/MilliSim.Api/Services/UploadCleanupJob.cs`）

参照 `AuthorizationNotificationJob` 模式（IHostedService + Timer + CreateScope）：
- 每 6 小时执行一次 `CleanupExpiredAsync(24)`
- 清理 `ConsumedAt == null && UploadedAt < now - 24h` 的记录及对应文件

### 8. Program.cs 注册

```csharp
builder.Services.AddScoped<IUploadTrackingService, UploadTrackingService>();
builder.Services.AddHostedService<UploadCleanupJob>();
```

## 前端实现

### 9. 新增 API 方法（`frontend/src/api/index.ts` 的 systemApi）

```typescript
// 删除未使用的上传文件（仅限 pending 状态）
deleteUpload: (key: string) => http.delete<ApiResponse>('/system/upload', { params: { key } }),
```

同时修正 upload 方法的返回类型：
```typescript
upload: (formData: FormData) => http.upload<ApiResponse<{ url: string; key: string }>>('/system/upload', formData),
```

### 10. 新增 Composable（`frontend/src/composables/useUploadSession.ts`）

需先创建 `frontend/src/composables/` 目录。

```typescript
import { reactive } from 'vue'
import { systemApi } from '@/api'

interface TrackedUpload {
  key: string
  url: string
}

export function useUploadSession() {
  const tracked = reactive<TrackedUpload[]>([])

  /** 上传成功后注册跟踪 */
  function track(key: string, url: string) {
    if (key) tracked.push({ key, url })
  }

  /** 替换时删除旧上传（仅在本次会话跟踪中的） */
  async function deleteByUrl(url: string) {
    if (!url) return
    const idx = tracked.findIndex(t => t.url === url)
    if (idx === -1) return // 不在跟踪列表中（可能是已保存的旧文件），不删
    const item = tracked[idx]
    try {
      await systemApi.deleteUpload(item.key)
    } catch { /* 忽略删除失败 */ }
    tracked.splice(idx, 1)
  }

  /** 取消表单时删除全部跟踪文件 */
  async function cleanupPending() {
    for (const item of [...tracked]) {
      try {
        await systemApi.deleteUpload(item.key)
      } catch { /* 忽略 */ }
    }
    tracked.length = 0
  }

  /** 保存成功后清空跟踪（不删文件，后端标记消费） */
  function clear() {
    tracked.length = 0
  }

  return { tracked, track, deleteByUrl, cleanupPending, clear }
}
```

### 11. 修改 IconUpload.vue / VideoUpload.vue

**IconUpload.vue 改造点**：

1. 新增可选 prop：`uploadSession?: ReturnType<typeof useUploadSession>`
2. `uploadFile` 成功后：
   - 如果当前 `modelValue` 在 session 跟踪中（替换场景），先 `uploadSession.deleteByUrl(modelValue)`
   - 如果有 session，`uploadSession.track(response.data.key, response.data.url)`
   - `emit('update:modelValue', response.data.url)`
3. `handleDelete`：如果有 session 且当前值在跟踪中，`uploadSession.deleteByUrl(modelValue)` 后再 emit 空
4. XHR 响应类型增加 `key` 字段：`{ code: number; data?: { url: string; key: string } }`

**VideoUpload.vue**：同样改造（如有）。

> 不传 uploadSession 时行为完全不变（向后兼容）。

### 12. 修改表单页面

**弹窗模式页面**（Categories/Banners/Partners/Platforms/Tags/Employees/Customers）：
```typescript
import { useUploadSession } from '@/composables/useUploadSession'
const uploadSession = useUploadSession()

function handleAdd() {
  uploadSession.clear()  // 重置跟踪
  resetForm()
  // ...
}
function handleEdit(row) {
  uploadSession.clear()  // 重置跟踪（编辑已有数据，旧文件不在跟踪中）
  // 填充表单...
}
// 取消按钮改为 async
async function handleCancel() {
  await uploadSession.cleanupPending()
  dialogVisible.value = false
}
async function handleSubmit() {
  // ... 保存逻辑 ...
  uploadSession.clear()  // 保存成功，不删文件
  dialogVisible.value = false
}
```

模板传入：`<IconUpload v-model="form.icon" :upload-session="uploadSession" folder="..." />`

**页面级模式**（Settings/ProjectEdit）：
```typescript
const uploadSession = useUploadSession()
// 保存成功后
function onSaveSuccess() {
  uploadSession.clear()
}
// 离开页面时清理（onBeforeRouteLeave 或 onBeforeUnmount）
import { onBeforeRouteLeave } from 'vue-router'
onBeforeRouteLeave(async () => {
  await uploadSession.cleanupPending()
})
```

**Settings.vue**：5 个 Logo 共享一个 uploadSession，saveLogo 成功后 clear()。

**ProjectEdit.vue**：CoverImage + VideoUpload 共享一个 uploadSession，保存成功后 clear()，goBack 前 cleanupPending()。

### 需修改的页面清单

| 页面 | 类型 | 上传组件 | 字段 |
|------|------|---------|------|
| Categories.vue | 弹窗 | IconUpload | icon |
| Platforms.vue | 弹窗 | IconUpload | icon |
| Tags.vue | 弹窗 | IconUpload | icon |
| Banners.vue | 弹窗 | IconUpload | image |
| Partners.vue | 弹窗 | IconUpload | logo |
| Employees.vue | 弹窗 | IconUpload | avatar |
| Customers.vue | 弹窗 | IconUpload | avatar |
| Settings.vue | 页面级 | IconUpload×5 | Logo*5 |
| ProjectEdit.vue | 页面级 | IconUpload + VideoUpload | coverImage + video |

## 实现顺序

1. **后端基础**：PendingUpload 实体 → DbContext → DbSeeder → UploadTrackingService → Program.cs 注册
2. **后端端点**：SystemController Upload 注册 + DELETE 端点
3. **后端 GC**：UploadCleanupJob → Program.cs 注册
4. **后端业务**：各 Service 注入 + 消费 + 旧文件删除（ProjectService、ContentService、UserService、AuthService、SystemService）
5. **前端基础**：API 方法 → useUploadSession composable
6. **前端组件**：IconUpload + VideoUpload 改造
7. **前端页面**：9 个页面统一接入

## 验证方案

1. 新建分类→上传图标→取消→检查 DELETE `/api/system/upload?key=xxx` 被调用，文件已删
2. 新建分类→上传 A→上传 B 替换→检查 A 的 DELETE 被调用
3. 新建分类→上传图标→保存→检查无 DELETE 调用，PendingUpload 记录 ConsumedAt 已设置
4. 编辑分类→替换图标→保存→检查旧文件被删（后端 Service 层 DeleteAsync）
5. 上传图标→关闭浏览器→等待 GC 执行→检查文件已清理
6. 后端编译通过 + 前端 HMR 无报错
7. 确认已有数据的图标显示正常（未改存储格式，不应受影响）