- CHANGELOG [Unreleased]: consolidated the duplicated Added/Changed/Fixed
groups left by earlier batches into one group each (no entry dropped);
added batch C entries — port-based restructure, media/upload domain
packages, sweep moved to scanner ticker (B16), router contract test,
portsfake unit-test layer. Upload-sweep wording no longer promises the
old 24h opportunistic request-path behaviour.
- README.md / README_zh.md: new 'Backend structure' section documenting
the port/fake layout (cmd/webui composition root, handlers as HTTP-only,
internal/ports + portsfake, media/upload/store/scanner/bookfile
responsibilities) and the two-tier testing approach (real PG+Redis
integration vs fake-injected unit, route table pinned by contract test)
Gate: gofmt clean, go vet clean, go test -p 1 all pass (0 skip),
scripts/smoke.sh ALL SMOKE TESTS PASSED against a live webui on :18080
- seed.Admin: hand-rolled pgconn.PgError 23505 check → store.IsUniqueViolation
(single predicate for unique violations across the codebase)
- books.absBookPath: local hasPrefixDir (filepath.Rel-based) removed in favor
of bookfile.Contains, which also resolves symlinks — stricter escape check
- handlers isUnique alias + libraries.go local prefix check were already
folded into ports.IsUniqueViolation / bookfile.Contains in Task 25;
scanner.inside was folded in Task 24 — this commit closes the last two
Full gate green: gofmt, vet, go test -p 1 (real PG+Redis, 0 skip)
- internal/ports/portsfake: hand-written in-memory fakes for all 9 ports
(Users/Libraries/Books/Progress/Bookmarks/RateLimiter/Scanner/Media/Uploads);
error semantics mirror the real store exactly — pgx.ErrNoRows for misses,
store.ErrLastAdmin guard, and *pgconn.PgError{Code:23505} for unique
violations (ports.IsUniqueViolation only accepts the PgError shape, so the
fakes must produce it to exercise the 409 branch without touching prod code)
- Media/Uploads fakes are hook-programmable: one field per error branch, so a
test can force e.g. CompleteErr=ErrIncomplete without stubbing the rest
- Scanner fake is mutex-guarded + WaitForScan: handler fires ScanLibraryByID
in a goroutine, tests stay deterministic
- router_test.go: TestRouterContract pins all 27 routes — any route table
change now fails the test explicitly
- handler unit tests (~30 cases, no PG/Redis): users CRUD branches (self-delete
400, last-admin 400, dup 409, 204 ok), library reserved names (contract:
code=bad_request message=reserved_name, per original impl), upload sentinel
mapping (413/400/404 per branch)
- NewRouter takes pure port interfaces; main.go distributes *store.Store
across the 5 store ports at the composition root
Full gate green: gofmt, vet, go test -p 1 (real PG+Redis, 0 skip)
- H now holds only small port interfaces (UserStore/LibraryStore/BookStore/
ProgressStore/BookmarkStore/RateLimiter/Scanner/Media/UploadSessions);
NewRouter is the composition root distributing *store.Store and *redispkg.R
- ports.Media gains EnsurePage; ChaptersOf returns ports.Chapter (media's
local duplicate dropped); *media.M now provably satisfies ports.Media;
ports.UploadSessions gains LibraryID for root validation before Complete
- content.go: duplicated page-index cache + cover self-heal + page extract
logic removed in favor of media service — same redis keys, same contract;
path traversal check stays in handler (403 semantics preserved)
- getLibrary/getLibRow merged into getLib(c, id); idParam helper dedupes
:id parsing; isUnique replaced by ports.IsUniqueViolation (Task 28 partial)
- main.go assembles media + upload and passes upload.U as scanner Sweeper
Full gate green: gofmt, vet, go test -p 1 (real PG+Redis, 0 skip)
- internal/upload owns chunked-upload domain logic (fingerprint resume,
part tmp+rename, assemble, session sweep) and the shared UniquePath
helper used by both single-file and chunked completion paths
- handlers/uploads.go is now HTTP-only: bind params, call upload.U, map
sentinel errors to the unchanged status/code/message contract
- B16: session sweep moved out of the UploadInit request path onto the
scanner ticker via a Sweeper hook (upload.U satisfies it)
- unit tests for the package without PG/Redis; contract pinned by the
existing handler integration tests (all green)
XingfenD