feat(fileupload): 并入通用大文件分片上传服务端核心

- 六接口（init/chunk/merge/check/task/abort）+ 分片幂等 + 断点续传 + .part 原子改名 + 合并整文件 MD5 校验 + 秒传 - 零宿主耦合：Repository 接口注入存储、Envelope 注入响应封装、 OnMerged/OnInstantHit 回调衔接业务（仅依赖既有 gin/uuid） - 自 FileUpload 项目 restful/upload 抽出；maintain-service 云端文件为其首个宿主
2026-09-25 15:11:30 +08:00
parent 40c9f62c9f
commit 33574d4ac2
5 changed files with 711 additions and 0 deletions
@@ -0,0 +1,41 @@
+# zogo/fileupload
+
+通用大文件分片上传 Go/Gin 服务端核心（zogo 子包）。
+六接口（init/chunk/merge/check/task/abort）+ 分片幂等 + 断点续传 + `.part` 原子改名 + 合并整文件 MD5 校验 + 秒传。
+不依赖宿主的响应封装、ORM 或业务表——存储走 `Repository` 接口注入，业务衔接走 `Options` 回调。
+
+## 用法
+
+```go
+import "git.zeroonesoft.cn/golib/zogo/fileupload"
+
+opts := fileupload.Options{
+    ChunkRoot:      "./data/upload-chunks",        // 分片临时目录（建议在静态根之外）
+    CloudDir:       "./data/uploads/cloud",        // 合并产物目录
+    WebPathPrefix:  "cloud",                       // storagePath 的 Web 前缀（须与 CloudDir 相对静态根的子目录一致）
+    URLPrefix:      "/uploads",                    // fileUrl = URLPrefix + "/" + storagePath
+    MaxTotalSizeMB: 2048,                          // 0=不限
+    OnMerged: func(t fileupload.TaskInfo) error {
+        // 合并成功：宿主写自己的业务表（如云盘记录行）；失败则 merge 整体失败
+        return nil
+    },
+    OnInstantHit: func(t fileupload.TaskInfo) error {
+        // 秒传命中：宿主确保业务侧可见行（可空回调）
+        return nil
+    },
+    Envelope: func(c *gin.Context, resp any, err error) {
+        // 宿主自己的响应封装，如 httpx.HandleResult(c, resp, err)
+    },
+}
+_ = fileupload.Mount(api.Group("/upload"), opts, myRepo,
+    fileupload.WithIdentity(func(c *gin.Context) (string, int64) {
+        return c.GetString("UserName"), c.GetInt64("TenantId")
+    }))
+```
+
+`Repository`（12 个方法）由宿主按自己的表结构实现；软删/硬删自定，但删除后查询必须不可见。
+鉴权由宿主路由组的 JWT 中间件统一负责，本库不感知。
+
+## 版本
+
+- v0.1.0 首版：自 FileUpload 项目 restful/upload 模块抽出