# E-Commerce Project Developer Rules & Standards

This workspace-scoped rules document defines developer guidelines, architectural patterns, and styling standards for this repository. All subsequent changes, additions, and edits must strictly adhere to these rules.

---

## 1. Technology Stack & Framework Rules

- **Backend Framework:** Laravel 12
- **Language Requirements:** PHP 8.2+
- **Security & Auth:** Laravel Sanctum for API token validation; Laravel Session for Admin authentication.
- **Admin Dashboard Layout:** Modern Admin Dashboard using Laravel Blade Templates.
- **Admin Dashboard Styling:** Tailwind CSS (utility classes, custom theme extensions, dark mode styling).
- **Interactive Logic:** jQuery, AJAX requests, and vanilla JavaScript.
- **Data Grids:** Server-side Yajra Laravel DataTables.
- **Charts:** Chart.js loaded dynamically via AJAX.

---

## 2. File Structure & Backend Architecture

Maintain the following structure and guidelines:
- **Controllers:** Keep controllers small and thin. Delegate complex business logic to dedicated Service classes under `app/Services/`.
  - Admin dashboard controllers: `app/Http/Controllers/Admin/`
  - RESTful API controllers: `app/Http/Controllers/Api/V1/`
- **Validation:** Always use Form Request classes (`app/Http/Requests/Admin/` and `app/Http/Requests/Api/V1/`) for validation logic.
- **Responses:** APIs must return JSON responses formatted via API Resources (`app/Http/Resources/Api/V1/`).
- **Authorization:** Enforce authorization using Policy classes (`app/Policies/`) checked in controllers or routes.
- **Data Presentation:** Organize views under `resources/views/admin/` inside resource-specific subdirectories (e.g., `admin/products/`, `admin/orders/`). Place reusable Blade fragments in `resources/views/admin/partials/` or `resources/views/admin/layouts/`.

---

## 3. User Interface (UI) Design Guidelines

- **Typography & Font:** Standard font is Inter (`Inter, ui-sans-serif, system-ui`).
- **Layout Structure:**
  - Sidebar: Left-anchored, collapsible. Divided into logical navigation groups (Workspace, Commerce, Content, Insights, Administration).
  - Header: Top-anchored. Contains dashboard page titles, theme switches (light/dark mode toggle), notification badges, and the user profile dropdown.
- **Color System:**
  - Primary Tones: Slate slate colors (`text-slate-900`, `bg-slate-50`, `border-slate-200` in light mode; `text-white`, `bg-slate-950`, `border-slate-800` in dark mode).
  - Brand Accents: Accent green (`#16a36a` / `bg-brand-500` / `text-brand-600` / `hover:bg-brand-600`).
- **Cards & Shadows:** Cards must use soft rounded corners (`rounded-2xl`) and a soft shadow (`shadow-soft` / `box-shadow: 0 1px 2px rgba(15,23,42,.04), 0 8px 30px rgba(15,23,42,.05)`).
- **Dark Mode:** Fully support dark mode styling using the standard Tailwind `dark:` prefix class. Ensure all text, background, border, input fields, tables, and buttons have compatible dark mode values.
- **Interactivity:**
  - Micro-animations: Hover states must have subtle scale translations (`hover:-translate-y-px`) and transitions (`transition duration-150 ease-in-out`).
  - Validation Feedback: Clear feedback banners (`bg-rose-50 text-rose-700 border-rose-200`).

---

## 4. Database Schema Standards

- **Money Calculations:** Always use `DECIMAL(10,2)` columns for monetary values (`price`, `fee`, `discount`, `subtotal`, `total`). Never use floating-point types (`float` or `double`).
- **Soft Deletes:** Add soft deletes (`deleted_at` timestamp) to catalog tables (`products`, `categories`, `brands`, `shipping_methods`).
- **Indexes:** Ensure all foreign key columns, code columns (`sku`, `code`, `order_number`), status flags, and timestamps frequently used in sorting have indexes.
- **Order Snapshots:** To prevent past orders from changing when methods or rates change, write snapshots of the shipping method and customer address data directly into the order record:
  - `shipping_method_id` (nullable, set null on delete)
  - `shipping_method_name`
  - `shipping_method_code`
  - `shipping_fee`

---

## 5. Yajra DataTables & Grid Standards

- **Server-Side Rendering:** All admin data tables must load server-side via AJAX queries processed by Yajra DataTables.
- **Columns & Formatting:**
  - Truncation: Long descriptions and notes must use string helpers like `Str::limit($text, 50)`.
  - Badges: Enclose statuses in styled badges (e.g. `bg-emerald-100 text-emerald-700` for active/paid, `bg-slate-100 text-slate-600` for draft/inactive, `bg-rose-100 text-rose-700` for cancelled).
- **Interactive Features:**
  - Bulk Actions: Provide a multi-checkbox column to allow batch processes (like bulk status toggle, bulk publish, or bulk deletion).
  - Filters: Incorporate filters above the grid (Category filter, Brand filter, Date range filters, and Status dropdown filters).

---

## 6. Reporting Module Standards

- **Interactive Canvas:** Use Chart.js on visual dashboards and sales summary pages.
- **AJAX Driven:** Load chart datasets dynamically via API endpoints to keep page loading fast.
- **Filtering Options:** Include a time-range filter panel (Today, Yesterday, This Week, This Month, Last Month, This Year, Custom Date Range).
- **Exports:** Provide options to download or print filtered datasets as CSV or printer-friendly layouts.

---

## 7. CMS Content Guidelines

- **Page Layouts:** Support table-driven page content records (`PageContent`) with multi-language headings (`title_en` and `title_km`) and content fields.
- **Homepage Blocks:** Render homepage sections (such as Hero Slider, Featured Categories, Promise Banners) from the database settings, allowing administrators to toggle sections on or off.
- **Media Optimization:** File uploads must validate MIME types (`jpg`, `jpeg`, `png`, `webp`) and enforce maximum file sizes (e.g., 5MB). Process and save images in modern formats (like WebP) where applicable to improve page speeds.
