# ADMIN BULK UPDATE — TASKS.md

## Backend

### BULK-BE-001
**ID**: BULK-BE-001
**Title**: BulkOperation domain types
**Goal**: Define all types for bulk operations
**Why**: Shared contracts for handlers, orchestrator, and API
**Dependencies**: None
**Applications**: Backend
**Modules**: bulk/domain/bulk-operation.ts
**Database impact**: None
**API contracts**: Shapes of request/response objects
**Permissions**: N/A
**Implementation**: Define BulkOperationType enum, BulkOperationParams union, PreviewItem, PreviewResult, ExecuteResult interfaces; ValidationResult
**Tests**: Type tests (TypeScript compilation)
**Expected blast radius**: Low
**Definition of Done**: All types defined; TypeScript compiles without errors

### BULK-BE-002
**ID**: BULK-BE-002
**Title**: BulkOperationHandler port + handler registry
**Goal**: Define the extension interface for bulk operations
**Why**: Allows adding future operations without touching core orchestrator
**Dependencies**: BULK-BE-001
**Applications**: Backend
**Modules**: bulk/domain/ports.ts
**Database impact**: None
**API contracts**: BulkOperationHandler interface
**Permissions**: N/A
**Implementation**: Define `BulkOperationHandler` interface; create `HANDLERS` registry map; export from bulk/index.ts
**Tests**: Handler lookup by type works; unknown type returns undefined
**Expected blast radius**: Low
**Definition of Done**: Interface exists; registry is extensible; adding a handler requires only adding to registry

### BULK-BE-003
**ID**: BULK-BE-003
**Title**: Price bulk operation handlers
**Goal**: Implement SET, INCREASE_PERCENT, DECREASE_PERCENT, INCREASE_FIXED, DECREASE_FIXED
**Why**: Initial price operations
**Dependencies**: BULK-BE-002
**Applications**: Backend
**Modules**: bulk/application/handlers/price-handlers.ts
**Database impact**: None
**API contracts**: None (domain)
**Permissions**: N/A
**Implementation**: Five handler classes; each implements validate(), preview(), buildPatch(); rounding uses Math.round(); VAT is stored as net price
**Tests**:
- BULK-BE-UT-001: INCREASE_PERCENT 5% on 350 cents → 368 cents
- BULK-BE-UT-002: DECREASE_PERCENT 5% on 350 cents → 333 cents
- BULK-BE-UT-003: INCREASE_FIXED 50 on 350 cents → 400 cents
- BULK-BE-UT-004: DECREASE_FIXED 50 on 350 cents → 300 cents
- BULK-BE-UT-005: DECREASE_FIXED below 0 → floor at 0
- BULK-BE-UT-006: SET_PRICE 500 → 500
- BULK-BE-UT-007: invalid percent (0, negative, >1000) → ValidationResult.valid=false
- BULK-BE-UT-008: missing VAT rate → ValidationResult.valid=false
- BULK-BE-UT-009: product without price → PreviewItem.status=failed, error=PRICE_NOT_FOUND
**Expected blast radius**: Low
**Definition of Done**: All five handlers produce correct price calculations; invalid params rejected at validate()

### BULK-BE-004
**ID**: BULK-BE-004
**Title**: Category bulk operation handlers
**Goal**: Implement ADD_CATEGORY, REMOVE_CATEGORY, REPLACE_CATEGORIES
**Why**: Initial category operations
**Dependencies**: BULK-BE-002
**Applications**: Backend
**Modules**: bulk/application/handlers/category-handlers.ts
**Database impact**: None
**API contracts**: None (domain)
**Permissions**: N/A
**Implementation**: Three handler classes; ADD deduplicates; REMOVE filters; REPLACE replaces entirely; validates categoryId exists (optional — can be deferred)
**Tests**:
- BULK-BE-UT-010: ADD_CATEGORY to product with 2 categories → 3 categories
- BULK-BE-UT-011: ADD_CATEGORY with duplicate → no-op (deduplicated)
- BULK-BE-UT-012: REMOVE_CATEGORY from product with 3 categories → 2 categories
- BULK-BE-UT-013: REMOVE_CATEGORY not present → no change
- BULK-BE-UT-014: REPLACE_CATEGORIES with 2 new categories → exactly those 2
- BULK-BE-UT-015: ADD without categoryId → ValidationResult.valid=false
**Expected blast radius**: Low
**Definition of Done**: All three handlers produce correct category patches; validation rejects invalid input

