docs(quotes): add approve-and-send-from-list design spec
Lifts the detail-screen "Approve & send email" button behaviour onto the pending-approvals list rows. Replaces the list's existing two-step approve + drill-in flow with the existing combined review-approve endpoint behind the same SendQuoteModal the detail page already uses. Out of scope: "approve without send" toggle in the modal, inline markup-edit on a row. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Dave
parent
721b0f6bf7
commit
d87a007be3
1 changed files with 152 additions and 0 deletions
|
|
@ -0,0 +1,152 @@
|
||||||
|
# Approve & Send from Pending-Approvals List — design spec
|
||||||
|
|
||||||
|
**Status:** Approved (verbal, 2026-08-27; awaiting written-spec review)
|
||||||
|
**Date:** 2026-08-27
|
||||||
|
**Owner:** Dave
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
The Pending Approvals list page (`/quotes/approvals`) currently exposes "Approve" and "Approve partial" buttons per row that **stop short of sending** — they only flip the status to `approved` and tell the operator via toast to drill in to send. The detail-screen already has a one-step "Approve & send email" button that goes straight through `review-approve`. Lift that detail-screen behaviour onto the list rows. Operator clicks the row button once, the same `SendQuoteModal` opens, they confirm, and the email goes.
|
||||||
|
|
||||||
|
This trims one round-trip for the common case where the rep already trusts the quote.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Motivation
|
||||||
|
|
||||||
|
Today, on the approvals list, the operator must:
|
||||||
|
1. Click "Approve" on the row → row leaves the list with status `approved`, toast says "proceed to send from the quote page"
|
||||||
|
2. Drill into the quote detail (now under `/quotes/[id]` or the orders page) and send separately
|
||||||
|
|
||||||
|
Most of the time the rep is ready to approve *and* send at the same moment. The detail page already supports this via "Approve & send email". The list should match.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decisions log
|
||||||
|
|
||||||
|
Resolved during brainstorming on 2026-08-27:
|
||||||
|
|
||||||
|
| Question | Decision |
|
||||||
|
|---|---|
|
||||||
|
| Which detail-screen button gets lifted? | The "Approve & send email" button — the one that opens `SendQuoteModal` and submits via `review-approve action: "approve"`. |
|
||||||
|
| Replace or supplement the existing list button? | Replace. "We never just approve it" — the standalone approve path on the list is no longer useful once the combined path exists. |
|
||||||
|
| Same treatment for partial rows? | Yes. The current "Approve partial" button also gets the combined treatment. `review-approve` already handles `partial_approval_pending` (flips to `partial_approved → sending → emailed`). The narrower `/partial-approve` endpoint is no longer called from the list. |
|
||||||
|
| Modal opens over list or replaces list? | Opens over the list (same modal component, no UI to clear it). Same affordance as today on the detail page. |
|
||||||
|
| Inline markup-edit affordance from list row? | Out of scope for v1. If the rep needs to nudge markup, they drill in (existing escape hatch preserved). |
|
||||||
|
| "Approve without send" toggle? | Deferred. Reuses the future `SendQuoteModal` toggle mentioned in conversation; not in this commit. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UI
|
||||||
|
|
||||||
|
### Files touched
|
||||||
|
|
||||||
|
- `src/app/(app)/quotes/approvals/page.tsx` — only file.
|
||||||
|
|
||||||
|
### Per-row button changes
|
||||||
|
|
||||||
|
| Row state | Current button | New button |
|
||||||
|
|---|---|---|
|
||||||
|
| `approval_pending` | "Approve" → `pb.collection.update` direct write | "Approve & send" → opens `SendQuoteModal`, then calls `review-approve action: "approve"` |
|
||||||
|
| `partial_approval_pending` | "Approve partial" → POST `/partial-approve` | "Approve & send" → opens `SendQuoteModal`, then calls `review-approve action: "approve"` (server handles partials) |
|
||||||
|
| Both | "Reject" → existing handler | "Reject" (unchanged) |
|
||||||
|
|
||||||
|
Button style matches the detail page's existing "Approve & send email" button — same label, same visual treatment (secondary button group typically). The detail page already passes `submitLabel="Approve & send"` to `SendQuoteModal`; the list passes the same.
|
||||||
|
|
||||||
|
### `SendQuoteModal` integration
|
||||||
|
|
||||||
|
The modal is reused unchanged. The list page needs:
|
||||||
|
- A piece of state per row: `openSendModalForRowId: string | null` (or a Map keyed by row id)
|
||||||
|
- A single `sendApprove` callback lifted to page level (same shape as the detail page's `sendApprove`), callable per row
|
||||||
|
- On success: refresh the list (`router.refresh()` or local state update), toast same as detail page
|
||||||
|
|
||||||
|
### Toast behaviour
|
||||||
|
|
||||||
|
Same as detail page — branched:
|
||||||
|
- Full approve success → `"Approved — email sent to the customer."`
|
||||||
|
- Partial approve success → `"Partial approved — email sent for the priced items."`
|
||||||
|
- Mail send failure (422) → `"Saved — but email send failed: <msg>. Retry from the quote page."`
|
||||||
|
- Race / already-approved (422 invalid_status) → parse `{error}` body, surface `"This quote was already actioned — refreshing."` (then refresh the list)
|
||||||
|
|
||||||
|
The existing toasts `"Quote approved — proceed to send from the quote page"` and `"<N> items marked approved — open the quote to send the email."` are removed; they describe the old broken two-step flow.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API surface
|
||||||
|
|
||||||
|
### Reused (no new endpoints)
|
||||||
|
|
||||||
|
- `POST /api/v1/quotes/[id]/review-approve` with `action: "approve"`, optional `email{}`, optional `itemChanges[]` — already atomically approves and sends. Already handles full + partial quotes. Already rejects on `placeholder_customer`, `invalid_status`, mail-fail. The detail page calls this; the list page will too.
|
||||||
|
|
||||||
|
### No longer called from the list
|
||||||
|
|
||||||
|
- `POST /api/v1/quotes/[id]/partial-approve` — the list's "Approve partial" button used this; replaced by `review-approve`. The endpoint stays (used elsewhere in the app).
|
||||||
|
- Direct `pb.collection("quotes").update(...)` writes from the list — replaced by `review-approve`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error handling
|
||||||
|
|
||||||
|
| Failure | Behaviour |
|
||||||
|
|---|---|
|
||||||
|
| `placeholder_customer` (422) | Modal disables the submit button on render (matches detail's `customerIsPlaceholder` gate). Operator drills in to fix. |
|
||||||
|
| `invalid_status` (422) — already approved by another rep, race | Surface toast: `"This quote was already actioned — refreshing."` then `router.refresh()`. |
|
||||||
|
| Mail send failure (422 — email sub-object) | Toast: `"Saved — but email send failed: <msg>. Retry from the quote page."` Row stays in list with `mail_failed` status (server flips it). |
|
||||||
|
| Network/5xx | Toast: `"Couldn't approve. Try again."` Keep modal open. |
|
||||||
|
| `customer` not found / record deleted (404) | Toast: `"This quote no longer exists. Refreshing."` then `router.refresh()`. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
Component-level tests for the list page (`src/app/(app)/quotes/approvals/page.test.tsx` if it exists; if not, create a focused spec file that does NOT replicate the entire list page render — only exercises the button + modal interaction).
|
||||||
|
|
||||||
|
| # | Test |
|
||||||
|
|---|---|
|
||||||
|
| 1 | Clicking "Approve & send" on an `approval_pending` row opens `SendQuoteModal` with the quote pre-loaded |
|
||||||
|
| 2 | Submitting the modal calls `POST /api/v1/quotes/[id]/review-approve` with `action: "approve"` and an `email{}` payload taken from the modal |
|
||||||
|
| 3 | On 200, the list removes the row (filter no longer matches) and shows the success toast |
|
||||||
|
| 4 | On 422 `invalid_status`, the list refreshes and shows a toast |
|
||||||
|
| 5 | On 422 mail-failed, the toast reads "Saved — but email send failed..." |
|
||||||
|
| 6 | Clicking "Approve & send" on a `partial_approval_pending` row invokes the same endpoint and shows the partial-success toast |
|
||||||
|
|
||||||
|
`SendQuoteModal` itself is not re-tested — it's the existing component, unchanged.
|
||||||
|
|
||||||
|
`review-approve` endpoint tests already cover the success / placeholder / mail-fail branches in `src/app/api/v1/quotes/[id]/review-approve/route.test.ts` — re-run those after the merge to confirm no regression.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Out of scope (deferred)
|
||||||
|
|
||||||
|
- "Approve without send" checkbox on `SendQuoteModal` — Dave mentioned this as a future toggle. Adds a payload flag and a separate code path on `review-approve`. Not in this commit.
|
||||||
|
- Inline markup-edit affordance on a list row — would require a new modal/dialog. Punt.
|
||||||
|
- Removing the standalone "Approve and don't send" path from the entire app (wherever else the operator "approves without sending" is a separate concern).
|
||||||
|
- Visual indicator on a list row showing whether the rep already nudged markup on the detail page (i.e. a hint that the quote is "trustworthy" for one-click). Deferrable polish.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rollout
|
||||||
|
|
||||||
|
Single deploy:
|
||||||
|
|
||||||
|
1. Replace the two handler blocks and two button labels in `src/app/(app)/quotes/approvals/page.tsx`.
|
||||||
|
2. Manual smoke: queue a quote, click "Approve & send" on the list, confirm modal opens with the right fields, submit, verify email goes out, verify row disappears from the list.
|
||||||
|
3. Same smoke for partial row.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File structure
|
||||||
|
|
||||||
|
| File | Touched | Responsibility |
|
||||||
|
|---|---|---|
|
||||||
|
| `src/app/(app)/quotes/approvals/page.tsx` | Yes — only file modified | Replace per-row handlers + button labels; lift `sendApprove`; render modal at page level keyed by row id |
|
||||||
|
| `src/components/quotes/send-quote-modal.tsx` | No | Reused unchanged |
|
||||||
|
| `src/app/api/v1/quotes/[id]/review-approve/route.ts` | No | Endpoint already supports the call |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Open questions
|
||||||
|
|
||||||
|
None at design time.
|
||||||
Loading…
Reference in a new issue