# NGBVD Backend Implementation Scope

This patch preserves the accepted UI/UX baseline and introduces backend controls for permissions, data scope, integrations, API logs, API v2 data-quality output, and public UUID identifiers.

## Permissions and Data Scope

Functional permissions remain module/action based, for example:

- `case_intake.create`
- `profiled_cases.view`
- `api_integrations.ubos_push`
- `roles.configure`

Data-scope permissions are added separately:

- `data_scope.national`
- `data_scope.district`
- `data_scope.partner`
- `data_scope.own_records`

The `DataScopeService` enforces district/partner/own-record restrictions. It reads existing `users.district`, `users.partnerid`, `users.partner`, and the new optional `user_data_scopes` table for more granular assignments.

## Route Protection

Important routes are protected by `ngbvd.permission`. Menus should continue using `hasNgbvdPermission()` for navigation visibility, while routes prevent direct URL access.

## API Clients

New admin URLs:

- `/integrations`
- `/integrations/api-clients`
- `/integrations/logs`
- `/integrations/logs/{uuid}`

New API URLs:

- `GET /api/v2/health`
- `GET /api/v2/reference-data`
- `GET|POST /api/v2/incidents/statistics`
- `POST /api/v2/incidents/push/ubos`

API client authentication uses headers:

- `X-Client-Key`
- `X-Client-Secret`

## Integration Logs

The `integration_logs` table tracks inbound/outbound sharing status, request hash, masked request preview, response preview, retry count, and user/system that triggered the share.

## UBOS GBV Portal

Configure `.env`:

```env
UBOS_GBV_ENABLED=true
UBOS_GBV_BASE_URL=https://example.ubos.go.ug
UBOS_GBV_PUSH_ENDPOINT=/api/v1/incidents
UBOS_GBV_TIMEOUT=30
UBOS_GBV_VERIFY_SSL=true
```

## UUID Strategy

The patch does not replace integer primary keys immediately. It adds `uuid` columns to core tables and backfills them. Use UUIDs externally in APIs and URLs while keeping integer IDs internally until the database is fully mapped and tested.

Recommended migration order on staging:

```bash
php artisan migrate --path=database/migrations/2026_06_04_000100_create_api_clients_integration_logs_and_user_scopes.php
php artisan migrate --path=database/migrations/2026_06_04_000110_add_public_uuid_columns_to_core_tables.php
```

## API Data Quality Fixes

`/api/v2/incidents/statistics` implements the corrections raised in the UBOS/MGLSD data quality report:

- `total_incidents` is the real record count, not dictionary-key count.
- Gender includes Male, Female and Unknown.
- National status and religion use genuine group-by logic.
- All dimensions use the same base `incident_data` population.
- Blank incident types are quarantined and reported in metadata.
- Response includes `api_version`, `data_as_of`, `filters_applied` and `record_count`.