# E‑hailing App Provider Registration (NPTR)

This document describes the new NPTR sub‑module to register E‑hailing App Providers, issue 7‑year certificates (R5 000 fee), and expose a read‑only registry to NPTR and PRE users.

## Feature flag
- System setting: `ehailing.providers.enabled`
- Values: `TRUE` or `FALSE`
- When FALSE:
  - Start Application chooser hides types 60/61/62
  - Left‑nav App Provider Registry hidden
  - Endpoints remain RBAC‑guarded; UI does not expose actions

## New application types
- 60 NPTR_EhailingProviderRegistration (New)
- 61 NPTR_EhailingProviderRegistrationRenewal (Renewal)
- 62 NPTR_EhailingProviderRegistrationAmendConditions (Amend Conditions)

## Gazetting (Task #74)
- **14-day notice period (NPTR only)**: For **NPTR** division gazettes that contain e-hailing applications (60, 61, 62), notice expiry is set to print date + 14 days. **PRE** division always uses the default 21 days. System setting: `GazettePeriodDaysEhailing` = `14`. Run script in `DBUp/Scripts/2026/74_E-Hailing App Provider Gazetting/` before deploy.
- **Bypass expiry (dev/test only)**: The Gazette Console “Bypass expiry date” button is shown for e-hailing applications only when `AllowBypassGazetteExpiryForEhailing` = TRUE (dev/test). Set to FALSE or omit in production. Same script folder.

## Data model (DB)
- `Verified.PlatformProviders`
  - LegalName, TradingName?, BusinessRegNumber (unique), VatNumber?, Email?, Phone?
  - RegisteredAddressLine1/…/ProvinceID/PostalCode, timestamps, IsCancelled
- `Verified.ProviderCertificates`
  - PlatformProviderID (FK), CertificateNumber (unique), IssuedAt, ExpiresAt (+7y), ReissuedFromID?, IsCancelled
- View `Verified.Vw_ProviderRegistry`
  - Latest certificate per provider; computed Status (Active/Expired/Cancelled)

## Public flows
### 1) Start Application (NPTR)
- Access via Applications → Start New Application (NPTR) with types 60/61/62
- Steps: Request ID/Type → Applicant Details → Confirm Documents → Create Application
- Payment (POP/receipt) reuses existing Payment Details console (R5 000 fee)
- Verification/Adjudication reuse existing queues and transitions

### 2) Certificate Issue/Reissue
- Issue: upon approval (type 60), NPTR can Generate certificate
- Reissue: upon approval (type 61/62) NPTR can Reissue certificate (new number, history kept)
- Numbering: `NPTR-EHP-YYYY-####`

### 3) Registry (NPTR/PRE)
- Left‑nav: App Provider Registry (visible if `ehailing.providers.enabled=TRUE` and user is NPTR/PRE)
- Screen: Search by name/reg/cert; filter by Status; optional "Expiring within N days"

## API
### Providers Registry
- GET `/ProvidersRegistry/Search`
  - Query params:
    - `q` (string, contains match on LegalName/TradingName/BusinessRegNumber/CertificateNumber)
    - `status` (Active|Expired|Cancelled)
    - `expiringWithinDays` (int; optional)
    - `page` (int), `pageSize` (int)
  - Auth: NPTR or PRE; feature flag must be TRUE
  - Response:
    ```json
    {
      "Success": true,
      "Result": {
        "items": [
          {
            "PlatformProviderID": 1,
            "LegalName": "...",
            "TradingName": "...",
            "BusinessRegNumber": "...",
            "CertificateNumber": "NPTR-EHP-2025-0001",
            "IssuedAt": "2025-09-26T00:00:00Z",
            "ExpiresAt": "2032-09-26T00:00:00Z",
            "Status": "Active"
          }
        ],
        "total": 1
      }
    }
    ```

### Certificates
- POST `/ApplicationRequest/IssueProviderCertificate`
  - Body: `{ applicationDetailID: number }`
  - Auth: adjudication approval securable
  - Effect: Upsert provider by business reg no from applicant; insert certificate; email notification

- POST `/ApplicationRequest/ReissueProviderCertificate`
  - Body: `{ applicationDetailID: number, reason: string }`
  - Auth: adjudication approval securable
  - Effect: Insert new certificate with `ReissuedFromID`; email notification

## Notifications
- Templates are stored in `Crm.MessageTemplates` and executed by ID using `Crm.Pr_MessageCreateTemplatedEmails(@MessageTemplateID)`.
- Seeded scenarios:
  - Submission
  - Decision Approved / Rejected
  - Certificate Issued / Reissued
- Recipients: applicant email and (optionally) proxy email
- Execution: handlers resolve template ID by key then call the ID‑based runner (best effort; non‑blocking)

## RBAC
- Start new application: `ApplicationsModule_Home_StartNewApplication`
- Adjudication capture decision: `ApplicationsModule_ApplicationRequest_Adjudication_CaptureDecision`
- Registry (read‑only): allowed for NPTR or PRE + feature flag TRUE; optional dedicated securable can be added later

## Deployment
1) Run DBUp scripts (in order):
   - `2025/0923_NPTR_EhailingProviderRegistration.sql`
   - `2025/0924_App_Pr_IssueProviderCertificate.sql`
   - `2025/0925_Verified_Vw_ProviderRegistry.sql`
   - `2025/0926_App_Pr_ReissueProviderCertificate.sql`
   - `2025/0927_Crm_MessageTemplates_Providers.sql`
   - `2025/0928_System_Settings_EhailingProviders.sql`
2) Confirm `System.Settings` → `ehailing.providers.enabled=TRUE` (or set per environment)
3) Verify RBAC for NPTR/PRE users
4) Smoke test end‑to‑end (submit → payment → verify → approve → issue → registry)

## Known limitations (MVP)
- No provider API for real‑time suspensions/expulsions; manual update only (future)
- Returned‑for‑correction email not wired yet (will be added where the return action is handled)
- No QR on certificate (client request to skip)