test: portsfake + router contract test + handler unit tests (Task 27)

- 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)

backend/cmd/webui/api/router_test.go

@@ -7,7 +7,6 @@ import (
 	"time"
 
 	"booklib/internal/config"
-	"booklib/internal/redispkg"
 )
 
 func testCfg() *config.Config {
@@ -16,7 +15,7 @@ func testCfg() *config.Config {
 }
 
 func TestHealthz(t *testing.T) {
-	r := NewRouter(testCfg(), nil, redispkg.New(""), nil, nil, nil)
+	r := NewRouter(testCfg(), nil, nil, nil, nil, nil, nil, nil, nil, nil)
 	req := httptest.NewRequest(http.MethodGet, "/api/healthz", nil)
 	w := httptest.NewRecorder()
 	r.ServeHTTP(w, req)
@@ -24,3 +23,56 @@ func TestHealthz(t *testing.T) {
 		t.Fatalf("healthz = %d, want 200", w.Code)
 	}
 }
+
+// TestRouterContract 钉死全量路由表(Task 27):增删改任何路由都会使此测试失败,
+// 必须显式更新——路由即对外契约。
+func TestRouterContract(t *testing.T) {
+	r := NewRouter(testCfg(), nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	want := map[string]bool{
+		"GET /api/healthz":                    true,
+		"POST /api/auth/login":                true,
+		"GET /api/auth/me":                    true,
+		"GET /api/users":                      true,
+		"POST /api/users":                     true,
+		"DELETE /api/users/:id":               true,
+		"GET /api/libraries":                  true,
+		"POST /api/libraries":                 true,
+		"POST /api/libraries/:id/scan":        true,
+		"POST /api/libraries/:id/upload":      true,
+		"POST /api/libraries/:id/upload/init": true,
+		"GET /api/uploads/:uid":               true,
+		"POST /api/uploads/:uid/complete":     true,
+		"PUT /api/uploads/:uid/parts/:index":  true,
+		"GET /api/books":                      true,
+		"GET /api/books/:id":                  true,
+		"DELETE /api/books/:id":               true,
+		"GET /api/books/:id/cover":            true,
+		"GET /api/books/:id/file":             true,
+		"GET /api/books/:id/pages":            true,
+		"GET /api/books/:id/pages/:n":         true,
+		"PUT /api/books/:id/progress":         true,
+		"GET /api/progress":                   true,
+		"GET /api/books/:id/bookmarks":        true,
+		"POST /api/books/:id/bookmarks":       true,
+		"PATCH /api/bookmarks/:id":            true,
+		"DELETE /api/bookmarks/:id":           true,
+	}
+	got := map[string]bool{}
+	for _, rt := range r.Routes() {
+		key := rt.Method + " " + rt.Path
+		if got[key] {
+			t.Errorf("duplicate route %s", key)
+		}
+		got[key] = true
+	}
+	for k := range want {
+		if !got[k] {
+			t.Errorf("missing route %s", k)
+		}
+	}
+	for k := range got {
+		if !want[k] {
+			t.Errorf("unexpected route %s", k)
+		}
+	}
+}