# Tasks

Phased build plan. Each task references requirement IDs (see requirement.md) and
lists deliverables. Build in order — later phases depend on earlier ones. "DoD" =
definition of done for the phase (must pass before moving on). Keep migrations,
models, services, and views scoped per task, not all at once.

Legend: [ ] todo · [~] in progress · [x] done

---

## Phase 0 — Foundation & theme
- [ ] Init Laravel 13 project, PHP 8.3, strict types, Pint, Pest. *(NFR-1..6)*
- [ ] Configure `database` queue, DB sessions/cache; `.env` template.
- [ ] Fortify auth (customer + admin guards), rate limiting. *(R6.1, R6.2)*
- [ ] Localization: `SetLocale` middleware, `lang/ms` + `lang/en`, switcher,
      spatie/laravel-translatable. *(R12.1–R12.3)*
- [ ] Define all backed **enums** (design.md → Enums).
- [ ] `Money` value object + cents helpers.
- [ ] Theme: `resources/css/theme.css` tokens (purple `#720eec`, gold `#c4a35c`,
      etc.), Tailwind mapping, fonts (Cinzel/Cormorant/Jost), base layout.
- [ ] Port hero: `components/hero.blade.php` + `components/jewellery/ring.blade.php`
      + `home.php` lang (BM/EN). *(R11.2)*
- **DoD:** app boots, auth + locale switch work, hero renders, `pint` + tests green.

## Phase 1 — Pricing core
- [ ] Migration + model `gold_prices` (append-only). *(R2.6, R2.7)*
- [ ] `GoldPriceProvider` interface + DB impl (cached current price). *(R2.8)*
- [ ] `PricingService::priceFor()` + product price range. *(R2.3–R2.5)*
- [ ] Cache-bust current price on new gold-price row.
- [ ] Filament: gold price admin (record new rate per purity). *(R13.2)*
- [ ] Unit tests: per-gram vs flat, override, range, current-price selection.
- **DoD:** adding a gold-price row reprices computed values; tests cover all pricing paths.

## Phase 2 — Catalog
- [ ] Migrations/models: categories, products, product_variations, product_images,
      category_product. *(R1.3, R2.1, R2.2)*
- [ ] Filament resources: category tree, product + variations + image upload
      (validated mime/ext/size). *(R13.1, NFR-1)*
- [ ] Storefront: shop listing (paginate, sort, filter), category pages, search,
      empty states. *(R1.1, R1.2, R1.4, R1.6)*
- [ ] Product detail: images, variations, computed price/range, related. *(R1.5)*
- [ ] Eager-load to avoid N+1; factories + seeders.
- **DoD:** browse/search/filter works with live prices; no N+1; lists paginated.

## Phase 3 — Cart
- [ ] Migrations/models: carts, cart_items. *(R3.3)*
- [ ] Livewire cart + mini-cart; add/update/remove; live subtotal. *(R3.1, R3.2)*
- [ ] Stock validation where tracked. *(R3.4)*
- **DoD:** guest + customer carts persist; prices always current.

## Phase 4 — Checkout & orders
- [ ] Migrations/models: orders, order_items. *(R4.2, R4.8)*
- [ ] Checkout flow: address form (MY only), final price+weight confirm. *(R4.1, R4.3)*
- [ ] `ShippingCalculator` (free ≥ RM300, zone rates). *(R4.3)*
- [ ] `PlaceOrder` action: transaction, snapshot items, order number, statuses. *(R4.2, R4.6)*
- [ ] Order confirmation email (queued). *(R4.6)*
- [ ] Customer order history + tracking view. *(R4.7)*
- [ ] Order cancellation rule (24h/unshipped → e-voucher). *(R4.9)*
- [ ] Feature tests: price-lock snapshot, shipping thresholds, cancellation.
- **DoD:** placed orders freeze totals; snapshots immutable; emails queued.

