# Phase 10A Execution Checklist (Card Management and Rewards/Offers UX)

Reference artifacts:
- docs/wallet-implementation-plan-apps-mode.md
- docs/phase-tracker.md
- docs/domain-map.md
- docs/phase-9A-execution-checklist.md
- docs/phase-9B-execution-checklist.md
- docs/phase-9C-execution-checklist.md
- docs/adr/0005-api-error-and-idempotency-response-contract.md
- docs/adr/0006-security-and-key-management-baseline.md
- docs/adr/0011-compliance-and-data-governance-controls.md

## 1. Phase Objective
Deliver web UX for card management and rewards/offers capabilities, including debit/credit card controls, external card linking, and rewards visibility journeys for customers — plus admin back-office management of cards (block/unblock, search across users) and rewards/offers (create/expire offers, adjust points, view reward activity) — with policy-protected sensitive actions and audit traceability.

Phase status target:
- Start: not-started
- End: done when all Phase 10A customer card/rewards journeys AND admin card/rewards management are implemented and validated.

Current phase status: done (2026-03-26) - customer UX (Tracks A–D) and admin management (Track E) delivered and validated.

## 2. Scope
In scope:
- Debit card management panel UX (limits, freeze/unfreeze, virtual card, PIN reset).
- Credit card management panel UX (limits, freeze/unfreeze, virtual card, PIN reset).
- External bank card linking UX with validation flow.
- Offer listing UI with validity period display and lifecycle states.
- Points/rewards balance visibility and transaction history UX.
- Sensitive-action confirmation and re-auth checkpoints for card controls.
- Baseline audit/observability for card and rewards privileged actions.
- Admin card search and management (block/unblock across all users, ops_agent read-only view).
- Admin rewards & offers management (create/expire offers, adjust points balance, view all reward transactions).
- Role-gated admin menu entries and policy actions for card/rewards admin operations.

Out of scope:
- Loan and insurance UX (covered in Phase 10B).
- Full partner/provider implementation details beyond UI integration contracts.
- Multi-tenant runtime branding and tenant-level content execution.
- Native mobile card/rewards implementation.

## 3. Work Breakdown

## Track A: Debit and Credit Card Management UX
1. Define card panel IA and action taxonomy.
- Owner: Product Team + Wallet Web Team
- Output: IA covering debit/credit panel sections and action hierarchy.
- Status: done (2026-03-26)
- Evidence: CardManagementLive with debit/credit/linked tabs at /app/cards.

2. Implement debit card management journeys.
- Owner: Wallet Web Team
- Output: freeze/unfreeze, virtual card request, PIN reset, and card listing UX.
- Status: done (2026-03-26)
- Evidence: CardManagementLive :debit tab; FreezeCard/UnfreezeCard/RequestVirtualCard/ResetCardPin commands; commands_test.exs.

3. Implement credit card management journeys.
- Owner: Wallet Web Team
- Output: freeze/unfreeze, virtual card, PIN reset, and card listing UX.
- Status: done (2026-03-26)
- Evidence: CardManagementLive :credit tab; same command suite; card_management_live_test.exs.

4. Implement sensitive-action UX safeguards.
- Owner: Security Team + Wallet Web Team
- Output: data-confirm prompts for freeze/PIN-reset; ABAC policy gates (:freeze_card, :reset_card_pin in @ownership_required_actions + @mfa_required_actions).
- Status: done (2026-03-26)
- Evidence: policy.ex privileged/mfa/ownership lists updated; LiveView events validated.

## Track B: External Card Linking UX
1. Define external card linking user flow and consent pattern.
- Owner: Integrations Team + Wallet Web Team
- Output: linking form with network/last-four/nickname fields.
- Status: done (2026-03-26)
- Evidence: CardManagementLive :linked tab with link-card form; LinkExternalCard command.

2. Implement add/link external card UX.
- Owner: Wallet Web Team
- Output: card entry, success flash, and error handling.
- Status: done (2026-03-26)
- Evidence: handle_event "link_card" in CardManagementLive; commands_test.exs LinkExternalCard test.

3. Implement linked-card management UX.
- Owner: Wallet Web Team
- Output: list/remove linked cards with status indicators.
- Status: done (2026-03-26)
- Evidence: active_linked filter + remove_linked event; LinkedCardStore.update to :removed status.

4. Define reconciliation visibility touchpoints.
- Owner: Integrations Team + Operations Team
- Output: reference/status visibility for linked-card operations.
- Status: deferred to Track E (admin view provides ops visibility).

## Track C: Rewards and Offers UX
1. Implement offers listing and lifecycle visibility.
- Owner: Wallet Web Team + Product Team
- Output: active offers grid with validity, points cost, and status chip.
- Status: done (2026-03-26)
- Evidence: OffersLive at /app/offers; 6 seeded sample offers; offers_live_test.exs.

