Background Job — QuickBooks Posting Engine (picks → QB)

(background process — no screen)

Technical Spec Ver 1 Updated 2026-09-06 Matches the live screen

Background Job — QuickBooks Posting Engine

Turns a completed pick/issue session into QuickBooks documents. Code: app/ro_post.py (generated from skills/requirements_orders/scripts/post_pick_to_qb.py, verified live against production QuickBooks 2026-09-02).

Trigger / schedule

Not scheduled — it is request-driven. There is no timer, cron or queue. Entry points in app/ro_pick.py:

POST /ro/picks/{pick_id}/post → picks_post_one → _do_post
POST /ro/picks/post with {"pick_ids": [...]} → picks_post_bulk → _do_post per id (errors collected, batch never crashes)
both call post_pick_to_qb(pick_id) → ro_post.post()

Global lockout: ro_pick.POSTING_ENABLED = False ("Posting is not allowed during test." — Dave, 2026-09-02). Until that flag is flipped, every post attempt returns 403/ok:false and no QuickBooks document is created. Permission is additionally gated by _require_post(user).

Inputs

ro_pick (session header, must be status='OPEN', locked with FOR UPDATE OF p), ro_pick_line, joined to ro_detail on line_key for qty_source / line_type, and ro_header (LEFT JOIN — a no-RO direct issue has order_no IS NULL and carries its own customer + class on the pick row, which win).
im2.items.qb_item_id for the SKU → QB item map (separate connection on IM2_DSN).
Connections: RO_DSN (RealDictCursor) and IM2_DSN.

Rules

Pick documents post at $0 — quantity carries the inventory movement, UnitPrice = 0.
Positive picked qty → Invoice line; negative → CreditMemo line. A mixed pick creates two QB documents (Option A, Dave 2026-09-02).
Explicit zero / zeroed → no QB line; writes ro_detail.qty_adj = -qty_source (plus qty_source_at_adj, adj_by, adj_at, adj_note). Never touches qty_required or qty_source.
SURPLUS lines consume the RO line and create no QB document, only an ro_txn row.
qty_picked IS NULL = untouched line, ignored.
Class is mandatory. COALESCE(pick.class_ref, header.class_ref), else derived from ro_type (service 1202540 / residential 1202519 / commercial 1202520). Service ROs with no customer are forced to QB customer SA:Admin (15326) with the Service class. A no-RO issue with no class raises PostError.
Customer resolution is exact match only — FullyQualifiedName then DisplayName; anything other than exactly one hit raises PostError rather than guessing the job.
Any SKU with no qb_item_id aborts the whole post ("No QB item id for SKUs: …").

Tables written

Table	Change
`ro_txn`	one row per posted line: `pick_id, order_no, line_key, sku, direction ('Issue'/'Return'), qty, qb_doc_type, qb_doc_id, qb_doc_number, txn_date, operator, source='Workbench'`. Surplus rows get `qb_doc_type = NULL`.
`ro_pick`	on success `status='POSTED'`, `posted_by`, `posted_at`, `updated_at`, `qb_invoice_id/_number`, `qb_credit_id/_number`. On failure `_do_post` writes `post_error` in a separate small transaction.
`ro_detail`	zero-adjustment columns for explicitly zeroed lines.
`ro_header`	back-fills `qb_customer_id`, `qb_customer_name`, `class_ref` when they were resolved during the post.

External calls

QuickBooks Online via app/qb.py (QBO, direct Intuit API, credentials in /opt/im2/env): POST Invoice and/or POST CreditMemo. dry_run=True returns the line counts and makes no QB call.

Failure behaviour / idempotency

All DB work happens inside one with conn: transaction; the QB POST happens inside it too, so a DB failure after a successful QB post would roll back ro_txn while the QB document remains — the known hole in this design. There is no compensating delete.
PostError (bad class, ambiguous customer, unmapped SKU) is raised before any QB call.
Not idempotent by itself; re-posting is prevented by state: the session must be OPEN, and _do_post rejects POSTED (400 "already posted") and VOID sessions. A failed attempt leaves the session OPEN with post_error set — that is the error state (there is no post_status column) — and it can be retried from the Pick Review screen.
Bulk posting reports {posted, failed, results, errors} and never aborts on one failure.

Logs to look at

ro_pick.post_error (truncated to 400 chars) — first place to look.
journalctl -u im2 on the droplet for the uvicorn traceback.
ro_txn rows joined to ro_pick to confirm what actually reached QuickBooks.

Known limits

Posting is disabled (POSTING_ENABLED = False) — nothing reaches QB today.
No automatic reversal/void path: a posted document must be corrected in QuickBooks.
Customer match is exact-string only, so a QB job renamed after the RO was created will fail the post until the RO's job_name or the QB job is corrected.
Requires both RO_DSN and IM2_DSN in the environment; the SKU→QB item map lives in a different database than the pick data.