# Requirements

Requirements for the Amaleena rebuild (Laravel). IDs (e.g. `R2.3`) are referenced
by task.md. "Shall" statements are acceptance criteria.

## Personas
- **Guest** — browses and can check out without an account.
- **Customer** — registered; has orders, addresses, store-credit balance.
- **Affiliate** — customer with a referral code and commission dashboard.
- **Admin / Staff** — manages catalog, gold price, orders, trade-ins, affiliates,
  vouchers, reviews.

## Resolved assumptions
- **Upah:** products support both per-gram and flat workmanship; admin chooses per product.
- **Gold price:** entered manually by admin (interface allows an API feed later).
- **Payments:** one gateway behind an interface (ToyyibPay/Billplz assumed; confirm at build).
- **Stock:** optional per variation; null = made-to-order (no stock limit).
- **Checkout:** guest checkout allowed; account creation optional at the end.
- **Locale:** BM default + English; switch persisted in session.

---

## 1. Catalog & browsing
- **R1.1** The system shall list products in a shop page, paginated, newest first by default.
- **R1.2** The system shall support sorting (latest, price low→high, high→low) and
  filtering by category and purity.
- **R1.3** The system shall present categories as a hierarchy (parent → child → grandchild)
  and allow a product to belong to multiple categories.
- **R1.4** The system shall provide product search by name.
- **R1.5** A product detail page shall show images, purity, description, weight
  variations, the computed price (or price range), and related products.
- **R1.6** The system shall show empty states when a category/search has no results.

## 2. Products & pricing (gold-computed)
- **R2.1** A product shall have a purity (916 or 375) and a type (simple | variable).
- **R2.2** A variable product shall have variations keyed by weight (grams); each may
  have its own SKU and optional stock.
- **R2.3** The system shall compute a variation's retail price as
  `weight × current gold price per gram (for its purity) + upah`, where upah is
  per-gram or flat per the product's `workmanship_type`.
- **R2.4** The system shall allow an optional manual price override per variation that
  bypasses computation.
- **R2.5** The system shall display a price range for variable products spanning the
  cheapest and dearest variation.
- **R2.6** Admin shall record a new gold price (per gram, per purity, with sell and
  buy rates); doing so shall reprice the whole catalog without editing products.
- **R2.7** Gold price history shall be immutable (append-only) and auditable.
- **R2.8** Cart and product pages shall always reflect the current computed price.

## 3. Cart
- **R3.1** A guest or customer shall add a specific variation + quantity to a cart.
- **R3.2** The cart shall show live computed prices and a subtotal.
- **R3.3** The system shall persist a guest cart by session and a customer cart by account.
- **R3.4** The system shall validate stock (where tracked) before adding/checkout.

## 4. Checkout & orders
- **R4.1** Before payment, the system shall display the final price and weight for
  confirmation (policy requirement).
- **R4.2** On order placement, the system shall snapshot each line's weight, purity,
  gold price per gram, upah, and unit price; the order total shall never change afterward.
- **R4.3** The system shall apply free shipping when subtotal ≥ RM300, else a zone rate
  (Peninsular vs East Malaysia); Malaysia addresses only.
- **R4.4** The system shall allow applying a valid store credit / e-voucher at checkout.
- **R4.5** The system shall capture affiliate attribution (if present) onto the order.
- **R4.6** The system shall generate a unique human-readable order number and send a
  confirmation email with transaction details.
- **R4.7** A customer shall view their orders, statuses, and tracking numbers.
- **R4.8** Order status shall follow: pending_payment → paid → processing → shipped →
  delivered, with cancelled/refunded branches.
- **R4.9** Order cancellation shall be allowed within 24h if not shipped (size/address
  change reasons); refund issued as e-voucher (or original method on request).

## 5. Payments
- **R5.1** The system shall redirect to the configured gateway to collect payment.
- **R5.2** The system shall verify the gateway callback signature and update the order
  idempotently (duplicate callbacks have no additional effect).
- **R5.3** On successful payment, the system shall mark the order paid, decrement stock
  (where tracked), queue the confirmation email, and record affiliate commission.
