modified: Agents.md

2025-11-21 15:12:12 +10:00
parent 5d4079579a
commit ccb24b2606
1 changed files with 355 additions and 20 deletions
@@ -1,31 +1,366 @@
-Purpose
+# AGENTS.md --- StockFill

-StockFill is an offline-first Progressive Web App (PWA) designed to help service station staff create pick lists used to restock various store areas (drinks fridge, chips, chocolate, dairy, deli, etc.).
-It uses IndexedDB (Dexie) for local storage, no backend, and runs fully offline.
+## Purpose

-All code generated must follow the architecture, conventions, and rules below.
+StockFill is an offline-first Progressive Web App (PWA) designed to help
+service station staff create pick lists used to restock various store
+areas (drinks fridge, chips, chocolate, dairy, deli, etc.).\
+It uses **IndexedDB (Dexie)** for local storage, has **no backend**, and
+runs fully offline.

-1. Core Architecture
+All code generated must follow the architecture, conventions, and rules
+below.
+
+------------------------------------------------------------------------
+
+## 1. Core Architecture

 StockFill is:

-🟩 React + Vite
+-   React + Vite\
+-   PWA (service worker + manifest)\
+-   Dexie.js for local DB (IndexedDB)\
+-   React Router\
+-   Context + Hooks\
+-   Mobile-first UI\
+-   Hosted via Docker using Nginx

-🟩 PWA (service worker + manifest)
-
-🟩 Dexie.js for local DB (IndexedDB)
-
-🟩 React Router for navigation
-
-🟩 Context + Hooks for app logic
-
-🟩 Mobile-first UI
-
-🟩 Hosted via Docker using Nginx
-
-There is no remote API.
+There is **no remote API**.\
 All data stays local to the device.

-2. Directory Structure
+------------------------------------------------------------------------
+
+## 2. Directory Structure

 Codex must always generate files within this structure:
