feat(upload): resumable chunked upload protocol for large files — init(parts≤32MB)/status/complete endpoints with fingerprint-derived deterministic uploadId (same file resumes, no restart), sessions in BOOKS_DIR/.uploads with 24h sweep, frontend uploadBook auto-switches >16MB to 8MB parts (retry x3 in place, skip received); oversize single POST now reports honest 413 too_large instead of "multipart field 'file' required" (was MaxBytesReader abort mislabeled); UPLOAD_MAX_MB wired into both compose stacks (cap total, .env.example 2048), nginx body limit drops to 32m; testCfg limit 1MB, CJK/fullwidth-colon filename proven unaffected; e2e verified with 311MB real file (39 parts, sha1 match)

2026-09-07 23:56:40 +08:00
parent aba1e58fa6
commit 7d650107d2
12 changed files with 540 additions and 10 deletions
@@ -8,8 +8,15 @@ The format loosely follows Keep a Changelog and can be adapted to the team's hab

 ## [Unreleased]

+### Added / 新增
+
+- API: resumable chunked upload protocol for large files — `POST /api/libraries/:id/upload/init` (fingerprint-derived deterministic `uploadId`, rejects totals over `UPLOAD_MAX_MB` with `413 too_large`), `PUT /api/uploads/:uid/parts/:index` (parts ≤ 32MB), `GET /api/uploads/:uid` (received parts, for resume), `POST /api/uploads/:uid/complete` (assemble + atomic land, same path contract as single-POST upload). Sessions persist under `BOOKS_DIR/.uploads/` with 24h opportunistic sweep. `UPLOAD_MAX_MB` is now wired through both compose stacks/`.env`; `.env.example` sets 2048 and drops `NGINX_CLIENT_MAX_BODY_SIZE` to 32m (nginx only ever sees one chunk).
+- API: 新增大文件可续传分片上传协议——`POST /api/libraries/:id/upload/init`（按指纹派生确定性 `uploadId`，总量超 `UPLOAD_MAX_MB` 返回 `413 too_large`）、`PUT /api/uploads/:uid/parts/:index`（单片 ≤32MB）、`GET /api/uploads/:uid`（查询已传分片以续传）、`POST /api/uploads/:uid/complete`（拼接后原子落盘，返回与单发上传一致的 `path`）。会话存于 `BOOKS_DIR/.uploads/`，超 24h 顺手清理。`UPLOAD_MAX_MB` 已接入两份 compose/`.env`；`.env.example` 调至 2048 并将 `NGINX_CLIENT_MAX_BODY_SIZE` 降为 32m（nginx 只见单个分片）。
+
 ### Changed / 变更

+- API: upload over `UPLOAD_MAX_MB` now returns `413 too_large` with the limit in the message; previously the size abort was misreported as `400 bad_request "multipart field 'file' required"`.
+- API：超过 `UPLOAD_MAX_MB` 的上传现在返回 `413 too_large` 并在消息中带上限额；此前体积超限被误报为 `400 bad_request "multipart field 'file' required"`。
 - API: `POST /api/libraries` now takes only `{name}`; `root_path` is generated server-side as `BOOKS_DIR/<sanitized name>` (no client-supplied paths, validated at creation).
 - API：`POST /api/libraries` 只需 `{name}`；`root_path` 由服务端生成为 `BOOKS_DIR/<清洗后的库名>`（不再接受客户端指定路径，创建时即校验）。
 - Repo structure conformed to `AGENTS.md`: `web/` renamed to `frontend/`; backend HTTP layer moved from `internal/api` to `cmd/webui/{api,handlers}` (`cmd/server` → `cmd/webui`); README/CHANGELOGs relocated under `docs/` (`README_zh.md` added as Chinese mirror); module-level `.gitignore`s added (`backend/`, `deploy/`); stray root `library/` removed (book files live in `deploy/api/storage/`); debug binaries untracked.
@@ -10,6 +10,9 @@ The format loosely follows Keep a Changelog and can be adapted to the team's hab

 ### Added / 新增

+- Library uploads over 16MB now auto-switch to the resumable chunked protocol (8MB parts): failed parts retry in place up to 3 times and already-sent parts are skipped, so a flaky upload continues instead of starting over; small files keep the original single request.
+- 书库上传超过 16MB 自动切换为可续传分片协议（每片 8MB）：失败的分片原地重试至多 3 次，已传片自动跳过，中断后继续而不是从头再来；小文件仍走原单次上传。
+
 - Immersive reading for text & comics (微信读书/Mihon-style): tap the middle of the page to show/hide the reader header and control bar; controls now live in a slide-up bottom sheet — a progress slider jumps to any position (text) or page (CBZ), theme swatches (纸/米/夜) are WYSIWYG color dots, plus A−/A+ font size; body text is serif with a readable justified measure; all prefs persist (localStorage).
 - 文本与漫画进入沉浸阅读:点正文中央唤出/隐藏顶栏与工具条;控件收进底部滑出抽屉——进度/页码滑条直接跳到全书任意位置或任意页,主题改为所见即所得的色卡(纸/米/夜),保留 A−/A+ 字号;txt/md 正文为衬线、限宽两端对齐;偏好本地持久化。
 - CBZ adds reading modes — 连读 (continuous scroll) / 整页 (snap to page top) / 适高 (one page per screen, full width) — cycle button in the bar, choice remembered; tapping the left/right edges turns a page/screen and ←/→/PageUp/PageDown work too.