JIRA

In-App Support — Jira Plan

Pairs with: PRD.md Epic / story IDs use the format IAS-Exx (epic) / IAS-Snn (story) / IAS-Tnn (subtask). Final IDs will be assigned in Jira.

---

Components & labels

Components

• app:rechaj-swap — mobile swap-app changes
• app:atlas — backoffice changes
• svc:support-case — support case service (new)
• svc:audit-log — audit log service (extension)
• svc:notification — push + in-app notification (extension)
• svc:rbac — role-based access (new / extension)
• infra:storage — photo / voice attachment storage

Labels (apply liberally for filtering)

• area:station-assignment
• area:wallet
• area:battery
• area:other
• feature:park-a-swap
• feature:message-thread
• feature:auto-population
• feature:feedback-rating
• feature:rbac
• risk:wrong-rider — anything touching wallet credits or case-payload binding
• release:p0 — required for GA
• release:p1 — required for ops sign-off
• release:p2 — nice-to-have, may slip

---

Epic breakdown

ID	Epic	One-liner	Success criterion
IAS-E1	Issue data model & case service	Build the Issue / IssuePayload / IssueMessage / IssueAttachment / ParkedSwap model + state machine + APIs.	All 11 issue types + Other can be created, routed, parked, escalated, resolved via API; integration tests pass for the wrong-rider hard rule.
IAS-E2	Officer roles & RBAC	Multi-officer-type model + queue scoping + escalation handoff.	A multi-role user sees scoped queues; escalation moves ownership atomically; RBAC enforced at the action layer.
IAS-E3	Atlas resolution workspace	Per-issue-type resolution screens with auto-populated payload + one-click actions.	Every resolution form in Atlas binds to a case ID and rejects mismatched identifiers. No free-text rider/wallet/battery inputs.
IAS-E4	Rechaj Swap report-side flows	Per-issue-type capture sheets + the consolidated “How is the rider paying?” entry point + the new “Rider had previously paid today” sub-flow.	All 11 issue types + Other can be reported end-to-end on staging; submissions create cases with full payload.
IAS-E5	Park-a-Swap	Multiple-parallel parking + resume on push + linked-issue thread integration.	A manager can park ≥3 swaps and resume each independently with no state collision.
IAS-E6	Message thread + retake loop	Per-issue bi-directional thread + photo-version chips + send-back roundtrip.	Send-back → retake → version chip lands in Atlas in <30s end-to-end on staging.
IAS-E7	Feedback & Rating	Post-swap feedback module + Atlas Manager feedback screen + dashboard snippet.	Every completed swap can submit feedback; Atlas feed updates within 30s.
IAS-E8	Audit log & PM instrumentation	Immutable audit trail for every resolution / escalation / message + PM dashboard surfaces.	Every action of interest writes an audit entry; PM dashboard queries return per-type / per-station / per-officer rollups.

---

Stories per epic

IAS-E1 · Issue data model & case service

ID	Story	AC
IAS-S101	Define and migrate the Issue / IssuePayload / IssueMessage / IssueAttachment / ParkedSwap / SwapFeedback schemas.	Schema review + migration applied to staging; rollback tested.
IAS-S102	Define OfficerType / BusinessUnit / OfficerRole / ResolutionAction reference data; seed the 5 officer types + 2 BUs (Swap, Facility) with Energy as a config-only entry.	Reference seed loaded; querying officer types returns the 5 expected rows.
IAS-S103	POST /v1/cases — create a case with full payload from Rechaj Swap.	Returns case ID; validates against issue-type-specific required fields.
IAS-S104	POST /v1/cases/{id}/messages — append a thread message.	Both manager and officer auth tokens accepted with the right from_side.
IAS-S105	POST /v1/cases/{id}/attachments — upload a photo / voice.	Returns version number scoped to (case_id, kind).
IAS-S106	POST /v1/cases/{id}/actions/{action_type} — execute a typed resolution action against the loaded payload.	Body-supplied identifiers are rejected when they conflict with the payload; idempotency enforced on (case_id, action_type, request_key).
IAS-S107	POST /v1/cases/{id}/escalate — switch owning_officer_type atomically.	Original officer retains read; new officer can act. Audit entry written.
IAS-S108	POST /v1/cases/{id}/park and POST /v1/cases/{id}/resume — link to a ParkedSwap record.	One manager can hold multiple ParkedSwap rows; resume returns the parked-at step.
IAS-S109	Server-side overdraft eligibility guardrail: POST /v1/wallet/overdraft rejects unless the linked case type is in the wallet-overdraft-eligible set AND the case’s rider ID matches the request’s rider ID.	Contract test: case A overdraft with rider B → 400 with code: wrong_rider.
IAS-S110	Outstanding-overdraft flag on rider wallet: swap_eligible: false + originating case pointer, surfaced on GET /v1/wallet/balance.	Powers issue 2.2.