- **R5.4** The system shall log payment callbacks without storing secrets.

## 6. Customer accounts
- **R6.1** A user shall register, log in, reset password, and manage profile/addresses.
- **R6.2** Authentication, password reset, and OTP endpoints shall be rate-limited.
- **R6.3** A customer shall see their store-credit balance and transaction history.

## 7. Store credit / e-voucher
- **R7.1** The system shall issue store credit from refunds, cancellations, and
  approved trade-ins, each with a unique non-sequential code and optional expiry.
- **R7.2** Redemption shall be server-validated (owner, active, unexpired, balance>0)
  and atomic (no double-spend under concurrency), recording a ledger entry.
- **R7.3** A customer shall apply available credit as an order discount at checkout.

## 8. Trade-in (buy used gold)
- **R8.1** A customer shall submit a trade-in request listing items (purity + weight);
  the system shall show an estimated value from the current buy price.
- **R8.2** Admin shall review, set final per-item values, and approve or reject.
- **R8.3** On approval the system shall issue store credit for the final total.
- **R8.4** Every trade-in status change shall be audit-logged.

## 9. Affiliate
- **R9.1** An affiliate shall have a unique referral code and a dashboard showing
  referrals, commission amounts, and statuses — scoped to their own data only.
- **R9.2** A `?ref=CODE` visit shall attribute subsequent orders (cookie window) to
  that affiliate; self-referral shall be blocked.
- **R9.3** Commission shall be computed when an order becomes paid/completed, with
  statuses pending → approved → paid.

## 10. Reviews
- **R10.1** A customer shall submit a 1–5 star review with text for a product.
- **R10.2** Reviews shall be moderated (default pending) before public display.
- **R10.3** The system shall flag verified-purchase reviews and limit one review per
  customer per product.
- **R10.4** Review text shall be escaped/sanitised on output.

## 11. Content (CMS)
- **R11.1** The system shall render editorial pages: About, Terms, Refund Policy,
  Gallery, campaigns.
- **R11.2** The homepage shall present the animated hero, category tiles, new arrivals,
  and testimonials.

## 12. Localization
- **R12.1** All UI strings shall be available in BM and English via translation files.
- **R12.2** Product names/descriptions, category names, and CMS pages shall be
  translatable (BM/EN).
- **R12.3** A visible switcher shall change locale; BM is default; choice persists.

## 13. Admin
- **R13.1** Admin shall CRUD categories, products, variations, and images.
- **R13.2** Admin shall manage gold prices, orders (status/tracking), trade-ins,
  affiliates, store credits, and moderate reviews.
- **R13.3** Admin actions on sensitive records (price, approvals, refunds, order status)
  shall be authorized by policy and audit-logged.

---

## Non-functional requirements
- **NFR-1 Security:** treat all input as untrusted; validate via Form Requests;
  authorize server-side (policies/gates/middleware); protect against SQLi, XSS, CSRF,
  IDOR, mass-assignment, privilege escalation, insecure uploads. Never trust
  client-supplied prices/IDs.
- **NFR-2 Performance:** eager-load to avoid N+1; paginate lists; queue slow work
  (email, commission, exports); cache the current gold price.
- **NFR-3 Hosting:** runs on cPanel/shared hosting; DB queue via cron; compiled assets
  uploaded; no Redis assumption.
- **NFR-4 Accessibility:** responsive to mobile; visible keyboard focus; reduced-motion
  respected; accessible form validation feedback.
- **NFR-5 SEO:** correct locale meta, clean slugs, per-page titles/OG, valid canonical.
- **NFR-6 Reliability:** money as integer cents; immutable order snapshots; idempotent
  payment callbacks; audit logs for sensitive actions.
- **NFR-7 Integrity:** DB foreign keys and unique constraints enforce ownership and
  prevent duplicates (e.g. one review per customer/product; unique order number/SKU/code).

## Out of scope (v1)
International shipping; multi-currency; marketplace/third-party sellers; native mobile app.
