feat(series): fix one book's series, and keep removed books out (#2554)

[francisrath]

Summary

Fixing one book's series from the book, and keeping a book out of a series it was taken out of. This is the second half of #2554, split from #3057 at review (now merged); it builds on its series_aliases.

Refs #2554.

What changes

Edit metadata → Series	The author's series, No series and New series…, plus an optional position. Picking a series makes it the book's primary one and takes the book out of the series it was named under; No series takes it out of every series. Uses POST /series and POST /series/{id}/books, no new write endpoint
One primary per book	UpsertBookLink demotes the book's other series in the same transaction when it files a book as primary (#2525)
Removed stays removed	RemoveBookFromSeries records the removal in book_series_exclusions (migration 102), keyed by the series' provider id so it follows a merge through the aliases. LinkBookIfMissing, which every automatic path goes through, skips an excluded pair inside its INSERT. Adding the book back by hand clears it, and so does Unlock all fields by an admin
Restore	The book page lists the series the book was taken out of, with Restore, from GET /book/{id}/series-exclusions
Merge	Drops exclusions that resolve to the target for books in it, and those of a hand-made source
Users who aren't admins	Series controls are hidden from them on the series page, the book page, Edit metadata and the authors toolbar, since the server answers 403 (#468)
Smaller fixes	Position is optional in Add Book to Series, as on the server. The author page regroups its books by series after a refresh without a reload

Schema

CREATE TABLE book_series_exclusions (
    book_id            INTEGER  NOT NULL REFERENCES books(id) ON DELETE CASCADE,
    series_foreign_id  TEXT     NOT NULL,
    position_in_series TEXT     NOT NULL DEFAULT '',
    created_at         DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (book_id, series_foreign_id)
);

Suggested review order

1. 102_book_series_exclusions.sql, then RemoveBookFromSeries, LinkBookIfMissing, UpsertBookLink and the exclusion list/clear in internal/db/series.go, with series_exclusions_test.go
2. The merge step in internal/db/series_merge.go
3. internal/api/book_series_exclusions.go and the Unlock all change in internal/api/books.go
4. EditBookModal.tsx, then BookDetailPage.tsx
5. useIsAdmin and the gating on the series, book and authors pages
6. Docs: docs/API.md, "Fixing One Book's Series" in docs/Hardcover-Series-Wiki.md, changelog.d/2554-book-series.md

Checklist

• Every commit carries a Signed-off-by that matches its author (git commit -s)
• Changelog fragment added as changelog.d/2554-book-series.md
• Tests added or updated
• Wiki pages under docs/ updated
• No new dependency

Test plan

• gofmt, go vet ./..., golangci-lint v2.11.4 (0 issues)
• go test ./cmd/... ./internal/...
• cd web && npm run typecheck && npm run build && npm test (1861 passed)
• Atomicity checked with an aborting trigger; each review follow-up has a test that fails without it
• Manually on a local Docker build with the NB provider and Sigrid Undset's Kristin Lavransdatter, before the split (steps in feat(series): merge series, keeping the old ids as aliases (#2554) #3057). The four review follow-ups came after that and rely on their unit tests

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 85.37736% with 31 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/db/series.go	79.45%	10 Missing and 5 partials ⚠️
web/src/components/EditBookModal.tsx	91.93%	0 Missing and 5 partials ⚠️
web/src/pages/BookDetailPage.tsx	80.00%	1 Missing and 4 partials ⚠️
internal/api/book_series_exclusions.go	75.00%	2 Missing and 1 partial ⚠️
internal/api/series.go	83.33%	1 Missing and 1 partial ⚠️
web/src/pages/AuthorDetailPage.tsx	80.00%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[vavallee]

Thanks Francis, this is a really careful piece of work. The exclusion check sitting inside the INSERT in LinkBookIfMissing means every automatic writer (author sync, ABS and Calibre imports, rebind, list sync) honours it without any caller changing, and the merge handling through aliases is nice. Migration 102 looks safe to me, including running it again over its own table. I checked an upgrade from a database that has 106 but not 102, and a database that already has the table, and both come up fine. Mutating each guard makes your tests fail, which is what I wanted to see.

One thing I would like changed before merge. If you take a book out of a series and then click Add on that same book in the Hardcover missing list, the response says queued 1 but the book is not linked, because ensureHardcoverCatalogBook goes through LinkBookPreservingPrimary and the exclusion skips the link silently. The series page then keeps listing it as missing and Add can never fix it. For the explicit single book Add, which is the user asking for it, I think it should clear the exclusion first, the same way adding by hand does. Bulk fill should keep honouring it.

Smaller things, none blocking. If Edit metadata saves the series and then the book update fails, a retry with New series selected would create the series a second time. The Restore button is the same size as its neighbours but still under 44px on touch. Thanks again for splitting this out and for the tests.

[vavallee]

Thanks for the careful work on this, Francis. I pushed a few commits to your branch to cover the review. Add on a book you removed from a series now clears the removal and puts it back, so it no longer sits in the missing list forever. Fill all still leaves removed books out, and both cases have tests. In Edit metadata, a retry after a failed save no longer creates the new series a second time. I also gave Restore the touch hit area and merged main in, and a test fixture needed a small tweak after #2915 added the covered list. CI is green, so I am merging this.