### BULK-BE-005
**ID**: BULK-BE-005
**Title**: BulkService orchestrator
**Goal**: Orchestrate preview + execute; integrate with audit
**Why**: Core business logic tying handlers, repository, and audit together
**Dependencies**: BULK-BE-001, BULK-BE-002, BULK-BE-003, BULK-BE-004
**Applications**: Backend
**Modules**: bulk/application/bulk-service.ts
**Database impact**: None
**API contracts**: None (service)
**Permissions**: N/A
**Implementation**: BulkService with preview() and execute(); execute() uses transaction; logs audit entry on execution; rollback on error; generate operationId
**Tests**:
- BULK-BE-UT-020: preview() calls handler.validate() and handler.preview() for each product
- BULK-BE-UT-021: execute() calls handler.buildPatch() for each valid product
- BULK-BE-UT-022: execute() logs one audit entry per bulk operation
- BULK-BE-UT-023: execute() rollback on error → no product modified
- BULK-BE-UT-024: unknown operation type → AppError(400)
**Expected blast radius**: Medium — changes persistence
**Definition of Done**: BulkService correctly orchestrates all operations; audit entry is complete; transaction is atomic

### BULK-BE-006
**ID**: BULK-BE-006
**Title**: BulkProductRepository — read products with pricing in batch
**Goal**: Efficiently load product+price data for bulk operations
**Why**: Avoids N queries for N products
**Dependencies**: BULK-BE-001
**Applications**: Backend
**Modules**: bulk/infrastructure/pg-bulk-repository.ts
**Database impact**: None
**API contracts**: None
**Permissions**: N/A
**Implementation**: Single SQL query to JOIN catalog_products + pricing_variants; returns ProductWithPrice[] (internal type); handles products with no price gracefully
**Tests**: BULK-BE-IT-001: batch load of 20 products returns correct data; BULK-BE-IT-002: product without price returns null price field
**Expected blast radius**: Low
**Definition of Done**: Products loaded in one query; missing price handled gracefully

### BULK-BE-007
**ID**: BULK-BE-007
**Title**: Bulk API routes — preview and execute
**Goal**: Expose bulk operations via REST API
**Why**: Admin UI needs these endpoints
**Dependencies**: BULK-BE-005, BULK-BE-006
**Applications**: Backend
**Modules**: bulk/api/bulk.routes.ts
**Database impact**: None (read for preview; write for execute)
**API contracts**: POST /admin/bulk/preview, POST /admin/bulk/execute
**Permissions**: admin role required on both
**Implementation**: Register routes in build-app.ts; parse request body; call BulkService; serialize response; handle errors with AppError
**Tests**:
- BULK-BE-IT-010: POST /admin/bulk/preview with valid INCREASE_PERCENT → 200 + PreviewResult
- BULK-BE-IT-011: POST /admin/bulk/preview with invalid params → 422
- BULK-BE-IT-012: POST /admin/bulk/preview without auth → 401
- BULK-BE-IT-013: POST /admin/bulk/execute with valid params → 200 + ExecuteResult
- BULK-BE-IT-014: POST /admin/bulk/execute → applies changes to DB; products updated
- BULK-BE-IT-015: audit log entry created after execute
**Expected blast radius**: Low — new routes
**Definition of Done**: Both routes respond correctly; auth enforced; changes persisted

