# Changelog / 更新日志

All notable non-WebUI user-visible changes should be documented in this file, newest version on top.
本文件记录所有非 WebUI 的重要用户可见变更，最新版本在最上方。

The format loosely follows Keep a Changelog and can be adapted to the team's habits.
本文档参考了 Keep a Changelog 的思路，也可以根据团队习惯调整。

## [Unreleased]

### Changed / 变更

- Add ordered migration system with `schema_migrations` tracking and pg advisory lock for safe multi-replica schema evolution. Existing databases are auto-baselined. To change the schema, add a new `NNNN_description.sql` file under `backend/internal/db/migrations/`; never modify an already-applied file. No down migrations — rollback via backup, fix-forward.
- 新增有序迁移系统，通过 `schema_migrations` 表和 pg advisory lock 实现安全的多副本 schema 演进，已有数据库自动基线化。修改 schema 时在 `backend/internal/db/migrations/` 下新增 `NNNN_description.sql`，已应用的文件不可修改。不支持 down 迁移——回滚靠备份，fix-forward。

### Fixed / 修复

- Serve goroutine `log.Fatalf` replaced with channel-based shutdown to preserve graceful teardown (B14).
- 服务 goroutine 中的 `log.Fatalf` 改为 channel 通知方式，确保优雅关停流程不被绕过（B14）。
- `DATABASE_URL` is now validated at startup (required, parseable); empty `REDIS_URL` logs a clear "redis disabled" message (B15).
- `DATABASE_URL` 在启动时校验（必填、可解析）；空 `REDIS_URL` 记录明确的 "redis disabled" 日志（B15）。
- `scripts/smoke.sh` aligned with current API contract, removed ignored `root_path` field (B17).
- `scripts/smoke.sh` 对齐当前 API 契约，移除被忽略的 `root_path` 字段（B17）。

### Added / 新增

- CI workflow (`.github/workflows/ci.yml`) compatible with both GitHub Actions and Gitea Actions.
- CI 工作流（`.github/workflows/ci.yml`），兼容 GitHub Actions 和 Gitea Actions。

### Added / 新增

- API: per-user bookmarks — `GET/POST /api/books/:id/bookmarks` (locator+percent snapshot with optional ≤500-char note; list ordered by percent) and `PATCH/DELETE /api/bookmarks/:id`; not-yours uniformly 404. New `bookmarks` table keyed like progress, cleaned up with the user (no cascade on book delete, same precedent).
- API：新增按用户隔离的书签——`GET/POST /api/books/:id/bookmarks`（存当前 locator+percent，备注可选、≤500 字，列表按进度升序）与 `PATCH/DELETE /api/bookmarks/:id`；不属于自己的一律 404。新 `bookmarks` 表与进度同款定位键，随用户删除而清（删书不级联，沿用既有先例）。

- API: CBZ page indexing now skips macOS packaging junk (`__MACOSX/…` and `._*` AppleDouble files), which used to land in the page list as ~163-byte black "pages"; `GET /api/books/:id/pages` additionally returns `chapters:[{title,start}]` derived from the archive's folder structure (e.g. 第1話…), so per-folder comics expose their real organization.
- API：CBZ 页索引现会跳过 macOS 打包垃圾（`__MACOSX/…` 与 `._*` 资源叉文件），此前它们以 ~163 字节黑页混入页列表；`GET /api/books/:id/pages` 新增 `chapters:[{title,start}]`，按压缩包内目录结构（如 第1話…）给出真实章节。

- 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 / 变更

- Scanner: an image-list-less archive (`.zip`/`.cbz` with no page images — video packs, document dumps) is now recorded as `state=error` ("no images in archive") instead of registering as an empty CBZ with a blank reader.
- 扫描器：不含任何图片条目的 `.zip`/`.cbz`（视频包、文档包）现记录为 `state=error`（"no images in archive"），不再注册成空 CBZ 留下一个白板阅读器。

- 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.
- Docs: `docs/README.md` is now the English primary; previous Chinese README mirrored to `docs/README_zh.md`.