# QR V2 Refactor Specification

This document records the QR V2 refactor: design, phases, data types, behavior contract, factory pattern, error handling, response normalization, configuration, file structure, and next steps.

## Overview
The V2 refactor creates a parallel provider system that runs alongside the existing V1 code. The goals were:

- Keep V1 intact (zero-impact)
- Create a standardized provider contract and types
- Implement a factory for provider lookup and routing
- Add comprehensive error normalization, response normalization, and logging
- Implement V2 controllers and providers in parallel

---

## Phases

### Phase 1 — Design & Standard Types
- Standard types and data structures implemented in `lib/da_product_app/qr_providers_v2/types.ex`.
  - Standard request shape: `standard_request` map with fields such as `transaction_refid`, `amount`, `merchant_id`, `device_id`, `merchant_name`, `transaction_currency`, etc.
  - Standard response shape: `standard_response` map with fields such as `status`, `qr_code_url`, `qr_code_data`, `qr_code_id`, `payment_reference_id`, `provider_transaction_id`, `provider_data`, `expires_at`, `provider_response_time_ms`, etc.
- Helper functions for validation and conversion live in the provider modules or utility modules.
- Standardized error codes and statuses are defined in `lib/da_product_app/qr_providers_v2/error_handler.ex`.

---

### Phase 2 — Behaviour Contract
- `lib/da_product_app/qr_providers_v2/behaviour.ex` defines the required callbacks for any provider:
  - `generate(standard_request)`
  - `cancel_payment(operation_request)`
  - `refund_payment(operation_request)`
  - `inquiry_payment(operation_request)`
  - `get_capabilities()`
- Each provider implements the behaviour and returns `Types.success_response/1` or `Types.error_response/2`.
- Examples are included in provider modules.

---

### Phase 3 — Factory Pattern
- `lib/da_product_app/qr_providers_v2/factory.ex` provides provider lookup and method routing.
- Provider registration happens via config with provider code keys mapping to module atoms.
- Factory wraps provider calls with monitoring, timing, and error handling.
- Startup validation checks configured providers implement the behaviour.

---

### Phase 4 — Error Handling & Response Normalization
- Centralized error normalization in `lib/da_product_app/qr_providers_v2/error_handler.ex`.
- `lib/da_product_app/qr_providers_v2/response_normalizer.ex` contains provider-specific converters that map provider outputs to the V2 standard.
- Sanitization and security helpers ensure provider data doesn't leak secrets.

---

## Implementation Notes

### UPI Provider (UPI V2)
- Implemented a native V2 UPI provider that calls Mercury PSP directly.
- Fixed mapping: PSP `qr_string` -> V2 `qr_code_data`, `qr_url` -> `qr_code_url`.
- Gzip decompression and JSON parsing handled inside `call_mercury_api/2`.
- All PSP response fields are logged (transaction_refid included) for debugging.

### Aani & Alipay Providers
- Standardized wrappers created for Aani and Alipay.
- They implement `get_capabilities/0` and `generate/1` etc., following the behaviour.

---

## File Structure
- `lib/da_product_app/qr_providers_v2/` - V2 provider modules and helpers
  - `behaviour.ex` - Provider contract
  - `types.ex` - Standard types and helper constructors
  - `factory.ex` - Provider factory and routing
  - `error_handler.ex` - Error normalization and mapping
  - `response_normalizer.ex` - Provider response mapping helpers
  - `providers/` - Provider implementations: `alipay_v2.ex`, `aani_v2.ex`, `upi_v2.ex`

---

## How to Test (Quick)

- Start server:

```bash
mix phx.server
```

- Generate a V2 QR (example payload):

```bash
curl -X POST http://localhost:4000/api/v2/qr/generate \
  -H 'Content-Type: application/json' \
  -d '{"provider":"upi","amount":15000,"deviceId":"DEV123","stid":"STID123","transaction_refid":"TRX123"}'
```

---

## Next Steps (Phase 2 continued)
- Add more unit tests for response normalization and PSP parsing.
- Add docs index and link to README.
- Iterate on provider error handling and retries.

---

## Architecture Benefits
- Provider self-responsibility
- Zero core changes to V1
- Consistent interface for all providers
- Enhanced logging and monitoring
- Easier provider onboarding via config

---

## Contact
For questions about this refactor or to review specific provider implementations, contact the engineering team responsible for QR middleware.