garage-erp/docs/dashboard/swagger-client-frontend-gap-report.md

# Phase 1 Backend and Frontend Gap Report

Date: 2026-04-11

This report answers the two deliverables requested for Phase 1:

1. Backend todos, measured against the Phase 1 roadmap using the Swagger contract in `packages/api/types/index.ts`
2. Frontend todos, measured by comparing the domain client layer in `packages/api/src/clients` and `packages/api/src/api.ts` against real dashboard usage

The frontend section still uses the contract -> client -> usage audit. The backend section has been remapped to the business roadmap instead of treating missing client wrappers as missing backend work.

## Rules Used

- Backend ready = the Phase 1 capability is clearly represented by an endpoint or response shape in `packages/api/types/index.ts`
- Backend todo = the Phase 1 workflow is missing from Swagger, or only partially represented by base CRUD without the required workflow depth
- Frontend implemented = any client method is used somewhere in dashboard source
- Shared CRUD usage counts as implementation:
  - `getClient={(api) => api.foo}` on `ResourcePage` or `CrudResource` counts as `list` and `destroy`
  - explicit `api.foo.bar()` calls count as direct method usage
- Generated output under `.next` was excluded

## Executive Summary

Backend contract coverage is stronger than the earlier UI-only Phase 1 comparison suggested. The API already covers the main CRUD and operational foundation for dashboard metrics, customers, vehicles, services, parts, vendors, appointments, inspections, job cards, employees, permissions, roles, time sheets, and workshop settings.

The remaining backend work is concentrated in a smaller set of deeper workflows: history and reporting views, estimate approval and estimate line-item depth, stock intelligence such as low-stock or reorder alerts, technician-specific workload data, a visible final `closed` job-card state, and clearer system email or currency configuration.

Frontend audit counts:

- Swagger paths found: 260
- Distinct client route strings found: 232
- Swagger paths with no client wrapper: 28
- Clients exposed by `createApi()`: 57
- Clients used somewhere in dashboard source: 50
- Completely unused clients: 7
- Partially used clients: 44
- Fully wired clients under the current rule: 6

## Backend Todos

These are the Phase 1 backend todos after checking the roadmap against the actual Swagger contract.

### Already ready in backend contract

- Dashboard `/api/home` already returns financial charts, work-order status cards, appointment KPIs, upcoming appointments, inventory counts, customer segmentation counts, and vehicle breakdowns.
- Customers already support CRUD, customer types, notes, `company_name`, and insurance-related fields.
- Vehicles already support CRUD, make/model/year, VIN, plate, mileage, owner linking, documents, and mileage logs.
- Services already expose duration-related data through `labor_hours`.
- Parts and inventory already expose SKU, opening stock, and min/max stock, plus inventory-adjustment resources.
- Vendors, purchase orders, bills, vendor credits, and payment flows already exist in the contract.
- Appointments already support CRUD, status changes, and job-card unlinking.
- Inspections already support CRUD, checkpoints, labels, media, and attachments.
- Job cards already support technician and service-writer assignment, parts, services, expense items, attachments, check-in, delivery, digital-authorisation flags, and parts-issuing flags.
- Employees already support CRUD, per-employee permissions, and attendance or time-sheet related fields.
- Roles already exist in Swagger through `/api/roles` and `/api/roles/{id}`.
- Time tracking already exists in Swagger through `/api/time-sheets`, `/api/time-sheet/clock-in`, and `/api/time-sheet/clock-out`.
- Workshop settings and operational configuration already exist through `/api/settings` and `/api/configurations...`.

### Real backend todos by Phase 1 area

| Phase 1 area | Contract status | Backend todo |
|---|---|---|
| Dashboard workload | Partial | `/api/home` covers generic work-order KPIs, but there is no clear technician-workload or active-repairs-by-technician feed. |
| Customer, vehicle, and supplier history | Missing | No dedicated customer service-history, vehicle service-history, vehicle purchase-history, or vendor purchase-history routes were found. |
| Estimates | Partial | Swagger only exposes `/api/estimates` and `/api/estimates/{id}`. The `{id}` route has no `GET` in schema, and there are no approval, customer-authorisation, service-line, part-line, or totals-specific routes. |
| Inspection reporting | Missing | No inspection report, print, export, or PDF endpoints were found. |
| Inventory intelligence | Partial | Parts expose `opening_stock`, `min_stock`, and `max_stock`, but there is no barcode field and no low-stock, reorder, or alert workflow in the contract. |
| Job card final closure | Partial | Contract evidence shows `draft`, `check_in`, `in_progress`, `on_hold`, `ready_to_delivery`, and `delivered`, but no visible `closed` status. |
| System email and currency config | Partial | Settings and configuration endpoints cover workshop profile, tax or discount behavior, digital authorisation, and parts-issuing flags, but there is no clear email-delivery configuration endpoint and no clear currency-setting field even though currency is returned in dashboard responses. |

