OpenFlare/.agent/skills/file-upload/SKILL.md

name, description

name	description
file-upload	Wavelet 项目专用：当业务需要上传文件、读取已上传文件、在 Worker/任务中程序化摄取字节流、选择存储引擎能力、或排查 w_uploads / 文件统计异常时必须使用。本技能指导 storage 与 upload 分层、upload.Ingest 策略选型、前后端接入与禁止旁路写表。

存储引擎与文件上传开发规范

本技能是 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 压缩	展示 / 下载

业务模块 ──► upload.Ingest / upload.Remove（唯一写入门禁）
                ├── storage.Backend.Put/Get/Delete
                ├── repository.CreateUpload（仅 upload 内部）
                └── RecordUploadStatsAdd/Remove（ingest 内置，禁止业务直调）

---

核心防线（Guardrails）

以下写法一律禁止：

// ❌ 业务包直接写 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）中调用：

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

删除

// 管理员 / 系统删除
_, err := upload.Remove(ctx, uploadID)

// 用户删除自己的文件
_, err := upload.RemoveOwned(ctx, userID, uploadID)

读取已存储对象（不上传）

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/：

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 不一致（常见于历史旁路写表）：

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

Handler 回归

修改 upload handler 后运行：

go test ./internal/apps/upload/...
make code-check

若变更 HTTP 接口，运行 make swagger。

---

存量代码迁移（旁路写表 → Ingest）

将以下模式：

storage.Active(ctx)
backend.Put(ctx, key, reader, size, mime)
db.DB(ctx).Create(&upload)

替换为：

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