mohammadkhayata/garage-erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
garage-erp/docs/dashboard/swagger-client-frontend-gap-report.md

14 KiB
Raw Blame History

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.