### BULK-BE-008
**ID**: BULK-BE-008
**Title**: Wire bulk module into build-app.ts
**Goal**: Register bulk routes with Fastify
**Why**: Module must be mounted in the application
**Dependencies**: BULK-BE-007
**Applications**: Backend
**Modules**: app/build-app.ts
**Database impact**: None
**API contracts**: None
**Permissions**: N/A
**Implementation**: Import registerBulkRoutes; call in build-app.ts alongside other modules; pass pool, authenticate, audit
**Tests**: Integration test that /admin/bulk/preview and /admin/bulk/execute respond
**Expected blast radius**: Low
**Definition of Done**: Bulk routes accessible at /admin/bulk/*

## Admin

### BULK-ADM-001
**ID**: BULK-ADM-001
**Title**: Bulk Update page shell + product selection
**Goal**: Product selection step of the wizard
**Why**: Admin needs to pick which products to update
**Dependencies**: BULK-BE-007
**Applications**: Admin
**Modules**: apps/admin/src/app/(dashboard)/bulk-update/page.tsx
**Database impact**: None
**API contracts**: GET /catalog/products (existing)
**Permissions**: products.bulk_update
**Implementation**: Full-width page with product table; checkbox column; search/filter bar; selected count badge; "Continue to Configure" button
**Tests**: Products load; checkboxes select/deselect; selected count accurate; filter narrows selection
**Expected blast radius**: Low
**Definition of Done**: Admin can select products and see selection count

### BULK-ADM-002
**ID**: BULK-ADM-002
**Title**: Operation selector + configuration step
**Goal**: Choose and configure the bulk operation type
**Why**: Second step of the wizard
**Dependencies**: BULK-ADM-001
**Applications**: Admin
**Modules**: apps/admin/src/app/(dashboard)/bulk-update/page.tsx
**Database impact**: None
**API contracts**: None yet
**Permissions**: products.bulk_update
**Implementation**: Two cards: Price / Categories; selecting Price shows sub-options (SET, +%, -%, +FIXED, -FIXED) with parameter inputs; selecting Categories shows (ADD, REMOVE, REPLACE) with category picker; Back button returns to selection
**Tests**: Selecting each operation shows correct sub-options; invalid input shows error state
**Expected blast radius**: Low
**Definition of Done**: Admin can select operation type and enter parameters

### BULK-ADM-003
**ID**: BULK-ADM-003
**Title**: Preview step
**Goal**: Show proposed changes before committing
**Why**: Critical safety step — see what will change before writing
**Dependencies**: BULK-BE-007, BULK-ADM-002
**Applications**: Admin
**Modules**: apps/admin/src/app/(dashboard)/bulk-update/page.tsx
**Database impact**: None (dry-run)
**API contracts**: POST /admin/bulk/preview
**Permissions**: products.bulk_update
**Implementation**: Call preview API with selected productIds, operation, parameters; display table (Product | Current | Proposed | Status); show summary bar ("18 valid, 2 failed"); Back button to Configure
**Tests**: Preview loads; shows correct current→proposed values; failed rows highlighted with error reason
**Expected blast radius**: Low
**Definition of Done**: Preview accurately reflects what execute() would do; no product modified

### BULK-ADM-004
**ID**: BULK-ADM-004
**Title**: Confirmation + execution step
**Goal**: Require explicit confirmation before executing bulk operation
**Why**: Safety barrier — prevent accidental bulk changes
**Dependencies**: BULK-ADM-003, BULK-BE-007
**Applications**: Admin
**Modules**: apps/admin/src/app/(dashboard)/bulk-update/page.tsx
**Database impact**: MODIFIES PRODUCTS
**API contracts**: POST /admin/bulk/execute
**Permissions**: products.bulk_update
**Implementation**: Show warning message ("X changes will be applied. This cannot be undone."); [Cancel] [Apply Changes] buttons; on Apply: call execute API; on success: show result summary; on error: show error + retry option
**Tests**: Confirmation dialog shows before any write; cancel returns to preview; apply calls execute; result shows success/failure counts
**Expected blast radius**: HIGH — modifies products
**Definition of Done**: Confirmation required; execute called only after explicit confirmation; result displayed accurately

### BULK-ADM-005
**ID**: BULK-ADM-005
**Title**: Navigation sidebar — add Bulk Update link
**Goal**: Make bulk update accessible from admin navigation
**Why**: Discoverability
**Dependencies**: BULK-ADM-001
**Applications**: Admin
**Modules**: apps/admin/src/lib/permissions.ts
**Database impact**: None
**API contracts**: None
**Permissions**: products.bulk_update
**Implementation**: Add to NAV_ITEMS: { href: '/bulk-update', label: 'Actualización masiva', icon: '📦', permission: 'products.bulk_update' }
**Tests**: Bulk Update appears in sidebar for admin users
**Expected blast radius**: Low
**Definition of Done**: Nav item visible in admin sidebar

## QA

### BULK-QA-001
**ID**: BULK-QA-001
**Title**: Bulk update E2E tests
**Goal**: End-to-end validation of complete bulk update flow
**Why**: Critical safety feature — full flow must work
**Dependencies**: BULK-BE-007, BULK-ADM-004
**Applications**: QA
**Modules**: E2E tests
**Tests**:
- BULK-QA-UT-001: Select 5 products → preview shows correct proposed prices
- BULK-QA-UT-002: Preview does NOT modify any product
- BULK-QA-UT-003: Confirm → products actually updated in DB
- BULK-QA-UT-004: Audit log entry exists for bulk operation
- BULK-QA-UT-005: 5% increase on products with VAT general → correct net price applied
- BULK-QA-UT-006: ADD_CATEGORY → categories added without removing existing
- BULK-QA-UT-007: REMOVE_CATEGORY → category removed, others preserved
- BULK-QA-UT-008: REPLACE_CATEGORIES → only new categories remain
- BULK-QA-UT-009: Product without price → failed in preview and in execute (not silently skipped)
- BULK-QA-UT-010: Non-admin user → 401 on /admin/bulk/execute
**Expected blast radius**: N/A
**Definition of Done**: All tests pass; QA sign-off obtained

---

## Task Summary Table

| Task | Layer | Feature | Depends On | Risk | Parallel |
|------|-------|---------|-----------|------|---------|
| BULK-BE-001 | Backend | Domain types | — | Low | * |
| BULK-BE-002 | Backend | Handler interface | BULK-BE-001 | Low | * |
| BULK-BE-003 | Backend | Price handlers | BULK-BE-002 | Low | * |
| BULK-BE-004 | Backend | Category handlers | BULK-BE-002 | Low | * |
| BULK-BE-005 | Backend | BulkService orchestrator | BULK-BE-001..004 | Medium | * |
| BULK-BE-006 | Backend | BulkProductRepository | BULK-BE-001 | Low | * |
| BULK-BE-007 | Backend | API routes | BULK-BE-005, BULK-BE-006 | Medium | * |
| BULK-BE-008 | Backend | Wire into build-app | BULK-BE-007 | Low | * |
| BULK-ADM-001 | Admin | Product selection UI | BULK-BE-007 | Low | * |
| BULK-ADM-002 | Admin | Operation config step | BULK-ADM-001 | Low | * |
| BULK-ADM-003 | Admin | Preview step | BULK-ADM-002, BULK-BE-007 | Low | * |
| BULK-ADM-004 | Admin | Confirm + execute step | BULK-ADM-003, BULK-BE-007 | Medium | * |
| BULK-ADM-005 | Admin | Sidebar nav link | BULK-ADM-001 | Low | * |
| BULK-QA-001 | QA | E2E tests | BULK-BE-007, BULK-ADM-004 | Medium | After all |

**Parallel group**: BULK-BE-001 and BULK-BE-002 are independent; BULK-BE-003 and BULK-BE-004 are parallel (both depend on BE-002); BULK-BE-005 depends on all four handlers; BULK-BE-006 independent; BULK-BE-007 depends on BE-005 + BE-006; Admin tasks BULK-ADM-001 through BULK-ADM-005 are sequential (wizard flow).

**Recommended order**:
1. BULK-BE-001 + BULK-BE-002 + BULK-BE-006 (parallel, no deps)
2. BULK-BE-003 + BULK-BE-004 (parallel, both depend on BE-002)
3. BULK-BE-005 (depends on BE-001..004)
4. BULK-BE-007 (depends on BE-005, BE-006)
5. BULK-BE-008 (depends on BE-007)
6. BULK-ADM-001 (depends on BE-007)
7. BULK-ADM-002 through BULK-ADM-004 (sequential wizard)
8. BULK-ADM-005 (parallel with any ADM task)
9. BULK-QA-001 (after everything)

**High-risk tasks**:
- BULK-BE-005: Transaction logic must be correct — wrong rollback = data corruption
- BULK-ADM-004: Executes actual DB writes — requires confirmation UI; must not auto-submit
- BULK-BE-007: New API endpoints with admin auth — verify auth enforced

**MVP boundary**: BULK-BE-001 through BULK-BE-008 (backend) + BULK-ADM-001 through BULK-ADM-005. BULK-QA-001 is required before go-live.

**Migration risks**: None — bulk update is purely additive; no existing data migration required.