# ZUMRI Phase 7 Orders and Payments

## Objective
Convert checkout snapshots into durable orders and establish authoritative payment, invoice, refund, and return lifecycles without delivery or rewards.

## Existing Components Reused
Checkout snapshots, inventory reservations, pricing money helpers, coupons, ReferenceNumber, document infrastructure, audit queue, authentication, and permissions.

## Order Architecture
Order/payment/fulfillment states are independent. Commercial and address/shipping details are immutable snapshots.

## Checkout Conversion
The centralized transaction locks an owned READY checkout, verifies reservations, returns any existing order, copies items, and converts checkout/cart.

## Order State Machine
Explicit transition sets reject illegal terminal-state transitions and arbitrary status patches.

## Order Snapshots
Items retain product/variant IDs, reservation key, SKU, names, quantity, unit price, discount, total, currency, and limited metadata.

## Payment Architecture
Payments retain immutable attempts. Only server/provider reconciliation changes authoritative financial state.

## Provider Adapters
Generic payment logic delegates verification/parsing/initiation/refund/status behavior to provider modules.

## PayHere
Merchant secrets are environmental. Browser redirects are non-authoritative; the notify hash, reference, amount, and currency must validate.

## Stripe
An explicit disabled boundary is present. Integration awaits official SDK/configuration rather than accepting unverified callbacks.

## Webhook Verification
Invalid signatures, currencies, amounts, and references are rejected.

## Webhook Idempotency
Unique provider/event records and locked payment/order rows ensure duplicate success cannot repeat side effects.

## Inventory Consumption
Checkout reserves; confirmed online payment consumes. Failed payment does not consume. Unpaid cancellation releases.

## Payment Reconciliation
Webhook persistence supports reconciliation, but remote status polling is deferred until the enabled provider supplies a validated status API.

## Business Credit
Disabled pending an approved immutable credit-ledger/accounting policy; concurrent unsafe balance mutation was not introduced.

## Invoice Architecture
One invoice per order uses transaction-safe ReferenceNumber sequencing. The existing document worker remains the PDF integration point.

## Refund Architecture
Idempotent itemized requests validate remaining quantity and captured amount. Provider processing is separate from request approval.

## Return/RMA Architecture
Owner-scoped requests and explicit admin transitions track physical receipt/condition independently from refunds.

## Exchange Boundary
EXCHANGE is recorded as resolution intent; no replacement order or fulfillment is created.

## Coupon Redemption
Redemption occurs once on confirmed payment while the coupon row is locked. Full-refund restoration is deferred by policy.

## Verified Purchase Reviews
Review creation derives verification only from an actual paid order containing the product.

## Permissions
Orders read/manage/cancel, payments read/manage/refund, invoices read, and returns read/manage were added.

## Audit Events
Order, payment creation, cancellation, refund request, return lifecycle, and admin operations reuse sanitized Phase 2 activity logging.

## Database Changes
Forward-only migration `20260909070000` creates eleven commerce tables with unique references/idempotency and lifecycle indexes.

## Tests
Unit tests cover order transitions, PayHere signature validation, forged notifications, secure return/refund inputs, and configurable return eligibility.

## Remaining Known Issues
Real PayHere, refunds, document generation, migration, webhook delivery, and MySQL concurrency were not exercised. Refund approval/provider completion APIs and reconciliation polling require provider policy/configuration.

## Phase 8 Prerequisites
Apply all migrations on restored staging, seed permissions, configure/validate PayHere sandbox, test concurrent duplicate webhooks, final-stock payment consumption, coupon quotas, invoice jobs, refund callbacks, and return restocking.

Module 16 AI Customer Support Chatbot is intentionally excluded and planned as a separate service.