From 26111e73af4ae4f6ce34ec773ede539357d4b14c Mon Sep 17 00:00:00 2001
From: XingfenD <xingfen.fendy@outlook.com>
Date: Mon, 14 Sep 2026 19:38:16 +0800
Subject: [PATCH] docs: changelog + README updates for batch A (migrations, CI,
 B14/B15/B17)

---
 docs/CHANGELOG.md | 19 +++++++++++++++++++
 docs/README.md    | 17 ++++++++++++++++-
 docs/README_zh.md | 17 ++++++++++++++++-
 3 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 80a7f8a..dff0d81 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,25 @@ The format loosely follows Keep a Changelog and can be adapted to the team's hab
 
 ## [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).
diff --git a/docs/README.md b/docs/README.md
index 95e5f99..5f065b3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -68,7 +68,22 @@ Book files: move the contents of the old host `./library/` into `deploy/api/stor
 
 ## Read this before changing the schema
 
-`db.Migrate` only runs the `CREATE TABLE IF NOT EXISTS` statements of `schema.sql` — column adds/changes **do not take effect** on existing databases. Before any column change, introduce a `schema_migrations` version table + ordered migrations, otherwise old deployments silently run on the old shape.
+Schema changes go through the ordered migration system in `backend/internal/db/migrations/`:
+
+1. Create a new file: `NNNN_description.sql` (four-digit sequence number, lowercase snake_case).
+2. Never modify an already-applied migration file — they are immutable.
+3. No down migrations: rollback via database backup, fix-forward.
+4. Existing databases are auto-baselined on first startup (0001 marked applied without re-running DDL).
+5. Migrations run with `pg_advisory_lock` so `--scale api=N` replicas serialize safely.
+
+Local gate before each batch merge: `go vet ./... && gofmt -l . && go test -p 1 -count=1 ./...` with dev PG+Redis running.
+
+## CI
+
+- Workflow: `.github/workflows/ci.yml` (standard GitHub Actions syntax, Gitea Actions compatible).
+- **Gitea**: register an `act_runner` instance, enable Actions in repo settings. Works out of the box.
+- **GitHub**: works out of the box.
+- Until a runner is registered, run the local gate manually before merging.
 
 ## PWA
 
diff --git a/docs/README_zh.md b/docs/README_zh.md
index 902e02d..e49e612 100644
--- a/docs/README_zh.md
+++ b/docs/README_zh.md
@@ -68,7 +68,22 @@ docker volume rm book-comic-library_pgdata book-comic-library_cache
 
 ## 改 schema 前必读
 
-`db.Migrate` 只执行 `schema.sql` 的 `CREATE TABLE IF NOT EXISTS`——对已存在的库**加列/改列不会生效**。任何列变更之前,必须先引入 `schema_migrations` 版本表 + 有序迁移脚本,否则老部署会静默跑在旧结构上。
+Schema 变更通过 `backend/internal/db/migrations/` 中的有序迁移系统执行：
+
+1. 新建文件：`NNNN_description.sql`（四位序号，小写下划线命名）。
+2. 已应用的迁移文件不可修改——它们是不可变的。
+3. 不支持 down 迁移：回滚靠数据库备份，fix-forward。
+4. 已有数据库在首次启动时自动基线化（0001 标记为已应用，不重跑 DDL）。
+5. 迁移使用 `pg_advisory_lock` 确保 `--scale api=N` 副本串行执行。
+
+每批合入前的本地门禁：`go vet ./... && gofmt -l . && go test -p 1 -count=1 ./...`（需启动 dev PG+Redis）。
+
+## CI
+
+- 工作流：`.github/workflows/ci.yml`（标准 GitHub Actions 语法，兼容 Gitea Actions）。
+- **Gitea**：注册 `act_runner` 实例，在仓库设置中启用 Actions，开箱即用。
+- **GitHub**：开箱即用。
+- Runner 注册前，合入前手动执行本地门禁。
 
 ## PWA