# ZTG Billing Portal Framework

Laravel-based internal billing operations framework for telecoms/connectivity/IT billing.

## Implemented Foundation
- Azure Entra SSO login (`/auth/azure/redirect`, `/auth/azure/callback`)
- Local fallback break-glass login (`/login/local`)
- Internal roles: `Admin`, `BillingOperator`, `ReadOnly`
- Pluggable CSV import adapters with validation + normalization pipeline
- Billing run lifecycle (`Draft -> ReadyToPublish -> Published/Failed`)
- Xero draft invoice publishing skeleton with idempotency keys
- Queue-backed jobs for import processing, billing validation, and Xero publish
- Structured JSON logging + queue/dead-letter status page

## API Endpoints
- `POST /api/imports`
- `GET /api/imports/{importBatch}`
- `POST /api/billing-runs`
- `POST /api/billing-runs/{billingRun}/validate`
- `POST /api/billing-runs/{billingRun}/publish-xero`
- `GET /api/billing-runs/{billingRun}`

All API endpoints require authenticated internal users. Role checks are enforced by middleware and policies.

## Environment Profiles
- `.env.dev.example`
- `.env.prod.example`

Copy one into `.env` and configure:
- MySQL connection
- Azure Entra credentials
- Xero profile credentials (`dev` and `prod`)

## Local Run
```bash
php artisan migrate
php artisan db:seed
php artisan serve
php artisan queue:work
```

## Tests
```bash
php artisan test
```