mercadodevida/project/specs/expiration-tracking/TASKS.md

EXPIRATION TRACKING — TASKS.md

Backend

EXP-BE-001

ID: EXP-BE-001 Title: Product expiration_tracking_enabled column Goal: Add boolean column to catalog_products Why: Products need to declare whether they require expiration tracking Dependencies: None Applications: Backend Modules: catalog_products table, Product domain, ProductRepository Database impact: ALTER TABLE catalog_products ADD COLUMN expiration_tracking_enabled boolean NOT NULL DEFAULT false API contracts: GET /products/:id returns field; PATCH /products/:id accepts field Permissions: admin Implementation: Add to NewProduct interface, ProductPatch type, pg-product-repository Tests: Unit — default false; Integration — column exists with correct default Migration: See MIGRATION.md Phase 1 Expected blast radius: Low — only affects new product queries Definition of Done: Column exists, defaults to false, persists on create/update

EXP-BE-002

ID: EXP-BE-002 Title: InventoryLot domain and repository Goal: New InventoryLot entity and InventoryLotRepository port + PgInventoryLotRepository Why: Core data model for lot-level stock Dependencies: EXP-BE-001 Applications: Backend Modules: inventory/domain, inventory/infrastructure Database impact: CREATE TABLE inventory_lots (see DESIGN.md) API contracts: None yet (repository only) Permissions: N/A Implementation: InventoryLot interface, CreateLotCommand, InventoryLotRepository port, PgInventoryLotRepository Tests: Unit — CRUD operations; Integration — table constraints, FK Expected blast radius: Low — new table, no existing data touched Definition of Done: Lot CRUD works, FK to catalog_variants enforced, CHECK constraint on expiration_date

EXP-BE-003

ID: EXP-BE-003 Title: LotService — create, update, delete, FEFO allocation Goal: Domain service handling lot business rules Why: Encapsulates expiration validation and FEFO logic Dependencies: EXP-BE-002 Applications: Backend Modules: inventory/application API contracts: None (domain service) Permissions: N/A Implementation: LotService class with createLot (validates expiry required), allocateLots (FEFO), adjustQuantity Tests: Unit — missing expiry rejected; past expiry rejected; FEFO order; partial lot allocation Expected blast radius: Low Definition of Done: LotService methods have correct business rules; FEFO allocates from earliest expiry first

EXP-BE-004

ID: EXP-BE-004 Title: InventoryLots API routes Goal: CRUD endpoints for lots + availability query with filter Why: Admin needs to manage lots; frontend needs to display them Dependencies: EXP-BE-003 Applications: Backend Modules: inventory/api API contracts: GET /inventory/lots, POST /inventory/lots, PATCH /inventory/lots/:id, DELETE /inventory/lots/:id (all admin) Permissions: admin role required Implementation: New route registrations in inventory module; serialize LotService results Tests: Integration — CRUD round-trip; filter=expiring|expired|all Expected blast radius: Low — new routes Definition of Done: All 5 routes respond correctly; filter parameters work; auth enforced

EXP-BE-005

ID: EXP-BE-005 Title: InventoryService — integrate LotService for expiration products Goal: Extend existing InventoryService to delegate to LotService when expiry is enabled Why: Preserve existing InventoryServicePort contract while adding expiration support Dependencies: EXP-BE-001, EXP-BE-003 Applications: Backend, Checkout Modules: inventory/application, checkout API contracts: Existing InventoryServicePort contract unchanged Permissions: N/A Implementation: In InventoryService, check product.expiration_tracking_enabled; if true, use LotService.getAvailableStock and LotService.allocateLots; feature flag gates behavior Tests: Unit — delegation to LotService for expiry products; existing path for non-expiry products Expected blast radius: Checkout uses InventoryServicePort — must not break Definition of Done: Checkout reserve/confirm still works for both expiry and non-expiry products; FEFO used for expiry products

EXP-BE-006

ID: EXP-BE-006 Title: Extend inventory_movements with lot operation types Goal: Track lot_create, lot_adjust, lot_delete in movement audit log Why: Full auditability of lot changes Dependencies: EXP-BE-002 Applications: Backend Modules: inventory/infrastructure, security Database impact: ALTER TABLE inventory_movements — new operation types + optional lot_id FK API contracts: Movement audit reflects lot operations Permissions: N/A Implementation: Add operation types in pg-inventory-repository insertMovement calls Tests: Integration — movements logged with correct operation type Expected blast radius: Low Definition of Done: Lot mutations produce audit entries

Database

EXP-DB-001

ID: EXP-DB-001 Title: Run expiration tracking migrations Goal: Apply all DB changes from MIGRATION.md Phase 1 Why: Infrastructure for lot model Dependencies: EXP-BE-001 (column on catalog_products), EXP-BE-002 (lots table) Applications: Database Modules: N/A Database impact: See MIGRATION.md Phase 1 API contracts: N/A Permissions: DBA Implementation: Add migration file or run raw SQL against dev DB; apply via docker-compose migration pipeline Tests: Verify schema after migration Expected blast radius: Low — additive changes Definition of Done: Migration runs without error; new columns/tables exist with correct constraints

Admin

EXP-ADM-001

ID: EXP-ADM-001 Title: Product Editor — expiration tracking toggle Goal: Add checkbox to General tab: "Track expiration dates" Why: Admin configures per-product policy Dependencies: EXP-BE-001 Applications: Admin Modules: ProductEditor, GeneralSection Database impact: None (uses EXP-BE-001) API contracts: PATCH /catalog/products/:id Permissions: products.write Implementation: Add toggle to GeneralSection; saves { expiration_tracking_enabled: boolean } on save Tests: Toggle saves correctly; shows/hides expiration UI based on state Expected blast radius: Low Definition of Done: Admin can enable/disable expiry tracking per product; toggle persists

