From bbfe20ec2d09201d4c1eae03580df528c5d76af0 Mon Sep 17 00:00:00 2001 From: SJCoetz Date: Thu, 6 Aug 2026 23:29:55 +0200 Subject: [PATCH] docs: register stock_purchases.add_attachment in feature backlog + API reference Co-authored-by: Orca --- docs/AGENT_INSTRUCTIONS.md | 9 ++++++++- docs/api-mcp-layer.md | 18 +++++++++++++++++- src/app/api/mcp/FEATURE-REQUESTS.md | 8 +++++++- 3 files changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/AGENT_INSTRUCTIONS.md b/docs/AGENT_INSTRUCTIONS.md index 4b87462..e914a6a 100644 --- a/docs/AGENT_INSTRUCTIONS.md +++ b/docs/AGENT_INSTRUCTIONS.md @@ -124,7 +124,14 @@ specific** tool that fits the task. | `collection_pool.list` | Inspect what drivers need to collect. | | `order_items.update_status` | Move an item through the operational pipeline. | -### 4.4 CRM maintenance +### 4.4 Stock purchase + PO attachments + +| Tool | Use it for | +| --- | --- | +| `purchase_orders.add_attachment` | Attach a supplier quote PDF or proof-of-delivery to a PO (base64, ≤25 MB). | +| `stock_purchases.add_attachment` | Attach a supplier invoice, packing slip, or damaged-stock photo to a stock purchase (base64, ≤25 MB). Appends to `additional_attachments`; does NOT touch the versioned-PDF `documents` ledger. | + +### 4.5 CRM maintenance | Tool | Use it for | | --- | --- | diff --git a/docs/api-mcp-layer.md b/docs/api-mcp-layer.md index faf7085..bb1fda9 100644 --- a/docs/api-mcp-layer.md +++ b/docs/api-mcp-layer.md @@ -141,8 +141,17 @@ noted. Pagination defaults to `page=1`, `perPage=50` where relevant. | `GET` | `/api/v1/purchase-orders/{id}/send-email/outcome` | — | Outcome of last send. | | `GET` | `/api/v1/purchase-orders/{id}/pdf` | — | Render PO PDF. | | `GET` | `/api/v1/purchase-orders/stale` | `?days=...` | List POs untouched for N days. | +| `POST` | `/api/v1/purchase-orders/{id}/attachments/upload` | `multipart/form-data` field `file` | Append a free-form attachment to `additional_attachments`. Max 25 MB. | +| `DELETE` | `/api/v1/purchase-orders/{id}/attachments/{filename}` | — | Remove a single additional-attachment token. | -### 2.12 Users / file proxy +### 2.12 Stock purchases + +| Method | Path | Body | Notes | +| --- | --- | --- | --- | +| `POST` | `/api/v1/stock-purchases/{id}/attachments/upload` | `multipart/form-data` field `file` | Append a free-form attachment (supplier invoice, packing slip) to `stock_purchases.additional_attachments`. Max 25 MB. | +| `DELETE` | `/api/v1/stock-purchases/{id}/attachments/{filename}` | — | Remove a single additional-attachment token. | + +### 2.13 Users / file proxy | Method | Path | Body | Notes | | --- | --- | --- | --- | @@ -189,6 +198,13 @@ JSON-RPC over HTTP. Same `Authorization` bearer as `/api/v1/*`. | `customers.list` / `.get` / `.create` / `.update` / `.delete` | Full CRUD. `company` / `rep` accept id or name. | | `suppliers.list` / `.get` / `.create` / `.update` / `.delete` | Full CRUD. | +#### Stock purchases / POs (attachments) + +| Tool | Purpose | +| --- | --- | +| `purchase_orders.add_attachment` | Upload one free-form attachment to a PO (base64, ≤25 MB). | +| `stock_purchases.add_attachment` | Upload one free-form attachment (supplier invoice, packing slip, photo of damaged stock) to a stock purchase (base64, ≤25 MB). Appends to `additional_attachments`; does NOT touch the versioned-PDF `documents` ledger. | + ### 3.3 Tool input shapes (condensed) `quotes.create_from_email` (required: `subject`): diff --git a/src/app/api/mcp/FEATURE-REQUESTS.md b/src/app/api/mcp/FEATURE-REQUESTS.md index 895cdce..62b851e 100644 --- a/src/app/api/mcp/FEATURE-REQUESTS.md +++ b/src/app/api/mcp/FEATURE-REQUESTS.md @@ -95,6 +95,12 @@ When one ships, move it to **Implemented** with a one-line commit/PR reference. - **Schema needs:** none — the `stock_purchase` + `stock_purchase_item` collections already exist - **Open questions:** which PDF format(s) does the user want supported? Many SA suppliers send bespoke PO PDFs — a generic parser would need supplier-specific extraction rules. Probably needs an LLM-driven extraction step rather than layout heuristics. Worth scoping before implementation. +### Stock purchases: paperclip badge on list table +- **Surfaced:** 2026-08-06 — surfaced during the attachments-card PR (UI ships the detail-page affordance but the list table still shows no document indicator) +- **Severity:** nice-to-have +- **Suggested tool:** add a `count_additional_attachments` field to `stock_purchases.list` (or a separate `/api/v1/stock-purchases/attachment-counts` endpoint mirroring `/api/v1/sprint/attachment-counts`), render the sprint-style `` chip in `StockOrdersTable` per row +- **Schema needs:** none — derived from `additional_attachments.length` + ### Drivers: no MCP visibility or assignment - **Surfaced:** 2026-08-06 — "can you see the driver stops and assign stops to drivers?" - **Workaround:** "driver" data lives only as three fields on `order_items` (`drv_id`, `drv_assigned_at`, `drv_collected_at`). There is no separate `drivers` collection, no MCP tool to list drivers, no tool to see today's stops for one driver, no tool to bulk-assign stops to a driver. Operators can call `orders.list` and manually click through. Effectively the driver flow is invisible to the agent. @@ -121,4 +127,4 @@ These came up but need a human answer before code changes: ## Implemented -_(move entries here with a PR / commit link when they ship)_ +- 2026-08-06 — `stock_purchases.add_attachment` shipped (commits `f89bbb3`, `dd57d29`). Adds a sibling to `purchase_orders.additional_attachments` plus the matching REST upload/delete routes and a UI card on `/stock-orders/[id]`. PB schema: new `stock_purchases.additional_attachments` file field (multi, maxSelect 10, any MIME).