techxcar/docs/superpowers/specs/2026-06-22-plan3-core-pages-design.md

# TechXCar — Plan 3: Core Workshop Pages

**Date:** 2026-06-22
**Status:** Approved

## Scope

Build the 3 missing tenant-facing pages: Clients, Catalog, Work Orders. Backend has all 31 endpoints ready. Frontend needs hooks, pages, modals, and routing wired up.

---

## Architecture

Approach: **hooks-per-domain + pages**. Each domain has a dedicated hook file in `frontend/src/hooks/` that wraps TanStack Query. Pages consume hooks and stay presentational.

### New files

```
frontend/src/
├── hooks/
│   ├── useClients.ts
│   ├── useCatalog.ts
│   └── useWorkOrders.ts
├── components/
│   └── ui/
│       └── dialog.tsx          ← shadcn Dialog (shared by all modals)
└── pages/app/
    ├── clients/
    │   ├── ClientsPage.tsx
    │   └── ClientDetailPage.tsx
    ├── catalog/
    │   └── CatalogPage.tsx
    └── work-orders/
        ├── WorkOrdersPage.tsx
        └── WorkOrderDetailPage.tsx
```

### New routes (added to `App.tsx`)

```
/app/clients              → ClientsPage
/app/clients/:id          → ClientDetailPage
/app/catalog              → CatalogPage
/app/work-orders          → WorkOrdersPage
/app/work-orders/:id      → WorkOrderDetailPage
```

---

## Domain: Clients

### `useClients.ts`

| Hook | Method | Endpoint |
|---|---|---|
| `useClients()` | GET | `/clients` |
| `useClient(id)` | GET | `/clients/:id` |
| `useCreateClient()` | POST | `/clients` |
| `useUpdateClient()` | PUT | `/clients/:id` |
| `useDeleteClient()` | DELETE | `/clients/:id` |
| `useClientVehicles(clientId)` | GET | `/clients/:id/vehicles` |
| `useCreateVehicle(clientId)` | POST | `/clients/:id/vehicles` |
| `useUpdateVehicle()` | PUT | `/vehicles/:id` |

All mutations call `queryClient.invalidateQueries` on success.

### `ClientsPage`

- Table columns: Nome, NIF, Telefone, Email, Data criação
- "Novo Cliente" button → modal (create)
- Edit icon per row → same modal prefilled
- Modal fields: nome (required), NIF, telefone, email, morada, notas

### `ClientDetailPage`

- Header: client name + fields (NIF, phone, email, address, notes) + Edit button
- "Veículos" section below: table with matrícula, marca, modelo, ano
- "Adicionar Veículo" → modal: matrícula (required), marca (required), modelo (required), ano, VIN, quilómetros, notas
- Edit icon per vehicle row → same modal prefilled
- Back link → `/app/clients`

---

## Domain: Catalog

### `useCatalog.ts`

| Hook | Method | Endpoint |
|---|---|---|
| `useCatalog()` | GET | `/catalog` |
| `useCreateCatalogItem()` | POST | `/catalog` |
| `useUpdateCatalogItem()` | PUT | `/catalog/:id` |
| `useDeleteCatalogItem()` | DELETE | `/catalog/:id` |

### `CatalogPage`

- Table columns: Código, Nome, Categoria, Unidade, Preço Base, Estado (badge)
- "Novo Item" button → modal (create)
- Edit icon per row → modal prefilled
- Delete: button toggles to "Confirmar?" before calling DELETE
- Modal fields: código, nome (required), categoria, unidade (select: un/hora/litro/kg), preço base (number), activo (checkbox)

---

## Domain: Work Orders

### `useWorkOrders.ts`

| Hook | Method | Endpoint |
|---|---|---|
| `useWorkOrders(status?)` | GET | `/work-orders?status=` |
| `useWorkOrder(id)` | GET | `/work-orders/:id` |
| `useCreateWorkOrder()` | POST | `/work-orders` |
| `useTransitionWorkOrder()` | POST | `/work-orders/:id/transition` |
| `useAddWOItem()` | POST | `/work-orders/:id/items` |
| `useRemoveWOItem()` | DELETE | `/work-orders/:id/items/:itemId` |
| `useAddStaffHours()` | POST | `/work-orders/:id/staff-hours` |
| `useRemoveStaffHours()` | DELETE | `/work-orders/:id/staff-hours/:shId` |

### `WorkOrdersPage`

- Table columns: Nº OT, Cliente, Veículo, Estado (badge colorido), Data
- Status filter: tabs (Todas / Abertas / Em Progresso / Concluídas / Faturadas / Canceladas)
- "Nova OT" → modal: cliente (searchable dropdown from `/clients`), veículo (filtered by client), notas internas, notas cliente
- Click row → navigate to `/app/work-orders/:id`

### `WorkOrderDetailPage`

Two-column layout:

**Left column — info + transitions:**
- OT number, status badge, client name, vehicle plate + brand/model
- Internal notes, client notes (editable inline via PUT)
- State stepper: `Aberta → Em Progresso → Concluída → Faturada`
- Transition buttons: advance to next state, or "Cancelar OT" (any state except invoiced)
- Back link → `/app/work-orders`

**Right column — items + hours:**
- "Peças / Serviços" table: descrição, qty, preço unitário, desconto %, total
  - "Adicionar Item" → modal: select catalog item (searchable), qty, unit price (prefilled from catalog), discount %
  - Remove icon per row (DELETE)
- "Horas de Técnico" table: técnico (staff_id), horas, custo/hora, total
  - "Adicionar Horas" → modal: staff_id (text for now — staff module in Plan 4), horas, custo/hora
  - Remove icon per row (DELETE)
- Totals row at bottom: subtotal peças + subtotal horas + total geral

### State badge colours

| Status | Colour |
|---|---|
| open | slate |
| in_progress | blue |
| completed | green |
| invoiced | purple |
| cancelled | red |

---

## Shared components

- **`dialog.tsx`** — shadcn Dialog, used by all create/edit modals. Install via shadcn CLI or copy pattern from existing ui components.
- All pages follow existing dark slate theme: `bg-slate-950` root, `bg-slate-900` panels, `border-slate-700/800`, white text.
- Loading states: `<p className="text-slate-400">A carregar...</p>`
- Empty states: `<p className="text-slate-500 text-sm">Nenhum registo.</p>`
- Error states: show `ApiError.message` in a red banner.

---

## Out of scope (Plan 4+)

- Staff management (staff_id is free text for now)
- PDF invoice generation
- Notifications (Telegram / email)
- Dashboard statistics
- Billing / invoicing module