bookhoard/CREATE_COLLECTION_MANUAL_BOOKS_UPDATE.md

CreateCollection Manual Books Support - Update Summary

Changes Made to CAROUSEL_DASHBOARD_PLAN.md

1. Added Phase 4.6: Update CreateCollection Endpoint

Location: After Phase 4.5 (line ~1070)

Content Added:

• Documentation of ManualBookIDs field addition to CreateCollectionRequest struct
• Updated CreateCollection handler implementation
• Validation logic (max 50 book IDs)
• Error handling for invalid book IDs
• Reuses existing AddBookToCollection service method
• Backward compatible implementation

2. Added Bruno Tests for CreateCollection

Location: In Phase 12.5 (line ~4030)

New Bruno Tests:

• bruno/collections/create-collection-with-manual-books.bru - Success case
• bruno/collections/create-collection-too-many-books.bru - Validation test
• bruno/collections/create-collection-invalid-book-id.bru - Invalid UUID handling
• bruno/collections/create-collection-rules-only.bru - Auto-assign rules only
• bruno/collections/create-collection-unauthorized.bru - No auth test

New Bruno Directory Structure:

bruno/
└── collections/  # NEW DIRECTORY
    ├── create-collection-with-manual-books.bru
    ├── create-collection-too-many-books.bru
    ├── create-collection-invalid-book-id.bru
    ├── create-collection-rules-only.bru
    └── create-collection-unauthorized.bru

3. Added Collections API Documentation

Location: New section 13.3 (line ~4650)

Documentation Updates:

• docs/developer/api/collections/create_collection.md
• Added manual_book_ids field to request body table
• Documented validation (max 50 items)
• Added example combining auto-assign rules + manual books
• Added error response examples
• Explained graceful handling of invalid book IDs

4. Updated Section Numbering

Impact: Section 13.3 became 13.4, all subsequent sections shifted by +1

---

Changes Made to CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md

1. Added Section 6.4: Verify CreateCollection Endpoint

Location: After section 6.3 (line ~858)

Verification Items Added:

• Struct field verification (ManualBookIDs)
• Validation tag verification (validate:"max=50")
• Handler implementation verification
• Error handling verification
• Logging verification
• Graceful degradation verification

Verification Commands:

rg "ManualBookIDs.*\[\]string" internal/handlers/collections.go
rg 'validate:"max=50"' internal/handlers/collections.go
rg "ManualBookIDs" internal/handlers/collections.go -A 30
rg "AddBookToCollection.*ManualBookIDs" internal/handlers/collections.go -A 5
rg "Logger.*Errorf.*Invalid book ID" internal/handlers/collections.go

2. Updated Section Numbering

Impact: All sections from 6.4 onwards shifted to 6.5+

3. Added Section 19.1b: Verify Collections Bruno Tests

Location: In section 19 (line ~2900)

Verification Items:

• Bruno test directory exists (bruno/collections/)
• All 5 required test files exist
• Test coverage verification
• Response structure verification

4. Added Section 19.1b: Verify Collections API Documentation

Location: In section 19 (line ~3015)

Documentation Requirements:

• manual_book_ids field in documentation
• Validation limit documented (max 50)
• Example requests showing combined usage
• Error handling explained
• Backward compatibility noted

---

Key Design Decisions

1. Validation Limit: 50 Manual Books

Rationale:

• UI constraint (users won't select 1000+ books manually)
• Prevents DoS attacks
• Reasonable limit for custom sections

Implementation:

• Validation tag: validate:"max=50"
• Returns 400 Bad Request if exceeded
• Collections can still have unlimited books via auto-assign rules

2. Graceful Degradation

Design:

• Invalid book IDs are skipped (not fail fast)
• Collection created even if some books fail to add
• Errors logged for debugging
• Success response returned (201)

Benefits:

• Better user experience
• No lost work due to one bad ID
• Matches user expectations

3. Backward Compatibility

Design:

• manual_book_ids is optional field
• Existing API clients unaffected
• No breaking changes

4. Reuse Existing Infrastructure

Design:

• Reuses AddBookToCollection service method
• No new database queries needed
• No schema changes required

Benefits:

• Less code to maintain
• Proven, tested logic
• Faster implementation

---

Implementation Effort

Task	Time	Status
Update CreateCollectionRequest struct	5 min	Documented
Update CreateCollection handler	30 min	Documented
Add validation logic	10 min	Documented
Create Bruno tests	45 min	Documented
Update API documentation	20 min	Documented
Update verification checklist	15 min	Complete
TOTAL	2 hours	Ready to implement

---

Testing Checklist

Unit Tests (None exist yet - should be added)

• Test CreateCollection with manual_book_ids
• Test CreateCollection with > 50 book IDs (expect 400)
• Test CreateCollection with invalid book IDs
• Test CreateCollection with empty manual_book_ids
• Test CreateCollection with only auto-assign rules

Integration Tests (None exist yet - should be added)

• Test end-to-end collection creation with manual books
• Test books actually added to collection_items table
• Test WebSocket broadcast for collection update

Bruno Tests (Documented in plan)

• create-collection-with-manual-books.bru
• create-collection-too-many-books.bru
• create-collection-invalid-book-id.bru
• create-collection-rules-only.bru
• create-collection-unauthorized.bru

Manual Testing

• Create collection via UI with manual books
• Verify books appear in collection
• Try adding 51 books (verify error)
• Mix auto-assign rules + manual selection
• Verify graceful handling of invalid book IDs

---

Files Modified

Plan Document

1. CAROUSEL_DASHBOARD_PLAN.md
   • Added Phase 4.6 (30-45 min)
   • Updated Phase 12.5 (added collections Bruno tests)
   • Added section 13.3 (collections API docs)
   • Shifted section numbering (13.3+ → 13.4+)

Verification Checklist

2. CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md
   • Added section 6.4 (CreateCollection endpoint verification)
   • Shifted section numbering (6.4+ → 6.5+)
   • Added section 19.1b (Collections Bruno tests)
   • Added section 19.1b (Collections API docs)
   • Fixed BuildSections function signature (line 659)

---

Pre-Implementation Checklist

Before implementing Phase 4.6:

• Impact analysis completed
• All documentation updated
• Verification checklist updated
• Bruno tests documented
• Error handling strategy defined
• Validation requirements clear
• Backward compatibility confirmed

---

Post-Implementation Checklist

After implementing Phase 4.6:

• Go build succeeds: go build ./cmd/server
• All Bruno tests pass
• Manual testing via UI works
• Documentation matches implementation
• No errors in logs when adding invalid book IDs
• WebSocket broadcasts work correctly
• Collection shows correct book count
• Verification checklist items all pass

---

Notes

1. No Database Schema Changes Required

   • collection_items table already supports all needed fields
   • No migration needed

2. No New Service Methods Needed

   • Reuses existing AddBookToCollection
   • Keep it simple

3. User Experience

   • Custom Section Builder now fully functional
   • Users can mix rules + manual selection
   • Validation prevents abuse (max 50)

4. Mobile Apps

   • API is backward compatible
   • Mobile apps can ignore manual_book_ids field
   • Or implement support for manual selection

5. Future Enhancements

   • Could increase limit if users request it
   • Could add bulk remove endpoint
   • Could add "replace manual books" endpoint

---

Last Updated: 2026-02-19 Status: ✅ Documentation complete, ready for implementation