## Phase 5 — Payments
- [ ] `PaymentGateway` interface + chosen impl (ToyyibPay/Billplz). *(R5.1)*
- [ ] Redirect to gateway; callback route with signature verify + idempotent transition. *(R5.2)*
- [ ] `OrderPaid` event → queued: email, stock decrement, commission. *(R5.3)*
- [ ] Callback logging (no secrets). *(R5.4)*
- [ ] Feature tests: duplicate callback idempotency, amount == order total.
- **DoD:** full pay→paid path works; replayed callbacks are safe.

## Phase 6 — Store credit / e-voucher
- [ ] Migrations/models: store_credits, store_credit_transactions. *(R7.1)*
- [ ] `IssueStoreCredit` + `RedeemStoreCredit` actions (row-locked, ledger). *(R7.2)*
- [ ] Apply credit at checkout; customer balance + history view. *(R7.3, R6.3)*
- [ ] Filament: store-credit admin.
- [ ] Feature test: concurrent redeem — no double-spend.
- **DoD:** credits issue/redeem atomically with an auditable ledger.

## Phase 7 — Trade-in
- [ ] Migrations/models: trade_in_requests, trade_in_items. *(R8.1)*
- [ ] Customer submit + live estimate (buy price). *(R8.1)*
- [ ] Filament review: set final values, approve/reject → issue credit. *(R8.2, R8.3)*
- [ ] Audit log on transitions. *(R8.4)*
- **DoD:** approved trade-in produces store credit; every change logged.

## Phase 8 — Affiliate
- [ ] Migrations/models: affiliates, affiliate_referrals. *(R9.1)*
- [ ] Referral capture middleware (`?ref=`, signed cookie); attach to order;
      block self-referral. *(R9.2)*
- [ ] Commission on `OrderPaid` (pending→approved→paid). *(R9.3)*
- [ ] Affiliate dashboard (policy-scoped to own data). *(R9.1, NFR-1)*
- [ ] Feature tests: attribution, self-referral block, IDOR on dashboard.
- **DoD:** commissions computed correctly; dashboard leaks no other affiliate's data.

## Phase 9 — Reviews
- [ ] Migration/model: reviews (unique per customer/product). *(R10.1, R10.3)*
- [ ] Submit review (verified-purchase flag); moderation queue in Filament. *(R10.2, R10.3)*
- [ ] Render approved reviews, escaped. *(R10.4)*
- **DoD:** only approved reviews show; one per customer/product; output safe.

## Phase 10 — Content & home assembly
- [ ] Migration/model: cms_pages; seed About/Terms/Refund/Gallery/campaigns. *(R11.1)*
- [ ] Home page: hero + category tiles + new arrivals + testimonials. *(R11.2)*
- [ ] Header/nav (real logo SVG), footer, promo bar, socials.
- [ ] Bilingual content for all pages. *(R12.2)*
- **DoD:** all editorial pages render in BM/EN; home matches brand.

## Phase 11 — Hardening & deploy
- [ ] Audit log wired to sensitive actions. *(R13.3, NFR-6)*
- [ ] Security pass: policies on every owned resource, mass-assignment guards,
      upload validation, rate limits, CSRF, secure cookies. *(NFR-1)*
- [ ] Performance pass: N+1 sweep, pagination, gold-price cache, queue slow jobs. *(NFR-2)*
- [ ] Accessibility + SEO pass (focus, reduced motion, meta/OG, slugs, canonical). *(NFR-4, NFR-5)*
- [ ] cPanel deploy: docroot=`public/`, compiled assets, cron `schedule:run`,
      `migrate --force`, `config/route cache`. *(NFR-3)*
- **DoD:** security/perf/a11y/SEO checklists pass; deploys cleanly on shared hosting.

---

## Confirm at the relevant phase (non-blocking)
- Phase 5: actual payment gateway + credentials.
- Phase 1: keep gold price manual, or add an API feed?
- Phase 10: courier/tracking integration or manual tracking numbers?
- Phase 0: locale URL strategy (session switch vs `/en` prefix) — affects routing/SEO.