2. Implement rewards balance and transaction history views.
- Owner: Wallet Web Team
- Output: points balance hero + earn/redeem transaction list.
- Status: done (2026-03-26)
- Evidence: RewardsLive at /app/rewards; PointsStore + RewardStore; rewards_live_test.exs.

3. Implement redemption entry points and guidance UX.
- Owner: Wallet Web Team + Product Team
- Output: redeem button (disabled when insufficient), confirmation, flash success/error.
- Status: done (2026-03-26)
- Evidence: OffersLive handle_event "redeem"; RedeemPoints command with offer-active + balance checks.

4. Validate consistency between offers and rewards contexts.
- Owner: QA + Wallet Web Team
- Output: unified experience across offer-to-reward actions.
- Status: done (2026-03-26)
- Evidence: balance deduction reflected in OffersLive after redeem; RewardsLive history shows new txn.

## Track D: Quality, Security, and Operational Readiness
1. Validate responsive behavior for card/rewards critical pages.
- Owner: QA + UX Team
- Output: viewport readiness — mobile hamburger + overlay sidebar available for all pages.
- Status: done (2026-03-26)
- Evidence: customer_shell.html.heex mobile sidebar; Phase 9D responsive baseline.

2. Validate accessibility baseline for card/reward actions.
- Owner: QA + UX Team
- Output: aria-current, data-confirm, status_chip semantics on card/reward pages.
- Status: done (2026-03-26)
- Evidence: Phase 9A UIComponents baseline applied; status_chip on card status and offer status.

3. Validate audit/telemetry for sensitive card and rewards actions.
- Owner: Observability Team + Security Team
- Output: AuditEvent + telemetry emitted for FreezeCard, ResetCardPin, RedeemPoints, LinkExternalCard.
- Status: done (2026-03-26)
- Evidence: each command calls AuditEvent.build + :telemetry.execute; PubSub broadcast on events.

4. Validate negative paths and rollback UX.
- Owner: Wallet Web Team + QA Team
- Output: insufficient-points flash, wrong-owner error, already-frozen error handled.
- Status: done (2026-03-26)
- Evidence: FreezeCard :already_frozen, :unauthorized; RedeemPoints :insufficient_points, :offer_not_active tested.

## Track E: Admin Card and Rewards Management (NEW)
1. Add admin BlockCard command and events.
- Owner: Wallet Web Team
- Output: BlockCard command (admin-initiated hard block, distinct from customer freeze); CardBlocked + CardUnblocked events.
- Status: done (2026-03-26)
- Evidence: BlockCard/UnblockCard commands + CardBlocked/CardUnblocked events in wallet_cards; commands_test.exs 17 tests passing.

2. Add admin AdjustPoints command and CreateOffer command.
- Owner: Wallet Web Team
- Output: AdjustPoints (manual credit/debit with reason, ops_supervisor+); CreateOffer (admin-only offer creation); ExpireOffer; PointsAdjusted event; OfferCreated event.
- Status: done (2026-03-26)
- Evidence: AdjustPoints/CreateOffer/ExpireOffer commands in wallet_rewards; rewards_test.exs 9 tests passing.

3. Update policy.ex with 6 new admin actions.
- Owner: Wallet Web Team
- Output: view_any_cards (ops_agent+), block_card (ops_supervisor+), unblock_card (ops_supervisor+), manage_offers (admin), adjust_points (ops_supervisor+), view_any_rewards (ops_agent+).
- Status: done (2026-03-26)
- Evidence: policy.ex updated with all 6 actions across ops_agent/ops_supervisor/admin roles; MFA guards on block_card + adjust_points.

4. Create CardSearchLive admin LiveView (/admin/cards).
- Owner: Wallet Web Team
- Output: search cards by user_id; filter by status/type; Block/Unblock actions (supervisor+, confirm-gated); linked cards tab.
- Status: done (2026-03-26)
- Evidence: card_search_live_test.exs — 11 tests, 0 failures.

5. Create RewardsManagementLive admin LiveView (/admin/rewards).
- Owner: Wallet Web Team
- Output: Offers tab (list all, expire, create new — admin only); Transactions tab (reward history across users); Points tab (lookup balance, manual adjust — supervisor+).
- Status: done (2026-03-26)
- Evidence: rewards_management_live_test.exs — 16 tests, 0 failures.

6. Update AdminMenu and Router.
- Owner: Wallet Web Team
- Output: "Cards" + "Rewards" items in Operations nav group; 4 new /admin/cards + /admin/rewards routes.
- Status: done (2026-03-26)
- Evidence: admin_menu.ex Cards + Rewards entries; router.ex 4 admin routes; 53 admin tests, 0 failures.

