feat: add maintenance ticketing and parts inventory prototype

[jmarrxyz]

Reviewable diff: +7740/-1 across 52 files (excludes generated, test, and story files).

Summary

This draft adds a maintenance workspace for triaging repair tickets, reviewing repair history, and tracking spare-parts inventory. It also defines the protobuf, persistence schema, domain services, and Connect handlers needed to turn the current UI prototype into an operator-backed workflow. The stale branch has been brought onto current main; its superseded infrastructure-device implementation was removed in favor of the production infrastructure stack already on main.

This remains a draft because the maintenance page currently uses local mock data and the client API adapters, SQL store implementations, and fleetd handler registration still need to be wired before the workflow is production-ready.

How it works

Users with maintenance:read see a new lazy-loaded Maintenance destination. The page exposes list and Kanban queue views, history, and inventory, plus ticket create/detail, comments, status, RMA, completion, bulk-close, and stock-adjustment UI flows; today those views are backed by feature-local mock data. Review feedback is reflected in a standard bulk-close modal, a constrained scrolling ticket detail with shared dropdown icons, and a streamlined create form with a Miner-defaulted category dropdown, current-site selection, and a single description field.

The server-side contract is defined in parallel: maintenance and inventory protobuf services generate Connect clients and handlers, handlers enforce maintenance:read or maintenance:manage, domain services validate mutations and coordinate transactional work, and sqlc queries target the new repair-ticket, comment, part-usage, and inventory tables. Cursor requests are validated before narrowing enum values or passing IDs to the domain layer.

flowchart LR
    U["Fleet operator"] --> N["Maintenance navigation"]
    N --> P["Maintenance page"]
    P --> Q["Ticket queue and detail"]
    P --> H["Repair history"]
    P --> I["Parts inventory"]
    Q --> M["Feature-local mock data (current draft)"]
    H --> M
    I --> M
    P --> A["Generated client adapters (to wire)"]
    A --> C["Connect handlers"]
    C --> D["Maintenance and inventory domain services"]
    D --> S["SQL stores (to implement)"]
    S --> T["Repair and inventory tables"]

Loading

sequenceDiagram
    participant Operator
    participant UI as Maintenance UI
    participant API as Client adapter
    participant Handler as Connect handler
    participant Domain as Domain service
    participant DB as Postgres
    Operator->>UI: Create or update repair work
    UI-->>Operator: Prototype interaction from local state
    Note over UI,DB: Production request path is defined but not fully wired in this draft
    UI->>API: Maintenance or inventory request
    API->>Handler: Validated protobuf message
    Handler->>Domain: Organization-scoped command
    Domain->>DB: Transactional sqlc operation
    DB-->>Domain: Ticket or inventory state
    Domain-->>UI: Generated response

Loading

Areas of the code involved

Area / package / file	What changed	Why it matters for review
client/src/protoFleet/features/maintenance/	Added list/Kanban queue views, ticket detail/create/close flows, repair history, inventory views, and prototype data	Review workflow coverage, component boundaries, and clarity that data is still local
client/src/protoFleet/features/maintenance/**/*.stories.tsx	Added 16 focused Storybook scenarios across the workspace, ticket lifecycle states, dialogs, history, and inventory	Story files — use these as the primary UI review surface
client/src/protoFleet/api/	Added typed maintenance and inventory adapter surfaces	Review the intended UI-to-RPC boundary; RPC calls remain TODO
client/src/protoFleet/config/navItems.ts, routePrefetch.ts, router.tsx	Added permission-gated navigation and coordinated lazy route prefetch	Review route visibility and bundle-loading behavior
proto/maintenance/v1/, proto/inventory/v1/	Added service contracts, request validation, enums, and read models	Review API shape, lifecycle operations, and pagination semantics
server/internal/handlers/	Added permission checks, protobuf/domain translation, bulk mutation handling, enum bounds checks, and CSV preview/confirm handling	Review the service boundary and organization scoping
server/internal/domain/maintenance/, inventory/	Added validation, activity events, transaction coordination, CSV parsing, and store-facing models	Review lifecycle rules and transaction boundaries
server/internal/domain/stores/interfaces/	Added persistence interfaces and generated mocks	Generated mocks — skip; review interface completeness
server/migrations/000144–000148	Added repair ticket, comment, part-usage, and inventory schemas, plus permission-catalog seeding, with matching down migrations	Review constraints, indexes, tenancy, permissions, and migration ordering
server/sqlc/queries/	Added CRUD, filtering, pagination, stats, bulk update, and stock queries	Review organization filters and mutation safety
Generated protobuf/sqlc files	Regenerated from the protobuf and SQL sources	Generated — skip
Existing infrastructure-device stack	Kept current main implementation and discarded the branch's obsolete parallel stack	Avoids restoring duplicate APIs, tables, and UI after the branch revival

Key technical decisions & trade-offs

• Keep main's production infrastructure-device stack instead of reconciling the stale branch's duplicate infradevice implementation.
• Renumber the branch's undeployed migrations to 000144–000147 instead of editing or colliding with migrations added since the branch diverged.
• Introduce maintenance:read and maintenance:manage instead of reusing site permissions, because repair workflows are organization-wide and include inventory operations.
• Use descending ID cursors for the initial list queries instead of exposing database offsets; richer sort-aware cursor tokens remain future work.
• Keep the PR as a draft instead of presenting the mock-backed UI and unwired persistence interfaces as production-complete.

Testing & validation

• just lint — protobuf, client, server, and plugin lint all pass.
• server/just build — all server packages build.
• go test ./... -run '^$' — every server package compiles, including generated maintenance/inventory services.
• go test ./server/internal/ha/deployment — passes after the final sync with main.
• Client Prettier check, TypeScript --noEmit, and ProtoFleet production build pass.
• npm run build-storybook passes for 16 maintenance scenarios across eight story files.
• Four focused maintenance UI test files (5 tests) cover the standard bulk-close modal, create-form defaults, ticket-detail scrolling/dropdown controls, and all Kanban lanes.
• Browser checks cover the list/Kanban queue, category switching, standard bulk close, ticket-detail scrolling, inventory, and CSV-import interactions with no runtime errors.
• Server regeneration and protobuf/sqlc generation complete with no lint errors.
• CI Server Checks / Test passes the full database-backed suite, including migrations through 000148 and built-in-role seeding.
• Desktop visual CI currently expects the pre-Maintenance sidebar baseline; refreshing that approval-gated snapshot remains pending explicit reviewer confirmation.
• The end-to-end maintenance RPC/store path is intentionally not covered until it is wired.