# Admin Panel — Module Reference

> Per-module field, column and permission contract for the Dolphin Japan
> admin panel. Read [`Guidelines.md`](Guidelines.md) first — that document
> covers the **how** (architecture, conventions, AI playbook); this one
> covers the **what** (the modules themselves).

---

## Routes

```
/admin                              → Dashboard
/admin/permissions                  → Role permissions matrix
/admin/users/admin                  → Admin users CRUD
/admin/users/editor                 → Editor users CRUD
/admin/cars/list                    → Vehicle CRUD (complex form)
/admin/cars/brand                   → Brand CRUD
/admin/cars/model                   → Model CRUD
/admin/cars/body-style              → Body style CRUD
/admin/cars/color                   → Color CRUD
/admin/faq                          → FAQ CRUD
/admin/price-calculator             → Pricing rule CRUD
/admin/gallery                      → Gallery image CRUD
/admin/inquiry                      → Vehicle inquiries (read)
/admin/orders                       → Custom orders (read + status update)
/admin/contacts                     → Contact messages (read)
/admin/payments                     → Payment tracking
```

All admin routes are mounted under `app/admin/layout.tsx` which:

- Wraps `AdminLayout` (sidebar + topbar from `features/admin/components/`).
- Sets `metadata.robots = { index: false, follow: false }`.
- Will eventually enforce auth via `features/auth`.

---

## Color tokens (admin chrome)

| Element              | Value       |
| -------------------- | ----------- |
| Sidebar background   | `#1a2535`   |
| Header background    | `#2a7fa6`   |
| Active nav item      | `#263545`   |
| Content background   | `#eef0f3`   |
| Edit button          | `#2a7fa6`   |
| Delete button        | `#c0392b`   |
| Table alt row        | `#f7f9fb`   |
| White cards          | `#ffffff`   |

These are encoded in `src/features/admin/components/theme.ts` and the
`.admin-*` utility classes in `src/styles/admin.css`.

---

## Sidebar structure

```
Dashboard
Role Permissions
▸ Users
    Admin Users
    Editor Users
▸ Inventory
    Cars
    Brand
    Model
    Body Style
    Color
    FAQ
    Price Calculator
    Gallery
Inventory Inquiries
Custom Order Inquiries
Contacts
Orders
Payments
```

The canonical `NAV_ITEMS` array lives in
[`src/features/admin/components/AdminLayout.tsx`](../src/features/admin/components/AdminLayout.tsx).
Edit that file to adjust the menu — do **not** duplicate this list.

---

## Module specifications

### 1 · Dashboard

**Stat cards (4-column grid):**
- Total Cars in Inventory
- Total Registered Users
- Pending Inquiries
- Monthly Revenue (USD)

**Sections:**
- Popular Brands — horizontal bar chart (recharts)
- Sales Overview — week / month / year tabs (bar chart)
- Recent Inquiries — mini table with status badges

**Endpoint:** `GET /admin/dashboard/stats` → [`DashboardStats`](../src/features/admin/types/admin.types.ts)

---

### 2 · Role Permissions

**Roles:** `super_admin` · `admin` · `editor` · `viewer`
*(`super_admin` row is always all-checked and disabled.)*

**Permission keys** are listed in
[`src/features/admin/data/dummy.ts`](../src/features/admin/data/dummy.ts).
Update both that file and `docs/API.md` when adding a new permission.

**Endpoints:**
- `GET /admin/permissions`
- `GET /admin/permissions/roles`
- `PUT /admin/permissions/roles/{role}`

---

### 3 · User Management (Admin / Editor)

**Table columns:** S/N · Name · Email · Phone · Country code · Country · Address · Gender · Active? · Actions

**Add / Edit modal fields:**
- Name *(text, required)*
- Email *(email, required)*
- Phone *(text)*
- Phone country code *(text)*
- Phone country name *(text)*
- Address *(text)*
- Gender *(select: Male / Female / Other)*
- Is Active *(checkbox)*
- Password *(password — only shown on Add)*
- Module Permissions *(checklist — Admin / Editor only; Super Admin is implicit)*

