Add PocketBase collections, APIs & migration docs
Introduce PocketBase workflow support, migration tooling, server APIs and documentation. Adds a set of PocketBase collection JSONs (order_items, order_items_v2, collection_pool, delivery_notes, delivery_note_items, repairs) and a large import manifest for workflow collections; includes docs describing MCP/API layer, migration audit, order-item schema and rollout plans. Adds server-side agent/MCP endpoints and services (api/mcp, api/v1/orders, collection-pool, order-items status, health) plus helper modules (pocketbase-admin, orders-service, order-item-status, agent-auth) and a migration script to create order_items_v2/collection_pool. UI: new pages for collection-pool, delivery-notes, repairs and several updates to orders/quotes pages, sidebar, tooltip and pb helpers/types. Also updates package.json (migration script and related changes) and global styles. Required env vars and suggested migration command are documented (e.g. NEXT_PUBLIC_POCKETBASE_URL, PB_ADMIN_EMAIL, PB_ADMIN_PASSWORD, ORDER_ITEMS_COLLECTION; run npm run pb:migrate:orders-v2).
2026-05-25 16:39:33 +00:00
|
|
|
# Order Items Naming Standard (PocketBase)
|
|
|
|
|
|
|
|
|
|
## Goal
|
|
|
|
|
Use one consistent, driver-oriented naming convention in `order_items` with `drv_*` prefixes.
|
|
|
|
|
|
|
|
|
|
## Recommended Canonical Fields
|
|
|
|
|
- `item_status` (global item lifecycle)
|
|
|
|
|
- `drv_status` (driver/collection lifecycle)
|
|
|
|
|
- `drv_id` (relation to driver/user table)
|
|
|
|
|
- `drv_assigned_at`
|
|
|
|
|
- `drv_collected_at`
|
|
|
|
|
- `drv_problem_flag`
|
|
|
|
|
- `drv_problem_type`
|
|
|
|
|
- `drv_problem_notes`
|
|
|
|
|
|
|
|
|
|
## Transition Mapping
|
|
|
|
|
During migration, support these aliases in API:
|
|
|
|
|
- `driver_status` -> `drv_status`
|
|
|
|
|
- `driver` -> `drv_id`
|
|
|
|
|
- `problem_flag` -> `drv_problem_flag`
|
|
|
|
|
- `problem_type` -> `drv_problem_type`
|
|
|
|
|
- `problem_notes` -> `drv_problem_notes`
|
|
|
|
|
|
|
|
|
|
## Safe Migration Plan
|
|
|
|
|
1. Add new `drv_*` fields (keep old fields temporarily).
|
|
|
|
|
2. Backfill new fields from existing values.
|
|
|
|
|
3. Update UI and automation writes to new fields only.
|
|
|
|
|
4. Keep read-compat for old fields for 1-2 release cycles.
|
|
|
|
|
5. Remove deprecated fields once no writers remain.
|
|
|
|
|
|
|
|
|
|
## Minimal State Model
|
|
|
|
|
- `item_status`: `pending`, `processing`, `po_generated`, `ready_delivery`, `delivered`, `cancelled`
|
|
|
|
|
- `drv_status`: `unassigned`, `assigned`, `en_route`, `collected`, `failed`
|
|
|
|
|
|
2026-06-11 18:30:02 +00:00
|
|
|
Keep item lifecycle and driver lifecycle separate to avoid status collisions.
|