### Not backend todos anymore

These Phase 1 items are already represented in Swagger and should be treated as client or frontend work instead of backend work:

- fleet, company, and insurer customer segmentation
- service duration
- roles and permissions
- time clock, clock-in, and clock-out data layer
- digital authorisation and parts-issuing configuration flags
- appointment calendar or scheduler presentation, which looks more like a frontend presentation gap than a contract gap

### Client-layer Gaps Against Existing Swagger

These are not missing backend capabilities. They are existing Swagger routes that still do not have matching domain-client wrappers.

#### 1. Entire backend resources missing from the client layer

| Area | Missing Swagger routes | Notes |
|---|---|---|
| Roles | `/api/roles`, `/api/roles/{id}` | Swagger exposes role CRUD, but there is no `RolesClient` and no `api.roles` entry. |

#### 2. Existing client families with missing route coverage

| Area | Missing Swagger routes | Notes |
|---|---|---|
| Configurations | `/api/configurations` | `ConfigurationsClient` only wraps the specialized subroutes, not the aggregate base route. Review whether the base GET is required. |
| Make and Models | `/api/get-makes`, `/api/get-models`, `/api/toggle-make-and-model-status` | `MakeAndModelsClient` currently wraps only CRUD. Helper lookups and the status toggle are missing. |
| Invoice Sequences | `/api/remove-default-invoice-sequence`, `/api/set-default-invoice-sequence` | `InvoiceSequencesClient` currently wraps only CRUD. Default-sequence workflow is missing. |

#### 3. Inspection routes missing from `InspectionsClient`

- `/api/inspections/{id}/add-attachment`
- `/api/inspections/{id}/add-label`
- `/api/inspections/{id}/delete-attachment`
- `/api/inspections/{id}/delete-label`
- `/api/inspections/{id}/get-attachment`

Current `InspectionsClient` wraps checkpoint-level attachment and media helpers, but not these inspection-level attachment and label routes.

#### 4. Job card routes missing from `JobCardsClient`

- `/api/job-cards/{id}/add-expense-item`
- `/api/job-cards/{id}/add-expense-item-attachment`
- `/api/job-cards/{id}/add-internal-note`
- `/api/job-cards/{id}/add-part-attachment`
- `/api/job-cards/{id}/delete-expense-item`
- `/api/job-cards/{id}/delete-expense-item-attachment`
- `/api/job-cards/{id}/delete-internal-note`
- `/api/job-cards/{id}/delete-part-attachment`
- `/api/job-cards/{id}/edit-internal-note`
- `/api/job-cards/{id}/get-expense-item-attachment`
- `/api/job-cards/{id}/get-expense-items`
- `/api/job-cards/{id}/get-internal-notes`
- `/api/job-cards/{id}/get-part-attachment`
- `/api/job-cards/{id}/get-service-attachment`
- `/api/job-cards/{id}/update-expense-item`

Current `JobCardsClient` already covers remarks, recommendations, parts, services, and service attachments, but it does not wrap expense-item subresources, part attachments, internal notes, or attachment retrieval endpoints.

## Frontend Todos

These are client capabilities that are already available in the API layer, but are still missing or only partially wired in dashboard source.

### 1. Completely unused clients

These clients have zero usage anywhere in `apps/dashboard/app`, `apps/dashboard/modules`, or `apps/dashboard/shared`.

| Client | Gap |
|---|---|
| `holidays` | Entire client unused |
| `invoiceSequences` | Entire client unused |
| `serviceGroupIncludes` | Entire client unused, including `changeArrangement` |
| `serviceGroupParts` | Entire client unused |
| `serviceGroupPricings` | Entire client unused |
| `serviceGroupServices` | Entire client unused |
| `timeSheets` | Entire client unused, including `clockIn` and `clockOut` |

### 2. High-signal partial clients

These clients are used, but important workflows are still not wired in the frontend.

