295 lines
15 KiB
Markdown
295 lines
15 KiB
Markdown
# 上传垃圾资源清理 - 前端实施计划
|
||
|
||
## 概述
|
||
|
||
延续上一会话已完成的后端基础（PendingUpload 实体、UploadTrackingService、UploadCleanupJob、各业务 Service 的 Consume/Delete 旧文件逻辑、SystemController 的 Upload/DELETE 端点），本计划聚焦**前端集成**，确保所有上传场景在「取消表单、替换文件、关闭弹窗」时主动调用后端 DELETE 清理 pending 文件，避免形成垃圾资源。
|
||
|
||
## 当前状态分析
|
||
|
||
### 后端（已完成，需验证编译）
|
||
|
||
- `Common/Entities/Entities.cs`：新增 `PendingUpload` 实体（ObjectKey/Folder/UploadedBy/UploadedAt/ConsumedAt）
|
||
- `Data/MilliSimDbContext.cs`：注册 `PendingUploads` DbSet + 两个索引
|
||
- `Data/DbSeeder.cs`：`PatchDatabaseSchemaAsync` 末尾新增建表补丁
|
||
- `Services/Infrastructure/UploadTrackingService.cs`：RegisterAsync / ConsumeAsync / DeletePendingAsync / CleanupExpiredAsync
|
||
- `Services/UploadCleanupJob.cs`：IHostedService + Timer（启动 5 分钟后首次执行，之后每 6 小时一次，清理 24h 未消费文件）
|
||
- `Program.cs`：注册 `IUploadTrackingService`（Scoped）+ `UploadCleanupJob`（Hosted）
|
||
- `Controllers/SystemController.cs`：
|
||
- Upload 端点：成功后 `RegisterAsync`，返回 `{ url, key }`
|
||
- 新增 DELETE `/api/system/upload?key=xxx`：仅删 pending 状态文件
|
||
- `Services/ProjectService.cs`、`ContentService.cs`、`UserService.cs`、`AuthService.cs`、`SystemService.cs`：
|
||
- Create：保存后 `ConsumeAsync(ExtractKey(field))`
|
||
- Update：记录 oldKey/newKey，保存后对比，不同则 `DeleteAsync(oldKey)` + `ConsumeAsync(newKey)`
|
||
|
||
### 前端（未实施，本计划范围）
|
||
|
||
- `api/index.ts`：`systemApi.upload` 返回类型仅 `{ url: string }`，缺 `key`；无 `deleteUpload` 方法
|
||
- `components/IconUpload.vue`：XHR 上传只用 `response.data.url`，丢弃 `key`；`handleDelete` 仅 `emit('update:modelValue', '')`，不调后端删除
|
||
- `components/VideoUpload.vue`：同 IconUpload 问题
|
||
- 9 个表单页面均未跟踪上传会话、未在取消/关闭时清理 pending 文件
|
||
|
||
## 三层防御策略
|
||
|
||
1. **前端即时清理（本计划核心）**：`useUploadSession` composable 跟踪表单会话中的上传文件；取消表单时 `cleanupPending()` 批量删除；替换文件时 IconUpload/VideoUpload 自动调 DELETE 删除旧 pending 上传
|
||
2. **后端保存时清理（已完成）**：各 Service Update 方法对比新旧 key，删除旧文件 + 消费新文件
|
||
3. **后端 GC 兜底（已完成）**：`UploadCleanupJob` 每 6 小时清理 24h 未消费的 pending 文件
|
||
|
||
## 关键设计决策
|
||
|
||
- **不修改各 Service 的存储格式** — 后端 `ExtractKey` 幂等（签名URL/key 都能归一化），前端只需把上传返回的 `key` 原样存入 form，提交时随业务字段一起发送
|
||
- **DELETE 端点只删 pending 文件** — `DeletePendingAsync` 检查 `ConsumedAt == null`，已保存到实体的文件不会被误删
|
||
- **前端通过 key 跟踪上传** — IconUpload/VideoUpload 捕获 `UploadResultDto.key`，通过 `uploadSession.register(key)` 注册到会话
|
||
- **替换文件即时清理** — IconUpload/VideoUpload 在 emit 新值前，若旧值是本次会话上传的 pending key，立即调 `deleteUpload(key)` 删除（不等表单取消）
|
||
- **会话生命周期** — 弹窗页面：`openDialog` 时 `resetSession()`，`cancelDialog`/`closed` 时 `cleanupPending()`；页面级：`onMounted` 时创建，`onBeforeUnmount` 时 `cleanupPending()`，保存成功后 `resetSession()` 标记已消费
|
||
|
||
## 实施步骤
|
||
|
||
### 阶段 A：后端编译验证（前置）
|
||
|
||
1. 杀掉后端进程（PID 17372 或当前运行的 MilliSim.Api.exe）
|
||
2. `dotnet build backend/MilliSim.Api/MilliSim.Api.csproj -c Debug`
|
||
3. 预期：编译通过（可能有 2 个无害 nullable 警告：UserService.cs L186、ProjectService.cs L1021）
|
||
4. 启动后端：`dotnet run --project backend/MilliSim.Api/MilliSim.Api.csproj`，确认 PendingUploads 表已建表、Swagger 显示 DELETE `/api/system/upload`
|
||
|
||
### 阶段 B：前端基础设施
|
||
|
||
#### B1. `frontend/src/api/index.ts`
|
||
|
||
修改 `systemApi`：
|
||
|
||
```typescript
|
||
// 通用文件上传接口（返回 url 用于预览 + key 用于跟踪）
|
||
upload: (formData: FormData) =>
|
||
http.upload<ApiResponse<{ url: string; key: string }>>('/system/upload', formData),
|
||
// 删除未使用的上传文件（仅限 pending 状态）
|
||
deleteUpload: (key: string) =>
|
||
http.delete<ApiResponse>('/system/upload', { key }),
|
||
```
|
||
|
||
#### B2. 创建 `frontend/src/composables/useUploadSession.ts`
|
||
|
||
需先创建 `composables` 目录。
|
||
|
||
```typescript
|
||
import { ref, onBeforeUnmount } from 'vue'
|
||
import { systemApi } from '@/api'
|
||
|
||
interface UploadSession {
|
||
/** 注册一个上传的 key（emit 前调用） */
|
||
register(key: string): void
|
||
/** 标记某个 key 已被保存消费（不再清理） */
|
||
consume(key: string): void
|
||
/** 取消表单/关闭弹窗时调用：批量删除所有未消费的 pending 文件 */
|
||
cleanupPending(): Promise<void>
|
||
/** 保存成功后重置会话（清空跟踪列表，不删文件） */
|
||
reset(): void
|
||
}
|
||
|
||
export function useUploadSession() {
|
||
const pendingKeys = ref<string[]>([])
|
||
|
||
function register(key: string) {
|
||
if (!key || pendingKeys.value.includes(key)) return
|
||
pendingKeys.value.push(key)
|
||
}
|
||
|
||
function consume(key: string) {
|
||
if (!key) return
|
||
pendingKeys.value = pendingKeys.value.filter(k => k !== key)
|
||
}
|
||
|
||
async function cleanupPending() {
|
||
const keys = [...pendingKeys.value]
|
||
pendingKeys.value = []
|
||
await Promise.all(
|
||
keys.map(key =>
|
||
systemApi.deleteUpload(key).catch(() => {/* 静默失败，不影响 UX */})
|
||
)
|
||
)
|
||
}
|
||
|
||
function reset() {
|
||
pendingKeys.value = []
|
||
}
|
||
|
||
// 组件卸载时自动清理（防止页面级表单忘记调用）
|
||
onBeforeUnmount(() => {
|
||
cleanupPending()
|
||
})
|
||
|
||
return { register, consume, cleanupPending, reset }
|
||
}
|
||
```
|
||
|
||
### 阶段 C：上传组件改造
|
||
|
||
#### C1. `frontend/src/components/IconUpload.vue`
|
||
|
||
修改点：
|
||
1. 新增 prop `uploadSession?`（可选，类型为 useUploadSession 返回的对象的方法集合）
|
||
2. `uploadFile` 成功后：用 `response.data.key` 调 `uploadSession?.register(key)`，再 emit url
|
||
3. `handleDelete`：若当前 `modelValue` 是本次会话上传的 key（即 uploadSession 中存在），调 `systemApi.deleteUpload(key)` 即时删除；emit `''`
|
||
4. 替换图片场景：`uploadFile` 成功后，若旧 `modelValue` 是 pending key，先 `deleteUpload(oldKey)` 再注册新 key
|
||
|
||
具体改造：
|
||
- props 增加 `uploadSession?: { register: (k: string) => void; consume: (k: string) => void }`
|
||
- 新增内部状态 `currentKey`（保存最近一次上传返回的 key）
|
||
- `uploadFile` 成功分支：
|
||
```typescript
|
||
if (response.code === 200 && response.data?.url) {
|
||
const newKey = response.data.key || ''
|
||
// 若旧值是 pending 上传，先清理（替换场景）
|
||
if (props.uploadSession && currentKey.value && currentKey.value !== newKey) {
|
||
// 旧的 currentKey 是上一次上传的 pending，本次替换前删除
|
||
// 注意：只能删本次会话上传的，不能删已保存的（即 form 中来自后端的值）
|
||
// 由于 IconUpload 在初始化时 modelValue 是签名URL，currentKey 为空，
|
||
// 只有用户主动上传后 currentKey 才有值，所以可以放心删
|
||
systemApi.deleteUpload(currentKey.value).catch(() => {})
|
||
}
|
||
currentKey.value = newKey
|
||
props.uploadSession?.register(newKey)
|
||
emit('update:modelValue', response.data.url)
|
||
ElMessage.success('上传成功')
|
||
}
|
||
```
|
||
- `handleDelete`：
|
||
```typescript
|
||
async function handleDelete() {
|
||
if (currentKey.value) {
|
||
// 仅删本次会话上传的，已保存的（currentKey 为空）不删
|
||
await systemApi.deleteUpload(currentKey.value).catch(() => {})
|
||
currentKey.value = ''
|
||
}
|
||
emit('update:modelValue', '')
|
||
}
|
||
```
|
||
- 不再使用 `uploadSession.consume`，因为消费逻辑由后端 Service 在保存时通过 `ConsumeAsync` 处理；前端只需在取消表单时通过 `cleanupPending()` 批量清理剩余 pending
|
||
|
||
#### C2. `frontend/src/components/VideoUpload.vue`
|
||
|
||
与 IconUpload 相同的改造：新增 `uploadSession` prop + `currentKey` + 替换时清理旧 pending + handleDelete 调 DELETE。
|
||
|
||
### 阶段 D：9 个表单页面接入
|
||
|
||
所有页面统一模式：
|
||
- 弹窗页面：在 setup 顶层 `const uploadSession = useUploadSession()`；handleAdd/handleEdit 时 `uploadSession.reset()`；取消按钮和 dialog 的 `closed` 事件调 `uploadSession.cleanupPending()`；handleSubmit 成功后 `uploadSession.reset()`；把 `:upload-session="uploadSession"` 传给所有 IconUpload/VideoUpload
|
||
- 页面级：setup 顶层 `const uploadSession = useUploadSession()`；onMounted 时 `uploadSession.reset()`（清空上一次残留）；保存成功后 `uploadSession.reset()`；离开页面前 onBeforeUnmount 由 composable 自动 cleanupPending
|
||
|
||
#### 弹窗页面（7 个）
|
||
|
||
| 文件 | 上传字段 | 改造点 |
|
||
|------|---------|--------|
|
||
| `views/admin/Categories.vue` | icon | useUploadSession + reset/cleanup/reset + 传 prop |
|
||
| `views/admin/Platforms.vue` | icon | 同上 |
|
||
| `views/admin/Tags.vue` | icon | 同上 |
|
||
| `views/admin/Banners.vue` | image | 同上 |
|
||
| `views/admin/Partners.vue` | logo | 同上 |
|
||
| `views/admin/Employees.vue` | avatar | 同上 |
|
||
| `views/admin/Customers.vue` | avatar | 同上 |
|
||
|
||
每个弹窗页面统一改造模式：
|
||
1. 导入：`import { useUploadSession } from '@/composables/useUploadSession'`
|
||
2. setup：`const uploadSession = useUploadSession()`
|
||
3. `handleAdd`：在 `resetForm()` 后加 `uploadSession.reset()`
|
||
4. `handleEdit`：在 `Object.assign(form, ...)` 后加 `uploadSession.reset()`（编辑模式不清理已保存的文件，仅开始新会话）
|
||
5. 取消按钮：`@click="handleCancel"`，新增 `handleCancel` 函数：`uploadSession.cleanupPending(); dialogVisible.value = false`
|
||
6. dialog 增加 `@closed="uploadSession.cleanupPending()"`（点击右上角 X 关闭时也触发）
|
||
7. `handleSubmit` 成功后：`uploadSession.reset()`（标记已消费，防止 onBeforeUnmount 重复清理）
|
||
8. 模板中所有 `<IconUpload>` 增加 `:upload-session="uploadSession"`
|
||
|
||
#### 页面级页面（2 个）
|
||
|
||
**`views/admin/Settings.vue`** — 5 个 Logo
|
||
1. 导入 useUploadSession
|
||
2. setup：`const uploadSession = useUploadSession()`
|
||
3. `fetchSettings` 完成后 `uploadSession.reset()`（加载完成后开始新会话）
|
||
4. `saveLogo` 成功后 `uploadSession.reset()`（5 个 Logo 一起保存）
|
||
5. 模板中 5 个 IconUpload 都传 `:upload-session="uploadSession"`
|
||
6. onBeforeUnmount 由 composable 自动 cleanupPending
|
||
|
||
**`views/admin/ProjectEdit.vue`** — coverImage + videoUrl
|
||
1. 导入 useUploadSession
|
||
2. setup：`const uploadSession = useUploadSession()`
|
||
3. `fetchProject` 完成后 `uploadSession.reset()`
|
||
4. `handleSave` 成功后（无论 create 还是 update）：`uploadSession.reset()`
|
||
5. `goBack` 函数：先 `await uploadSession.cleanupPending()` 再 `router.push`
|
||
6. 模板中 IconUpload（coverImage）和 VideoUpload（videoUrl）都传 `:upload-session="uploadSession"`
|
||
|
||
## 验证步骤
|
||
|
||
### 后端编译验证
|
||
1. 杀进程 → `dotnet build` → 启动后端
|
||
2. 浏览器访问 `http://localhost:5041/swagger`，确认 DELETE `/api/system/upload` 端点存在
|
||
3. 查看启动日志，确认 `PendingUploads` 表建表 SQL 执行成功
|
||
|
||
### 前端 HMR 验证
|
||
1. Vite dev server 已运行（http://localhost:5173）
|
||
2. 改动文件后观察 HMR 日志无编译错误
|
||
3. `npm run build` 验证生产构建通过
|
||
|
||
### 功能场景测试（关键）
|
||
|
||
#### 场景 1：新增分类 - 取消表单
|
||
1. 进入分类管理 → 点击「新增分类」
|
||
2. 上传一个图标（看到预览）
|
||
3. **不点确定，点取消**
|
||
4. 预期：后端日志显示 DELETE `/api/system/upload` 调用，COS/本地存储中该文件被删除
|
||
|
||
#### 场景 2：新增分类 - 替换图标后取消
|
||
1. 新增分类 → 上传图标 A
|
||
2. 点击「更换图片」→ 上传图标 B
|
||
3. 预期：图标 A 立即被 DELETE（前端替换时清理）
|
||
4. 点击取消
|
||
5. 预期：图标 B 被 DELETE（cleanupPending 清理）
|
||
|
||
#### 场景 3：编辑分类 - 替换图标后保存
|
||
1. 编辑已有分类 → 上传新图标
|
||
2. 点击确定保存
|
||
3. 预期：后端 Service Update 方法删除旧文件（已保存的 COS 文件）+ ConsumeAsync 新文件
|
||
|
||
#### 场景 4：编辑分类 - 替换图标后取消
|
||
1. 编辑已有分类（已有图标 A）→ 上传新图标 B
|
||
2. 点击取消
|
||
3. 预期：图标 B 被 DELETE（pending 清理）；图标 A 保留（已消费，不在 pending 列表）
|
||
|
||
#### 场景 5：编辑分类 - 删除图标后取消
|
||
1. 编辑已有分类（已有图标 A）→ 点击图标上的「删除」按钮
|
||
2. 预期：图标 A **不会被删除**（currentKey 为空，因为 A 是后端加载的已保存文件，不是本次会话上传的）
|
||
3. 点击取消
|
||
4. 预期：无 pending 文件需要清理（currentKey 为空）
|
||
|
||
#### 场景 6：项目编辑 - 封面+视频，取消
|
||
1. 进入项目编辑 → 替换封面 + 上传新视频
|
||
2. 点击「取消」返回列表
|
||
3. 预期：goBack 调用 cleanupPending，新上传的封面和视频都被 DELETE
|
||
|
||
#### 场景 7：系统设置 - Logo 上传后切换页面
|
||
1. 进入系统设置 → 上传新 Logo（未点保存）
|
||
2. 直接点击侧边栏跳转到其他页面
|
||
3. 预期：onBeforeUnmount 触发 cleanupPending，新 Logo 被 DELETE
|
||
|
||
#### 场景 8：GC 兜底
|
||
1. 上传文件后强制关闭浏览器（模拟用户中途离开）
|
||
2. 等待 24 小时（或临时调整 `UploadCleanupJob.ExpireHours` 为 0 立即触发）
|
||
3. 预期：后端 GC 任务清理该 pending 文件
|
||
|
||
## 假设与决策
|
||
|
||
- **假设 1**：后端编译只需通过，无新错误（之前已有 2 个无害 nullable 警告）
|
||
- **假设 2**：前端 Vite dev server 在 5173 端口可用
|
||
- **决策 1**：IconUpload 内部维护 `currentKey`，仅当 currentKey 非空时（即用户本次会话主动上传）才在 delete/replace 时调 DELETE；从后端加载的已保存文件（currentKey 为空）不删，避免误删已消费文件
|
||
- **决策 2**：`useUploadSession` 通过 onBeforeUnmount 自动 cleanup，作为兜底；显式调用 cleanupPending 用于「取消按钮」「goBack」等需要立即清理的场景
|
||
- **决策 3**：保存成功后必须调 `reset()` 清空 pending 列表，防止 onBeforeUnmount 重复 DELETE 已被后端消费的文件（DeletePendingAsync 会因 ConsumedAt != null 而拒绝删除，但调用本身是无意义的网络请求）
|
||
- **决策 4**：cleanupPending 内部对每个 DELETE 用 `.catch(() => {})` 静默失败，不阻塞 UX
|
||
- **决策 5**：批量并发删除使用 `Promise.all`，不串行等待，避免取消表单时长时间卡顿
|
||
|
||
## 实施顺序
|
||
|
||
1. 阶段 A：后端编译验证
|
||
2. 阶段 B1：api/index.ts 改造
|
||
3. 阶段 B2：useUploadSession composable
|
||
4. 阶段 C1：IconUpload.vue 改造
|
||
5. 阶段 C2：VideoUpload.vue 改造
|
||
6. 阶段 D：9 个页面逐一改造（先 Categories.vue 跑通，再批量套用模式）
|
||
7. 验证：HMR + 8 个功能场景测试
|