EXP-ADM-002

ID: EXP-ADM-002 Title: Inventory — lot-level stock view Goal: Show lots table for expiry-tracking products in inventory page Why: Operational visibility into expiration state Dependencies: EXP-BE-004 Applications: Admin Modules: InventorySection, inventory page Database impact: None API contracts: GET /inventory/lots?variant_id=X Permissions: inventory.read Implementation: Extend InventorySection to show lots when product has expiry enabled; compute status (VALID/NEAR_EXPIRY/EXPIRED) client-side from FLAG_EXPIRY_WARNING_DAYS Tests: Lot table renders correctly; status computed from dates Expected blast radius: Low Definition of Done: Lots displayed with correct quantity, date, and status badge

EXP-ADM-003

ID: EXP-ADM-003 Title: Inventory — lot create/edit/delete Goal: Inline lot management in inventory section Why: Admin must be able to add/update/remove lots Dependencies: EXP-BE-004 Applications: Admin Modules: InventorySection Database impact: None API contracts: POST/PATCH/DELETE /inventory/lots/:id Permissions: inventory.write Implementation: Add lot form (quantity, expiration date); inline edit on lot row; delete confirmation Tests: Create lot with required expiry date; edit quantity; delete lot; 422 shown for missing expiry Expected blast radius: Low Definition of Done: Admin can fully manage lots; validation errors shown correctly

EXP-ADM-004

ID: EXP-ADM-004 Title: Inventory filters — expiring, expired, all, no-expiry Goal: Filter inventory page by expiration status Why: Operational efficiency for stock management Dependencies: EXP-BE-004 Applications: Admin Modules: inventory page Database impact: None API contracts: GET /inventory/lots?filter=expiring|expired|all|no-expiry Permissions: inventory.read Implementation: Add filter tabs/dropdown to inventory page; calls API with filter param Tests: Each filter returns correct lot subset Expected blast radius: Low Definition of Done: Filters work; filter state reflected in URL or UI

QA

EXP-QA-001

ID: EXP-QA-001 Title: Expiration tracking regression tests Goal: Ensure existing checkout flow is unbroken Why: No regressions on existing products Dependencies: EXP-BE-005, EXP-DB-001 Applications: QA Modules: E2E tests Tests:

• Normal product (non-expiry) still checks out correctly
• Expiry product with no lots: unavailable
• Expiry product with valid lot: available and reservable
• FEFO: earliest expiry lot consumed first
• Expired lot: contributes zero sellable units Expected blast radius: N/A Definition of Done: All regression tests pass

EXP-QA-002

ID: EXP-QA-002 Title: Expiration tracking unit/integration tests Goal: Comprehensive test coverage for all new domain code Why: Business rules must be correct Dependencies: EXP-BE-003, EXP-BE-004, EXP-BE-005 Applications: QA Modules: Backend test suite Tests: See TESTS.md Expected blast radius: N/A Definition of Done: 100% pass rate on expiration-specific tests

---

Task Summary Table

Task	Layer	Feature	Depends On	Risk	Parallel
EXP-BE-001	Backend	Product expiry column	—	Low	*
EXP-BE-002	Backend	Lot model + repository	—	Low	*
EXP-BE-003	Backend	LotService domain	EXP-BE-002	Low	*
EXP-BE-004	Backend	Lot API routes	EXP-BE-003	Low	*
EXP-BE-005	Backend	InventoryService + LotService	EXP-BE-001, EXP-BE-003	Medium	*
EXP-BE-006	Backend	Movement audit for lots	EXP-BE-002	Low	EXP-BE-004
EXP-DB-001	DB	Run migrations	EXP-BE-001, EXP-BE-002	Low	*
EXP-ADM-001	Admin	Product expiry toggle	EXP-BE-001	Low	*
EXP-ADM-002	Admin	Lot stock view	EXP-BE-004	Low	*
EXP-ADM-003	Admin	Lot CRUD	EXP-BE-004	Low	*
EXP-ADM-004	Admin	Expiry filters	EXP-BE-004	Low	*
EXP-QA-001	QA	Checkout regression	EXP-BE-005, EXP-DB-001	Medium	After backend
EXP-QA-002	QA	Domain unit tests	All BE tasks	Low	With backend

Parallel group: EXP-BE-001 and EXP-BE-002 can run in parallel. BE-003 depends on BE-002. BE-004 and BE-006 depend on BE-003. BE-005 depends on BE-001 + BE-003.

Recommended order:

1. EXP-BE-001 + EXP-BE-002 (parallel, no dependencies)
2. EXP-BE-003 (depends on BE-002)
3. EXP-BE-004 + EXP-BE-006 (depend on BE-003, parallel)
4. EXP-DB-001 (run after BE-001 + BE-002 code is deployed)
5. EXP-BE-005 (depends on BE-001 + BE-003)
6. EXP-ADM-001 (depends on BE-001)
7. EXP-ADM-002 + EXP-ADM-003 + EXP-ADM-004 (depend on BE-004, parallel)
8. EXP-QA-001 + EXP-QA-002 (after all backend + admin)

High-risk tasks: EXP-BE-005 (changes InventoryService contract internal behavior, affects checkout — thorough regression testing required).

MVP boundary: EXP-BE-001 through EXP-BE-005 + EXP-DB-001 + EXP-ADM-001 through EXP-ADM-004. EXP-BE-006 (audit) is low priority for MVP. EXP-QA-002 is bundled with implementation. EXP-QA-001 is blocking go-live.