## 4. Deliverables
1. Debit and credit card management web panels with core actions. done (2026-03-26)
2. External bank card linking and linked-card management UX. done (2026-03-26)
3. Rewards/offers listing, points visibility, and transaction history UX. done (2026-03-26)
4. Sensitive-action security UX safeguards and policy protections. done (2026-03-26)
5. Accessibility/responsiveness and audit/telemetry baseline evidence. done (2026-03-26)
6. Admin CardSearchLive: cross-user card search, block/unblock controls. done (2026-03-26)
7. Admin RewardsManagementLive: offers catalog management, reward tx log, points adjustment. done (2026-03-26)
8. 6 new admin policy actions with role gates and ownership guards. done (2026-03-26)

## 5. Entry and Exit Criteria
Entry criteria:
- Phase 9A foundation and policy baseline approved. MET
- Phase 9B and 9C core customer/admin pathways established. MET
- Security controls for step-up re-auth and policy decisions available. MET
- wallet_cards + wallet_rewards umbrella apps delivered. MET (2026-03-26)

Exit criteria:
1. Debit/credit card action journeys complete and validated. done (2026-03-26)
2. External card linking flows complete with clear success/failure behavior. done (2026-03-26)
3. Rewards/offers surfaces complete with validity and history visibility. done (2026-03-26)
4. Sensitive-action policy and audit coverage verified. done (2026-03-26)
5. Admin card search + block/unblock management delivered and tested. done (2026-03-26)
6. Admin offers management + points adjustment delivered and tested. done (2026-03-26)
7. Phase 10B and 10C dependencies remain unblocked. done (2026-03-26)

## 6. Risks and Mitigations
1. Risk: Sensitive card actions expose weak authorization paths.
- Mitigation: enforce ABAC checks and step-up verification for high-risk operations.
- Status: mitigated for customer paths (policy + ownership guards). Admin paths gated by :block_card/:adjust_points privilege.

2. Risk: External linking failures produce unclear user outcomes.
- Mitigation: deterministic failure messaging, retries, and clear next-step guidance.
- Status: mitigated — flash error messages on link failure.

3. Risk: Rewards and offers states drift from backend truth.
- Mitigation: contract-driven data mapping and consistency checks across views.
- Status: mitigated — OfferStore/PointsStore single source of truth; admin view reads same stores.

4. Risk: Admin block action conflicts with customer freeze state.
- Mitigation: BlockCard produces :blocked status (terminal for customer actions); admin-only UnblockCard restores :active.
- Status: mitigated — BlockCard produces :blocked status (terminal for customer actions); admin-only UnblockCard restores :active. CardSearchLive block/unblock confirm-gated.

5. Risk: Deferred multi-tenant scope causes expectation mismatch.
- Mitigation: explicit deferred notes and non-operational labeling where relevant.
- Status: open

## 7. Suggested Sprint Plan (3 Sprints)
Sprint A: (DONE)
- Card panel IA and debit/credit baseline flows.
- Sensitive-action safeguard patterns.
- External card linking flow.
- Rewards/offers UX baseline.

Sprint B: (DONE)
- Full debit/credit action journeys.
- Rewards history and redemption UX.
- Quality hardening for responsive/accessibility/negative paths.
- Audit/telemetry validation.

Sprint C: (DONE)
- Admin CardSearchLive with block/unblock.
- Admin RewardsManagementLive with offers + points management.
- Policy actions for admin operations.
- Admin menu entries and router routes.
- Test coverage and sign-off.

## 8. Evidence Checklist
- [x] Card panel IA and action taxonomy delivered (CardManagementLive tabs).
- [x] Debit card management scenario test reports (commands_test.exs + card_management_live_test.exs).
- [x] Credit card management scenario test reports (same test suite).
- [x] External card linking and linked-card lifecycle validation (commands_test.exs LinkExternalCard).
- [x] Rewards/offers rendering and history verification results (rewards_live_test.exs, offers_live_test.exs).
- [x] Sensitive-action policy and step-up re-auth validation (policy.ex @mfa_required_actions, @privileged_actions).
- [x] Responsive and accessibility baseline (Phase 9A UIComponents + customer_shell mobile sidebar).
- [x] Audit/telemetry traceability for card/reward sensitive operations (AuditEvent.build in each command).
- [x] Admin card search and block/unblock validation report.
- [x] Admin offers management and points adjustment validation report.
- [x] Phase 10A sign-off note with owner approvals.

## 9. Deferred Backlog (Explicit TODO)
1. Multi-tenant card/rewards theming and tenant-level content activation remain deferred.
2. Native iOS and Android card/rewards implementation remains deferred.
3. Advanced campaign personalization and dynamic offer targeting remain deferred unless promoted by governance.
4. Set-card-limits UI form (daily/monthly limits input) deferred to Phase 10C hardening.