TBNilles/workorders
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
309f19520ba0ff21fdb77b452d6ccd8d433a9ce5
workorders/CLAUDE.md
T

2558 lines
117 KiB
Markdown
Raw Blame History

# Work Order System — Build TODO
> Hand this file to Claude Code. All frontend files use `.mjs` extensions.
> Stack: Go · Pure JS + Web Components · SQL Server · Docker
---
## Table of Contents
- [Design System](#design-system)
- [Project Structure](#project-structure)
- [Phase 1 — Foundation](#phase-1--foundation)
- [Phase 2 — Field Features](#phase-2--field-features)
- [Phase 3 — Integrations & Admin](#phase-3--integrations--admin)
- [Phase 4 — Polish & Optimization](#phase-4--polish--optimization)
- [Component Inventory](#component-inventory)
- [API Endpoints](#api-endpoints)
- [Database Schema](#database-schema)
- [Conventions](#conventions)
---
## Design System
### Color Palette
```css
:root {
/* Brand */
--navy: #0D2137; /* Primary dark — sidebar, headers */
--teal: #0A7EA4; /* Primary accent — buttons, links, active states */
--teal-lt: #14B8D4; /* Light accent — hover states, highlights */
--teal-dk: #075E7A; /* Dark accent — pressed states */
/* Surfaces */
--bg: #F0F6FA; /* Page background */
--surface: #FFFFFF; /* Cards, panels */
--surface-2: #E8F0F5; /* Inset areas, table stripes */
--sidebar-bg: #0D2137; /* Sidebar background */
--sidebar-hover: #153248;
--sidebar-active: #0A7EA4;
/* Text */
--text: #1A2E3B; /* Primary text */
--text-muted: #64748B; /* Secondary / helper text */
--text-inv: #FFFFFF; /* Text on dark backgrounds */
/* Semantic */
--success: #1D9D6C;
--warning: #E07B39;
--danger: #C0392B;
--info: #0A7EA4;
/* Borders & Shadows */
--border: #D1DDE6;
--border-lt: #E8F0F5;
--shadow-sm: 0 1px 3px rgba(0,0,0,.08);
--shadow-md: 0 4px 12px rgba(0,0,0,.10);
--shadow-lg: 0 8px 24px rgba(0,0,0,.12);
/* Status Pills */
--status-draft: #94A3B8;
--status-assigned: #0A7EA4;
--status-scheduled: #8B5CF6;
--status-in_progress: #E07B39;
--status-pending_review: #D97706;
--status-closed: #1D9D6C;
/* Priority */
--priority-low: #64748B;
--priority-normal: #0A7EA4;
--priority-high: #E07B39;
--priority-urgent: #C0392B;
/* Spacing */
--radius-sm: 4px;
--radius: 8px;
--radius-lg: 12px;
--radius-xl: 16px;
/* Sidebar width */
--sidebar-w: 260px;
--sidebar-collapsed: 64px;
}
```
### Typography
Load via `<link>` in `index.html` — no build step needed:
```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
```
```css
:root {
--font-body: 'Inter', 'Segoe UI', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', 'Cascadia Code', monospace;
--text-xs: 0.70rem; /* 11px — labels, caps */
--text-sm: 0.813rem; /* 13px — helper, meta */
--text-base: 0.938rem; /* 15px — body */
--text-md: 1.063rem; /* 17px — subheadings */
--text-lg: 1.25rem; /* 20px — section headers */
--text-xl: 1.5rem; /* 24px — page titles */
--text-2xl: 2rem; /* 32px — dashboard hero numbers */
--weight-normal: 400;
--weight-medium: 500;
--weight-semibold: 600;
--weight-bold: 700;
}
```
### Component Design Patterns
- Cards: white background, `var(--border)` border, `var(--radius)` corners, `var(--shadow-sm)`
- Buttons: filled primary = `--teal`, ghost = transparent + `--teal` border, danger = `--danger`
- Inputs: `--border` border, focus ring `--teal` 2px outline-offset, `--radius-sm` corners
- Tables: header row `--surface-2`, alternating rows, sticky header on scroll
- Status pills: colored dot + label, pill shape, light background tint of the status color
- Icon + label pattern everywhere — use Lucide icons loaded via CDN (no npm)
### Icons
```html
<!-- index.html — Lucide icon CDN, no API key, tree-shakeable -->
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
```
Call `lucide.createIcons()` after each render. Use named icons:
`clipboard-list`, `users`, `truck`, `wrench`, `map-pin`, `camera`, `file-invoice`,
`layout-dashboard`, `settings`, `bell`, `chevron-left`, `plus`, `search`, `filter`
---
## Project Structure
```
workorder/
├── CLAUDE.md ← !! READ FIRST — conventions for Claude Code
├── cmd/server/main.go
├── internal/
│ ├── api/
│ │ ├── router.go
│ │ ├── middleware/
│ │ │ ├── auth.go
│ │ │ ├── cors.go
│ │ │ └── logger.go
│ │ └── handlers/
│ │ ├── auth.go
│ │ ├── workorder.go
│ │ ├── step.go
│ │ ├── resource.go
│ │ ├── attachment.go
│ │ ├── accounting.go
│ │ ├── user.go
│ │ ├── registry.go ← people/vehicle/equipment/material master lists
│ │ ├── dashboard.go
│ │ └── report.go
│ ├── service/
│ │ ├── workorder.go
│ │ ├── notification.go
│ │ ├── spatial.go
│ │ └── export.go ← CSV/Excel export
│ ├── repository/
│ │ ├── db.go
│ │ ├── workorder.go
│ │ ├── step.go
│ │ ├── resource.go
│ │ ├── attachment.go
│ │ ├── accounting.go
│ │ ├── user.go
│ │ └── registry.go
│ ├── model/
│ │ ├── workorder.go
│ │ ├── step.go
│ │ ├── resource.go
│ │ ├── attachment.go
│ │ ├── accounting.go
│ │ ├── user.go
│ │ └── dashboard.go
│ └── config/config.go
│
├── web/ ← All frontend — served as static files by Go
│ ├── index.html ← App shell, loads fonts, Lucide, Leaflet
│ ├── app.mjs ← <app-root> custom element + client router
│ │
│ ├── components/
│ │ ├── layout/
│ │ │ ├── app-sidebar.mjs ← Left nav — collapsible, mobile drawer
│ │ │ ├── app-topbar.mjs ← Top bar — breadcrumb, notifications bell, user avatar
│ │ │ ├── app-root.mjs ← Shell that wires sidebar + topbar + <main>
│ │ │ └── app-mobile-nav.mjs ← Bottom tab bar for mobile (≤768px)
│ │ │
│ │ ├── work-orders/
│ │ │ ├── wo-list.mjs ← Searchable, filterable WO list
│ │ │ ├── wo-kanban.mjs ← Kanban board view (by status column)
│ │ │ ├── wo-form.mjs ← Create / edit full form
│ │ │ ├── wo-detail.mjs ← Read-only detail — tabs for each section
│ │ │ ├── wo-checklist.mjs ← Step checklist with check-off + progress bar
│ │ │ ├── wo-resource-panel.mjs← Assign people, vehicles, equipment, materials
│ │ │ ├── wo-photo-panel.mjs ← Photo gallery, capture, before/during/after
│ │ │ ├── wo-map.mjs ← Leaflet map + directions button
│ │ │ ├── wo-accounting.mjs ← GL, cost center, WBS, billing ref fields
│ │ │ ├── wo-timeline.mjs ← Audit/activity log feed
│ │ │ └── wo-print.mjs ← Print-friendly layout for field packets
│ │ │
│ │ ├── dashboard/
│ │ │ ├── dash-root.mjs ← Dashboard page shell
│ │ │ ├── dash-kpi-card.mjs ← Reusable stat card (number + trend + icon)
│ │ │ ├── dash-status-chart.mjs← Doughnut chart — WOs by status
│ │ │ ├── dash-priority-bar.mjs← Bar chart — WOs by priority
│ │ │ └── dash-recent-feed.mjs ← Recent activity feed
│ │ │
│ │ ├── registry/
│ │ │ ├── people-list.mjs ← Manage crew / technician records
│ │ │ ├── people-form.mjs
│ │ │ ├── vehicle-list.mjs ← Manage fleet / vehicles
│ │ │ ├── vehicle-form.mjs
│ │ │ ├── equipment-list.mjs ← Manage tools & equipment
│ │ │ ├── equipment-form.mjs
│ │ │ ├── material-list.mjs ← Manage materials / inventory
│ │ │ └── material-form.mjs
│ │ │
│ │ ├── users/
│ │ │ ├── user-list.mjs ← User management (admin only)
│ │ │ ├── user-form.mjs ← Create / edit user, assign role
│ │ │ └── user-profile.mjs ← Current user profile + password change
│ │ │
│ │ ├── reports/
│ │ │ ├── report-root.mjs ← Reports landing page
│ │ │ ├── report-by-status.mjs
│ │ │ ├── report-by-cost.mjs
│ │ │ └── report-export.mjs ← CSV / Excel download triggers
│ │ │
│ │ └── shared/
│ │ ├── ui-badge.mjs ← <ui-badge> — status + priority pills
│ │ ├── ui-button.mjs ← <ui-button> — primary/ghost/danger variants
│ │ ├── ui-card.mjs ← <ui-card> — surface container
│ │ ├── ui-dialog.mjs ← <ui-dialog> — modal with backdrop
│ │ ├── ui-drawer.mjs ← <ui-drawer> — slide-in panel (mobile forms)
│ │ ├── ui-toast.mjs ← <ui-toast> — success/error notifications
│ │ ├── ui-spinner.mjs ← <ui-spinner> — loading state
│ │ ├── ui-empty.mjs ← <ui-empty> — empty state illustration + CTA
│ │ ├── ui-confirm.mjs ← <ui-confirm> — "Are you sure?" dialog
│ │ ├── ui-search.mjs ← <ui-search> — debounced search input
│ │ ├── ui-tabs.mjs ← <ui-tabs> — tab bar + panels
│ │ ├── ui-avatar.mjs ← <ui-avatar> — initials or photo avatar
│ │ └── ui-tooltip.mjs ← <ui-tooltip> — hover tooltip
│ │
│ ├── lib/
│ │ ├── api.mjs ← Fetch wrapper, auth header, error handling
│ │ ├── router.mjs ← Hash/history client router
│ │ ├── store.mjs ← Reactive state (lightweight signal pattern)
│ │ ├── auth.mjs ← JWT storage, decode, role checks
│ │ ├── format.mjs ← Date, currency, phone formatters
│ │ ├── validate.mjs ← Form field validators
│ │ └── utils.mjs ← Misc helpers, debounce, deepMerge
│ │
│ └── styles/
│ ├── global.css ← CSS custom properties (design tokens above)
│ ├── reset.css ← Modern CSS reset
│ ├── typography.css ← Base font rules
│ ├── forms.css ← Shared input/select/textarea styles
│ ├── tables.css ← Shared table styles
│ └── print.css ← Print overrides for wo-print.mjs
│
├── migrations/
│ ├── 001_initial.sql
│ ├── 002_resources.sql
│ ├── 003_attachments.sql
│ ├── 004_accounting.sql
│ ├── 005_users_roles.sql
│ └── 006_audit_log.sql
│
├── uploads/ ← Bind-mounted in Docker
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── go.mod
```
---
## Phase 1 — Foundation
**Goal:** Running app with shell, sidebar, auth, and WO CRUD.
### 1.1 CLAUDE.md (create first)
- [ ] Document `.mjs` extension convention for all frontend JS modules
- [ ] Document Go conventions: package names, error wrapping, named DB params
- [ ] Document CSS convention: always use design token vars, never hardcoded hex
- [ ] Document component convention: Shadow DOM, `#private` fields, custom events
- [ ] List all CDN dependencies and their globals (`L` for Leaflet, `lucide`, `Chart`)
### 1.2 Go Project Bootstrap
- [ ] `go mod init github.com/yourorg/workorder`
- [ ] Add dependencies: `chi/v5`, `sqlx`, `go-mssqldb`, `golang-jwt/jwt/v5`, `google/uuid`, `joho/godotenv`
- [ ] `internal/config/config.go` — load from env: `ADDR`, `DB_DSN`, `JWT_SECRET`, `UPLOAD_PATH`, `BASE_URL`
- [ ] `internal/repository/db.go` — `sqlx.Connect`, pool settings (max open 25, max idle 5, lifetime 5min)
- [ ] `cmd/server/main.go` — wire config → db → router → `http.ListenAndServe`
### 1.3 Database — Migration 001
```sql
-- work_orders table (full schema as planned)
-- Computed wo_number column: 'WO-' + zero-padded id
-- status CHECK constraint
-- priority CHECK constraint
-- Indexes on status, parent, scheduled_start
```
### 1.4 Auth
- [ ] `migrations/005_users_roles.sql`
```sql
CREATE TABLE users (
id INT IDENTITY PRIMARY KEY,
username NVARCHAR(100) NOT NULL UNIQUE,
email NVARCHAR(200) NOT NULL UNIQUE,
display_name NVARCHAR(200),
password_hash NVARCHAR(200) NOT NULL, -- bcrypt
role NVARCHAR(30) NOT NULL DEFAULT 'viewer',
-- admin | dispatcher | field_tech | viewer
avatar_url NVARCHAR(500),
active BIT NOT NULL DEFAULT 1,
last_login DATETIME2,
created_at DATETIME2 NOT NULL DEFAULT GETUTCDATE()
);
-- Seed one admin user
```
- [ ] `POST /api/auth/login` — bcrypt compare, return `{ token, user }` with 8hr JWT
- [ ] `POST /api/auth/refresh` — accepts valid token, returns new token
- [ ] `GET /api/auth/me` — current user from token claims
- [ ] JWT middleware: attach user to `context.Context`, return 401 JSON on failure
- [ ] Role helper: `RequireRole(roles ...string)` middleware
### 1.5 Work Order Backend (CRUD)
- [ ] `model/workorder.go` — `WorkOrder`, `WorkOrderListItem`, `WorkOrderDetail` structs with `db:` and `json:` tags
- [ ] `repository/workorder.go`
- `List(ctx, filters)` — status, search, priority, parentType, page/limit
- `GetByID(ctx, id)` — single WO
- `Create(ctx, wo)` — insert + return generated ID
- `Update(ctx, wo)` — partial update, always set `updated_at = GETUTCDATE()`
- `UpdateStatus(ctx, id, status, userID)` — transition + audit log insert
- `Delete(ctx, id)` — soft delete (add `deleted_at` column)
- `GetDetail(ctx, id)` — joins WO + steps + resources + attachments + accounting in one call
- [ ] Handlers: `List`, `Get`, `Create`, `Update`, `Delete`, `UpdateStatus`
- [ ] Paginated response: `{ data: [...], meta: { page, per_page, total } }`
### 1.6 Frontend Shell
- [ ] `web/index.html`
- Load Google Fonts (Inter + JetBrains Mono)
- Load Lucide CDN
- Load Leaflet CSS + JS CDN
- Load Chart.js CDN
- `<script type="module" src="app.mjs">`
- Viewport meta tag: `width=device-width, initial-scale=1`
- [ ] `web/styles/reset.css` — modern reset (box-sizing, margin 0, img max-width)
- [ ] `web/styles/global.css` — all design tokens, base body/font rules
- [ ] `web/styles/forms.css` — input, select, textarea, label, fieldset base styles
- [ ] `web/lib/api.mjs` — fetch wrapper, auto-inject `Authorization`, handle 401 → emit `auth:expired`
- [ ] `web/lib/auth.mjs` — `getToken()`, `setToken()`, `clearToken()`, `getUser()`, `hasRole()`
- [ ] `web/lib/router.mjs` — hash router, `on(pattern, handler)`, `navigate(path)`, `start()`
- [ ] `web/lib/format.mjs` — `formatDate()`, `formatDateTime()`, `formatRelative()`, `formatPhone()`
- [ ] `web/lib/store.mjs` — reactive signal: `createStore(initial)` returns `{ get, set, subscribe }`
### 1.7 Sidebar Layout
- [ ] **`web/components/layout/app-sidebar.mjs`**
- Dark navy background (`var(--sidebar-bg)`)
- Top: app logo / wordmark
- Nav items with Lucide icon + label (see nav items below)
- Active item: left accent bar + `--teal` background
- Hover: `--sidebar-hover` background, smooth transition
- Bottom: current user avatar + name + logout button
- **Collapsible:** click toggle collapses to icon-only mode (`--sidebar-collapsed` width)
- Collapse state stored in `localStorage`
- Collapsed: show only icons with `<ui-tooltip>` on hover showing label
- [ ] **Nav items (in order):**
```
─── Main ────────────────
Dashboard / (layout-dashboard icon)
Work Orders /work-orders (clipboard-list icon)
─── Resources ───────────
People /registry/people (users icon)
Vehicles /registry/vehicles (truck icon)
Equipment /registry/equipment (wrench icon)
Materials /registry/materials (package icon)
─── Operations ──────────
Reports /reports (bar-chart-2 icon)
─── Admin ──────────────── (only shown if role = admin)
Users /users (user-cog icon)
Settings /settings (settings icon)
```
- [ ] **`web/components/layout/app-topbar.mjs`**
- Left: hamburger menu button (mobile) / breadcrumb (desktop)
- Right: notification bell with unread count badge, user avatar dropdown
- Dropdown: "My Profile", "Change Password", divider, "Sign Out"
- Topbar is fixed/sticky at top, `z-index` above content
- [ ] **`web/components/layout/app-mobile-nav.mjs`**
- Fixed bottom tab bar on screens ≤ 768px
- Show 5 main items: Dashboard, Work Orders, People, Reports, Menu (opens drawer)
- Active tab: `--teal` color + underline indicator
- Safe area padding for iOS notch: `padding-bottom: env(safe-area-inset-bottom)`
- [ ] **`web/components/layout/app-root.mjs`**
- Orchestrates sidebar + topbar + `<main>` content slot
- Desktop: sidebar left, content fills remaining width
- Mobile: sidebar hidden (drawer), topbar + bottom tab bar
- CSS Grid layout:
```css
/* Desktop */
display: grid;
grid-template-columns: var(--sidebar-w) 1fr;
grid-template-rows: 56px 1fr;
/* Mobile ≤768px */
grid-template-columns: 1fr;
grid-template-rows: 56px 1fr 56px;
```
- [ ] **`web/app.mjs`**
- Register all components
- Initialize router: map hash routes to `<main>` innerHTML swaps
- Listen for `auth:expired` → clear token → navigate to `/login`
### 1.8 Shared UI Components (needed in Phase 1)
- [ ] **`ui-badge.mjs`** — status & priority pills
```html
<ui-badge type="status" value="in_progress">In Progress</ui-badge>
<ui-badge type="priority" value="urgent">Urgent</ui-badge>
```
Colored dot + label, background is 15% opacity of the status color
- [ ] **`ui-button.mjs`** — `variant="primary|ghost|danger|icon"`, `size="sm|md|lg"`, `loading` attr shows spinner
- [ ] **`ui-spinner.mjs`** — CSS animated ring, `size` attr
- [ ] **`ui-toast.mjs`** — fixed top-right, slide-in animation, auto-dismiss after 4s, `type="success|error|info"`
- [ ] **`ui-empty.mjs`** — centered illustration + heading + body + optional CTA button
- [ ] **`ui-dialog.mjs`** — `<dialog>` element, backdrop, close on Escape + backdrop click, `size="sm|md|lg"`
### 1.9 WO List Page
- [ ] **`wo-list.mjs`**
- Page header: "Work Orders" title + "New Work Order" primary button
- Filter bar: search input, status dropdown, priority dropdown, date range pickers
- View toggle: List view | Kanban view (icon buttons, remember choice in localStorage)
- **List view:** table on desktop, card stack on mobile
- Columns: WO#, Title, Site, Status, Priority, Scheduled, Steps progress, Photos count, Actions
- Row click → navigate to detail
- Actions column: Edit (pencil), delete (trash, confirm dialog)
- Sticky header, sortable columns (client-side sort for Phase 1)
- Loading: skeleton rows (CSS animation, not a spinner)
- Empty state: `<ui-empty>` with clipboard illustration + "Create your first Work Order"
- Pagination: page controls at bottom
- [ ] **`wo-kanban.mjs`**
- Columns: Draft | Assigned | Scheduled | In Progress | Pending Review | Closed
- Each column header: status color + count badge
- Cards: WO#, title, site name, priority badge, assignee avatars, step progress bar
- Horizontal scroll on mobile (each column is scrollable vertically)
- Drag-and-drop to change status (HTML5 drag API, no lib needed)
### 1.10 WO Form Page
- [ ] **`wo-form.mjs`** — used for both Create and Edit
- Page header: "New Work Order" or "Edit WO-000123" + breadcrumb
- Layout: two-column on desktop (`grid-template-columns: 2fr 1fr`), single column mobile
- **Left column — main fields:**
- Title (required, full width)
- Description (textarea, 3 rows)
- Instructions (textarea, 5 rows — will become rich text in Phase 4)
- Site Name
- Address (with optional geocode button → fills Lat/Lng)
- Lat / Lng (read-only display, set by geocoder or map click)
- Access Notes (gate codes, road conditions)
- **Right column — metadata:**
- Status (select)
- Priority (select with colored indicator)
- Parent Type (select: None / Project / Trouble Ticket / Service Order)
- Parent ID (text field, shown only when parent type selected)
- Scheduled Start (datetime-local input)
- Scheduled End (datetime-local input)
- Footer: Cancel (ghost) | Save Draft | Save & Open (primary)
- Validation: highlight invalid fields, scroll to first error, toast on success
- Unsaved-changes guard: warn before navigating away if form is dirty
### 1.11 WO Detail Page
- [ ] **`wo-detail.mjs`** — tabbed layout
- Header section: WO number (mono font), title, status badge, priority badge
- Metadata strip: site, scheduled date, created by, parent link (clickable)
- Action buttons: Edit, Print, Change Status (dropdown), Close WO
- Tabs: **Overview | Checklist | Resources | Photos | Accounting | Activity**
- Each tab is its own component loaded lazily when tab is clicked
- Tab indicator: `--teal` underline, smooth slide transition
---
## Phase 2 — Field Features
**Goal:** Everything a crew needs on their phone in the field.
### 2.1 Database Migrations
- [ ] `002_resources.sql` — `wo_steps`, `wo_resources`, `resource_people`, `resource_vehicles`, `resource_equipment`, `resource_materials`
- [ ] `003_attachments.sql` — `wo_attachments`
### 2.2 Checklist / Steps
**Backend:**
- [ ] `GET /api/work-orders/{id}/steps` — ordered list
- [ ] `POST /api/work-orders/{id}/steps` — add step `{ title, description, step_order, required }`
- [ ] `PUT /api/work-orders/{id}/steps/{sid}` — edit step (title, description, reorder)
- [ ] `PUT /api/work-orders/{id}/steps/reorder` — bulk reorder `{ steps: [{id, order}] }`
- [ ] `POST /api/work-orders/{id}/steps/{sid}/complete` — check off, record `completed_by`, `completed_at`, optional `notes`
- [ ] `POST /api/work-orders/{id}/steps/{sid}/uncomplete` — undo check (dispatcher+ only)
- [ ] `DELETE /api/work-orders/{id}/steps/{sid}`
**Frontend `wo-checklist.mjs`:**
- [ ] Progress bar at top: `X of Y steps complete` with animated fill
- [ ] Each step row:
- Checkbox (large, touch-friendly — min 44px tap target)
- Step number + title (strikethrough when complete)
- Description (collapsed, expand on tap)
- "Add note" button → inline textarea for completion note
- Photo camera button → triggers photo capture attached to this step
- Completed by + timestamp (shown when done, muted)
- [ ] Add Step form at bottom: title field + optional description + Add button
- [ ] Drag handle for reordering (desktop; long-press on mobile)
- [ ] Steps auto-saved — no save button, immediate API call on check
- [ ] If all steps complete → confetti animation + prompt to move status to Pending Review
### 2.3 Resource Registry (Master Lists)
**Backend:**
- [ ] `GET /api/registry/people?search=&active=true` — paginated list
- [ ] `POST /api/registry/people` — create person record
- [ ] `PUT /api/registry/people/{id}` — update
- [ ] `DELETE /api/registry/people/{id}` — soft delete (set `active = 0`)
- [ ] Same CRUD for `/registry/vehicles`, `/registry/equipment`, `/registry/materials`
**Frontend — People (`people-list.mjs`, `people-form.mjs`):**
- [ ] List page: avatar + name + role + phone + email + active badge + edit/deactivate actions
- [ ] Form fields: display name, role/title, email, phone, notes, active toggle
- [ ] Avatar: show initials in colored circle (hash name to color), or upload photo
**Frontend — Vehicles (`vehicle-list.mjs`, `vehicle-form.mjs`):**
- [ ] List: unit number, description, type, license plate, active status
- [ ] Form fields: unit number, description, vehicle type (bucket truck / van / trailer / other), license plate, notes, active toggle
**Frontend — Equipment (`equipment-list.mjs`, `equipment-form.mjs`):**
- [ ] List: name, asset tag, category, last assigned WO, active status
- [ ] Form fields: name, asset tag, category (fusion splicer / OTDR / blower / reel / other), serial number, notes, active toggle
**Frontend — Materials (`material-list.mjs`, `material-form.mjs`):**
- [ ] List: name, part number, unit of measure, active status
- [ ] Form fields: name, part number, unit (ft / ea / box / roll), notes, active toggle
### 2.4 Resource Assignment Panel
**Backend:**
- [ ] `GET /api/work-orders/{id}/resources`
- [ ] `POST /api/work-orders/{id}/resources` — `{ resource_type, resource_id, quantity?, notes? }`
- [ ] `DELETE /api/work-orders/{id}/resources/{rid}`
- [ ] `GET /api/registry/people?search=` — for typeahead pickers
**Frontend `wo-resource-panel.mjs`:**
- [ ] Four sections: People · Vehicles · Equipment · Materials
- [ ] Each section:
- Assigned list: avatar/icon + name + remove (×) button
- "Add" button → opens `<ui-dialog>` with searchable picker
- Picker: search input + scrollable list with checkboxes → "Add Selected" button
- Materials: quantity field next to each assigned item
- [ ] Empty section shows `<ui-empty>` inline: "No people assigned yet"
- [ ] Changes reflect immediately, API call on each add/remove
- [ ] Total counts shown in section header: "People (3)"
### 2.5 Photo Panel
**Backend:**
- [ ] `POST /api/work-orders/{id}/attachments` — multipart, fields: `file`, `phase`, `caption`, `step_id?`
- [ ] `GET /api/work-orders/{id}/attachments`
- [ ] `PUT /api/work-orders/{id}/attachments/{aid}` — update caption/phase
- [ ] `DELETE /api/work-orders/{id}/attachments/{aid}`
- [ ] Extract EXIF GPS on server if present in JPEG
- [ ] Generate thumbnail on upload (use `imaging` Go package, 400px wide JPEG)
- [ ] Serve originals at `/uploads/{path}`, thumbs at `/uploads/thumbs/{path}`
**Frontend `wo-photo-panel.mjs`:**
- [ ] Phase tabs at top: **All · Before · During · After** — filter photos by phase
- [ ] Photo grid: 3 columns desktop, 2 columns tablet, 2 columns mobile
- [ ] Each photo tile: thumbnail, hover overlay with caption + phase badge
- [ ] Click → lightbox modal with full-size image, prev/next arrows, swipe on mobile
- [ ] Upload button:
- Desktop: file picker (multi-select, drag-and-drop zone)
- Mobile: `<input type="file" accept="image/*" capture="environment">` for camera
- [ ] Upload flow: show thumbnail preview + phase selector + caption field before confirm
- [ ] Upload progress: per-file progress bar, queue multiple uploads
- [ ] Geo-tagged indicator: small pin icon if lat/lng present
- [ ] Empty state per phase: "No 'before' photos yet — capture site condition before starting"
### 2.6 Map & Location
**Backend:**
- [ ] `GET /api/work-orders/{id}/location` — return `{ lat, lng, address, site_name, access_notes }`
- [ ] `PUT /api/work-orders/{id}/location` — update coordinates + address
**Frontend `wo-map.mjs`:**
- [ ] Leaflet map, 300px height (expandable to full-screen on mobile)
- [ ] OpenStreetMap tile layer (no API key)
- [ ] Custom pin: teal SVG marker with WO number label
- [ ] "Get Directions" button → deeplink:
- iOS: `maps://maps.apple.com/?daddr={lat},{lng}`
- Android/other: `https://maps.google.com/maps?daddr={lat},{lng}`
- [ ] "Set Location" mode: click map to drop pin → updates lat/lng fields in WO form
- [ ] Geocode button in WO form: type address → calls OpenStreetMap Nominatim → fills lat/lng (free, no key)
- [ ] Access notes shown below map in an info box with lock icon
### 2.7 Mobile Responsiveness Audit
- [ ] All tap targets ≥ 44×44px
- [ ] No horizontal scroll on any page at 375px width
- [ ] Forms: single column, full-width inputs
- [ ] Tables: horizontal scroll container or card-based list on mobile
- [ ] Sidebar: hidden, accessible via hamburger → slides in as drawer with backdrop
- [ ] Bottom nav `app-mobile-nav.mjs` visible on ≤ 768px, hidden on desktop
- [ ] Photo capture uses `capture="environment"` on mobile
- [ ] Map "Get Directions" opens native maps app
- [ ] Dialogs: full-screen on mobile (`position: fixed; inset: 0`)
- [ ] Test breakpoints: 375px (iPhone SE), 390px (iPhone 14), 768px (iPad), 1024px, 1440px
---
## Phase 3 — Integrations & Admin
### 3.1 Accounting Codes
**Backend:**
- [ ] `004_accounting.sql` — `wo_accounting` table (wo_id, code_type, code_value, description)
- [ ] `GET /api/work-orders/{id}/accounting`
- [ ] `PUT /api/work-orders/{id}/accounting` — upsert all codes in one request `[{ code_type, code_value, description }]`
**Frontend `wo-accounting.mjs`:**
- [ ] Four fields in a clean two-column grid:
- GL Account Code (text + description)
- Cost Center / Department (text + description)
- Project WBS / Phase (text + description)
- Billing Reference (text + description)
- [ ] Each field: code input + description input on same row
- [ ] Auto-save on blur (no save button)
- [ ] Show "auto-populated from parent" chip if code came from parent record
- [ ] Future: lookup/typeahead from your chart of accounts
### 3.2 Polymorphic Parent Linking
- [ ] WO form: parent type select (None / Project / Trouble Ticket / Service Order)
- [ ] When type selected: show search/ID input for the parent record
- [ ] In WO detail header: linked parent shown as a chip with icon
```
📋 Project: Elm Street FTTH Build →
```
- [ ] Clicking the chip opens a drawer with parent record summary (Phase 4: deep link)
- [ ] Backend: `GET /api/work-orders?parent_type=project&parent_id=42` — list WOs for a given parent
### 3.3 Audit Log / Activity Timeline
**Backend:**
- [ ] `006_audit_log.sql` — `wo_audit_log` (id, wo_id, action, old_value, new_value, performed_by, performed_at)
- [ ] Log every status change, resource assignment, step completion, photo upload, accounting change
- [ ] `GET /api/work-orders/{id}/activity` — paginated, newest first
**Frontend `wo-timeline.mjs`:**
- [ ] Vertical timeline feed: dot + connector line
- [ ] Each entry: user avatar + action description + timestamp (relative + absolute on hover)
- [ ] Status changes: colored badge showing old → new
- [ ] Photo uploads: thumbnail preview inline
- [ ] Step completions: step title + optional note
- [ ] Load more button at bottom (pagination)
- [ ] Auto-refresh every 30s if WO is `in_progress`
### 3.4 User Management (Admin Only)
**Backend:**
- [ ] `GET /api/users` — list all users (admin only)
- [ ] `POST /api/users` — create user, auto-send invite email
- [ ] `PUT /api/users/{id}` — update name, role, active status
- [ ] `PUT /api/users/{id}/password` — admin reset
- [ ] `DELETE /api/users/{id}` — deactivate (soft delete)
- [ ] `GET /api/users/me` — current user profile
- [ ] `PUT /api/users/me` — update own display name, avatar
- [ ] `PUT /api/users/me/password` — change own password (requires current password)
**Frontend:**
- [ ] **`user-list.mjs`** — table: avatar, name, email, role badge, last login, active toggle, edit button
- [ ] **`user-form.mjs`** — dialog: display name, email, role select, active toggle, force password reset checkbox
- [ ] **`user-profile.mjs`** — own profile: avatar upload, display name, current password + new password fields
- [ ] Role badges with colors: Admin=danger, Dispatcher=teal, Field Tech=warning, Viewer=muted
### 3.5 Notifications
**Backend:**
- [ ] `wo_notifications` table: (id, user_id, wo_id, type, message, read, created_at)
- [ ] Create notifications when:
- WO assigned to you
- WO status changes (for creator and assignees)
- All steps completed (for dispatcher/admin)
- WO approaching scheduled time (30 min warning, cron job)
- [ ] `GET /api/notifications?unread=true` — list notifications
- [ ] `PUT /api/notifications/{id}/read` — mark read
- [ ] `PUT /api/notifications/read-all` — mark all read
- [ ] Email notification: Go `net/smtp` with HTML template, send on assignment
**Frontend:**
- [ ] Bell icon in topbar: unread count badge (red dot with number)
- [ ] Click bell → dropdown panel with notification list
- [ ] Each notification: icon, message, WO link, relative time, unread dot
- [ ] "Mark all read" button at top
- [ ] Click notification → navigate to WO detail + mark read
- [ ] Poll `/api/notifications?unread=true` every 60s for new count
### 3.6 Print / Field Packet
**Frontend `wo-print.mjs`:**
- [ ] Triggered by "Print" button in WO detail header
- [ ] Opens print-preview page (new tab or print dialog)
- [ ] Printed layout includes:
- WO number, title, site info, scheduled date
- All resource assignments (people, vehicles, equipment, materials)
- Full instructions + access notes
- Map static image (use Leaflet's `map.printPlugin` or OpenStreetMap static tiles)
- Numbered step checklist (checkbox squares for pen check-off)
- Accounting codes
- Photo thumbnails (before photos only, 2×3 grid)
- Signature / completion line
- [ ] `print.css`: hide sidebar, topbar, action buttons; show print-only elements; break pages sensibly
### 3.7 Reports
**Backend:**
- [ ] `GET /api/reports/summary` — total WOs by status, by priority, by date range
- [ ] `GET /api/reports/by-cost-center` — WO count and open/closed by cost center
- [ ] `GET /api/reports/by-resource` — WOs per person/vehicle over date range
- [ ] `GET /api/reports/overdue` — WOs past scheduled end still not closed
- [ ] `GET /api/reports/export?format=csv&status=closed&from=&to=` — CSV download
**Frontend:**
- [ ] **`report-root.mjs`** — filter bar: date range, status, cost center, parent type
- [ ] **`report-by-status.mjs`** — doughnut chart (Chart.js) + summary table
- [ ] **`report-by-cost.mjs`** — bar chart by cost center + table with WO list
- [ ] **`report-export.mjs`** — "Export to CSV" button + date range picker + format select
---
## Phase 4 — Polish & Optimization
### 4.1 Dashboard
**Backend:**
- [ ] `GET /api/dashboard` — single endpoint returns all KPIs:
```json
{
"open_count": 42,
"in_progress_count": 12,
"overdue_count": 5,
"closed_today": 8,
"by_status": [...],
"by_priority": [...],
"recent_activity": [...],
"upcoming": [...]
}
```
**Frontend `dash-root.mjs`:**
- [ ] **KPI row** — four `<dash-kpi-card>` components:
- Open Work Orders (blue, clipboard icon)
- In Progress (orange, activity icon)
- Overdue (red, alert-circle icon)
- Closed Today (green, check-circle icon)
- Each card: large number, trend indicator (↑↓ vs yesterday), icon, click → filtered WO list
- [ ] **Charts row** (2 columns):
- Doughnut: WOs by Status (Chart.js, use status colors from design system)
- Bar: WOs by Priority (horizontal bars)
- [ ] **Bottom row** (2 columns):
- Recent Activity feed (`<dash-recent-feed>`)
- Upcoming WOs this week (compact list, sorted by scheduled_start)
- [ ] Dashboard auto-refreshes every 2 minutes
- [ ] Skeleton loading state while data loads
### 4.2 Offline / PWA Basics
- [ ] `manifest.json` — app name, icons, `display: standalone`, theme color `#0D2137`
- [ ] `sw.js` — Service Worker:
- Cache shell (index.html, CSS, .mjs files) on install
- Cache API GET responses in IndexedDB for offline read
- Queue photo uploads when offline, sync on reconnect (Background Sync API)
- [ ] Offline indicator banner: "You're offline — viewing cached data"
- [ ] "Add to Home Screen" prompt on mobile
### 4.3 Rich Text Instructions
- [ ] Swap `<textarea>` for [Trix editor](https://trix-editor.org/) (no build needed, CDN available)
- [ ] Store as HTML in `instructions` column (`NVARCHAR(MAX)`)
- [ ] Display with sanitized `innerHTML` (strip `<script>` tags server-side)
### 4.4 Full-Text Search
- [ ] SQL Server `CONTAINS` or `FREETEXT` on `work_orders.title`, `description`, `instructions`, `site_name`
- [ ] Global search bar in topbar — results show WOs, people, equipment matching query
- [ ] Keyboard shortcut: `Ctrl+K` / `Cmd+K` opens search spotlight dialog
### 4.5 Scheduling Calendar
- [ ] **`wo-calendar.mjs`** — monthly/weekly view
- [ ] Each WO block: title, priority color stripe, assignee avatars
- [ ] Click WO block → detail drawer slides in without leaving calendar
- [ ] Drag WO block to reschedule (updates `scheduled_start`, `scheduled_end`)
### 4.6 Crew Scheduling View
- [ ] Gantt-style view: rows = people, columns = days
- [ ] Each WO shown as a bar on the assigned person's row
- [ ] Spot conflicts: overlapping WOs on same person highlighted in red
### 4.7 Additional Polish
- [ ] Dark mode: add `[data-theme="dark"]` overrides for all CSS vars, toggle stored in localStorage
- [ ] Keyboard navigation: all interactive elements focusable, visible focus rings, tab order logical
- [ ] Error boundaries: if a component throws, show error card instead of crashing whole page
- [ ] Rate limiting on API (chi middleware: 100 req/min per IP)
- [ ] API response compression (`gzip` middleware)
- [ ] Input sanitization: strip HTML from all text fields server-side before saving
- [ ] `ETag` / `Last-Modified` headers on GET responses for browser caching
---
## Component Inventory
| Component | File | Status | Phase |
|-----------|------|--------|-------|
| App shell | `app-root.mjs` | ⬜ | 1 |
| Sidebar | `app-sidebar.mjs` | ⬜ | 1 |
| Topbar | `app-topbar.mjs` | ⬜ | 1 |
| Mobile nav | `app-mobile-nav.mjs` | ⬜ | 1 |
| WO List | `wo-list.mjs` | ⬜ | 1 |
| WO Kanban | `wo-kanban.mjs` | ⬜ | 1 |
| WO Form | `wo-form.mjs` | ⬜ | 1 |
| WO Detail | `wo-detail.mjs` | ⬜ | 1 |
| Status Badge | `ui-badge.mjs` | ⬜ | 1 |
| Button | `ui-button.mjs` | ⬜ | 1 |
| Dialog | `ui-dialog.mjs` | ⬜ | 1 |
| Toast | `ui-toast.mjs` | ⬜ | 1 |
| Spinner | `ui-spinner.mjs` | ⬜ | 1 |
| Empty state | `ui-empty.mjs` | ⬜ | 1 |
| Checklist | `wo-checklist.mjs` | ⬜ | 2 |
| Resource panel | `wo-resource-panel.mjs` | ⬜ | 2 |
| Photo panel | `wo-photo-panel.mjs` | ⬜ | 2 |
| Map | `wo-map.mjs` | ⬜ | 2 |
| People list/form | `people-list.mjs` | ⬜ | 2 |
| Vehicle list/form | `vehicle-list.mjs` | ⬜ | 2 |
| Equipment list/form | `equipment-list.mjs` | ⬜ | 2 |
| Material list/form | `material-list.mjs` | ⬜ | 2 |
| Accounting | `wo-accounting.mjs` | ⬜ | 3 |
| Timeline | `wo-timeline.mjs` | ⬜ | 3 |
| Print packet | `wo-print.mjs` | ⬜ | 3 |
| User list/form | `user-list.mjs` | ⬜ | 3 |
| User profile | `user-profile.mjs` | ⬜ | 3 |
| Reports | `report-root.mjs` | ⬜ | 3 |
| Dashboard | `dash-root.mjs` | ⬜ | 4 |
| KPI card | `dash-kpi-card.mjs` | ⬜ | 4 |
| Calendar | `wo-calendar.mjs` | ⬜ | 4 |
| Search spotlight | (in `app-topbar.mjs`) | ⬜ | 4 |
---
## API Endpoints
### Auth
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/auth/login` | ✗ | Login, returns JWT + user |
| POST | `/api/auth/refresh` | ✓ | Refresh token |
| GET | `/api/auth/me` | ✓ | Current user |
### Work Orders
| Method | Path | Role | Description |
|--------|------|------|-------------|
| GET | `/api/work-orders` | viewer+ | List (filter: status, priority, search, parent, date) |
| POST | `/api/work-orders` | dispatcher+ | Create |
| GET | `/api/work-orders/{id}` | viewer+ | Full detail |
| PUT | `/api/work-orders/{id}` | dispatcher+ | Update |
| DELETE | `/api/work-orders/{id}` | admin | Soft delete |
| PUT | `/api/work-orders/{id}/status` | field_tech+ | Status transition |
| GET | `/api/work-orders/{id}/steps` | viewer+ | List steps |
| POST | `/api/work-orders/{id}/steps` | dispatcher+ | Add step |
| PUT | `/api/work-orders/{id}/steps/{sid}` | dispatcher+ | Edit step |
| PUT | `/api/work-orders/{id}/steps/reorder` | dispatcher+ | Bulk reorder |
| POST | `/api/work-orders/{id}/steps/{sid}/complete` | field_tech+ | Check off |
| POST | `/api/work-orders/{id}/steps/{sid}/uncomplete` | dispatcher+ | Undo check |
| DELETE | `/api/work-orders/{id}/steps/{sid}` | dispatcher+ | Delete step |
| GET | `/api/work-orders/{id}/resources` | viewer+ | List assignments |
| POST | `/api/work-orders/{id}/resources` | dispatcher+ | Assign resource |
| DELETE | `/api/work-orders/{id}/resources/{rid}` | dispatcher+ | Remove assignment |
| GET | `/api/work-orders/{id}/attachments` | viewer+ | List photos/files |
| POST | `/api/work-orders/{id}/attachments` | field_tech+ | Upload photo/file |
| PUT | `/api/work-orders/{id}/attachments/{aid}` | field_tech+ | Update caption/phase |
| DELETE | `/api/work-orders/{id}/attachments/{aid}` | dispatcher+ | Delete attachment |
| GET | `/api/work-orders/{id}/accounting` | viewer+ | Get accounting codes |
| PUT | `/api/work-orders/{id}/accounting` | dispatcher+ | Upsert accounting codes |
| GET | `/api/work-orders/{id}/activity` | viewer+ | Audit log feed |
| GET | `/api/work-orders/{id}/location` | viewer+ | Location data |
| PUT | `/api/work-orders/{id}/location` | dispatcher+ | Update location |
### Registries (Master Lists)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/registry/people` | List people (search, active filter) |
| POST | `/api/registry/people` | Create person |
| PUT | `/api/registry/people/{id}` | Update person |
| DELETE | `/api/registry/people/{id}` | Deactivate person |
| GET/POST/PUT/DELETE | `/api/registry/vehicles` | Same CRUD for vehicles |
| GET/POST/PUT/DELETE | `/api/registry/equipment` | Same CRUD for equipment |
| GET/POST/PUT/DELETE | `/api/registry/materials` | Same CRUD for materials |
### Users & Notifications
| Method | Path | Role | Description |
|--------|------|------|-------------|
| GET | `/api/users` | admin | List all users |
| POST | `/api/users` | admin | Create user |
| PUT | `/api/users/{id}` | admin | Update user |
| DELETE | `/api/users/{id}` | admin | Deactivate |
| GET | `/api/users/me` | any | Own profile |
| PUT | `/api/users/me` | any | Update own profile |
| PUT | `/api/users/me/password` | any | Change password |
| GET | `/api/notifications` | any | List notifications |
| PUT | `/api/notifications/{id}/read` | any | Mark read |
| PUT | `/api/notifications/read-all` | any | Mark all read |
### Reports & Dashboard
| Method | Path | Role | Description |
|--------|------|------|-------------|
| GET | `/api/dashboard` | viewer+ | All KPIs in one call |
| GET | `/api/reports/summary` | viewer+ | WOs by status/priority |
| GET | `/api/reports/by-cost-center` | dispatcher+ | Cost center breakdown |
| GET | `/api/reports/by-resource` | dispatcher+ | Resource utilization |
| GET | `/api/reports/overdue` | dispatcher+ | Overdue WOs |
| GET | `/api/reports/export` | dispatcher+ | CSV download |
---
## Database Schema
### Full Table List
| Table | Purpose |
|-------|---------|
| `work_orders` | Core WO records |
| `wo_steps` | Ordered checklist steps |
| `wo_resources` | Resource assignments (polymorphic) |
| `wo_attachments` | Photos and file uploads |
| `wo_accounting` | GL/cost center/WBS codes |
| `wo_audit_log` | All change events |
| `wo_notifications` | User notification records |
| `resource_people` | People master list |
| `resource_vehicles` | Vehicle master list |
| `resource_equipment` | Equipment master list |
| `resource_materials` | Material/inventory master list |
| `users` | App users with roles |
### Key Patterns
- Soft deletes: `deleted_at DATETIME2 NULL` — never hard delete, always filter `WHERE deleted_at IS NULL`
- Audit timestamps: every table has `created_at`, `updated_at` (auto via `DEFAULT GETUTCDATE()`)
- Polymorphic parent: `parent_type NVARCHAR(50)`, `parent_id INT` — handles any parent record type
- Named params only: never string-concatenate SQL — always use `@param_name` or `@p1`
---
## Conventions
### CLAUDE.md Content (create this file in project root)
```markdown
# Work Order System — Claude Code Conventions
## Frontend
- ALL frontend JavaScript module files use `.mjs` extension — no exceptions
- No build step, no npm for frontend — pure ES modules via <script type="module">
- CDN dependencies: Lucide (icons), Leaflet (maps), Chart.js (charts), Google Fonts
- Always use CSS custom property vars — never hardcode hex colors
- Component pattern: Shadow DOM, #private class fields, custom events with namespaces
- Custom event naming: colon-namespaced — 'wo:select', 'steps:updated', 'auth:expired'
- Imports always include .mjs extension: import { api } from '../lib/api.mjs'
## Go Backend
- Package names: lowercase single word (handlers, repository, model, service)
- Errors: always wrap with context — fmt.Errorf("repo.Create: %w", err)
- DB queries: named params only — @param_name, never string concat
- HTTP errors: always JSON — {"error": "message"} with correct status code
- Logging: use log/slog with structured key-value pairs
- Response envelope: { data: ..., meta: {...}, error: null }
## Database
- Soft deletes only — deleted_at column, filter WHERE deleted_at IS NULL
- Every table: created_at, updated_at with DEFAULT GETUTCDATE()
- Polymorphic refs: parent_type + parent_id columns
- All SQL in repository layer — no raw SQL in handlers or service
## Git
- Branches: feature/*, fix/*, chore/*
- Commit messages: conventional commits (feat:, fix:, chore:, docs:)
```
### Go Dependencies
```go
// go.mod
require (
github.com/go-chi/chi/v5 v5.1.0
github.com/jmoiron/sqlx v1.3.5
github.com/microsoft/go-mssqldb v1.7.1
github.com/golang-jwt/jwt/v5 v5.2.1
github.com/google/uuid v1.6.0
github.com/joho/godotenv v1.5.1
golang.org/x/crypto latest // bcrypt
github.com/disintegration/imaging latest // thumbnail generation
)
```
### Frontend CDN Deps (loaded in `index.html`)
```html
<!-- Fonts -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
<!-- Icons — Lucide (tree-shakeable, no API key) -->
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
<!-- Maps — Leaflet (no API key) -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9/dist/leaflet.css">
<script src="https://unpkg.com/leaflet@1.9/dist/leaflet.js"></script>
<!-- Charts — Chart.js -->
<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
```
---
*Start with Phase 1 in order. Each checkbox is one commit. Don't skip CLAUDE.md — it must exist before any code is written.*
---
# Work Order System — Technical Build Plan
**Stack:** Go (backend API) · Pure JavaScript + Web Components (frontend) · SQL Server (MSSQL) · Docker
---
## Table of Contents
1. [Architecture Overview](#1-architecture-overview)
2. [Project Structure](#2-project-structure)
3. [Database Schema](#3-database-schema)
4. [Go Backend](#4-go-backend)
5. [REST API Design](#5-rest-api-design)
6. [Frontend — Web Components](#6-frontend--web-components)
7. [File & Photo Handling](#7-file--photo-handling)
8. [Maps & Location](#8-maps--location)
9. [Authentication & Authorization](#9-authentication--authorization)
10. [Docker Deployment](#10-docker-deployment)
11. [Phased Build Plan](#11-phased-build-plan)
12. [Development Conventions](#12-development-conventions)
---
## 1. Architecture Overview
```
┌─────────────────────────────────────────────────────────┐
│ Browser Client │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Pure JS + Web Components SPA │ │
│ │ <wo-list> <wo-form> <wo-map> <wo-checklist> │ │
│ └───────────────────┬────────────────────────────────┘ │
└──────────────────────│──────────────────────────────────┘
│ REST/JSON over HTTPS
┌──────────────────────▼──────────────────────────────────┐
│ Go API Server │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Router │ │ Handlers │ │ Service │ │
│ │ (chi) │ │ │ │ Layer │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Auth │ │ Upload │ │ Spatial │ │
│ │ (JWT) │ │ Handler │ │ Utils │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬──────────────────────────────────┘
│ sqlx / database/sql
┌──────────────────────▼──────────────────────────────────┐
│ SQL Server (MSSQL) │
│ work_orders · wo_resources · wo_steps · wo_attachments │
│ wo_accounting · wo_parents · users · resource_registry │
└─────────────────────────────────────────────────────────┘
```
**Key decisions:**
- **No framework on the frontend** — Custom Elements v1, Shadow DOM, ES Modules. Works in all modern browsers with zero build step.
- **chi router** for Go — lightweight, idiomatic, stdlib-compatible middleware.
- **sqlx** for DB access — thin wrapper over `database/sql`, named params, struct scanning.
- **SQL Server** — matches your existing infrastructure; geography type for spatial data.
- **Multipart uploads** stored to local volume (or swap for Azure Blob / S3 later).
- **JWT** stateless auth — fits well with a SPA + API split.
---
## 2. Project Structure
```
workorder/
├── cmd/
│ └── server/
│ └── main.go # Entry point, wires everything together
├── internal/
│ ├── api/
│ │ ├── router.go # chi router setup, middleware chain
│ │ ├── middleware.go # JWT, CORS, logging, recovery
│ │ └── handlers/
│ │ ├── workorder.go # WO CRUD handlers
│ │ ├── resource.go # People / vehicle / equipment assignment
│ │ ├── step.go # Checklist steps
│ │ ├── attachment.go # Photo & file upload
│ │ ├── accounting.go # Accounting code endpoints
│ │ ├── parent.go # Parent record linking (polymorphic)
│ │ └── auth.go # Login / token refresh
│ ├── service/
│ │ ├── workorder.go # Business logic layer
│ │ ├── resource.go
│ │ ├── notification.go # Email/push when WO assigned
│ │ └── spatial.go # Geocoding, distance calc
│ ├── repository/
│ │ ├── workorder.go # SQL queries — work orders
│ │ ├── resource.go # SQL queries — resources
│ │ ├── step.go
│ │ ├── attachment.go
│ │ └── db.go # sqlx connection pool setup
│ ├── model/
│ │ ├── workorder.go # Structs: WorkOrder, WorkOrderSummary
│ │ ├── resource.go # Person, Vehicle, Equipment, Material
│ │ ├── step.go # Step, StepCompletion
│ │ ├── attachment.go # Attachment
│ │ ├── accounting.go # AccountingCode
│ │ └── auth.go # User, Claims
│ └── config/
│ └── config.go # Env-based config (DB DSN, JWT secret, upload path)
├── web/ # Frontend — served as static files by Go
│ ├── index.html # Shell — loads the app component
│ ├── app.mjs # <app-root> component, client-side router
│ ├── components/
│ │ ├── wo-list.mjs # Work order list / search
│ │ ├── wo-form.mjs # Create / edit work order
│ │ ├── wo-detail.mjs # Read-only detail view
│ │ ├── wo-checklist.mjs # Step checklist with check-off
│ │ ├── wo-resource-panel.mjs # Assign people, vehicles, equipment
│ │ ├── wo-photo-panel.mjs # Photo capture and gallery
│ │ ├── wo-map.mjs # Embedded map + directions
│ │ ├── wo-accounting.mjs # Accounting code fields
│ │ ├── wo-status-badge.mjs # Status pill (reusable)
│ │ └── wo-timeline.mjs # Activity / audit log
│ ├── lib/
│ │ ├── api.mjs # Fetch wrapper, auth header injection
│ │ ├── router.mjs # Tiny hash/history router
│ │ ├── store.mjs # Lightweight reactive state (no Redux)
│ │ └── utils.mjs # Formatters, validators
│ └── styles/
│ ├── global.css # CSS custom properties (design tokens)
│ └── reset.css
├── uploads/ # Stored attachments (bind-mounted in Docker)
├── migrations/
│ ├── 001_initial_schema.sql
│ ├── 002_resource_registry.sql
│ └── 003_spatial_fields.sql
├── docker-compose.yml
├── Dockerfile
└── .env.example
```
---
## 3. Database Schema
### Core Tables
```sql
-- ── Work Orders ───────────────────────────────────────────────────────────────
CREATE TABLE work_orders (
id INT IDENTITY PRIMARY KEY,
wo_number AS ('WO-' + RIGHT('000000' + CAST(id AS VARCHAR), 6)) PERSISTED,
title NVARCHAR(200) NOT NULL,
description NVARCHAR(MAX),
instructions NVARCHAR(MAX), -- Rich text / markdown
status NVARCHAR(30) NOT NULL DEFAULT 'draft',
-- draft | assigned | scheduled | in_progress | pending_review | closed
priority NVARCHAR(10) NOT NULL DEFAULT 'normal',
-- low | normal | high | urgent
scheduled_start DATETIME2,
scheduled_end DATETIME2,
actual_start DATETIME2,
actual_end DATETIME2,
-- Location
site_name NVARCHAR(200),
address NVARCHAR(400),
lat DECIMAL(10,7),
lng DECIMAL(10,7),
access_notes NVARCHAR(MAX), -- Gate codes, access roads
-- Polymorphic parent
parent_type NVARCHAR(50), -- 'project' | 'ticket' | 'service_order' | NULL
parent_id INT,
-- Audit
created_by INT NOT NULL,
created_at DATETIME2 NOT NULL DEFAULT GETUTCDATE(),
updated_at DATETIME2 NOT NULL DEFAULT GETUTCDATE(),
closed_at DATETIME2,
closed_by INT,
CONSTRAINT chk_wo_status CHECK (status IN ('draft','assigned','scheduled','in_progress','pending_review','closed')),
CONSTRAINT chk_wo_priority CHECK (priority IN ('low','normal','high','urgent'))
);
-- ── Resource Registry (master lists) ─────────────────────────────────────────
CREATE TABLE resource_people (
id INT IDENTITY PRIMARY KEY,
name NVARCHAR(100) NOT NULL,
role NVARCHAR(100),
email NVARCHAR(200),
phone NVARCHAR(30),
active BIT NOT NULL DEFAULT 1
);
CREATE TABLE resource_vehicles (
id INT IDENTITY PRIMARY KEY,
unit_number NVARCHAR(50) NOT NULL,
description NVARCHAR(200),
vehicle_type NVARCHAR(100),
active BIT NOT NULL DEFAULT 1
);
CREATE TABLE resource_equipment (
id INT IDENTITY PRIMARY KEY,
name NVARCHAR(200) NOT NULL,
asset_tag NVARCHAR(100),
category NVARCHAR(100),
active BIT NOT NULL DEFAULT 1
);
CREATE TABLE resource_materials (
id INT IDENTITY PRIMARY KEY,
name NVARCHAR(200) NOT NULL,
unit NVARCHAR(30), -- 'ft', 'each', 'box'
part_number NVARCHAR(100),
active BIT NOT NULL DEFAULT 1
);
-- ── Work Order Resource Assignments ───────────────────────────────────────────
CREATE TABLE wo_resources (
id INT IDENTITY PRIMARY KEY,
wo_id INT NOT NULL REFERENCES work_orders(id) ON DELETE CASCADE,
resource_type NVARCHAR(20) NOT NULL, -- 'person' | 'vehicle' | 'equipment' | 'material'
resource_id INT NOT NULL,
quantity DECIMAL(10,2), -- For materials
notes NVARCHAR(500),
assigned_at DATETIME2 NOT NULL DEFAULT GETUTCDATE(),
CONSTRAINT chk_resource_type CHECK (resource_type IN ('person','vehicle','equipment','material'))
);
-- ── Checklist Steps ───────────────────────────────────────────────────────────
CREATE TABLE wo_steps (
id INT IDENTITY PRIMARY KEY,
wo_id INT NOT NULL REFERENCES work_orders(id) ON DELETE CASCADE,
step_order INT NOT NULL,
title NVARCHAR(200) NOT NULL,
description NVARCHAR(MAX),
required BIT NOT NULL DEFAULT 1,
completed BIT NOT NULL DEFAULT 0,
completed_by INT,
completed_at DATETIME2,
notes NVARCHAR(MAX) -- Field notes added at completion
);
-- ── Attachments (photos, docs) ────────────────────────────────────────────────
CREATE TABLE wo_attachments (
id INT IDENTITY PRIMARY KEY,
wo_id INT NOT NULL REFERENCES work_orders(id) ON DELETE CASCADE,
step_id INT REFERENCES wo_steps(id), -- Optional: attach to a specific step
file_name NVARCHAR(500) NOT NULL,
file_path NVARCHAR(1000) NOT NULL, -- Relative path under /uploads
file_type NVARCHAR(100), -- MIME type
file_size BIGINT,
caption NVARCHAR(500),
phase NVARCHAR(20), -- 'before' | 'during' | 'after'
lat DECIMAL(10,7), -- Geo-tag from EXIF or device
lng DECIMAL(10,7),
uploaded_by INT NOT NULL,
uploaded_at DATETIME2 NOT NULL DEFAULT GETUTCDATE()
);
-- ── Accounting Codes ──────────────────────────────────────────────────────────
CREATE TABLE wo_accounting (
id INT IDENTITY PRIMARY KEY,
wo_id INT NOT NULL REFERENCES work_orders(id) ON DELETE CASCADE,
code_type NVARCHAR(50) NOT NULL, -- 'gl_account' | 'cost_center' | 'wbs' | 'billing_ref'
code_value NVARCHAR(200) NOT NULL,
description NVARCHAR(500),
CONSTRAINT uq_wo_accounting UNIQUE (wo_id, code_type)
);
-- ── Audit Log ─────────────────────────────────────────────────────────────────
CREATE TABLE wo_audit_log (
id INT IDENTITY PRIMARY KEY,
wo_id INT NOT NULL REFERENCES work_orders(id) ON DELETE CASCADE,
action NVARCHAR(100) NOT NULL,
old_value NVARCHAR(MAX),
new_value NVARCHAR(MAX),
performed_by INT NOT NULL,
performed_at DATETIME2 NOT NULL DEFAULT GETUTCDATE()
);
-- ── Indexes ───────────────────────────────────────────────────────────────────
CREATE INDEX ix_wo_status ON work_orders (status);
CREATE INDEX ix_wo_parent ON work_orders (parent_type, parent_id);
CREATE INDEX ix_wo_scheduled ON work_orders (scheduled_start);
CREATE INDEX ix_wo_resources ON wo_resources (wo_id, resource_type);
CREATE INDEX ix_wo_attachments ON wo_attachments (wo_id);
```
---
## 4. Go Backend
### `cmd/server/main.go`
```go
package main
import (
"log"
"net/http"
"github.com/yourorg/workorder/internal/api"
"github.com/yourorg/workorder/internal/config"
"github.com/yourorg/workorder/internal/repository"
)
func main() {
cfg := config.Load() // reads .env / environment variables
db, err := repository.Connect(cfg.DBDSN)
if err != nil {
log.Fatalf("db connect: %v", err)
}
defer db.Close()
r := api.NewRouter(cfg, db)
log.Printf("listening on %s", cfg.Addr)
if err := http.ListenAndServe(cfg.Addr, r); err != nil {
log.Fatal(err)
}
}
```
### `internal/config/config.go`
```go
package config
import "os"
type Config struct {
Addr string
DBDSN string
JWTSecret string
UploadPath string
BaseURL string
}
func Load() *Config {
return &Config{
Addr: env("ADDR", ":8080"),
DBDSN: env("DB_DSN", ""),
JWTSecret: env("JWT_SECRET", "change-me"),
UploadPath: env("UPLOAD_PATH", "./uploads"),
BaseURL: env("BASE_URL", "http://localhost:8080"),
}
}
func env(key, fallback string) string {
if v := os.Getenv(key); v != "" {
return v
}
return fallback
}
```
### `internal/api/router.go`
```go
package api
import (
"net/http"
"github.com/go-chi/chi/v5"
"github.com/go-chi/chi/v5/middleware"
"github.com/yourorg/workorder/internal/api/handlers"
mw "github.com/yourorg/workorder/internal/api/middleware"
"github.com/yourorg/workorder/internal/config"
"github.com/jmoiron/sqlx"
)
func NewRouter(cfg *config.Config, db *sqlx.DB) http.Handler {
r := chi.NewRouter()
// Global middleware
r.Use(middleware.Logger)
r.Use(middleware.Recoverer)
r.Use(middleware.RealIP)
r.Use(mw.CORS)
// Serve frontend static files
r.Handle("/*", http.FileServer(http.Dir("./web")))
// Auth routes (no JWT required)
r.Post("/api/auth/login", handlers.NewAuthHandler(cfg, db).Login)
r.Post("/api/auth/refresh", handlers.NewAuthHandler(cfg, db).Refresh)
// Protected API routes
r.Group(func(r chi.Router) {
r.Use(mw.JWT(cfg.JWTSecret))
wo := handlers.NewWorkOrderHandler(db)
r.Get("/api/work-orders", wo.List)
r.Post("/api/work-orders", wo.Create)
r.Get("/api/work-orders/{id}", wo.Get)
r.Put("/api/work-orders/{id}", wo.Update)
r.Delete("/api/work-orders/{id}", wo.Delete)
r.Put("/api/work-orders/{id}/status", wo.UpdateStatus)
res := handlers.NewResourceHandler(db)
r.Get("/api/work-orders/{id}/resources", res.List)
r.Post("/api/work-orders/{id}/resources", res.Assign)
r.Delete("/api/work-orders/{id}/resources/{rid}", res.Remove)
step := handlers.NewStepHandler(db)
r.Get("/api/work-orders/{id}/steps", step.List)
r.Post("/api/work-orders/{id}/steps", step.Create)
r.Put("/api/work-orders/{id}/steps/{sid}", step.Update)
r.Post("/api/work-orders/{id}/steps/{sid}/complete", step.Complete)
r.Delete("/api/work-orders/{id}/steps/{sid}", step.Delete)
att := handlers.NewAttachmentHandler(cfg, db)
r.Get("/api/work-orders/{id}/attachments", att.List)
r.Post("/api/work-orders/{id}/attachments", att.Upload)
r.Delete("/api/work-orders/{id}/attachments/{aid}", att.Delete)
r.Handle("/uploads/*", http.StripPrefix("/uploads/", http.FileServer(http.Dir(cfg.UploadPath))))
acc := handlers.NewAccountingHandler(db)
r.Get("/api/work-orders/{id}/accounting", acc.Get)
r.Put("/api/work-orders/{id}/accounting", acc.Upsert)
// Resource registries (master lists for assignment pickers)
r.Get("/api/registry/people", handlers.RegistryPeople(db))
r.Get("/api/registry/vehicles", handlers.RegistryVehicles(db))
r.Get("/api/registry/equipment", handlers.RegistryEquipment(db))
r.Get("/api/registry/materials", handlers.RegistryMaterials(db))
})
return r
}
```
### `internal/model/workorder.go`
```go
package model
import "time"
type WorkOrder struct {
ID int `db:"id" json:"id"`
WONumber string `db:"wo_number" json:"wo_number"`
Title string `db:"title" json:"title"`
Description string `db:"description" json:"description"`
Instructions string `db:"instructions" json:"instructions"`
Status string `db:"status" json:"status"`
Priority string `db:"priority" json:"priority"`
ScheduledStart *time.Time `db:"scheduled_start" json:"scheduled_start"`
ScheduledEnd *time.Time `db:"scheduled_end" json:"scheduled_end"`
ActualStart *time.Time `db:"actual_start" json:"actual_start"`
ActualEnd *time.Time `db:"actual_end" json:"actual_end"`
SiteName string `db:"site_name" json:"site_name"`
Address string `db:"address" json:"address"`
Lat *float64 `db:"lat" json:"lat"`
Lng *float64 `db:"lng" json:"lng"`
AccessNotes string `db:"access_notes" json:"access_notes"`
ParentType *string `db:"parent_type" json:"parent_type"`
ParentID *int `db:"parent_id" json:"parent_id"`
CreatedBy int `db:"created_by" json:"created_by"`
CreatedAt time.Time `db:"created_at" json:"created_at"`
UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
}
// Enriched view returned by GET /work-orders/{id}
type WorkOrderDetail struct {
WorkOrder
Resources []AssignedResource `json:"resources"`
Steps []Step `json:"steps"`
Attachments []Attachment `json:"attachments"`
Accounting []AccountingCode `json:"accounting"`
}
type WorkOrderListItem struct {
ID int `db:"id" json:"id"`
WONumber string `db:"wo_number" json:"wo_number"`
Title string `db:"title" json:"title"`
Status string `db:"status" json:"status"`
Priority string `db:"priority" json:"priority"`
SiteName string `db:"site_name" json:"site_name"`
ScheduledStart *time.Time `db:"scheduled_start" json:"scheduled_start"`
StepCount int `db:"step_count" json:"step_count"`
StepsDone int `db:"steps_done" json:"steps_done"`
PhotoCount int `db:"photo_count" json:"photo_count"`
}
```
### `internal/repository/workorder.go`
```go
package repository
import (
"context"
"github.com/jmoiron/sqlx"
"github.com/yourorg/workorder/internal/model"
)
type WorkOrderRepo struct{ db *sqlx.DB }
func NewWorkOrderRepo(db *sqlx.DB) *WorkOrderRepo {
return &WorkOrderRepo{db: db}
}
func (r *WorkOrderRepo) List(ctx context.Context, status, search string) ([]model.WorkOrderListItem, error) {
query := `
SELECT
wo.id, wo.wo_number, wo.title, wo.status, wo.priority,
wo.site_name, wo.scheduled_start,
COUNT(s.id) AS step_count,
SUM(CAST(s.completed AS INT)) AS steps_done,
COUNT(a.id) AS photo_count
FROM work_orders wo
LEFT JOIN wo_steps s ON s.wo_id = wo.id
LEFT JOIN wo_attachments a ON a.wo_id = wo.id
WHERE (@status = '' OR wo.status = @status)
AND (@search = '' OR wo.title LIKE '%' + @search + '%'
OR wo.wo_number LIKE '%' + @search + '%'
OR wo.site_name LIKE '%' + @search + '%')
GROUP BY wo.id, wo.wo_number, wo.title, wo.status,
wo.priority, wo.site_name, wo.scheduled_start
ORDER BY wo.scheduled_start DESC, wo.id DESC`
rows := []model.WorkOrderListItem{}
err := r.db.SelectContext(ctx, &rows, query,
sqlx.Named("status", status),
sqlx.Named("search", search),
)
return rows, err
}
func (r *WorkOrderRepo) GetByID(ctx context.Context, id int) (*model.WorkOrder, error) {
var wo model.WorkOrder
err := r.db.GetContext(ctx, &wo,
`SELECT * FROM work_orders WHERE id = @p1`, id)
if err != nil {
return nil, err
}
return &wo, nil
}
func (r *WorkOrderRepo) Create(ctx context.Context, wo *model.WorkOrder) (int, error) {
var id int
err := r.db.QueryRowContext(ctx, `
INSERT INTO work_orders
(title, description, instructions, status, priority,
scheduled_start, scheduled_end, site_name, address, lat, lng,
access_notes, parent_type, parent_id, created_by, updated_at)
OUTPUT INSERTED.id
VALUES
(@title, @description, @instructions, @status, @priority,
@scheduled_start, @scheduled_end, @site_name, @address, @lat, @lng,
@access_notes, @parent_type, @parent_id, @created_by, GETUTCDATE())`,
sqlx.Named("title", wo.Title),
// ... remaining named params
).Scan(&id)
return id, err
}
func (r *WorkOrderRepo) UpdateStatus(ctx context.Context, id int, status string, userID int) error {
_, err := r.db.ExecContext(ctx, `
UPDATE work_orders
SET status = @p1, updated_at = GETUTCDATE(),
actual_start = CASE WHEN @p1 = 'in_progress' AND actual_start IS NULL
THEN GETUTCDATE() ELSE actual_start END,
actual_end = CASE WHEN @p1 = 'closed' THEN GETUTCDATE() ELSE actual_end END,
closed_at = CASE WHEN @p1 = 'closed' THEN GETUTCDATE() ELSE closed_at END,
closed_by = CASE WHEN @p1 = 'closed' THEN @p2 ELSE closed_by END
WHERE id = @p3`, status, userID, id)
return err
}
```
---
## 5. REST API Design
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/auth/login` | Login, returns JWT |
| GET | `/api/work-orders?status=&search=&page=` | Paginated list |
| POST | `/api/work-orders` | Create work order |
| GET | `/api/work-orders/{id}` | Full detail (WO + resources + steps + photos + accounting) |
| PUT | `/api/work-orders/{id}` | Update work order fields |
| PUT | `/api/work-orders/{id}/status` | Status transition with audit |
| GET | `/api/work-orders/{id}/resources` | List assigned resources |
| POST | `/api/work-orders/{id}/resources` | Assign a resource |
| DELETE | `/api/work-orders/{id}/resources/{rid}` | Remove assignment |
| GET | `/api/work-orders/{id}/steps` | List checklist steps |
| POST | `/api/work-orders/{id}/steps` | Add a step |
| PUT | `/api/work-orders/{id}/steps/{sid}` | Edit step |
| POST | `/api/work-orders/{id}/steps/{sid}/complete` | Check off step |
| POST | `/api/work-orders/{id}/attachments` | Upload photo/file (multipart) |
| GET | `/api/work-orders/{id}/attachments` | List attachments |
| PUT | `/api/work-orders/{id}/accounting` | Upsert accounting codes |
| GET | `/api/registry/people` | Lookup: people for assignment picker |
| GET | `/api/registry/vehicles` | Lookup: vehicles |
| GET | `/api/registry/equipment` | Lookup: equipment |
| GET | `/api/registry/materials` | Lookup: materials |
### Standard Response Envelope
```json
{
"data": { ... },
"meta": { "page": 1, "per_page": 25, "total": 142 },
"error": null
}
```
### Status Transition Rules (enforced server-side)
```
draft → assigned → scheduled → in_progress → pending_review → closed
↘ (re-open) ↗
```
---
## 6. Frontend — Web Components
### Design Principles
- **No build step** — plain `<script type="module">` imports. Works directly in browser.
- **Shadow DOM** per component — style isolation, no CSS leakage.
- **Custom events** for cross-component communication — no shared global state pollution.
- **`api.mjs`** is the single HTTP layer — all fetch calls go through it.
### `web/lib/api.mjs`
```javascript
const BASE = '/api';
let _token = localStorage.getItem('wo_token') || '';
export function setToken(t) {
_token = t;
localStorage.setItem('wo_token', t);
}
async function request(method, path, body, isFormData = false) {
const headers = { Authorization: `Bearer ${_token}` };
if (!isFormData) headers['Content-Type'] = 'application/json';
const res = await fetch(BASE + path, {
method,
headers,
body: body
? (isFormData ? body : JSON.stringify(body))
: undefined,
});
if (res.status === 401) {
// Token expired — redirect to login
window.dispatchEvent(new CustomEvent('auth:expired'));
return;
}
const json = await res.mjson();
if (!res.ok) throw new Error(json.error || 'Request failed');
return json.data;
}
export const api = {
get: (path) => request('GET', path),
post: (path, body) => request('POST', path, body),
put: (path, body) => request('PUT', path, body),
delete: (path) => request('DELETE', path),
upload: (path, form) => request('POST', path, form, true),
};
```
### `web/lib/router.mjs`
```javascript
// Hash-based router — no server config needed
class Router {
#routes = [];
on(pattern, handler) {
this.#routes.push({ pattern: new URLPattern({ pathname: pattern }), handler });
return this;
}
start() {
const dispatch = () => {
const path = location.hash.slice(1) || '/';
for (const { pattern, handler } of this.#routes) {
const m = pattern.exec({ pathname: path });
if (m) { handler(m.pathname.groups); return; }
}
};
window.addEventListener('hashchange', dispatch);
dispatch();
}
}
export const router = new Router();
```
### `web/components/wo-list.mjs`
```javascript
import { api } from '../lib/api.mjs';
class WoList extends HTMLElement {
#data = [];
#status = '';
connectedCallback() {
this.attachShadow({ mode: 'open' });
this.#render();
this.#load();
}
async #load() {
const status = this.getAttribute('filter-status') || '';
this.#data = await api.get(`/work-orders?status=${status}`);
this.#render();
}
#render() {
this.shadowRoot.innerHTML = `
<style>
:host { display: block; }
.grid { display: grid; gap: 0.75rem; }
.card {
background: var(--surface, #fff);
border: 1px solid var(--border, #e2e8f0);
border-radius: 8px;
padding: 1rem 1.25rem;
cursor: pointer;
display: grid;
grid-template-columns: 1fr auto;
gap: 0.25rem 1rem;
transition: box-shadow .15s;
}
.card:hover { box-shadow: 0 4px 12px rgba(0,0,0,.08); }
.wo-number { font-size: .75rem; color: var(--muted); }
.title { font-weight: 600; color: var(--text); }
.progress { font-size: .8rem; color: var(--muted); }
</style>
<div class="grid">
${this.#data.map(wo => `
<div class="card" data-id="${wo.id}">
<div>
<div class="wo-number">${wo.wo_number}</div>
<div class="title">${wo.title}</div>
<div class="progress">
${wo.site_name} · ${wo.steps_done}/${wo.step_count} steps
</div>
</div>
<wo-status-badge status="${wo.status}"></wo-status-badge>
</div>
`).join('')}
</div>`;
this.shadowRoot.querySelectorAll('.card').forEach(card => {
card.addEventListener('click', () => {
this.dispatchEvent(new CustomEvent('wo:select',
{ detail: { id: card.dataset.id }, bubbles: true, composed: true }));
});
});
}
}
customElements.define('wo-list', WoList);
```
### `web/components/wo-resource-panel.mjs`
```javascript
import { api } from '../lib/api.mjs';
class WoResourcePanel extends HTMLElement {
#woId = null;
#resources = [];
#registry = { people: [], vehicles: [], equipment: [], materials: [] };
static get observedAttributes() { return ['wo-id']; }
attributeChangedCallback(name, _, val) {
if (name === 'wo-id') { this.#woId = val; this.#load(); }
}
connectedCallback() {
this.attachShadow({ mode: 'open' });
if (this.#woId) this.#load();
}
async #load() {
const [resources, people, vehicles, equipment, materials] = await Promise.all([
api.get(`/work-orders/${this.#woId}/resources`),
api.get('/registry/people'),
api.get('/registry/vehicles'),
api.get('/registry/equipment'),
api.get('/registry/materials'),
]);
this.#resources = resources;
this.#registry = { people, vehicles, equipment, materials };
this.#render();
}
async #assign(type, resourceId) {
await api.post(`/work-orders/${this.#woId}/resources`, {
resource_type: type, resource_id: Number(resourceId)
});
await this.#load();
}
async #remove(assignmentId) {
await api.delete(`/work-orders/${this.#woId}/resources/${assignmentId}`);
await this.#load();
}
#sectionHTML(label, type, list) {
const assigned = this.#resources.filter(r => r.resource_type === type);
const available = list.filter(item =>
!assigned.some(a => a.resource_id === item.id));
return `
<section>
<h3>${label}</h3>
<ul>
${assigned.map(a => `
<li>${a.name}
<button class="remove-btn" data-id="${a.id}">×</button>
</li>`).join('')}
</ul>
<select class="add-select" data-type="${type}">
<option value="">Add ${label.slice(0,-1)}...</option>
${available.map(item =>
`<option value="${item.id}">${item.name ?? item.unit_number}</option>`
).join('')}
</select>
</section>`;
}
#render() {
const { people, vehicles, equipment, materials } = this.#registry;
this.shadowRoot.innerHTML = `
<style>
:host { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
section { background: var(--surface); border-radius: 8px; padding: 1rem; }
h3 { margin: 0 0 .5rem; font-size: .9rem; text-transform: uppercase;
letter-spacing: .05em; color: var(--muted); }
ul { list-style: none; padding: 0; margin: 0 0 .5rem; }
li { display: flex; justify-content: space-between; padding: .25rem 0;
border-bottom: 1px solid var(--border); font-size: .9rem; }
select { width: 100%; padding: .4rem; border-radius: 6px;
border: 1px solid var(--border); }
.remove-btn { background: none; border: none; cursor: pointer;
color: var(--danger, #c0392b); font-size: 1.1rem; }
</style>
${this.#sectionHTML('People', 'person', people)}
${this.#sectionHTML('Vehicles', 'vehicle', vehicles)}
${this.#sectionHTML('Equipment', 'equipment', equipment)}
${this.#sectionHTML('Materials', 'material', materials)}`;
this.shadowRoot.querySelectorAll('.add-select').forEach(sel => {
sel.addEventListener('change', e => {
if (e.target.value) this.#assign(e.target.dataset.type, e.target.value);
});
});
this.shadowRoot.querySelectorAll('.remove-btn').forEach(btn => {
btn.addEventListener('click', () => this.#remove(btn.dataset.id));
});
}
}
customElements.define('wo-resource-panel', WoResourcePanel);
```
### `web/components/wo-checklist.mjs`
```javascript
import { api } from '../lib/api.mjs';
class WoChecklist extends HTMLElement {
#woId = null;
#steps = [];
static get observedAttributes() { return ['wo-id']; }
attributeChangedCallback(_, __, val) { this.#woId = val; this.#load(); }
connectedCallback() { this.attachShadow({ mode: 'open' }); }
async #load() {
this.#steps = await api.get(`/work-orders/${this.#woId}/steps`);
this.#render();
}
async #complete(stepId) {
await api.post(`/work-orders/${this.#woId}/steps/${stepId}/complete`, {});
await this.#load();
this.dispatchEvent(new CustomEvent('steps:updated', { bubbles: true, composed: true }));
}
#render() {
const done = this.#steps.filter(s => s.completed).length;
const total = this.#steps.length;
const pct = total ? Math.round(done / total * 100) : 0;
this.shadowRoot.innerHTML = `
<style>
.progress-bar { height: 6px; background: var(--border); border-radius: 3px; margin-bottom: 1rem; }
.progress-fill { height: 100%; border-radius: 3px;
background: var(--accent, #0a7ea4); width: ${pct}%; transition: width .3s; }
.step { display: flex; gap: .75rem; align-items: flex-start;
padding: .75rem 0; border-bottom: 1px solid var(--border); }
.step.done .step-title { text-decoration: line-through; color: var(--muted); }
input[type=checkbox] { width: 1.2rem; height: 1.2rem; accent-color: var(--accent); margin-top: .15rem; }
.step-title { font-weight: 500; }
.step-desc { font-size: .85rem; color: var(--muted); margin-top: .2rem; }
.summary { font-size: .85rem; color: var(--muted); margin-bottom: .5rem; }
</style>
<div class="progress-bar"><div class="progress-fill"></div></div>
<div class="summary">${done} of ${total} steps complete</div>
${this.#steps.map(s => `
<div class="step ${s.completed ? 'done' : ''}">
<input type="checkbox" data-id="${s.id}" ${s.completed ? 'checked disabled' : ''}>
<div>
<div class="step-title">${s.step_order}. ${s.title}</div>
${s.description ? `<div class="step-desc">${s.description}</div>` : ''}
</div>
</div>`).join('')}`;
this.shadowRoot.querySelectorAll('input[type=checkbox]:not([disabled])').forEach(cb => {
cb.addEventListener('change', () => this.#complete(cb.dataset.id));
});
}
}
customElements.define('wo-checklist', WoChecklist);
```
### `web/styles/global.css` — Design Tokens
```css
:root {
--navy: #0d2137;
--accent: #0a7ea4;
--accent-lt: #14b8d4;
--surface: #ffffff;
--bg: #f0f6fa;
--border: #e2ebf0;
--text: #1a2e3b;
--muted: #64748b;
--danger: #c0392b;
--success: #1d9d6c;
--warning: #e07b39;
--radius: 8px;
--shadow: 0 2px 8px rgba(0,0,0,.08);
font-family: Calibri, 'Segoe UI', system-ui, sans-serif;
font-size: 16px;
color: var(--text);
background: var(--bg);
}
```
---
## 7. File & Photo Handling
### Go Upload Handler
```go
func (h *AttachmentHandler) Upload(w http.ResponseWriter, r *http.Request) {
woID := chi.URLParam(r, "id")
r.ParseMultipartForm(32 << 20) // 32 MB max
file, header, err := r.FormFile("file")
if err != nil { respondError(w, 400, "missing file"); return }
defer file.Close()
// Build storage path: uploads/{wo_id}/{uuid}{ext}
ext := filepath.Ext(header.Filename)
fname := uuid.New().String() + ext
relPath := filepath.Join(woID, fname)
absPath := filepath.Join(h.cfg.UploadPath, relPath)
os.MkdirAll(filepath.Dir(absPath), 0755)
dst, _ := os.Create(absPath)
defer dst.Close()
io.Copy(dst, file)
// Extract EXIF GPS if it's a JPEG
lat, lng := extractGPS(absPath)
// Save record
att := &model.Attachment{
WOID: mustInt(woID),
FileName: header.Filename,
FilePath: relPath,
FileType: header.Header.Get("Content-Type"),
FileSize: header.Size,
Phase: r.FormValue("phase"),
Caption: r.FormValue("caption"),
Lat: lat,
Lng: lng,
UploadedBy: userIDFromCtx(r.Context()),
}
id, _ := h.repo.Create(r.Context(), att)
respond(w, 201, map[string]any{"id": id, "url": "/uploads/" + relPath})
}
```
### Frontend Photo Capture (`wo-photo-panel.mjs` key logic)
```javascript
// Use camera on mobile devices
async #capturePhoto() {
const input = document.createElement('input');
input.type = 'file';
input.accept = 'image/*';
input.capture = 'environment'; // rear camera
input.onchange = async (e) => {
const file = e.target.files[0];
const form = new FormData();
form.append('file', file);
form.append('phase', this.#phase); // 'before' | 'during' | 'after'
// Attach GPS from browser if available
if (navigator.geolocation) {
await new Promise(res => navigator.geolocation.getCurrentPosition(pos => {
form.append('lat', pos.coords.latitude);
form.append('lng', pos.coords.longitude);
res();
}, res));
}
await api.upload(`/work-orders/${this.#woId}/attachments`, form);
await this.#load();
};
input.click();
}
```
---
## 8. Maps & Location
- **Leaflet.mjs** (open source, no API key required) loaded via CDN for the embedded map.
- **Google Maps Directions API** (or OpenRouteService if you want fully open source) for turn-by-turn routing.
- Coordinates stored as `lat`/`lng` decimals in SQL Server. No geography type required unless you add spatial radius queries later.
### `web/components/wo-map.mjs` skeleton
```javascript
// Leaflet loaded via <script> in index.html
class WoMap extends HTMLElement {
connectedCallback() {
this.style.display = 'block';
this.style.height = '300px';
const map = L.map(this).setView([0, 0], 13);
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);
const lat = parseFloat(this.getAttribute('lat'));
const lng = parseFloat(this.getAttribute('lng'));
if (lat && lng) {
map.setView([lat, lng], 15);
L.marker([lat, lng]).addTo(map)
.bindPopup(this.getAttribute('site-name') || 'Work Site').openPopup();
}
}
}
customElements.define('wo-map', WoMap);
```
### Directions button
```javascript
// Opens Google Maps / Apple Maps turn-by-turn in native app on mobile
function openDirections(lat, lng, label) {
const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
const url = isIOS
? `maps://maps.apple.com/?daddr=${lat},${lng}&dirflg=d`
: `https://maps.google.com/maps?daddr=${lat},${lng}`;
window.open(url, '_blank');
}
```
---
## 9. Authentication & Authorization
### JWT Middleware (Go)
```go
func JWT(secret string) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
auth := r.Header.Get("Authorization")
if !strings.HasPrefix(auth, "Bearer ") {
http.Error(w, `{"error":"unauthorized"}`, 401); return
}
token, err := jwt.ParseWithClaims(strings.TrimPrefix(auth, "Bearer "),
&Claims{}, func(t *jwt.Token) (any, error) {
return []byte(secret), nil
})
if err != nil || !token.Valid {
http.Error(w, `{"error":"invalid token"}`, 401); return
}
claims := token.Claims.(*Claims)
ctx := context.WithValue(r.Context(), ctxKeyUser, claims)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
}
```
### Roles to implement
| Role | Can Do |
|------|--------|
| `admin` | Full CRUD, close any WO, manage registries |
| `dispatcher` | Create & assign WOs, edit all fields |
| `field_tech` | View assigned WOs, complete steps, upload photos |
| `viewer` | Read-only access |
---
## 10. Docker Deployment
### `Dockerfile`
```dockerfile
# ── Build stage ───────────────────────────────────────────
FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o workorder ./cmd/server
# ── Runtime stage ─────────────────────────────────────────
FROM alpine:3.20
WORKDIR /app
RUN apk add --no-cache tzdata ca-certificates
COPY --from=builder /app/workorder .
COPY web/ ./web/
EXPOSE 8080
CMD ["./workorder"]
```
### `docker-compose.yml`
```yaml
services:
api:
build: .
ports:
- "8080:8080"
environment:
ADDR: ":8080"
DB_DSN: "sqlserver://sa:${SA_PASSWORD}@mssql:1433?database=workorders"
JWT_SECRET: "${JWT_SECRET}"
UPLOAD_PATH: "/uploads"
volumes:
- uploads:/uploads
depends_on:
- mssql
restart: unless-stopped
mssql:
image: mcr.microsoft.com/mssql/server:2022-latest
environment:
SA_PASSWORD: "${SA_PASSWORD}"
ACCEPT_EULA: "Y"
MSSQL_PID: "Developer"
volumes:
- mssql_data:/var/opt/mssql
ports:
- "1433:1433" # Remove in production
volumes:
uploads:
mssql_data:
```
If you're connecting to your **existing SQL Server** instance, just point `DB_DSN` at it and drop the `mssql` service.
---
## 11. Phased Build Plan
### Phase 1 — Foundation (Weeks 1–4)
**Goal:** Working CRUD with project linking and status flow.
- [ ] Repo setup: Go module, chi, sqlx, godotenv
- [ ] DB migration: `work_orders` table + indexes
- [ ] Auth: login endpoint, JWT middleware, user table
- [ ] Work Order CRUD endpoints (list, get, create, update, status)
- [ ] Frontend shell: `index.html`, router, `api.mjs`, global CSS
- [ ] `<wo-list>` — list with search + filter by status
- [ ] `<wo-form>` — create / edit form with all base fields
- [ ] `<wo-status-badge>` — reusable status pill
- [ ] Docker Compose working locally
- [ ] Basic role checking (admin vs viewer)
### Phase 2 — Field Features (Weeks 5–8)
**Goal:** Everything a field crew needs on their phone.
- [ ] DB: `wo_steps`, `wo_resources`, resource registry tables
- [ ] Step endpoints + `<wo-checklist>` with check-off
- [ ] Resource registry endpoints + `<wo-resource-panel>` picker
- [ ] DB: `wo_attachments` table
- [ ] Photo upload endpoint with GPS extraction
- [ ] `<wo-photo-panel>` — capture, gallery, before/during/after phases
- [ ] `<wo-map>` — Leaflet map + site pin
- [ ] Directions button (native maps deeplink)
- [ ] Mobile-responsive layout (CSS Grid, touch-friendly targets)
### Phase 3 — Integrations (Weeks 9–12)
**Goal:** Connects to the rest of the system.
- [ ] DB: `wo_accounting` table
- [ ] `<wo-accounting>` — GL, cost center, WBS, billing ref fields
- [ ] Parent linking: polymorphic `parent_type`/`parent_id`
- [ ] Link WOs to existing Projects (query existing project IDs)
- [ ] Link to Trouble Tickets / Service Orders (when those APIs exist)
- [ ] Audit log table + `<wo-timeline>` component
- [ ] Email notification on assignment (Go `net/smtp` or SendGrid)
- [ ] Reporting endpoint: WOs by status, by cost center, by date range
### Phase 4 — Optimization (Week 13+)
- [ ] Dashboard `<wo-dashboard>` — KPI cards + charts (Chart.mjs via CDN)
- [ ] Crew scheduling calendar view
- [ ] Offline support (Service Worker + IndexedDB cache for field use)
- [ ] CSV / Excel export for accounting reconciliation
- [ ] Full-text search across WO title, site, instructions
- [ ] Webhook / API for third-party integrations
---
## 12. Development Conventions
### Go
```
Packages: lowercase, single word (handlers, repository, model)
Errors: always wrapped (fmt.Errorf("repo.Create: %w", err))
HTTP errors: JSON envelope {"error": "message"} with correct status code
DB queries: named params only @param_name — never string concat
Logging: log/slog structured key-value pairs
Tests: _test.go files table-driven, httptest.NewRecorder for handlers
```
### JavaScript
```
Components: kebab-case custom elements <wo-form>, <wo-map>
Private: # prefix for class fields #data, #load(), #render()
Events: colon namespaced 'wo:select', 'steps:updated', 'auth:expired'
API calls: always in the component no inline fetch(), always via api.mjs
Render: full innerHTML redraw simple, no virtual DOM needed at this scale
State: component-local lift to app-root only when truly shared
```
### Git Branch Strategy
```
main — production-ready, tagged releases
develop — integration branch
feature/* — individual features (feature/wo-checklist)
fix/* — bug fixes
```
---
## Go Dependencies
```go
// go.mod
require (
github.com/go-chi/chi/v5 v5.1.0
github.com/jmoiron/sqlx v1.3.5
github.com/microsoft/go-mssqldb v1.7.1
github.com/golang-jwt/jwt/v5 v5.2.1
github.com/google/uuid v1.6.0
github.com/joho/godotenv v1.5.1
)
```
## Frontend Dependencies (CDN, no npm)
```html
<!-- in index.html -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9/dist/leaflet.css">
<script src="https://unpkg.com/leaflet@1.9/dist/leaflet.mjs"></script>
<!-- Chart.mjs added in Phase 4 only -->
<script src="https://cdn.mjsdelivr.net/npm/chart.mjs@4/dist/chart.umd.min.mjs"></script>
```
Zero build tooling. Zero npm for the frontend. Open in browser and go.
## Work Order Profiles
### Overview
A **Work Order Profile** is a reusable template that defines the default structure and behavior for a category of work orders. When a profile is applied to a work order (at creation or post-creation), its steps, instructions, priority, and duration are loaded in — then customized as needed.
> **Key idea:** Profile = preset + flexibility. The profile defines the standard; each WO can deviate from it.
---
### Profile Step Types
Profile steps have a **type** that controls how they are displayed and completed in the field. Types are a fixed code-level constant — not a database table. Each type has optional **type_config** (stored as JSON) that gets set when the step is added to a profile.
#### Built-in Step Types
| Type | Value | Field behavior |
|------|-------|----------------|
| Work Step | `work_step` | Standard checkbox — mark done, optional note |
| Photo | `photo` | Camera capture required; config defines phase and prompt |
| Inspection | `inspection` | Pass / Fail / N/A buttons; config defines criteria text |
| Note | `note` | Free-text entry field; config defines the prompt label |
#### type_config JSON by Type
```json
// work_step — no config needed
{}
// photo
{
"phase": "before", // "before" | "during" | "after"
"caption_prompt": "Photo of existing equipment before any work begins"
}
// inspection
{
"criteria": "All cable slack coiled and secured per spec"
}
// note
{
"prompt": "Record any site hazards or access issues observed"
}
```
#### Example profile: Fiber Splice Job
```
1. [photo] Before — site overview { phase: "before", caption_prompt: "Wide shot of work area" }
2. [work_step] Power down splice enclosure
3. [work_step] Prep and strip fiber ends
4. [inspection] Check splice loss < 0.1 dB { criteria: "OTDR reading below 0.1 dB loss" }
5. [photo] Splice tray loaded and sealed { phase: "during", caption_prompt: "Tray with labeled splices" }
6. [work_step] Seal enclosure and torque to spec
7. [note] Record any deviations or notes { prompt: "Deviations from standard procedure?" }
8. [photo] After — completed enclosure { phase: "after", caption_prompt: "Sealed enclosure, final install" }
```
---
### Database
```sql
-- Profiles table
IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'wo_profiles')
BEGIN
CREATE TABLE wo_profiles (
id INT IDENTITY PRIMARY KEY,
name NVARCHAR(200) NOT NULL,
description NVARCHAR(MAX),
category NVARCHAR(100),
default_priority NVARCHAR(10) NOT NULL DEFAULT 'normal',
default_duration_hours INT,
default_instructions NVARCHAR(MAX),
active BIT NOT NULL DEFAULT 1,
created_at DATETIME2 NOT NULL DEFAULT GETUTCDATE(),
updated_at DATETIME2 NOT NULL DEFAULT GETUTCDATE()
);
END
-- Profile steps table (with step_type and type_config)
IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'wo_profile_steps')
BEGIN
CREATE TABLE wo_profile_steps (
id INT IDENTITY PRIMARY KEY,
profile_id INT NOT NULL REFERENCES wo_profiles(id) ON DELETE CASCADE,
step_order INT NOT NULL,
title NVARCHAR(200) NOT NULL,
description NVARCHAR(MAX),
required BIT NOT NULL DEFAULT 1,
step_type NVARCHAR(30) NOT NULL DEFAULT 'work_step',
-- 'work_step' | 'photo' | 'inspection' | 'note'
type_config NVARCHAR(MAX) -- JSON; shape depends on step_type
);
CREATE INDEX ix_profile_steps ON wo_profile_steps (profile_id, step_order);
END
-- WO steps also carry step_type and type_config (copied from profile on apply)
-- Migration: add columns if they do not exist
IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID('wo_steps') AND name = 'step_type')
ALTER TABLE wo_steps ADD step_type NVARCHAR(30) NOT NULL DEFAULT 'work_step';
IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID('wo_steps') AND name = 'type_config')
ALTER TABLE wo_steps ADD type_config NVARCHAR(MAX) NULL;
```
### API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/profiles` | List active profiles (search, category filter) |
| POST | `/api/profiles` | Create profile |
| GET | `/api/profiles/{id}` | Get profile with its steps |
| PUT | `/api/profiles/{id}` | Update profile fields |
| DELETE | `/api/profiles/{id}` | Soft delete (set active=0) |
| GET | `/api/profiles/{id}/steps` | List profile steps |
| POST | `/api/profiles/{id}/steps` | Add step to profile |
| PUT | `/api/profiles/{id}/steps/{sid}` | Update profile step |
| DELETE | `/api/profiles/{id}/steps/{sid}` | Remove step from profile |
| POST | `/api/work-orders/{id}/apply-profile/{profileId}` | Apply profile to WO |
#### apply-profile behavior
Request body: `{ "mode": "append" | "replace" }`
- **append** — inserts profile steps after existing steps (step_order continues from current max)
- **replace** — deletes all existing steps, then inserts profile steps starting at order 1
- Both modes copy `step_type` and `type_config` from the profile step into `wo_steps`
- Both modes update `instructions` if currently blank and `priority` if WO is still `draft`
### Go Models
```go
type Profile struct {
ID int `db:"id" json:"id"`
Name string `db:"name" json:"name"`
Description string `db:"description" json:"description"`
Category string `db:"category" json:"category"`
DefaultPriority string `db:"default_priority" json:"default_priority"`
DefaultDurationHours *int `db:"default_duration_hours" json:"default_duration_hours"`
DefaultInstructions string `db:"default_instructions" json:"default_instructions"`
Active bool `db:"active" json:"active"`
StepCount int `db:"step_count" json:"step_count"`
CreatedAt time.Time `db:"created_at" json:"created_at"`
UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
Steps []ProfileStep `db:"-" json:"steps,omitempty"`
}
type ProfileStep struct {
ID int `db:"id" json:"id"`
ProfileID int `db:"profile_id" json:"profile_id"`
StepOrder int `db:"step_order" json:"step_order"`
Title string `db:"title" json:"title"`
Description string `db:"description" json:"description"`
Required bool `db:"required" json:"required"`
StepType string `db:"step_type" json:"step_type"` // "work_step"|"photo"|"inspection"|"note"
TypeConfig string `db:"type_config" json:"type_config"` // JSON string
}
// Step also gains these two fields (in model/models.go)
// StepType string `db:"step_type" json:"step_type"`
// TypeConfig string `db:"type_config" json:"type_config"`
```
### Frontend Components
**`web/components/registry/profile-list.mjs`**
- List page at `/registry/profiles`
- Cards: name, category badge, step count, active status
- Search + category filter, edit/deactivate actions, "New Profile" button
**`web/components/registry/profile-form.mjs`**
- Modal dialog for create/edit
- Fields: name (required), description, category, default priority, default duration hours, default instructions
- Inline step editor: ordered step list with add / edit / reorder / delete
- When adding a step: type picker first (work_step / photo / inspection / note icon buttons)
- After type selected: type-specific config fields appear inline:
- `photo` → phase select (before/during/after) + caption prompt input
- `inspection` → criteria text input
- `note` → prompt label input
- `work_step` → no extra fields
- Active toggle in edit mode
**`web/components/work-orders/wo-checklist.mjs`**
- Each step renders differently based on `step_type`:
- `work_step` — large checkbox + title + optional note textarea
- `photo` — camera icon button labeled with `type_config.caption_prompt`; tapping opens photo panel pre-set to the configured phase; completed when a photo is attached to this step
- `inspection` — Pass / Fail / N/A button group; completed when any selection is made; result stored in completion notes
- `note` — text input labeled with `type_config.prompt`; completed when non-empty text is saved
- Progress bar counts all step types equally
**WO Form integration (`wo-form.mjs`)**
- "Load Profile" ghost button at top of form (shown only on new WOs or draft status)
- Searchable profile picker dialog — on confirm pre-fills priority and instructions (if blank)
- Steps applied server-side via apply-profile after the WO saves; checklist tab then refreshes
**WO Detail integration (`wo-detail.mjs`)**
- "Apply Profile" button in header actions alongside Edit / Change Status
- Two-step dialog: (1) pick profile, (2) if WO has existing steps — prompt append vs replace
- Calls `POST /api/work-orders/{id}/apply-profile/{profileId}` then refreshes Checklist tab
### Sidebar Nav
Under Resources section:
```
Profiles /registry/profiles (layout-template icon)
```
### apply-profile Handler (pseudocode)
```go
func (h *ProfileHandler) Apply(w http.ResponseWriter, r *http.Request) {
woID, profileID := intParam(r, "id"), intParam(r, "profileId")
var body struct { Mode string `json:"mode"` }
json.NewDecoder(r.Body).Decode(&body)
profile, steps := // load profile + steps
if body.Mode == "replace" {
db.Exec(`DELETE FROM wo_steps WHERE wo_id = @p1`, woID)
}
var maxOrder int
db.Get(&maxOrder, `SELECT ISNULL(MAX(step_order), 0) FROM wo_steps WHERE wo_id = @p1`, woID)
for _, s := range steps {
db.Exec(`INSERT INTO wo_steps (wo_id, step_order, title, description, required, step_type, type_config)
VALUES (@p1, @p2, @p3, @p4, @p5, @p6, @p7)`,
woID, maxOrder+s.StepOrder, s.Title, s.Description, s.Required, s.StepType, s.TypeConfig)
}
db.Exec(`
UPDATE work_orders SET
instructions = CASE WHEN (instructions IS NULL OR instructions = '') THEN @p1 ELSE instructions END,
priority = CASE WHEN status = 'draft' THEN @p2 ELSE priority END,
updated_at = GETUTCDATE()
WHERE id = @p3`,
profile.DefaultInstructions, profile.DefaultPriority, woID)
}
```
Reference in New Issue View Git Blame Copy Permalink