**Endpoints:**
- `GET /admin/users/admins` · `GET /admin/users/editors`
- `POST /admin/users` · `PUT /admin/users/{id}` · `DELETE /admin/users/{id}`

---

### 4 · Vehicle Brand (CRUD)

**Fields:** `name` *(text, required)*
**Columns:** S/N · Name · Actions
**Endpoints:** `/brands` · `/admin/brands` (full CRUD)

---

### 5 · Vehicle Model (CRUD)

**Fields:** `name` · `brandId` *(select)*
**Columns:** S/N · Name · Brand · Actions
**Endpoints:** `/models?brandId=` · `/admin/models` (full CRUD)

---

### 6 · Body Style (CRUD)

**Fields:** `name` · `image` *(file upload)*
**Columns:** S/N · Image · Name · Actions
**Endpoints:** `/body-styles` · `/admin/body-styles` (full CRUD)

---

### 7 · Vehicle Color (CRUD)

**Fields:** `name` · `hex` *(optional, for swatch)*
**Columns:** S/N · Swatch · Name · Actions
**Endpoints:** `/colors` · `/admin/colors` (full CRUD)

---

### 8 · Vehicle (CRUD) — Complex Form

**Table columns:** S/N · Title · Brand · Model · Year · Price (JPY) · Mileage · Status · Actions

**Form sections** (scrollable, collapsible):

#### Basic Info (3-col grid)

| Field             | Type                                                |
| ----------------- | --------------------------------------------------- |
| Brand             | select                                              |
| Model             | select (filtered by brand)                          |
| Body Style        | select                                              |
| Color             | select                                              |
| Title             | text                                                |
| Price (JPY)       | number — stored as integer yen                      |
| Model Year        | year picker                                         |
| Stock Number      | text                                                |
| Update Date       | date picker                                         |
| Location          | text                                                |
| Mileage           | number                                              |
| Mileage Unit      | select: KM / MI                                     |
| Repaired          | select: NONE / MINOR / MAJOR                        |
| Steering          | select: LEFT / RIGHT                                |
| Transmission      | select: AT / MT / CVT                               |
| Fuel              | select: GASOLINE / DIESEL / HYBRID / ELECTRIC       |
| Drive System      | select: 2WD / 4WD / AWD                             |
| Doors             | select: 2D / 3D / 4D / 5D                           |
| Displacement      | text                                                |
| Chassis No        | text                                                |
| Model Code        | text                                                |
| Description       | textarea                                            |
| Seating Capacity  | select: 1–9                                         |
| Is Featured?      | checkbox                                            |
| Cubic Meter       | text                                                |

#### Specific Info (boolean checkbox groups)

* **Car Condition** — Maintenance Record · One Owner · Non-smoking
* **Standard Features** — Welfare Vehicle · Cold-Weather Spec · Supercharger · Seating Capacity 2
* **Equipment** — Electric Retractable Mirror · Center Differential Lock · Clean Diesel · 100V Power · Bluetooth · USB · Drive Recorder · Idling Stop · Anti-theft · Power Windows · Power Steering · Downhill Assist · Lift Up · Double A/C · A/C · ABC · Sunroof · Manual Sliding Doors · Driver/Passenger Airbag
* **Interior / Exterior** — Headlight Washer · Air Suspension · Roof Rail · Side/All-around/Front/Back Camera · Seat A/C · Electric Rear Gate · Walk-Through · Seat Heater · Electric Retractable 3rd Seat · Ottoman · Tip-Up Seat · Full-Flat Sheet · Bench Seat · 3-row Seat · Power Seats · Run-Flat Tire · Lowdown · Smart Key · Aero · ETC · HID · LED Headlamp · Keyless · (Half-)Leather · Alloy Wheel · DVD · CD/Music Server · TV · Memory Navi
* **Self-Driving** — Park Assist · Auto Parking · Lane Keep · Auto Cruise
* **Safety** — Active Headrest · Auto Light · Auto High Beam · Clearance Sonar · CDR · Collision-Safety Body · ESC

