From 9c34a45ba6caaed99bd06c4dcbc2d3254d7410c0 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Thu, 19 Feb 2026 20:48:40 -0500 Subject: [PATCH] docs: Add verification checklist for Phase 4.6 Update the verification checklist to cover all aspects of Phase 4.6 (CreateCollection manual books support). New verification sections: - Section 6.4: Verify CreateCollection Endpoint Manual Books Support - Struct field verification (ManualBookIDs) - Validation tag verification (validate:"max=50") - Handler implementation verification - Error handling and logging verification - Graceful degradation verification - Section 19.1b: Verify Collections Bruno Tests Created - New bruno/collections/ directory structure - All 5 required test files - Test coverage verification - Section 19.1b: Verify Collections API Documentation - manual_book_ids field documentation - Validation limits (max 50) - Example requests - Error handling explanation - Backward compatibility notes Bug fix: - Fixed BuildSections function signature to match actual service (services.DashboardSection instead of services.SectionItems) All verification includes: - Step-by-step verification commands - Common pitfalls to avoid - Success criteria for each section --- CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md | 127 ++++++++++++++++++- 1 file changed, 125 insertions(+), 2 deletions(-) diff --git a/CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md b/CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md index 7a38694..e405f19 100644 --- a/CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md +++ b/CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md @@ -656,7 +656,7 @@ cd bruno/dashboard/ **Required function:** -- [ ] `BuildSections(items []services.SectionItems) []SectionData` in dashboard.go +- [ ] `BuildSections(sections []services.DashboardSection) []SectionData` in dashboard.go **Key requirements:** @@ -855,7 +855,66 @@ rg "manual_book_ids" internal/handlers/collections.go ls -la bruno/dashboard/preview-collection.bru ``` -### 6.4 Verify Config Setup +### 6.4 Verify CreateCollection Endpoint Manual Books Support + +**IMPORTANT: Custom Section Builder requires this feature** + +**Why this endpoint update is necessary:** +- Custom Section Builder allows users to select books manually + use filter rules +- Single API call creates collection + adds books (cleaner than separate calls) +- Reuses existing `AddBookToCollection` service method + +**For `internal/handlers/collections.go`:** + +**Struct updates:** +- [ ] `ManualBookIDs []string` field added to `CreateCollectionRequest` struct (after line 40) +- [ ] Field has JSON tag: `json:"manual_book_ids"` +- [ ] Field has validation tag: `validate:"max=50"` + +**Handler updates:** +- [ ] `CreateCollection` function updated (after line 97) +- [ ] Parses and validates `req.ManualBookIDs` +- [ ] Loops through manual book IDs +- [ ] Calls `h.collectionService.AddBookToCollection` for each valid book ID +- [ ] Logs errors for invalid book IDs but continues processing +- [ ] Logs summary of added books + +**Error handling:** +- [ ] Invalid book IDs are skipped (not added to collection) +- [ ] Errors are logged using `c.Logger().Errorf` +- [ ] Collection is still created even if some books fail to add +- [ ] Returns 201 on success (even if some books failed) + +**Validation:** +- [ ] Request validation checks manual_book_ids array length ≤ 50 +- [ ] Returns 400 if more than 50 book IDs provided +- [ ] Validation tag enforces max limit: `validate:"max=50"` + +**Verification commands:** +```bash +# Check ManualBookIDs field exists in struct +rg "ManualBookIDs.*\[\]string" internal/handlers/collections.go + +# Check validation tag is present +rg 'validate:"max=50"' internal/handlers/collections.go + +# Check CreateCollection handler processes manual books +rg "ManualBookIDs" internal/handlers/collections.go -A 30 + +# Verify AddBookToCollection is called +rg "AddBookToCollection.*ManualBookIDs" internal/handlers/collections.go -A 5 + +# Check error logging for invalid book IDs +rg "Logger.*Errorf.*Invalid book ID" internal/handlers/collections.go +``` + +**Common pitfalls:** +- Forgetting to validate array length (DoS vulnerability) +- Returning error on first invalid book ID (should continue processing) +- Not logging errors (makes debugging difficult) +- Creating separate service method (unnecessary - reuse existing) + +### 6.5 Verify Config Setup **CRITICAL: Config struct must be updated in 3 files** @@ -2852,6 +2911,36 @@ ls -la bruno/dashboard/*.bru 2>/dev/null | wc -l cd bruno/dashboard && bru run --env local ``` +### 19.1b Verify Collections Bruno Tests Created + +**Required files in `bruno/collections/` (NEW directory):** + +- [ ] `create-collection-with-manual-books.bru` - Create collection with manual books +- [ ] `create-collection-too-many-books.bru` - Validation test (max 50 books) +- [ ] `create-collection-invalid-book-id.bru` - Invalid UUID handling +- [ ] `create-collection-rules-only.bru` - Auto-assign rules only +- [ ] `create-collection-unauthorized.bru` - No authentication + +**Verification:** +```bash +# Check Bruno collections directory exists +ls -la bruno/collections/ || echo "Directory does not exist yet" + +# Verify test files exist (after Phase 12.5 of plan) +ls -la bruno/collections/*.bru 2>/dev/null | wc -l +# Should return at least 5 after Phase 12.5 + +# Run Bruno tests for collections +cd bruno/collections && bru run --env local +``` + +**Test coverage verification:** +- [ ] `manual_book_ids` field included in request body +- [ ] Validation test sends 51+ book IDs, expects 400 +- [ ] Invalid UUID test verifies graceful handling +- [ ] All tests verify 201 status on success +- [ ] Unauthorized tests verify 401 status + ### 19.2 Verify Bruno Test Response Structure **For `get-sections-success.bru`:** @@ -2925,6 +3014,40 @@ rg "continue-reading|recently-added|recently-read|not-started" docs/developer/ap # Should return at least 4 ``` +### 19.1b Verify Collections API Documentation + +**File: `docs/developer/api/collections/create_collection.md` (UPDATE existing):** + +- [ ] `manual_book_ids` field added to request body documentation +- [ ] Field type documented as array of strings (book UUIDs) +- [ ] Field marked as optional +- [ ] Validation limit documented (max 50 items) +- [ ] Error case documented (400 if > 50 items) +- [ ] Example request shows `manual_book_ids` usage +- [ ] Notes explain combining with `auto_assign_rules` +- [ ] Notes explain invalid book IDs are skipped gracefully + +**Documentation requirements:** +- [ ] Example shows both `auto_assign_rules` AND `manual_book_ids` +- [ ] Error handling explained for invalid book IDs +- [ ] Validation rule clearly stated (max 50) +- [ ] Backward compatibility noted (field is optional) + +**Verification:** +```bash +# Check manual_book_ids in documentation +rg "manual_book_ids" docs/developer/api/collections/create_collection.md + +# Verify validation is documented +rg "max.*50|50.*items" docs/developer/api/collections/create_collection.md -i + +# Check example request +rg "manual_book_ids.*\[" docs/developer/api/collections/create_collection.md -A 5 + +# Verify error cases documented +rg "400.*invalid|validation" docs/developer/api/collections/create_collection.md -i +``` + ### 19.2 Verify User Documentation **File: `docs/user/dashboard.md`:**