# ServiceM8 Project Progress

## Current Quote Template → JobMaterials Pipeline

### Live receiver
- `servicem8_webhook_receiver.py`
  - receives `form.response_created`
  - stores the raw webhook payload in `servicem8_webhooks.db`
  - checks incoming form responses for the Quote Template `form_uuid`
  - if matched, parses and queues the derived jobMaterials payload to:
    - `quote-template-jobmaterials-queue.jsonl`
  - does **not** perform live ServiceM8 writes at this stage

### Parser
- `servicem8-quote-template-parser.py`
  - parses Quote Template `field_data`
  - extracts:
    - description of works
    - `Item 1..12` include lines
    - `Works excluded 1..4` exclude lines
    - extra descriptive include rows such as labour/scaffolding/equipment fields
  - builds normalized `desired_job_materials`

### Create/apply script
- `servicem8-create-jobmaterials-from-form-response.py`
  - standalone script
  - consumes a Quote Template form response JSON payload
  - builds ServiceM8 Job Material API payloads
  - runs in **dry-run by default**
  - supports live create later with `--apply`
  - records created/generated mappings into local state DB

### Local state tracking
- `servicem8_quote_materials_state.db`
  - local SQLite DB for tracking generated jobMaterials
  - intended fields include:
    - job UUID
    - form response UUID
    - created job material UUID
    - kind/source metadata

### Queue/prepared output
- `quote-template-jobmaterials-queue.jsonl`
  - lightweight queue/output file written by webhook stage
  - contains parsed/prepared `desired_job_materials` objects
  - no live update performed yet

### Inspector
- `servicem8_inspector.py`
  - read-only browser for webhook DB
  - now also includes visibility of generated-materials state DB

## Current Status
Everything is staged and connected up to the point of:
- webhook receive
- UUID trigger check
- form parsing
- local queueing
- dry-run jobMaterial payload generation
- local state DB support
- inspector visibility

## Not Yet Enabled
- actual live POST creation of Job Materials into ServiceM8 during webhook processing
- any automatic update/delete reconciliation against live ServiceM8 records

## Design Notes
- Heavy lifting is intentionally kept **out of the live webhook handler**.
- The webhook handler is used only for:
  - capture
  - UUID gate
  - parse/prepare/queue
- Live ServiceM8 mutation remains a separate step/script for safety.