> **Editing tip:** Persist these as a `Record<string, boolean>` keyed by
> stable IDs, not as a positional array. Add/remove flags by key — do not
> shift indexes.

**Image gallery:** multi-image upload, drag-to-reorder, mark "primary".
Use the `Gallery` upload primitives, not a one-off implementation.

**Endpoints:**
- `GET /vehicles` · `GET /vehicles/{idOrSlug}`
- `POST /admin/vehicles` · `PUT /admin/vehicles/{id}` · `DELETE /admin/vehicles/{id}`

---

### 9 · FAQ (CRUD)

**Fields:** `question` *(textarea)* · `answer` *(textarea)* · `position` *(number)*
**Columns:** S/N · Position · Question (truncated) · Actions
**Endpoints:** `/faqs` · `/admin/faqs` (full CRUD)

---

### 10 · Price Calculator Rules (CRUD)

**Fields:**
- `country` *(select)*
- `destinationPort` *(text)*
- `deliveryCharge` *(number, USD)*
- `marineInsurance` *(number, USD)*
- `preExportInspection` *(number, USD)*

**Columns:** S/N · Country · Port · Delivery · Insurance · Inspection · Actions

**Public quote endpoint** (used on the customer-facing pricing widget):
`POST /pricing/calculate` → returns `CalculateQuoteResponse`.

**Admin endpoints:** `/admin/pricing/rules` (full CRUD).

---

### 11 · Gallery (CRUD)

**Fields:** `title` · `image` *(file upload)* · `category`
**View:** responsive image grid; each card shows title, category badge, delete button.
**Endpoints:** `/gallery` · `/admin/gallery` (full CRUD; `POST` accepts `multipart/form-data`).

---

### 12 · Contact List *(read + delete)*

**Columns:** S/N · Name · Company · Country · Email · Phone · Comment (truncated) · Status · Actions (View / Mark Read / Delete)
**Endpoints:** `POST /contact` (public) · `GET /admin/contacts` · `PATCH /admin/contacts/{id}` · `DELETE /admin/contacts/{id}`

---

### 13 · Inventory Inquiry *(read + status)*

**Columns:** S/N · Name · Vehicle · Country · Email · Phone · Message (truncated) · Date · Status · Actions
**Endpoints:** `POST /inquiries` (public) · `GET /admin/inquiries` · `PATCH /admin/inquiries/{id}` · `DELETE /admin/inquiries/{id}`

---

### 14 · Custom Orders *(read + status)*

**Columns:** S/N · User · Brand/Model · Country · Status · Date · Budget · Actions (View · Update Status)
**Endpoints:** `POST /orders/custom` (public) · `GET /admin/orders` · `PATCH /admin/orders/{id}` · `DELETE /admin/orders/{id}`

---

### 15 · Payments

**Columns:** S/N · User · Order ID · Amount · Currency · Status · Date · Method · Actions (View)
**Endpoints:** `GET /admin/payments` · `POST /admin/payments` · `PUT /admin/payments/{id}` · `DELETE /admin/payments/{id}`

---

## Cross-cutting admin patterns

* **Lists** — search input + sortable column headers + footer pagination.
  Use the shared `DataTable` primitive once it lands at
  `src/shared/components/ui/DataTable.tsx`.
* **Create/Edit** — `AdminModal` from `src/features/admin/components/`.
  Always disable submit while pending, surface errors via `toast.error()`,
  refresh the parent list on success.
* **Delete** — `ConfirmDialog` from `src/features/admin/components/`.
  Optimistic UI is acceptable as long as the action is reverted on failure.
* **Empty state** — every list view should render a friendly empty state
  (icon + headline + CTA where applicable), not just a blank table.
* **Loading state** — skeleton rows, not a centered spinner, for tables.

For anything not covered here, defer to [`Guidelines.md`](Guidelines.md).