+
+    /app
+      /src
+        /components
+        /screens
+        /hooks
+        /db
+          index.ts
+          migrations.ts
+          seed.ts
+        /models
+          Product.ts
+          Area.ts
+          PickList.ts
+          PickItem.ts
+        /context
+          DBProvider.tsx
+        /utils
+          barcode.ts
+          longPress.ts
+          swipe.ts
+        /pwa
+          service-worker.js
+          manifest.json
+        App.tsx
+        main.tsx
+      Dockerfile
+      docker-compose.yml
+      vite.config.ts
+      AGENTS.md
+
+Codex must not introduce alternative or conflicting structures.
+
+------------------------------------------------------------------------
+
+## 3. Data Model Specification
+
+Dexie tables must be implemented exactly as follows:
+
+### Products
+
+    id: string (UUID)
+    name: string
+    category: string
+    unit_type: string
+    bulk_name?: string
+    units_per_bulk?: number
+    barcode?: string
+    archived: boolean
+    created_at: number
+    updated_at: number
+
+### Areas
+
+    id: string
+    name: string
+    created_at: number
+    updated_at: number
+
+### PickLists
+
+    id: string
+    area_id: string
+    created_at: number
+    completed_at?: number
+    notes?: string
+
+### PickItems
+
+    id: string
+    pick_list_id: string
+    product_id: string
+    quantity_units: number
+    quantity_bulk: number
+    status: "pending" | "picked" | "skipped"
+    created_at: number
+    updated_at: number
+
+------------------------------------------------------------------------
+
+## 4. UI & UX Rules
+
+-   Mobile-first screens\
+-   Large touch targets\
+-   Clean, minimal UI\
+-   Use MUI components\
+-   Follow workflow conventions\
+-   Avoid excessive modal dialogs\
+-   Ensure barcode scanning is fast\
+-   Ensure gesture operations are smooth
+
+------------------------------------------------------------------------
+
+## 5. Core Screens
+
+### HomeScreen
+
+-   Start New Pick List\
+-   View Pick Lists\
+-   Manage Products\
+-   Manage Areas\
+-   Scan Barcode (quick add)
+
+### StartPickListScreen
+
+-   Choose Area\
+-   Start button
+
+### ActivePickListScreen
+
+-   List of PickItems\
+-   Tap = +1 unit\
+-   Long-press = +1 bulk\
+-   Swipe left = mark picked\
+-   Swipe right = delete\
+-   Add Item button\
+-   Complete List button
+
+### AddItemScreen
+
+-   Search\
+-   Category filter\
+-   Scan barcode\
+-   Increment units & bulk\
+-   Add to pick list
+
+### ManageProductsScreen
+
+-   List\
+-   Search\
+-   Filters\
+-   Edit product\
+-   Add product
+
+### ManageAreasScreen
+
+-   Add\
+-   Edit\
+-   Delete
+
+### BarcodeScannerScreen
+
+-   Live camera preview\
+-   On detection → resolve product or prompt creation
+
+------------------------------------------------------------------------
+
+## 6. Gestures & Interaction Rules
+
+### Tap
+
+Increase `quantity_units` by **1**.
+
+### Long Press
+
+Increase `quantity_bulk` by **1** using a shared `useLongPress()` hook.
+
+### Swipe Left
+
+Mark item as `"picked"`.
+
+### Swipe Right
+
+Delete item.
+
+### Barcode Scanning
+
+-   Use `@zxing/browser`\
+-   Fallback to native `BarcodeDetector`
+
+------------------------------------------------------------------------
+
+## 7. Hooks Requirements
+
+### Database Hooks
+
+-   `useProducts()`\
+-   `useProduct(id)`\
+-   `usePickList(id)`\
+-   `usePickLists()`\
+-   `usePickItems(pickListId)`\
+-   `useAreas()`
+
+### Interaction Hooks
+
+-   `useLongPress()`\
+-   `useSwipe()`\
+-   `useBarcodeScanner()`
+
+### PWA Hooks
+
+-   `useServiceWorker()`
+
+------------------------------------------------------------------------
+
+## 8. Component Requirements
+
+-   ProductRow\
+-   PickItemRow\
+-   NumericStepper\
+-   BarcodeScannerView\
+-   LongPressButton
+
+All components must use TypeScript and be reusable.
+
+------------------------------------------------------------------------
+
+## 9. State Management Rules
+
+-   Use Context for DB provider\
+-   No Redux\
+-   Long-lived data must come from Dexie\
+-   No external APIs\
+-   Full offline functionality
+
+------------------------------------------------------------------------
+
+## 10. PWA Requirements
+
+### manifest.json
+
+-   name\
+-   short_name\
+-   icons\
+-   display: standalone\
+-   background_color\
+-   theme_color
+
+### service-worker.js
+
+-   Precache static assets\
+-   Cache index.html\
+-   Cache route requests\
+-   Provide offline fallback
+
+Must NOT break Dexie.
+
+------------------------------------------------------------------------
+
+## 11. Docker Requirements
+
+### Dockerfile
+
+-   Node build stage\
+-   Nginx serve stage\
+-   Copy build to `/var/www/html`\
+-   Must include service worker + PWA files
+
+### docker-compose.yml
+
+Expose port 8080:
+
+    ports:
+      - "8080:80"
+
+------------------------------------------------------------------------
+
+## 12. Code Style Rules
+
+-   TypeScript only\
+-   Strict mode\
+-   Prettier formatting\
+-   Named exports unless default is clearer\
+-   No files larger than 300--400 lines\
+-   Keep architecture consistent
+
+------------------------------------------------------------------------
+
+## 13. UX Workflow Requirements
+
+-   Minimise taps\
+-   Prioritise mobile experience\
+-   Search must be instant\
+-   Barcode scanning must be quick\
+-   Product creation must be minimal friction\
+-   Auto-save pick lists\
+-   Smooth animations on long press
+
+------------------------------------------------------------------------
+
+## 14. Testing and Validation
+
+Codex must generate:
+
+-   Unit tests for hooks\
+-   Component tests with React Testing Library\
+-   e2e tests only if explicitly requested
+
+Must support offline mode.
+
+------------------------------------------------------------------------
+
+## 15. Things Codex Must NOT Do
+
+Codex must **never**:
+
+-   Create a backend\
+-   Use remote APIs\
+-   Break PWA functionality\
+-   Change Dexie schema without migrations\
+-   Introduce Redux\
+-   Modify directory structure\
+-   Remove offline support\
+-   Add multi-user logic
+
+------------------------------------------------------------------------
+
+## 16. Output Rules for Codex
+
+-   Include file paths at top of each snippet\
+-   No placeholder TODOs\
+-   Code must be runnable\
+-   Must follow existing patterns\
+-   Must ensure offline correctness
+
+------------------------------------------------------------------------
+
+## 17. Project Evolution Rules
+
+-   New features must follow these patterns\
+-   DB changes must use migrations\
+-   Schema must remain forward-compatible
+
+------------------------------------------------------------------------
+
+## 18. Summary
+
+This document defines how Codex must generate, modify, and maintain the
+StockFill codebase.\
+Codex must follow this specification **exactly**, ensuring consistency
+and maintainability across all future changes.