Userflows
End-to-end manual-test playbooks, one MD per flow, for both Spade products. Each playbook is self-contained: it lists the actor, prerequisites (seed data references), step-by-step click path, the API contracts it exercises, and the DB / mailpit / S3 verifications you should expect at every step.
Use these whenever you are:
- onboarding to the codebase and want to walk a single feature without reading the whole testing guide
- writing or reviewing an integration test and need a canonical trace
- triaging a bug — match the failure to a flow and follow the verification points
- demoing a specific capability to a stakeholder
One-shot setup of every dependency the playbooks expect:
_shared/00-environment-setup.md. Run that once per machine; everything else assumes it.
Source-of-truth SOPs
The flows are derived directly from the SOPs and trace each numbered step back to a section anchor:
- Payroll —
docs/sop/Payroll_Processing.md - Bookkeeping —
docs/sop/SOP_AI_Bookkeeping_Automation.md
If a playbook diverges from the SOP, the playbook is wrong — file a ticket against the playbook, not the SOP.
Payroll
Anchor client: ACME (clientCode: ACME) — already seeded with a closed 2026-03 prior cycle and an open 2026-04 INTAKE_IN_PROGRESS cycle. GLOBEX is used for the approval-side flow because it is seeded mid-CLIENT_REVIEW.
| # | Flow | SOP step | File |
|---|---|---|---|
| P-01 | Initiate cycle (request data) | §6 / Step 1.0 (S0 → S1) | payroll/01-initiate-cycle.md |
| P-02 | Client intake — Yes-changes path | §6 / Step 2.0 (S1 → S4) | payroll/02-client-intake-changes.md |
| P-03 | Client intake — Zero-change fast path | §6 / Step 2.0 (one-click) | payroll/03-zero-change-fast-path.md |
| P-04 | Validation & completeness | §6 / Step 3.0 (S4 → S7) | payroll/04-validation.md |
| P-05 | Request info from client (issue resolution loop) | §7 / Exception Handling | payroll/05-request-info-from-client.md |
| P-06 | Internal review & override approvals | §6 / Step 4.0 (S7 → S8) | payroll/06-internal-review.md |
| P-07 | Generate Infotech export | §6 / Step 5.0 (S8 → S10) | payroll/07-generate-export.md |
| P-08 | Upload payroll output (optional) | §6 / Step 6.0 | payroll/08-upload-output.md |
| P-09 | Request client approval | §6 / Step 6.0 | payroll/09-request-approval.md |
| P-10 | Client approval decision (approve / revision / query) | §6 / Step 6.0 (S10 → S14) | payroll/10-client-approval.md |
| P-11 | Finalize, close, archive | §6 / Step 7.0 (S14 → S16) | payroll/11-finalize-close.md |
| P-12 | Reminder escalation (day 2 / 5 / 7) | §6 / Step 2.0 (timeline) | payroll/12-reminder-escalation.md |
Walk down P-01 → P-11 in order for the end-to-end story.
Bookkeeping
Anchor client: ZENITH (clientCode: ZENITH) — bookkeeping-only, Xero platform, SGD base, materiality SGD 50. Seeded with a draft April 2026 batch (4 entries spanning every status × confidence combination) and a UOB statement with 1 EXACT + 2 PROPOSED + 3 UNRECONCILED matches.
| # | Flow | SOP step | File |
|---|---|---|---|
| B-01 | Onboard a new bookkeeping client (cold path) | §2 + §4 | bookkeeping/01-onboard-client.md |
| B-02 | Configure ingestion channels (WhatsApp / Google Drive) | §3 | bookkeeping/02-ingestion-channels.md |
| B-03 | Ingest a document — manual upload path | §3 + §4.1 | bookkeeping/03-ingest-document-manual.md |
| B-04 | Ingest a document — WhatsApp / folder paths | §3.2 + §3.3 | bookkeeping/04-ingest-document-channels.md |
| B-05 | Review a journal batch (approve / edit / reject / escalate) | §4.5 | bookkeeping/05-review-journal-batch.md |
| B-06 | Generate upload file (Xero / QBO / Zoho / Tally) | §4.4 | bookkeeping/06-generate-upload-file.md |
| B-07 | Upload bank statement & parse | §5.1 | bookkeeping/07-bank-statement.md |
| B-08 | Run reconciliation matcher | §5.2 | bookkeeping/08-reconciliation-run.md |
| B-09 | Confirm proposed matches | §5.2 | bookkeeping/09-confirm-matches.md |
| B-10 | Dispatch unreconciled items to client | §5.3.1 | bookkeeping/10-dispatch-unreconciled.md |
| B-11 | Client portal — respond to unreconciled items | §5.3.2 / §5.3.3 / §5.3.4 | bookkeeping/11-client-portal-unreconciled.md |
| B-12 | Reviewer exception queue (NO_SUPPORTING above materiality) | §5.3.4 + Exception Handling | bookkeeping/12-exception-queue.md |
| B-13 | Complete reconciliation & generate report | §5.4 | bookkeeping/13-complete-reconciliation.md |
| B-14 | Annual bookkeeping batch flow | §6 | bookkeeping/14-annual-bookkeeping.md |
| B-15 | Audit export (immutable trail) | §8 | bookkeeping/15-audit-export.md |
Walk down B-01 → B-15 in order for the end-to-end story.
Conventions used in every playbook
Each file follows the same shape so you can scan one and skim the rest:
# <flow id> · <flow title>
> SOP: <link + section>
> Actors: <Staff / Client roles>
> Pre-state: <required cycle / batch state>
> Post-state: <expected outcome>
## 0. Prerequisites
- Seed data references (which client, which IDs)
- Other flows that must have run first
## 1. Steps
- Numbered click path with API endpoint, request body shape, expected response
## 2. Verification
- DB rows / state transitions
- Mailpit subjects + recipients
- S3 / MinIO objects
- Audit log entries
## 3. Negative & edge cases
- Bad-state attempts, validation failures, idempotency checksWhen a flow has multiple branches (e.g. happy path vs. revision-requested), each branch lives under its own H2 in the same file.
Naming
- Roles use SOP terminology (CR / PE / POL for payroll, Reviewer / Senior Accountant for bookkeeping) but cross-reference the codebase role enum (
PAYROLL_EXECUTIVE,BOOKKEEPER, etc.) when calling out RBAC checks. - "Staff user" / "Ops user" for internal actors. "Client user" / "Client contact" for external actors. Never "internal user".
- All dates are absolute (
2026-04-25), never relative.