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.go

@@ -7,18 +7,16 @@ import (
 
 	"booklib/cmd/webui/handlers"
 	"booklib/internal/config"
-	"booklib/internal/media"
-	"booklib/internal/redispkg"
-	"booklib/internal/scanner"
-	"booklib/internal/store"
-	"booklib/internal/upload"
+	"booklib/internal/ports"
 )
 
-// NewRouter 是组合根:接受具体实现,分发给 handlers.New 的小口径 port 字段。
-// *store.Store 满足 5 个 store 接口,*redispkg.R 满足 RateLimiter。
-func NewRouter(cfg *config.Config, st *store.Store, rdb *redispkg.R, sc *scanner.Scanner, med *media.M, up *upload.U) *gin.Engine {
+// NewRouter 只依赖 port 接口:main.go 传具体实现(*store.Store 满足 5 个 store
+// 接口,*redispkg.R 满足 RateLimiter),测试传 portsfake。
+func NewRouter(cfg *config.Config, users ports.UserStore, libs ports.LibraryStore, books ports.BookStore,
+	progress ports.ProgressStore, bookmarks ports.BookmarkStore, rl ports.RateLimiter,
+	sc ports.Scanner, med ports.Media, up ports.UploadSessions) *gin.Engine {
 	gin.SetMode(gin.ReleaseMode)
-	h := handlers.New(cfg, st, st, st, st, st, rdb, sc, med, up)
+	h := handlers.New(cfg, users, libs, books, progress, bookmarks, rl, sc, med, up)
 	r := gin.New()
 	if e := r.SetTrustedProxies(cfg.TrustedProxies); e != nil {
 		panic(e)
@@ -31,17 +29,17 @@ func NewRouter(cfg *config.Config, st *store.Store, rdb *redispkg.R, sc *scanner
 	p := g.Group("", h.AuthMw())
 	p.GET("/auth/me", h.Me)
 
-	users := p.Group("/users", h.AdminOnly())
-	users.GET("", h.ListUsers)
-	users.POST("", h.CreateUser)
-	users.DELETE("/:id", h.DeleteUser)
+	usersGrp := p.Group("/users", h.AdminOnly())
+	usersGrp.GET("", h.ListUsers)
+	usersGrp.POST("", h.CreateUser)
+	usersGrp.DELETE("/:id", h.DeleteUser)
 
-	libs := p.Group("/libraries")
-	libs.GET("", h.ListLibraries)
-	libs.POST("", h.AdminOnly(), h.CreateLibrary)
-	libs.POST("/:id/scan", h.AdminOnly(), h.ScanLibrary)
-	libs.POST("/:id/upload", h.AdminOnly(), h.Upload)
-	libs.POST("/:id/upload/init", h.AdminOnly(), h.UploadInit)
+	libsGrp := p.Group("/libraries")
+	libsGrp.GET("", h.ListLibraries)
+	libsGrp.POST("", h.AdminOnly(), h.CreateLibrary)
+	libsGrp.POST("/:id/scan", h.AdminOnly(), h.ScanLibrary)
+	libsGrp.POST("/:id/upload", h.AdminOnly(), h.Upload)
+	libsGrp.POST("/:id/upload/init", h.AdminOnly(), h.UploadInit)
 
 	uploads := p.Group("/uploads", h.AdminOnly())
 	uploads.GET("/:uid", h.UploadStatus)