Issues to Resolve — One RO, All, Unattached

Issues to Resolve — flat list routes — Technical Spec

app/ro.py. One template, ro_issues.html, screen key ro_issues, serves three GET routes that differ only in the filter they add and the title_suffix / chip_url they pass. The summary screen at /ro/issues is documented separately (help/tech ro_issues_summary).

Routes

All three GETs take status (default Open), issue_type, search. _query_url() builds chip links that merge the current filters with one override, so chips compose. All three pass back_url="/ro/issues", back_label="Issues Summary".

{order_no:int} is declared after /all and /unattached, so the literal paths win.

Query

query_issues(conn, status, issue_type, search, order_no, unattached, limit=LIST_LIMIT) against ro_issue:

• status unless All; issue_type exact; search ILIKE across title, sku, source_ref, detail.
• order_no and unattached are mutually exclusive by construction (no caller passes both).
• order by created_at asc limit 1000, plus a separate count(*) for the total.
• Adds computed age_days = now()::date - created_at::date; the template styles >= 7 red.

issue_status_counts(conn) is global (no filters at all) — the N open badge counts every Open issue in the system, even on a per-order list. Intentional but easy to misread.

ISSUE_TYPES: SKU not in QB, no qty, unmatched job, duplicate line, header only, unmatched NONINV refresh, unlinked QB PO. ISSUE_STATUSES: Open / Resolved / Ignored / All.

Write path — apply_issue_action()

Single chokepoint for both the row action and bulk. Order of operations:

1. require_write(user) (level3 rejected) — the routes themselves first call _ro_write(user) → require_action(user, "ro_write"), default admin + level1.
2. action must be resolve or ignore; ignore is rejected for types in NO_IGNORE = {"no qty"}; an issue not in status Open is rejected 400.
3. Typed resolves, from RESOLVE_INPUT = {"SKU not in QB": "sku", "no qty": "qty"}:

• the target line is found by _issue_line() — line_key first, else order_no + coalesce(src_ref, sku) and only when that matches exactly one row; no line → 400 "resolve it on the RO Maintenance screen instead".
• sku: value required, must exist in IM2 items (_sku_exists(), cross-database via im2_db()); sets ro_detail.line_type='INV', sku, adj_by, adj_at; writes a ro_audit row issue_resolve_sku; also stamps ro_issue.sku.
• qty: must parse as float and be > 0; sets ro_detail.qty_source (+ adj_by, adj_at); ro_audit row issue_resolve_qty; stamps ro_issue.qty.

1. ro_issue.status/resolved_at/resolved_by updated.
2. One ro_audit row issue_resolve / issue_ignore. ro_audit has no issue column, so the id is carried in note as a parseable prefix: issue_id=<id>; resolved as … / issue_id=<id>; ignored: ….
3. sync_line_hold(cur, line_key, operator) — if the line has no Open issue left, ro_detail.line_status HOLD → NULL plus a ro_audit hold_clear row. Cancelled / Closed Short are left alone.

Bulk calls the same function per id with no value, collecting HTTPException.detail per failure into errors and returning {ok, changed, errors}. All ids share one ro_db() transaction, committed once when the request ends, so a rejected id (validation raises before any write) does not undo the ones that succeeded.

Client behaviour (ro_issues.html)

RESOLVE_INPUT and NO_IGNORE are duplicated in JS to drive the prompt()s and to hide the Ignore button for no qty rows; the server enforces the same rules, so the JS copy is cosmetic. After a successful action the row is removed from the DOM and the counts decremented only when the active status filter is Open; otherwise location.reload().

The Help button on this template links to /docs/help/ro_issues_summary. See Known limits.

Known limits / gaps

• Help button points at the summary guide, not this one. ro_issues.html hard-codes /docs/help/ro_issues_summary; it should be /docs/help/ro_issues. Patch noted in group5_helplinks.md. [found 2026-09-06]
• The open badge is global, not scoped to the current list (see above).
• The JS duplicates the server's typed-resolve rules — change both together.
• No ro_view gate on the GETs (Depends(current_user) only); see tech ro_inquiry.

Permission gate (added 2026-09-06)

Every route in ro.py now depends on ro_user() instead of current_user directly. ro_user() calls require_action(user, "ro_view"), so revoking View Requirements Orders screens on the Field Permissions screen actually blocks the RO screens (403) — before this the key existed and nothing read it. All four roles hold ro_view by default, so nothing changed for anyone until someone revokes it. Pick and Rush screens live in ro_pick.py / rush.py and keep their own ro_write / rush_* checks.

Use Surplus + UOM (2026-09-07)

apply_issue_action() takes a third action, surplus, alongside resolve/ignore. It is refused unless the RO line is NONINV. It sets ro_detail.line_type = 'SURPLUS', stamps adj_note, writes two ro_audit rows (line change + issue status) and calls sync_line_hold() like the other paths.

po._demand_lines() excludes line_type = 'SURPLUS', so a surplus line never reaches the workbench or a buy list. Surplus lines are not yet on the pick screens — ro_pick still selects line_type = 'INV' only; the "SURPLUS row on the pick list" work is separate.

query_issues() is now aliased (ro_issue i) and left-joins ro_detail on line_key to bring uom and line_type onto the row. Every filter is i.-qualified — the join made sku and order_no ambiguous.

Quantity-required issues are decided by the line, not the label (2026-09-07)

The old rule was NO_IGNORE = {"no qty"} keyed on issue_type. The importer files the same defect under several labels (no qty, Qty problem for an unparseable source qty, sometimes Review), so a SKU line with qty 0 could be resolved with no quantity and Ignore was still offered. Dave, 2026-09-07: "SKU items must have a qty, no ignore option."

ro._needs_qty(issue, line) is now the single test: an INV line (or any line with a SKU) whose ro_detail.qty_source is null or <= 0 requires a quantity. It gates all three paths:

• query_issues() stamps needs_qty on every row (the query also returns line_qty / line_sku for it); the template renders data-needsqty and hides the Ignore button on those rows.
• apply_issue_action() refuses ignore (400) and forces needs = "qty" on resolve regardless of issue_type, so the API and the bulk actions are covered too, not just the buttons.
• Client-side, Resolve prompts for the qty and rejects <= 0 before the round trip.

RESOLVE_INPUT also gained "Qty problem": "qty" so the label-driven path agrees with the line-driven one.

Shared table sort (2026-09-07)

Column sorting is one implementation in templates/base.html (Dave, 2026-09-07: "all screens that have tables like this need sorts on the appropriate columns"). A table opts in with class="sorttable"; every thead th becomes sortable except those with class="nosort"/class="toggle", an empty heading, or a checkbox in the heading. Client-side only, over the rows already rendered. Details: tech/table_sorting.md.