Two follow-up fixes from the Task 5 code-quality review:
- scripts/generate-plant-hours-template.ts uses
fileURLToPath(import.meta.url) instead of __dirname. The
project's tsconfig has module: esnext, so the moment the
package flips to ESM the original would throw
ReferenceError: __dirname is not defined.
- src/lib/plant-hours-template.ts documents that the frozen
header row is a best-effort request — SheetJS Community
Edition silently drops the !freeze property (only Pro emits
frozen-pane XML). The function still produces the canonical
13-column workbook, but the doc comment no longer claims a
behaviour that doesn't happen.
buildPlantHoursTemplateWorkbook() emits the canonical 13-column xlsx
with a frozen header row, typed cells (date/time/number), a sample
row using the supplied vehicle, and a Notes column widened for
readability. Used by both /api/plant-hours/template and the seed
script that writes RAW_DOCS/Plant_Hours_Template_2.xlsx.
Adds two tests that lock in behaviour the previous test file relied on
implicitly:
- validatePlantHoursRow rejects when the supplied vehicle's qr_code_id
doesn't match row.vehicle_qr (the guard the schema extends beyond
the original spec)
- computePlantHoursFields rounds value to 2 decimal places (a
fractional-input case the integer-only assertion didn't exercise)
Pure validator covering all the error/warning cases from the spec:
unknown QR, bad date range, end_hours < start_hours, bad time format,
missing cost (cell + vehicle), duplicate week, and the type-mismatch
warning. computePlantHoursFields() derives hours/value/over_budget/
hours_mismatch and the vehicle_unit_type_at_import snapshot.
Moves normHeader/resolveColumn/parseDate/toNumber out of fuel-import-parse
into a new src/lib/import-parse.ts so plant-hours can reuse them. Adds
parseTime (HH:MM, 24h, single-digit hour normalised). Adds the
PLANT_COL_ALIASES table for the plant-hours route. fuel-import-parse
becomes a thin re-export shim — the fuel-logs route and its existing
test file are unchanged.
Pure predicate: returns true when a vehicle has been dismissed and
no flagged log is strictly newer than the dismissal. Six Vitest cases
covering each branch and the auto-undismiss boundary.
Updated the PurchasingPage component to include received items data, allowing for accurate fulfillment percentage calculations based on authoritative data. The implementation now sums received quantities per purchase order item, replacing the previous denormalized field. Additionally, the needs-review delivery notes component has been improved with a modal for reviewing slips and assigning purchase orders, enhancing user interaction. The SlipPreview component has been integrated for better visual representation of delivery slips.
Updated the OCR result processing to include validation of matched PO items before determining the verification tier. This change ensures that if the local PO items fetch is empty but n8n supplied matched IDs, the tier will downgrade to draft, requiring user review. Additionally, the `resolveOcrTier` function has been modified to account for item verifiability, improving the accuracy of tier assignments based on confidence levels and PO resolution status. Unit tests have been added to cover these new scenarios.
Updated the OCR result processing to include a more robust PO matching mechanism. The new implementation prioritizes exact matches, followed by normalized comparisons, and finally employs a Levenshtein-based fuzzy match for improved accuracy. This change ensures that delivery notes are correctly linked to purchase orders, even when OCR introduces minor errors. Additionally, the behavior for handling confidence levels and PO resolution has been clarified in the documentation, enhancing overall processing reliability.
- Updated the delivery note upload API to include site ID for better project association.
- Modified the delivery note schema to support additional fields such as processing status, OCR confidence, and received by name.
- Enhanced the UI components for uploading delivery notes to allow file drop functionality and improved user feedback during file selection.
- Refactored purchasing page to integrate delivery notes that require review, providing better visibility and management of pending items.
- Added new KPIs to track active purchase orders and fulfillment percentages, improving overall dashboard insights.
- Updated the timesheet import route to support optional metadata fields for site linking and auto-creation of missing employees.
- Enhanced parsing to detect multiple file formats, including Hills Casual Matrix and long-format CSV/XLSX.
- Modified response structure to include detected format and created employees in the JSON response.
- Improved UI components to allow project selection and options for creating new workers during import.
- Refactored import logic to ensure a seamless user experience when handling timesheet uploads.
- Integrated inline editing functionality for vehicle descriptions, allowing users to edit directly within the FuelView.
- Added a Topbar with EditModeToggle and ImportFuelLogsButton for improved user interaction.
- Implemented EditModeBanner to provide feedback during editing sessions.
- Updated FleetMobileCard and FleetRow components to support inline editing, enhancing the overall user experience.
- Refactored FuelView to accept title and subtitle props for better contextual information.
- Introduced a new optional field `job_start_date` in the site schema to track project start dates.
- Updated the SitesPage component to utilize `job_start_date` for determining site status and fallback logic.
- Enhanced the SitesView component to display the new status "upcoming" for sites with future start dates.
- Modified the SiteDetailPage to include `job_start_date` in the site details and added an EditSiteButton for site management.
- Updated the site templates to include `job_start_date` for better pre-filling in the site creation form.
- Updated the import route to accept both long-format CSV and Hills-style wide-format XLSX files.
- Implemented a new parsing mechanism that detects file type and processes accordingly.
- Enhanced error handling to provide more informative messages during file parsing failures.
- Modified the response structure to include total rows processed and detailed error reporting.
- Updated the UI components to reflect changes in file selection and user instructions for importing timesheets.
- Introduced a new section for flagged vehicles based on fuel variance, providing alerts and warnings for each vehicle.
- Updated data fetching to include fuel logs and compute variance for better tracking of fuel consumption.
- Improved site-level aggregation of fuel issues, allowing for a clearer overview of vehicles requiring attention.
- Refactored utility functions for fuel variance calculations and streamlined the data structure for better maintainability.
- Enhanced UI components to display alerts and warnings effectively, ensuring better visibility for users.
The Aug 2026 pump sheet from The Hills (and any future sheet from
the same source) uses different column names and a different date
format than the legacy CSV the import route was built for. Adapts
the route so the same endpoint accepts either Excel (.xlsx) or CSV,
maps the new column names onto the existing FUEL_LOGS schema, and
persists their 'Latest Consumption' column verbatim.
What's new
• SheetJS (xlsx) replaces PapaParse for parsing. Single code path
handles both .xlsx and .csv uploads.
• Resolves columns case-insensitively against an alias table so
legacy CSVs (vehicle_description, odo_reading) still work
alongside the new shape (Date Logged, Vehicle QR, Km's/ Hours,
Litres Pumped, Current Site, Latest Consumption).
• Date parser: DD/MM/YYYY first (with leading-space tolerance),
falls back to YYYY-MM-DD, then to Excel serial numbers.
• Vehicle match: QR code first (clean identifier in the source
data), falls back to description text for legacy CSV.
• Site match: by sites.name (one round-trip, cached for the
import). project_code is derived from the resolved site; falls
back to the vehicle's project_code.
• Latest Consumption persisted as a new FUEL_LOGS field
(latest_consumption, number, optional). Empty source cells
stay empty rather than getting coerced to 0.
PocketBase change
• scripts/migrations/2026-08-24-fuel-logs-latest-consumption.py
adds the new field. Idempotent; follows the pattern of the
2026-08-19 migration. Run it with PB_ADMIN_EMAIL +
PB_ADMIN_PASSWORD before importing the new sheets, or the
import will fail with 'latest_consumption is not a field'.
UI
• Import button now accepts .xlsx and CSV; SAMPLE_HEADERS +
SAMPLE_OPTIONAL show the new column expectations and the
DD/MM/YYYY date format hint.
• fuel-view.tsx shows a 'Consumption (src)' column on the row
table so operators can eyeball what their fuel team sent
against the app's recomputed variance.
Out of scope (intentionally untouched)
• vehicles, sites, data_import_batches and every other
collection — no schema changes there.
• PO / timesheets / delivery-notes imports.
• fuel/page.tsx business logic (variance calc, vehicle summaries).
Verified
• Dry-run against 'The Hills Diesel 1-24 August.xlsx': 134/134
rows parse cleanly, 0 errors. 12/134 rows correctly carry an
empty Latest Consumption (matches the source).
• vitest: 20/20 fuel-import-parse + 35/35 PO-schema tests pass.
• tsc --noEmit clean.
• One pre-existing failure in
src/app/api/purchase-orders/process-batch/route.test.ts
unrelated to fuel; confirmed failing on main before this change.
PO ingestion was rejecting valid line items with qty = 0 (base
corrections, pending test rows) because the schema strictly required
qty > 0. Loosen the guard to qty >= 0 while keeping rate, disc_percent
and vat_percent strict. Also tighten against non-finite numbers
(NaN, +/-Infinity) via Number.isFinite — the previous !(qty > 0) guard
let Infinity slip through.
- Schema: qty >= 0, finite; rate/disc/vat rules unchanged
- Tests: add positive case for qty = 0; add negative + NaN rejection
- 35/35 schema tests pass; tsc clean
When the route returns 500 with 'lookup_failed', include the failing
step name and the underlying error string in the response body so we
can pinpoint which catch block is firing (get_batch / dedup / match_site).
Production diagnostic - safe to revert once root cause is found.
- Enhanced VehicleSummary and PlantRow interfaces to include qrCodeId and costPerHour properties.
- Updated FuelView and PlantView components to display QR code information in the respective tables.
- Adjusted data fetching in FuelPage and VehicleDetailPage to retrieve and handle new fields from the API.
- Modified site detail views to reflect the unified VEHICLES collection, ensuring accurate data representation for plant utilization.
This update improves the visibility of QR codes and cost information for better tracking and management of vehicles and equipment.
Strips vendor prefixes (PO-, PO#, P.O., etc.), collapses whitespace,
uppercases. Used by the upload-route hash dedup and the process-batch
dedup-by-po_number check so OCR variants ('PO-1234' vs 'po 1234') fold
to the same canonical form.
Tests: 33 in this file (23 pre-existing for validatePurchaseOrderPayload,
matchSite, computeTotalValue + 10 new for normalizePoNumber).
- Purchase order upload route now returns 502 n8n_rejected when n8n
responds with a non-2xx status, instead of silently claiming success.
- Add a 10s AbortController timeout on the n8n fetch, returning 504
n8n_timeout on expiry (502 n8n_unreachable on other network errors).
- Extract ALLOWED_MIME and MAX_FILE_BYTES from upload/route.ts into
src/lib/purchase-order-schema.ts so the upcoming ingest route can
share the same validation constants.
- Updated the documentation to reflect the latest changes in the Purchase Order upload and n8n ingestion process.
- Clarified the data flow from browser to Next.js API endpoints and through to PocketBase.
- Ensured that the documentation aligns with the recent implementation and design specifications.
- Added `pocketbase` as a dependency in `package.json` and `package-lock.json`.
- Updated the `dev` script in `package.json` to run on port 6004 instead of 3000.
- Removed unused API routes: `src/app/api/health/route.ts`, `src/app/api/mcp/route.ts`, `src/app/api/upload/route.ts`, and their associated logic to streamline the codebase.
- Cleaned up `package-lock.json` by removing unnecessary peer dependencies and ensuring consistency in the dependency tree.
The previous commit dropped real data for The Hills ext 12
(sites, vehicles, employees, orders, plant hire rates, P&G
expenses) so the dashboard had something to render during design
iteration. With PB about to be wired, that data now belongs in
PocketBase rather than in the source tree.
This commit empties the data layer back to zero so the dashboard
falls into its empty-state UI on every page:
- src/lib/mock-data.ts SITES_DATA, SITES, SUPPLIERS, VEHICLES,
EMPLOYEES, ORDERS, FUEL_READINGS,
PLANT_HIRE_RATES, PG_EXPENSES → []
Header comment updated to point future
contributors at lib/pb.ts as the next
step.
- src/lib/uploads.ts UPLOAD_HISTORY → []. Acceptance rules
(mime / extensions / size limits) kept so
the Uploads page still shows format hints.
Type definitions, helper functions and date utilities are untouched
so all routes continue to render (HTTP 200 across the board). The
sidebar, dashboard, fuel, orders, employees, sites and uploads pages
all gracefully render their empty states.
When PocketBase is wired:
1. Install 'pocketbase' (npm)
2. Build src/lib/pb.ts with admin-authed server client + public
client
3. Replace the imports in pages like
import { SITES_DATA, VEHICLES, ... } from '@/lib/mock-data';
with calls like
import { getServerPB } from '@/lib/pb';
const records = await getServerPB().collection('sites').getList();
4. Keep the empty exports here as a final fallback so the dashboard
still works if PB is ever unreachable.
Data wired from the site cost sheet, fuel log, wage schedule and two
PO PDFs the user shared:
- src/lib/types.ts VehicleType expanded (Roller, TLB,
Pickup, Water Truck, Compressor,
Mixer) so plant types map cleanly to
the source data. Vehicle gains
optional kmPerL and expectedLPerHour
fields for the mixed L/h + km/L
allowance model.
- src/lib/mock-data.ts SITES_DATA[0] = The Hills ext 12,
contract value R24,988,663, contract
code C26/09, 8-month duration.
SITES, SUPPLIERS updated.
VEHICLES populated with 47 entries
covering rollers, TLBs, excavators,
graders, loaders, tipper trucks,
water trucks, pickups, mixers and
auxiliary equipment (compressors,
crushing machine).
EMPLOYEES populated with 15 permanent
+ 53 casuals, all at the project's
45h/week standard.
PLANT_HIRE_RATES populated with 32
entries matching the cost sheet
(R185–R680/h depending on equipment).
PG_EXPENSES populated with all 6 P&G
monthly lines (container, security,
salaries, overheads, insurance,
site facilities = R567,403.50/m).
ORDERS populated with MEGCPO9199
(PPE, Delivered) and MEGCPO9165
(aggregates, Partial).
FUEL_READINGS starts empty — drop
CSV-imported rows in once the depot
system is wired.
- src/lib/uploads.ts UPLOAD_HISTORY seeded with the GRN
attached to MEGCPO9199.
- src/lib/burn.ts New helper. burnBreakdown() joins
plant hire rates with the vehicles
list, multiplies each hire rate by
the standard 45h/week, adds weekly
P&G share, and surfaces both weekly
and monthly totals.
- src/lib/sites.ts summarizeSite + summarizeAllSites
now take PlantHireRate[] and
PgExpense[] so the site summary
exposes weeklyBurn / monthlyBurn /
weeklyPlantHire / monthlyPg etc.
- src/app/dashboard/page.tsx New 'Burn rate — weekly vs monthly'
panel. Two side-by-side cards show
weekly + monthly totals with plant
hire vs P&G breakdown, plus a
'Cost breakdown' card on the right.
- src/app/dashboard/sites/* Pass the new hireRates + pgExpenses
arrays through to the summary helpers.
Notes:
- The 'Spent to date' KPI on the Sites list / detail now sums PO
value (since there are no fuel readings yet). Once depot data is
ingested, it will pick up the actual R25.65/L burn automatically.
- Tank capacities + odometer start values are sensible estimates
for the equipment types — adjust per-unit when you have real
fleet specs.
- Weekly hours per employee default to 45h so the workforce
trends look populated; replace with timesheet imports as soon as
those land.
Wipe all seeded mock data so the user can drop in real numbers:
- src/lib/mock-data.ts SITES_DATA, SITES, SUPPLIERS, VEHICLES,
EMPLOYEES, ORDERS, FUEL_READINGS → []
Type definitions and helper functions
preserved; the FUEL_READINGS generator is
preserved as a commented block ready to
re-enable.
- src/lib/uploads.ts UPLOAD_HISTORY → []. Acceptance rules
(mime / extensions / size limits per kind)
kept so the UI still shows format hints.
While verifying empty states, caught a divide-by-zero on the Sites
list page: 'Workforce this week' KPI rendered as 'NaN% of total
contract value' when there are zero sites. Guard the divide.
All pages now render in their empty-state UI — KPIs show 0, charts
draw empty axes, tables say 'No X match the current filters', upload
history cards say 'No uploads yet'. Typecheck clean, all routes
return 200, no runtime errors.
Two small cleanup changes:
1. Drop the 'CSV uploads' card at the bottom of the Fuel page.
The Template / Upload CSV buttons in the topbar still let users
ingest readings, but the recent-uploads mini-list was redundant —
the Uploads page already shows every upload. The fuelCsvTemplate
import is still in use by the topbar download button.
Also clean up the now-unused uploads/setUploads state, the
FileSpreadsheet icon, and the unused CardDescription / Badge /
FileSpreadsheet references in the bottom block.
2. Plant a guaranteed critical anomaly on the most recent working
day so the Anomaly log's first page and the dashboard's 'Needs
attention' rail show one for demo purposes. The previous random
spike day often landed too far back to be visible without
paginating. Now MI-TT-07 (one of the tipper trucks) always has
a 2.4x-2.8x theft spike on the latest day, while the other
eight vehicles still get a random earlier spike for variety.
3. Sort the Anomaly log by date desc, then by severity desc
(critical → alert → watch → ok) so actionable entries surface
first within each day. The dashboard's 'Needs attention' rail
also benefits from the more recent critical sitting at the top.
4. Restore the Uploads nav item in the sidebar that was removed
in the previous commit by mistake.
New /dashboard/uploads page with a 2x2 grid of drop zones, one per
ingest source:
- Orders (orange) — CSV / XLS / XLSX, max 10 MB
- Delivery Notes (teal) — PDF / images, max 20 MB
- Fuel Logs (yellow-green) — CSV / XLS / XLSX, max 5 MB
- Time Sheets (green) — CSV / XLS / XLSX, max 5 MB
Each block has:
- A coloured left stripe + icon disc in the accent colour
- Title, format-count badge, and a long description of what to upload
- File-format chips and a max-size hint
- A drag-and-drop drop zone that also accepts files via click
- A primary 'Upload X' button in the accent colour
- A 'Recent' list showing the last 4 uploads with status badges
When files are dropped or picked, the client POSTs to
/api/upload with a 'type' field. The endpoint validates MIME and size
against the kind-specific rules in src/lib/uploads.ts and returns a
JSON descriptor with accepted/rejected entries. New entries are
prepended to the page's recent-uploads list in real time, and a
bottom-right toast shows accepted/rejected counts.
The sidebar gets a new 'Uploads' nav item with the upload icon.
Files:
- src/lib/types.ts type definitions
- src/lib/uploads.ts acceptance rules + mock history
- src/app/api/upload/route.ts type-aware upload handler
- src/app/dashboard/uploads/page.tsx the new page
- src/components/layout/sidebar.tsx Uploads nav entry
