feat(upload): add programmatic Ingest service and file-upload skill

Introduce upload/ingest as the single domain entry for storing files, writing w_uploads records, and maintaining incremental stats. Refactor HTTP UploadFile and delete handlers to delegate to ingest, fix stats decrement ordering on Remove, and document usage in the file-upload skill.
2026-10-05 15:26:36 +08:00 · 2026-06-18 14:56:19 +08:00
parent 9c6c697d95
commit 1cad0c5c55
13 changed files with 995 additions and 192 deletions
@@ -0,0 +1,265 @@
+---
+name: "file-upload"
+description: "Wavelet 项目专用：当业务需要上传文件、读取已上传文件、在 Worker/任务中程序化摄取字节流、选择存储引擎能力、或排查 w_uploads / 文件统计异常时必须使用。本技能指导 storage 与 upload 分层、upload.Ingest 策略选型、前后端接入与禁止旁路写表。"
+---
+
+# 存储引擎与文件上传开发规范
+
+本技能是 Wavelet **文件上传与对象存储**的唯一开发指导。开始开发前先阅读仓库根目录 [AGENTS.md](file:///Users/ryan/DEV/Go/Wavelet/AGENTS.md)，遵守项目级核心规则。
+
+---
+
+## 架构分层（必须理解）
+
+Wavelet 将「对象存储」与「上传业务」分为两层，**禁止混用职责**：
+
+| 层级 | 包路径 | 职责 | 业务是否直接调用 |
+| :--- | :--- | :--- | :--- |
+| **对象存储引擎** | `internal/storage` | `Backend` 接口：`Put` / `Get` / `Delete` / `Test`；按配置切换 Local / S3 / R2 / OSS / WebDAV | **禁止**（仅 upload 域内部使用） |
+| **上传域服务** | `internal/apps/upload` | `w_uploads` 记录、权限、秒传、统计、文件服务、`upload.Ingest` | **必须** |
+| **上传 HTTP 入口** | `internal/apps/upload/handler` | `POST /api/v1/upload` 等 multipart 接口 | 前端 / 用户侧上传 |
+| **文件访问** | `internal/apps/upload/filesrv` | `GET /f/:id` 流式响应、访问控制、图片 WebP 压缩 | 展示 / 下载 |
+
+```text
+业务模块 ──► upload.Ingest / upload.Remove（唯一写入门禁）
+                ├── storage.Backend.Put/Get/Delete
+                ├── repository.CreateUpload（仅 upload 内部）
+                └── RecordUploadStatsAdd/Remove（ingest 内置，禁止业务直调）
+```
+
+---
+
+## 核心防线（Guardrails）
+
+以下写法**一律禁止**：
+
+```go
+// ❌ 业务包直接写 blob
+storage.Active(ctx); backend.Put(...)
+
+// ❌ 旁路写 w_uploads
+db.DB(ctx).Create(&model.Upload{})
+repository.CreateUpload(ctx, upload)   // 仅 internal/apps/upload 允许
+
+// ❌ 手动维护统计
+upload.ApplyUploadStatsAdd(ctx, upload)  // 已 Deprecated
+
+// ❌ 业务表存物理路径
+invoice.FilePath = "uploads/2026/01/02/123.pdf"
+```
+
+**正确做法**：业务表只存 `upload_id`（`uint64` / JSON string），通过 `/f/{id}` 或 `upload.OpenStoredObject` 访问。
+
+---
+
+## Ingest 策略选型（Policy Decision）
+
+根据场景选择 `upload.Ingest` 的 `Policy`：
+
+| 场景 | Policy | 哈希命中时 | 未命中时 | 典型调用方 |
+| :--- | :--- | :--- | :--- | :--- |
+| 用户 HTTP 上传（含秒传） | `PolicyDedupNewRecord` | 复用 path，**新建记录 + 统计** | 写 blob + 新建记录 + 统计 | `handler.UploadFile`（已内置） |
+| Worker 生成全新文件 | `PolicyCreate` | 不查重，始终写 blob + 记录 | 同左 | 报表导出、定时生成 |
+| 镜像 / 去重摄取（Pixez） | `PolicyResolveExisting` | **直接返回已有记录**，不建新记录、不加统计 | 写 blob + 新建记录 + 统计 | 异步镜像任务 |
+| 业务只需引用已有文件 | 不调 Ingest | — | — | 业务 API 校验 `upload_id` 即可 |
+
+### Result 字段含义
+
+| 字段 | 含义 |
+| :--- | :--- |
+| `Created` | 是否新建了 `w_uploads` 记录 |
+| `Stored` | 是否写入了新 blob |
+| `Resolved` | 是否通过哈希解析到已有记录（仅 `PolicyResolveExisting`） |
+
+---
+
+## 后端：程序化上传（Worker / 业务逻辑）
+
+### 标准模板
+
+在 `logics.go`（接受 `context.Context`，不依赖 `*gin.Context`）中调用：
+
+```go
+import (
+    "bytes"
+
+    "github.com/Rain-kl/Wavelet/internal/apps/upload"
+    "github.com/Rain-kl/Wavelet/internal/model"
+)
+
+func ingestMirrorFile(ctx context.Context, userID uint64, data []byte, hash, filename, mime, ext string) (model.Upload, error) {
+    accessMode := 1
+    result, err := upload.Ingest(ctx, upload.IngestRequest{
+        UserID:     userID,
+        Reader:     bytes.NewReader(data),
+        Size:       int64(len(data)),
+        FileName:   filename,
+        MimeType:   mime,
+        Extension:  ext,
+        Hash:       hash, // 必填：SHA-256 hex
+        Type:       "your_biz_type",
+        AccessMode: &accessMode,
+        Metadata: model.UploadMetadata{
+            Extra: map[string]any{"source": "worker"},
+        },
+        Policy: upload.PolicyResolveExisting,
+    })
+    if err != nil {
+        return model.Upload{}, err
+    }
+    return result.Upload, nil
+}
+```
+
+### Request 关键字段
+
+| 字段 | 说明 |
+| :--- | :--- |
+| `Hash` | **必填**，推荐 SHA-256 hex；用于秒传 / 镜像去重 |
+| `Type` | 业务分类（如 `avatar`、`invoice`、`pixez_mirror`），用于筛选与统计 |
+| `AccessMode` | `nil` 时按 type 默认：`avatar` → 公开(1)，其余 → 私有(0) |
+| `SkipExtensionCheck` | Worker 场景若已自行校验扩展名，可设为 `true` |
+| `ObjectKeyFn` | 可选自定义存储路径；默认 `uploads/YYYY/MM/DD/{id}.{ext}` |
+
+### 错误处理
+
+| 错误 | 含义 | Handler 映射建议 |
+| :--- | :--- | :--- |
+| `upload.ErrIngestStorageReadOnly` | 存储迁移维护中 | `response.AbortConflict` |
+| `ingest.ErrForbidden` | 无权删除他人文件 | HTTP 403 |
+| `shared.ErrUnsupportedFormat` | 扩展名不在白名单 | `response.AbortBadRequest` |
+
+### 删除
+
+```go
+// 管理员 / 系统删除
+_, err := upload.Remove(ctx, uploadID)
+
+// 用户删除自己的文件
+_, err := upload.RemoveOwned(ctx, userID, uploadID)
+```
+
+### 读取已存储对象（不上传）
+
+```go
+uploadRec, err := repository.GetActiveUploadByID(ctx, uploadID)
+obj, err := uploadstorage.OpenStoredObject(ctx, &uploadRec)
+defer obj.Body.Close()
+```
+
+或通过门面（若已从 `exports` 暴露 `OpenStoredObject`）读取。HTTP 对外访问统一走 `GET /f/:id`。
+
+---
+
+## 后端：业务 API 引用已上传文件
+
+推荐 **两步流程**（先上传、后提交业务）：
+
+1. 前端 `POST /api/v1/upload` → 获得 `upload.id`
+2. 业务 API 接收 `upload_id`，用 `repository.GetActiveUploadByID` 校验存在且 `status` 为 active
+3. （可选）校验 `upload.Type` 是否为预期业务类型
+4. 将 `upload_id` 写入业务表字段（如 `cover_file_id`）
+
+**禁止**在业务 Handler 中重复实现 multipart 解析，除非有极强的特殊协议需求。
+
+---
+
+## 前端：用户侧上传
+
+使用 `frontend/lib/services/upload/`：
+
+```typescript
+import { services } from '@/lib/services'
+import { getFileUrl } from '@/lib/services/upload'
+
+// 上传
+const upload = await services.upload.uploadFile(file, 'invoice', { orderId: '123' })
+
+// 展示
+const url = getFileUrl(upload.id) // → /f/{id}
+
+// Base64 图片（头像等）
+const res = await services.upload.uploadBase64Image(croppedBase64, 'avatar', 'avatar.png')
+```
+
+### 前端规范
+
+- 新增上传相关 API 时，扩展 `UploadService` / `AdminUploadService`，在 `frontend/lib/services/index.ts` 注册
+- 图片预览使用 `getFileUrl(id, quality?)` 或 `FileImagePreview` 组件
+- 业务表单项只提交 `upload_id`，不要提交 blob URL 或 `file_path`
+
+---
+
+## 统计与排查
+
+`w_upload_stats` 由 `upload.Ingest` / `upload.Remove` **自动维护**，业务不得手动增量。
+
+若发现 trend / total 与 `w_uploads` 不一致（常见于历史旁路写表）：
+
+```go
+upload.RebuildUploadStats(ctx) // 从 w_uploads 全量重建统计
+```
+
+排查清单：
+
+1. 业务是否绕过 `upload.Ingest` 直接 `db.Create(&model.Upload{})`？
+2. 是否手动调用已 Deprecated 的 `ApplyUploadStatsAdd`？
+3. 删除是否走 `upload.Remove`（须在软删**前**扣减统计）？
+
+---
+
+## 测试要求
+
+### 后端 ingest 测试
+
+- 使用 `testhelper.SetupTestEnvironment(t)` 初始化 DB
+- 存储 mock：`storage.MockStorage(...)` + `storage.IsEnabledFunc = func() bool { return true }`
+- **禁止**在源码目录硬编码 `uploads/test` 路径；本地文件测试用 `t.TempDir()` 或 mock backend
+- 覆盖：三种 Policy、Remove 后统计归零、ReadOnly 拒绝写入
+
+参考：[internal/apps/upload/ingest/ingest_test.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/upload/ingest/ingest_test.go)
+
+### Handler 回归
+
+修改 upload handler 后运行：
+
+```bash
+go test ./internal/apps/upload/...
+make code-check
+```
+
+若变更 HTTP 接口，运行 `make swagger`。
+
+---
+
+## 存量代码迁移（旁路写表 → Ingest）
+
+将以下模式：
+
+```go
+storage.Active(ctx)
+backend.Put(ctx, key, reader, size, mime)
+db.DB(ctx).Create(&upload)
+```
+
+替换为：
+
+```go
+upload.Ingest(ctx, upload.IngestRequest{ Policy: upload.PolicyResolveExisting, ... })
+```
+
+迁移完成后执行一次 `upload.RebuildUploadStats(ctx)` 修复历史统计偏差。
+
+---
+
+## 质量门禁 Checklist
+
+完成文件上传相关开发后，确认：
+
+- [ ] 业务模块无 `repository.CreateUpload` / `SoftDeleteUpload` 调用
+- [ ] 业务模块无 `storage.Active` + `Put` 直接写文件
+- [ ] 业务表存 `upload_id`，不存 `file_path`
+- [ ] Worker 摄取使用正确的 `Policy`
+- [ ] 新增测试覆盖 ingest 路径
+- [ ] `make code-check` 通过
+- [ ] HTTP 变更已 `make swagger`