Phase,Task
P0: Vision/Alignment,State business goal: 30‑minute local delivery with 95% on‑time; write SLOs for ETA accuracy & data freshness.
P0: Vision/Alignment,”Define primary KPIs: order conversion, vendor acceptance time, on‑time %, average basket; list required data facts.”
P0: Vision/Alignment,Decide geo coverage (cities) for MVP; set defaults in providers/geo.jsonc with justification.
P0: Vision/Alignment,”Define pricing pillars: fees, surge, promos; outline data needed to explain totals to users.”
P0: Vision/Alignment,Choose currency strategy (single ‘USD’ vs multi‑currency); document impact on models.jsonc.
P0: Vision/Alignment,”Write ADR: JSONC single‑source strategy, change control, versioning, rollback.”
P1: Domain Model,”Map actors: customer, vendor, courier (future), admin; note responsibilities & data they own.”
P1: Domain Model,”Draft bounded contexts: Catalog, Ordering, Payments, Logistics; list entity ownership per context.”
P1: Domain Model,”Model vendor onboarding data: business name, KYC placeholders, bank payout stub; add to models.jsonc (optional).”
P1: Domain Model,Model store service area: max_range_km + polygon delivery_zones; prefer polygon when present.
P1: Domain Model,”Model product options (size, add‑ons) and option pricing deltas; extend entities accordingly.”
P1: Domain Model,Model order lifecycle states & payments states; confirm transitions cover happy/exception paths.
P1: Domain Model,Model inventory policy: deny/backorder/substitute; record chosen sub in order item if used.
P1: Domain Model,Model audit trail needs; decide minimal events to store for compliance and debugging.
P2: Contracts/Governance,Normalize enums into contracts/data/enums.jsonc; reference enums in models via $ref.
P2: Contracts/Governance,Define required/optional fields per entity; align with DTOs for create/update operations.
P2: Contracts/Governance,”Add uniques.jsonc for email, product (store_id+name), orderitem (order_id+product_id).”
P2: Contracts/Governance,Add rel.rules.jsonc with referential actions; default RESTRICT; allow CASCADE for Order→OrderItem.
P2: Contracts/Governance,Define retention policy in data-governance.jsonc for PII and orders; specify purge timelines.
P2: Contracts/Governance,Add gdpr.export.jsonc describing exportable fields; ensure no secrets included.
P2: Contracts/Governance,Set deprecation policy in project.jsonc; require 90‑day window for breaking data changes.
P2: Contracts/Governance,Add invariants.jsonc to assert money math & option rules; ensure error codes mapped.
P3: Storage/Schema,Review schema.prisma emission; ensure @@index from indexes.jsonc and @@unique from uniques.jsonc present.
P3: Storage/Schema,Decide soft‑delete vs hard‑delete per entity; add deleted_at fields where chosen; document restore flow.
P3: Storage/Schema,Add optimistic concurrency (version int) to mutable entities; plan executor update to increment.
P3: Storage/Schema,”Evaluate denormalizations (product_is_available, order_totals snapshot); add with rationale.”
P3: Storage/Schema,Confirm numeric precision for money (int cents only); forbid floats in monetary fields.
P3: Storage/Schema,Add created_by/updated_by nullable FK for auditing; seed default system user id=0 pattern.
P3: Storage/Schema,Run db push; perform drift check vs introspection; fail if divergence detected.
P3: Storage/Schema,”Seed minimal realistic data: 3 stores, 20 products, options, inventory; commit fixtures.”
P3: Storage/Schema,Add migration plan format migrations.jsonc; create example rename & backfill entry.
P4: Pricing,”Create pricing.rules.jsonc: delivery_fee base/per_km, free_threshold, surge multipliers with caps.”
P4: Pricing,Add tax.tables.jsonc with city/state rates and fallback; include tax‑exempt toggle for products.
P4: Pricing,”Define promo entity & rules.jsonc (code, percent/amount, min basket, store scope, date window).”
P4: Pricing,Model tip defaults (suggested %) and min/max; persist tip_cents on order; validate ≥ 0.
P4: Pricing,Define rounding rules (bankers/nearest) and total order math order; document computation steps.
P4: Pricing,Implement calc test vectors; assert subtotals/tax/fees/tips exactly match total_cents invariant.
P4: Pricing,Add currency policy tests (uppercase ISO‑4217; reject unknown codes).
P4: Pricing,Model receipt breakdown JSON shape for analytics; align with OpenAPI response schemas.
P5: Logistics/Geo,”Set providers/geo.jsonc: driving_kph, prep_buffer_min, eta_noise_min; justify defaults with city profile.”
P5: Logistics/Geo,Decide ETA algorithm v1 (distance/speed + prep + noise); document tunables for A/B later.
P5: Logistics/Geo,Add delivery_zones.jsonc polygons for seed stores; ensure winding order consistent; write validator.
P5: Logistics/Geo,Add geohash strategy for Store; emit on seed; build index; benchmark nearby prefilter vs haversine only.
P5: Logistics/Geo,Add invariant: order destination must be within polygon OR within max_range; implement either‑or rule.
P5: Logistics/Geo,Record coordinates quantization policy (6dp); normalize inputs; test idempotence of round‑trip.
P5: Logistics/Geo,Define capacity controls: max_concurrent_orders in providers/logistics.jsonc; enforce in create order plan.
P5: Logistics/Geo,Add SLA metrics fields for ETA error tracking; ensure available for analytics (actual vs predicted).
P6: Catalog,Add ProductOptionGroup & ProductOption entities; group constraints (min/max/required).
P6: Catalog,Add OrderItemOption entity for chosen options; compute price deltas into subtotal.
P6: Catalog,Define media provider config (S3 stub) in providers/media.jsonc; record max image size & MIME allowlist.
P6: Catalog,Add image_variants_json on Product; specify generation policy later; seed demo URLs.
P6: Catalog,Define categories & ProductCategory join; ensure indexes for browse by category.
P6: Catalog,”Add search.facets.jsonc stub (categories, price, availability); keep server only for now.”
P6: Catalog,”Write option pricing test matrix (size S/M/L, add‑ons) to validate deltas & totals.”
P6: Catalog,Ensure soft‑delete hides products from lists but preserves historical order references.
P7: Orders/States,Finalize order state machine; include cancellation & refund branches; map allowed actor transitions.
P7: Orders/States,Set payment_state transitions (unpaid→requires_action→paid→refunded); document linkage to order states.
P7: Orders/States,Add idempotency on order create; define header and TTL; test replay semantics.
P7: Orders/States,Add rate limits for create/list endpoints; align with expected mobile retry behavior.
P7: Orders/States,”Define error catalog for order edge cases (out_of_range, capacity_limit, invalid_transition).”
P7: Orders/States,Ensure ownership rules for vendor/customer visibility are declared and enforced pre‑handler.
P7: Orders/States,Persist ETA snapshot on order; allow later recompute for analytics without mutating snapshot.
P7: Orders/States,Document refunds & adjustments data fields even if not fully implemented (future readiness).
P8: Inventory,Create Inventory entity & policy overrides; choose decrement timing (on accept vs on place) and document trade‑offs.
P8: Inventory,Add invariants: qty ≥ 0; item qty ≤ available when policy=deny; tests for each policy mode.
P8: Inventory,Add RestockEvent stub for later automation; backfill inventory via seed script examples.
P8: Inventory,Define blackout windows (holidays) per store in availability.jsonc; hide store during blackout.
P8: Inventory,Add capacity/batching rules; block new orders if active >= limit; unit test boundary conditions.
P8: Inventory,Emit denormalized product_is_available boolean; update triggers (executor) on inventory change.
P8: Inventory,Add reporting-friendly fields (first_out_of_stock_at) for analytics.
P9: Security/Privacy,Classify PII fields; ensure redaction.jsonc covers headers/body; add masking tests.
P9: Security/Privacy,Add retention windows for sessions & soft‑deleted data; implement purge plan stub script.
P9: Security/Privacy,Define consent & terms acceptance fields; seed defaults; prepare exportable data mapping.
P9: Security/Privacy,Ensure password & tokens never appear in logs/exports; add invariant & tests.
P9: Security/Privacy,Add role/ownership assertions in data layer tests to prevent over‑exposure across joins.
P9: Security/Privacy,Create minimal audit log schema; record auth login and order create with safe fields.
P9: Security/Privacy,Document incident response data needs and where data will be sourced from.
P10: Observability,”Define SLIs for data paths (db latency, codegen time, seed time, query cache hit rate).”
P10: Observability,Set budgets.jsonc for payload sizes & p95 latencies; enforce warnings when exceeded.
P10: Observability,Instrument counts/timers around data hot paths; names from observability/metrics.jsonc.
P10: Observability,Decide local dev sampling; reduce log volume while keeping cardinality manageable.
P10: Observability,Create capacity model rough calc: QPS for list/estimate/create; document index adequacy.
P10: Observability,Propose plan to move rate limit/idempotency stores to Redis when scaling beyond single node.
P11: Data Quality,Add property tests (fast-check) for money math & options boundary cases.
P11: Data Quality,Add fuzz tests that mutate DTO_OrderCreate; expect clear error messages and codes.
P11: Data Quality,Create drift detector test: introspect DB vs schema.prisma; fail on mismatch.
P11: Data Quality,Snapshot contracts/ and generated prisma/schema.prisma; fail on unintended churn.
P11: Data Quality,”Load tests: synthetic 10k products, 1k orders; measure seed & query latencies; record results.”
P11: Data Quality,Create contract tests (schemathesis) focused on data constraints; cap examples for speed.
P11: Data Quality,Add test that deletes a required field in models.jsonc; verify codegen fails with actionable message.
P11: Data Quality,Review flaky tests; simplify data fixtures; introduce deterministic seeds.
P12: Finalization,Produce data dictionary (generated markdown) from models.jsonc with entity/field descriptions.
P12: Finalization,”Write backfill scripts examples (geohash, category slugs); ensure idempotent and logged.”
P12: Finalization,”Add pre‑prod checklist: migrations reviewed, backups tested, purge script dry‑run.”
P12: Finalization,Run end‑to‑end data path rehearsal: codegen → migrate → seed → tests → smoke; attach results.
P12: Finalization,”Create RELEASE_NOTES_Data.md summarizing data changes, risks, and next steps.”
P12: Finalization,”Propose next iteration topics (couriers, zones pricing, payouts, ML ETA) with data impacts.”