IAS-E2 · Officer roles & RBAC

ID	Story	AC
IAS-S201	RBAC middleware: every /v1/cases/{id}/actions/* and /v1/cases/{id}/escalate call checks the caller’s OfficerRole against ResolutionAction.requires_officer_type[].	Unauthorized officer → 403.
IAS-S202	Queue endpoint: GET /v1/queues/{officer_type} returns cases owned by that type only.	Officer-type filter is enforced server-side; a Swap Support user querying the Engineering queue → 403.
IAS-S203	Atlas sidebar shows one queue entry per officer type the user holds + a merged “All open” entry.	Multi-role user with Swap Support + Payment sees both queues + merged. (Pending Q10 resolution in PRD.)
IAS-S204	Re-route ownership on escalation: change owning_officer_type server-side, broadcast queue refresh to both old and new queues.	New queue surface gets the case within 5s; old queue removes it; original officer still loads case via direct link in read-only.
IAS-S205	Add Energy + Facility officer-type config rows without code changes; verify queue routing accepts them.	Config-only PR adds rows; integration test confirms no other type is affected.

IAS-E3 · Atlas resolution workspace

ID	Story	AC
IAS-S301	Auto-populated resolution shell: a reusable layout (issue main column · sticky resolution card · case history block) that binds all identifiers from IssuePayload.	Component-test snapshot confirms no free-text identifier inputs on the shell itself.
IAS-S302	screen-issue-temp-swap — 1.1 resolution flow with Approve / Deny + reason.	Auto-fills rider, primary station, current station, temp-swap-7d count.
IAS-S303	screen-issue-perm-change — 1.2 with Approve immediately / scheduled / Deny.	Scheduled approvals respect the effective date.
IAS-S304	screen-issue-funding-pending — 2.1 with the radio reference/session-ID input + inline “Receipt unreadable?” send-back block + eligibility checkbox + Issue overdraft.	Resolve disabled until radio + reference value + eligibility checkbox all set.
IAS-S305	screen-issue-overdraft-pending — 2.2 with Lift ban / Send back.	Lift writes swap_eligible: true; verifies link to originating 2.1 case.
IAS-S306	screen-issue-phantom-fee (new) — 2.4 with read-only wallet history + Escalate to Engineering.	Resolve disabled; Escalate enabled; route to Engineering queue.
IAS-S307	screen-issue-acct-invalid (new) — 2.5 with photo preview + Escalate to Engineering.	Escalation routes to Engineering queue.
IAS-S308	screen-issue-battery-release — 3.1 with evidence preview + version chips + thread + Release & reassign + Send back.	One-click reassignment atomically detaches + attaches.
IAS-S309	screen-issue-battery-claim — 3.2 single-battery + extend the existing screen-issue-battery-transfer for multi-battery submissions.	Each battery in a multi-submission resolves independently.
IAS-S310	screen-issue-battery-attribute — 3.3 with evidence preview + thread + Assign serial + Send back.	Resolution writes inventory assignment atomically.
IAS-S311	screen-issue-battery-mismatch — 3.4 with evidence preview + thread + Escalate to Inventory.	Escalation routes to Inventory queue.
IAS-S312	screen-issue-inventory-mismatch-resolve (Inventory Officer view) — manual inventory search + Issue corrected serial.	Issued serial pushes to Rechaj Swap; subsequent rescan validation in app.
IAS-S313	screen-triage-queue (new) — “Other” triage with re-route to typed queue / resolve in-thread / promote-to-formal-type-candidate.	Re-route changes the issue type + officer ownership; audit entry captures both.
IAS-S314	Retire screen-issue-mgr-transfer and screen-issue-deduction-fail from the active queue (subject to Q11 resolution).	If kept: tagged as debug-only and hidden from normal queue filters.

IAS-E4 · Rechaj Swap report-side flows

ID	Story	AC
IAS-S401	Wire all consolidated alert buttons + quick-request entries on the support log to the new POST /v1/cases endpoint.	Each entry produces a case of the correct type with the full payload.
IAS-S402	Persist the Wallet history button on every wallet-state surface (already on tricycle-detected; verify and add to any future wallet-display screens).	Visual regression test on all wallet-state combinations.
IAS-S403	“Rider had previously paid today” sub-flow (2.4): button + sheet-previously-paid + inline wallet-history snippet + Submit.	Submission creates a phantom-fee case; verifies Atlas screen receives full payload.
IAS-S404	Battery-transfer QR scan: real camera-overlay scanner (reticle, scan line, lock-on, commits the serial) for sheet-battery-transfer.	Tap → scanner opens → ~1.6s acquire → commits serial → overlay closes.
IAS-S405	Per-battery photo capture in sheet-battery-transfer, sheet-battery-release, sheet-battery-claim, sheet-battery-attribute, sheet-battery-mismatch.	Each submission carries a real attachment URI.
IAS-S406	sheet-overdraft-pending (2.2) — re-upload last unsettled payment receipt.	Photo is required; case payload links to the originating 2.1.
IAS-S407	sheet-acct-invalid (2.5) — provider chips (no “Other”), account number, screen-error photo.	Photo required; no “Other” provider option.
IAS-S408	sheet-station (1.1) and screen-perm-change-lookup (1.2) — reason chips (“Tell support…” placeholder on Other) + voice note + submission.	Submission routes to Swap Support queue with full context.
IAS-S409	sheet-support (“Other”) — category chips + description + optional photo + voice; routes to the triage queue.	Submission appears in screen-triage-queue.
IAS-S410	Manager-facing copy sweep: no “engineering” / “ops” / “float” anywhere user-facing; no internal case codes shown to managers.	Code grep + visual regression.
IAS-S411	Sheet back button + drag handle on every bottom sheet (already in support-cases-v3; verify on every new sheet).	Visual regression.

IAS-E5 · Park-a-Swap

ID	Story	AC
IAS-S501	Parked-swaps section on the home screen — list every parked swap with rider, plate, issue type, elapsed, status.	Sort: oldest first; count badge on home tab.
IAS-S502	Resume returns the manager to the exact parked-at step with resolution applied (or with the latest thread message visible).	Resume from a 2.1 case post-resolution shows the wallet-credit success state.
IAS-S503	Multiple parallel parked swaps: no state collision between concurrent parked swaps.	Two parked 3.1 cases against different riders both resume cleanly.
IAS-S504	Push notification on resolution + on new thread message that requires manager action (retake).	Deep-link to the parked swap, not the home screen.
IAS-S505	Parked-swap polling on wallet balance for 2.3 self-resolving path.	Polls every 30s; triggers resume push on balance >= daily_fee.

IAS-E6 · Message thread + retake loop

ID	Story	AC
IAS-S601	Full-page thread sheet in Rechaj Swap (sheet-support-thread with sheet-fullpage variant): renders messages, attached photos with thumbnail + tap-to-lightbox, retake CTA.	Photo thumbnails render real attachment URIs; lightbox opens full-size.
IAS-S602	Atlas thread-mini block inside the issue resolution shell: messages rendered with manager / officer side.	Real-time sync with Rechaj Swap (≤2s).
IAS-S603	Send-back round-trip: officer types reason in the inline “Receipt unreadable?” / “Photo unclear?” block → append officer message to thread → fire manager push → manager re-uploads → new attachment + thread message → version chip lands in Atlas.	End-to-end on staging in <30s wall-clock.
IAS-S604	Version-chip strip on Atlas evidence preview: chips per upload (v1, v2…) with current / rejected state; clicking a chip swaps the preview to that version.	Chip click does not lose officer’s typed input on the resolution form.
IAS-S605	Thread persistence after resolution: both sides can re-read; manager from the parked-swap entry; officer from the case detail link in audit.	Read-only post-resolution.

IAS-E7 · Feedback & Rating

ID	Story	AC
IAS-S701	Swap-complete feedback module in Rechaj Swap: stars + textarea + voice + photo + inline Submit. CTAs (Start another swap, Back to dashboard) remain visible without scrolling.	Visual regression on 390×844 with feedback module visible above the fold-equivalent.
IAS-S702	SwapFeedback create endpoint; idempotent on swap_id.	Re-submission for the same swap returns the existing record.
IAS-S703	screen-manager-feedback (Atlas, full screen): KPI tiles + filter pills + table + pagination. Reachable from sidebar + dashboard snippet.	Filter pills bind to URL params for shareable links.
IAS-S704	Dashboard snippet: “Manager feedback · last 24 hours” with “View all feedback →” → routes to the full screen.	Snippet refreshes every 60s.
IAS-S705	PM-overview surface: per-station average + outlier flagging.	Per-station drill-down accessible from the Manager feedback table.

IAS-E8 · Audit log & PM instrumentation

ID	Story	AC
IAS-S801	Audit-log writer middleware: every resolution endpoint writes an audit entry capturing case_id, actor, officer_type, before, after, delta, timestamp, note.	Audit table reflects every action; no resolution call succeeds without an audit row.
IAS-S802	Case-history block on every Atlas issue screen, auto-injected at the bottom on goto(). (Existing helper covers this; extend if any new screens land.)	All new issue screens carry the case-history block automatically.
IAS-S803	PM dashboard rollups: volume by issue type, by officer, by station; median time-to-resolve per type; rejection / clarification rates.	Queries return under 2s on staging-volume data.
IAS-S804	Per-issue-type distribution chart on the PM dashboard reflects the new 11-type taxonomy.	Old scenario labels (mgr-transfer-fail, deduction-fails, funds-other) are not present.

---

Subtasks

Where a story has clear front-end / back-end / mobile splits, break out subtasks. Naming: IAS-T<story>-<short>.

Example: IAS-S304 (Atlas funding-pending resolution)

• IAS-T304-be — overdraft eligibility guardrail + recon-id-kind and reference field validation on POST /v1/cases/{id}/actions/issue-overdraft.
• IAS-T304-fe — radio-chip group + dynamic placeholder + inline “Receipt unreadable?” block + checkbox-gated Submit; copy strings.
• IAS-T304-qa — contract test for body-supplied rider ID mismatch; UI test for radio-required gating.

Example: IAS-S603 (Send-back round-trip)

• IAS-T603-be — wire request-clarification action to write thread message + emit push event.
• IAS-T603-mobile — push handler on Rechaj Swap deep-links to the thread sheet + opens the retake dropzone.
• IAS-T603-fe-atlas — simulateManagerRetake lookalike now wired to real backend events (currently only the simulation runs).
• IAS-T603-qa — end-to-end staging test that send-back → retake → version chip completes in <30s.

Example: IAS-S504 (Parked swap push)

• IAS-T504-be — notification service routes case-resolved + thread-message events to push.
• IAS-T504-mobile — push payload deep-links to parked-swap entry; cold-start path tested.
• IAS-T504-qa — multiple parked swaps + multiple pushes in quick succession; verify no collision in routing.

(Apply the same FE/BE/mobile/QA breakdown to every story that touches multiple layers.)

---

Dependency graph

IAS-E1 (data model + case service)
   │
   ├─► IAS-E2 (RBAC) ──────────────────────────┐
   │                                            │
   ├─► IAS-E3 (Atlas resolution)  ◄─────────────┤
   │       │                                    │
   │       └─► E3 screens depend on E1 actions  │
   │                                            │
   ├─► IAS-E4 (Rechaj Swap report flows)        │
   │       │                                    │
   │       └─► E4 sheets depend on E1 case create endpoint
   │                                            │
   ├─► IAS-E5 (Park-a-Swap)                     │
   │       │                                    │
   │       └─► depends on E1 ParkedSwap entity + E6 push events
   │                                            │
   ├─► IAS-E6 (Thread + retake) ◄───────────────┤
   │       │                                    │
   │       └─► depends on E1 messages + attachments, E2 RBAC for officer actions
   │                                            │
   ├─► IAS-E7 (Feedback & Rating)               │
   │       │                                    │
   │       └─► largely independent of E1; needs SwapFeedback table only
   │                                            │
   └─► IAS-E8 (Audit log + PM)                  │
           │                                    │
           └─► writer middleware lands with E1; surfaces follow E3

Cross-epic blockers

• IAS-S109 (overdraft guardrail) blocks IAS-S304 (Atlas funding-pending resolution) and IAS-S305 (overdraft-pending lift).
• IAS-S204 (escalation routing) blocks IAS-S306 / IAS-S307 / IAS-S311 (the three escalating issue types’ resolution screens).
• IAS-S102 (officer-type seed) blocks IAS-S201–IAS-S205.
• IAS-S501 (parked-swaps section) blocks IAS-S504 (push deep-link target).
• IAS-S603 (send-back round-trip) blocks marking E6 done; depends on IAS-S104 (messages), IAS-S105 (attachments), IAS-S605 (thread persistence).

Sequencing principles

• Land the data model first so every other epic can integrate behind a stable contract.
• Land the auto-population endpoint guardrail before any Atlas resolution screen ships — this is the structural fix for the wrong-rider incident class.
• Land the highest-volume issue types (battery 3.1–3.3) before lower-volume (2.4 / 2.5 / Other / 1.2).
• Land RBAC + escalation routing before the two escalating wallet issues (2.4 / 2.5) and the escalating battery issue (3.4).

---

Sequencing recommendation

Assumes a 4-person backend team + 2-person mobile + 2-person Atlas + 1 QA, ~2-week sprints. Adjust to actual team shape.

Sprint 1 — Foundations

• IAS-E1 complete: schemas + migrations + POST /v1/cases + actions + escalate + park/resume + overdraft guardrail (IAS-S109).
• IAS-E2 start: officer-type seed (IAS-S102), RBAC middleware (IAS-S201), scoped queue endpoint (IAS-S202).
• IAS-E8 start: audit-writer middleware (IAS-S801).
• QA: contract tests for the wrong-rider hard rule (priority).

Exit criteria for sprint 1

• Wrong-rider test passes end-to-end: case A overdraft with case B’s rider → 400.
• Cases can be created + parked + resumed via API.
• Audit log captures every action.

Sprint 2 — High-volume battery + parking

• IAS-E4 start: sheet-battery-release (3.1) + sheet-battery-claim (3.2 single) + sheet-battery-attribute (3.3) — wired to POST /v1/cases.
• IAS-E3 start: screen-issue-battery-release + -claim + -attribute (IAS-S308–S310).
• IAS-E5 start: parked-swaps section + resume (IAS-S501, IAS-S502, IAS-S503).
• IAS-E6 start: thread sheet + thread-mini + retake loop on 3.1 / 3.3 (IAS-S601–S603).
• IAS-E8: case-history auto-inject on issue screens (IAS-S802).

Exit criteria for sprint 2

• A manager can report 3.1 → park → serve next rider → resume on resolution.
• Send-back-for-clearer-photo round-trips end-to-end on 3.1 and 3.3 in <30s.

Sprint 3 — Wallet flows + escalations

• IAS-E4: sheet-reconcile (2.1) + sheet-overdraft-pending (2.2) + sheet-previously-paid (2.4) + sheet-acct-invalid (2.5).
• IAS-E3: screen-issue-funding-pending (2.1) + screen-issue-overdraft-pending (2.2) + screen-issue-phantom-fee (2.4) + screen-issue-acct-invalid (2.5).
• IAS-E2: escalation routing end-to-end (IAS-S204); multi-role queue layout (IAS-S203).
• IAS-E6: retake loop on 2.1 (IAS-S603).
• IAS-E1: outstanding-overdraft flag on rider wallet (IAS-S110).

Exit criteria for sprint 3

• 2.1 → overdraft credit works against the radio-chip reference field, blocked without eligibility checkbox.
• 2.4 / 2.5 escalate to Engineering queue and Engineering can mark-fixed → manager push lands.
• 2.2 rider can be lifted from overdraft ban and immediately swap.

Sprint 4 — Station assignment + serial mismatch + Other

• IAS-E4: sheet-station (1.1) + screen-perm-change-lookup flow (1.2) + sheet-battery-mismatch (3.4) + multi-battery transfer scanner (IAS-S404) + sheet-support (“Other”).
• IAS-E3: screen-issue-temp-swap (1.1) + screen-issue-perm-change (1.2) + screen-issue-battery-mismatch (3.4) + Inventory Officer’s resolution view (IAS-S312) + screen-triage-queue (“Other”).
• IAS-E2: Energy + Facility config-only addition test (IAS-S205).

Exit criteria for sprint 4

• All 11 issue types + Other have end-to-end report → resolve flows in staging.
• Inventory Officer’s manual search + Issue corrected serial works end-to-end (3.4).
• “Other” cases land in triage and can be re-routed to typed queues.

Sprint 5 — Feedback + PM instrumentation + polish

• IAS-E7 entire: feedback module + endpoint + Manager feedback screen + dashboard snippet + per-station drill-down.
• IAS-E8: PM dashboard rollups (IAS-S803) + distribution chart re-keyed to new taxonomy (IAS-S804).
• IAS-E4 copy / drift sweep (IAS-S410, IAS-S411); retire old Atlas screens per Q11 decision (IAS-S314).
• QA: end-to-end test plan + load test on overdraft endpoint + RBAC matrix coverage.

Exit criteria for sprint 5 — GA candidate

• All acceptance criteria in PRD §9 satisfied.
• Ops sign-off after a 1-week parallel-run with WhatsApp.

---

Definition of done

Story-level

• Acceptance criteria in the linked PRD section satisfied.
• Unit tests + at least one integration test per resolution action / state transition.
• Audit-log entry verified for every state-changing action.
• Visual regression updated where the change touches a screen captured in the prototype.
• No new free-text inputs for identifiers that should be auto-populated (code grep on resolution screens).
• Copy verified against the feedback-* memory rules — no engineering / ops / float / technical case codes user-facing on Rechaj Swap.

Epic-level

• All stories in the epic completed and merged.
• End-to-end staging exercise of the canonical happy path + at least 2 unhappy paths.
• Ops walkthrough recorded; sign-off captured in the epic ticket.
• Linked PRD section’s acceptance criteria fully met.
• Wrong-rider integration test from IAS-S109 still passes (regression check).

Release-level (GA)

• All release:p0 and release:p1 epics done.
• 1-week parallel-run with WhatsApp shows ≥80% of new traffic on the in-app system without regressions.
• 0 incidents of the wrong-rider class during the parallel run.
• PM dashboard returns expected rollups within 2s on staging-volume data.
• Audit log retention + backup verified.

---

Notes

• The auto-population guardrail is the single most important deliverable. Land it in sprint 1, exercise it in every subsequent sprint, and treat any free-text identifier input on a resolution screen as a P0 bug.
• Officer-type model is config-driven. Adding Energy or any other future officer type should be a config PR, not a code PR. Verify this property continuously.
• Park-a-Swap is the throughput story. Without it, the in-app system actively makes a manager’s day worse than WhatsApp (where they at least could ignore the stuck rider and serve others). Treat park + resume as non-optional.
• Backwards compatibility with the old Atlas screens (mgr-transfer, deduction-fail) is an open question (PRD Q11). Default plan: hide from the active queue; keep as engineering-debug routes until the new model is fully bedded in.