feat: 支持 targetDir 指定上传目标目录（网盘式），固定路径模式不变

- 改动：init/check 接受可选 targetDir（相对 CloudDir，SanitizeDir 校验），merge 物理落盘 CloudDir/<targetDir>/
- 秒传跨目录 copy-on-hit：库把旧物理文件复制进目标目录，OnInstantHit 携带新路径；源缺失回退正常上传
- 断点续传按目录隔离：同 MD5 在途任务目录不同则另起新任务
- TaskInfo 新增 TargetDir（宿主须持久化）；Repository 12 方法接口零变更，向后兼容 v1.0.x
- 新增 dir.go（SanitizeDir/路径拼装反解/copyFile）与 service_test.go（10 个用例：双模式秒传/续传隔离/merge 回归）
- 原因：上传位置原本固定在 CloudDir 根，宿主无法实现网盘式选目录上传

README.md

@@ -1,7 +1,7 @@
 # fileupload
 
 通用大文件分片上传 Go/Gin 服务端核心（独立库，原 zogo/fileupload 子包）。
-六接口（init/chunk/merge/check/task/abort）+ 分片幂等 + 断点续传 + `.part` 原子改名 + 合并整文件 MD5 校验 + 秒传。
+六接口（init/chunk/merge/check/task/abort）+ 分片幂等 + 断点续传 + `.part` 原子改名 + 合并整文件 MD5 校验 + 秒传 + 目标目录（targetDir）。
 不依赖宿主的响应封装、ORM 或业务表——存储走 `Repository` 接口注入，业务衔接走 `Options` 回调。
 
 ## 用法
@@ -11,7 +11,7 @@ import "git.zeroonesoft.cn/golib/fileupload"
 
 opts := fileupload.Options{
     ChunkRoot:      "./data/upload-chunks",        // 分片临时目录（建议在静态根之外）
-    CloudDir:       "./data/uploads/cloud",        // 合并产物目录
+    CloudDir:       "./data/uploads/cloud",        // 合并产物目录（targetDir 的根）
     WebPathPrefix:  "cloud",                       // storagePath 的 Web 前缀（须与 CloudDir 相对静态根的子目录一致）
     URLPrefix:      "/uploads",                    // fileUrl = URLPrefix + "/" + storagePath
     MaxTotalSizeMB: 2048,                          // 0=不限
@@ -20,7 +20,7 @@ opts := fileupload.Options{
         return nil
     },
     OnInstantHit: func(t fileupload.TaskInfo) error {
-        // 秒传命中：宿主确保业务侧可见行（可空回调）
+        // 秒传命中：宿主确保业务侧可见行（可空回调）；跨目录命中时携带新 StoragePath/TargetDir
         return nil
     },
     Envelope: func(c *gin.Context, resp any, err error) {
@@ -36,6 +36,29 @@ _ = fileupload.Mount(api.Group("/upload"), opts, myRepo,
 `Repository`（12 个方法）由宿主按自己的表结构实现；软删/硬删自定，但删除后查询必须不可见。
 鉴权由宿主路由组的 JWT 中间件统一负责，本库不感知。
 
+## 目标目录（targetDir）
+
+上传位置不再固定：init 请求可带 `targetDir`（相对 `CloudDir`，`/` 分隔，**空=根目录**），
+合并产物物理落盘 `CloudDir/<targetDir>/<产物名>`，storagePath = `WebPathPrefix + "/" + targetDir + "/" + 产物名`。
+`/check` 亦接受可选 query `targetDir`。宿主可用 `fileupload.SanitizeDir` 复用同款目录校验
+（拒绝 `..`/`.`/空段/绝对路径/Windows 非法字符，限长 500、限深 16）。
+
+三档宿主形态（服务端无模式概念，字段缺省即固定路径模式，v1.0.x 行为不变）：
+
+| 形态 | 客户端行为 | 服务端表现 |
+|---|---|---|
+| 固定路径（默认） | 不传 targetDir | 与 v1.0.x 完全一致，落 CloudDir 根 |
+| 固定子目录 | 每次上传带同一 targetDir | 固定落该子目录 |
+| 网盘式自选 | 用户选目录后随 init 传入 | 落所选子目录，`MkdirAll` 自动创建 |
+
+语义要点：
+
+- **秒传 copy-on-hit**：秒传按全局 MD5 命中。同目录（含根目录）命中直接复用旧文件；跨目录命中由库把旧物理文件复制进目标目录，`OnInstantHit` 携带新 `StoragePath`/`TargetDir`；旧物理文件缺失或复制失败自动回退为正常分片上传。
+- **断点续传按目录隔离**：同 MD5 在途任务目标目录不同时不复用，另起新任务。
+- **宿主须持久化 `TaskInfo.TargetDir`**（建议 `upload_task` 加 `target_dir varchar(500)`）：不持久化时目录上传的断点续传会退化为每次新建任务，其余功能不受影响。
+
 ## 版本
 
-- v0.1.0 首版：自 FileUpload 项目 restful/upload 模块抽出
+- v1.1.0 新增 targetDir：init/check 支持目标目录，跨目录秒传 copy-on-hit，续传按目录隔离；Repository 接口零变更
+- v1.0.0 首个独立 tag：自 zogo/fileupload v0.3.2 抽出
+- v0.1.0 初版：自 FileUpload 项目 restful/upload 模块抽出