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
This commit is contained in:
@@ -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`:**
|
||||
|
||||
Reference in New Issue
Block a user