| Client | Already used | Still missing in frontend |
|---|---|---|
| `auth` | `login` | `logout`, `profile` |
| `expenses` | base CRUD plus `listItems` | bill subflow, expense-item subflow, item status toggle |
| `inspections` | base CRUD, categories, checkpoints, checkpoint media | inspection-level attachments, inspection-level labels, checkpoint label management |
| `inventory` | category and unit-type create/list, labor-rate list | labor-rate CRUD/defaults, category and unit-type update/destroy/defaulting |
| `invoices` | base CRUD, documents, notes | label CRUD/list, attachment helpers, document or note update helpers not used |
| `jobCards` | base CRUD, date/status flow, check-in, delivery, parts, services, attachments, remarks, recommendations | service-attachment UI flow, edit remark path, edit recommendation path, import/export |
| `labels` | `list`, `create` | `update`, `destroy`, `show`, import/export |
| `paymentModes` | `list` | create, update, delete, show, import/export |
| `paymentTerms` | `list` | create, update, delete, show, default-setting, import/export |
| `referralSources` | `list` | create, update, delete, show, default-setting, import/export |
| `reasons` | `list` | create, update, delete, show, import/export |
| `serviceGroups` | base CRUD | label workflows, status toggle, show, import/export |
| `shopCalendars` | `list`, `create`, `destroy` | `setDefault`, `removeDefault`, `updateDayType` |
| `tasks` | base CRUD | `complete` |
| `taskSections` | base CRUD | arrangement change, default toggles, `show`, import/export |
| `taskTypes` | base CRUD | default toggles, `show`, import/export |
| `vehicleAttributes` | create/list for body type, fuel type, transmission, color | update and destroy for all lookup records |
| `vehicleDocuments` | document and mileage flows, document-type create/list | document-type update and destroy |
| `vendors` | base CRUD | vendor address workflows, status toggle, `show`, import/export |
| `vendorCredits` | base CRUD | attachments and internal notes |

### 3. Lower-priority partials

These clients are already functionally present, but still miss mostly generic `show`, import, export, or default-toggle wiring.

- `appointments`: missing `show`, `importData`, `exportData`
- `bills`: missing `show`, `importData`, `exportData`
- `creditNotes`: missing `editInternalNote`, `importData`, `exportData`
- `customers`: the UI uses inherited `importData` and `exportData`, but the direct `import()` and `export()` alias methods are unused
- `departments`: missing `show`, `importData`, `exportData`
- `employees`: missing `importData`, `exportData`
- `estimates`: missing `show`, `importData`, `exportData`
- `expenseItems`: missing `importData`, `exportData`
- `insuranceTypes`: missing `show`, `importData`, `exportData`
- `inventoryAdjustments`: missing `show`, `importData`, `exportData`
- `inventoryCategories`: missing `show`, `importData`, `exportData`
- `makeAndModels`: missing `importData`, `exportData`
- `parts`: missing `show`, `toggleStatus`
- `paymentMades`: missing `show`, `importData`, `exportData`
- `paymentReceived`: missing `show`, `importData`, `exportData`
- `purchaseOrders`: missing `show`, `importData`, `exportData`
- `quickNotes`: missing `show`, `importData`, `exportData`
- `quickRemarks`: missing `show`, `importData`, `exportData`
- `services`: missing `show`
- `shopRecommendations`: missing `show`, `importData`, `exportData`
- `shopTimings`: missing `setDefault`, `removeDefault`, `importData`, `exportData`
- `shopTypes`: missing `show`, `importData`, `exportData`
- `taxes`: missing `show`, `importData`, `exportData`
- `vehicles`: the UI uses inherited `importData` and `exportData`, but the direct `import()` and `export()` alias methods are unused

## Corrections Versus `feature-checklist.md`

Under the stricter checklist rule, lookup-only usage did not count as UI coverage. Under the user rule for this audit, it does.

That changes the outcome materially:

- The old checklist had 21 `Client Only` resources
- The actual zero-usage client list under the current rule is 7 clients

Previously marked as `Client Only`, but already exercised somewhere in dashboard source under this rule:

- countries and states through `geo`
- customer types through `customers.listCustomerTypes`
- referral sources
- payment terms
- payment modes
- labels
- quick notes
- quick remarks
- reasons
- labor rates through `inventory.listLaborRates`

The remaining true zero-usage areas are concentrated in:

- holidays
- invoice sequences
- time sheets
- service-group includes, parts, pricings, and services

## Recommended Order

1. Close the real backend Phase 1 gaps first: estimate workflow depth, history or reporting endpoints, stock intelligence, technician-workload feeds, visible job-card closure, and missing email or currency configuration.
2. Close the client-layer omissions against existing Swagger: roles, invoice-sequence defaults, make/model helper routes, inspection-level attachment or label routes, and job-card expense or internal-note routes.
3. Build UI coverage for the 7 completely unused clients, then finish the high-signal partial workflows, especially expenses, inspections, inventory, job cards, vendors, service groups, shop calendars, and tasks.