# Phase 20 — Full System Integration and Acceptance Testing

## Purpose
Phase 20 is a release-readiness and acceptance milestone. It does not introduce new clinical features. It establishes a repeatable test process for the existing modules and identifies evidence required before production release.

## 1. Automated test harness repairs
- Added shared `tests/TestCase.php` extending Laravel's framework test case.
- Normalised `phpunit.xml` and forced an isolated in-memory SQLite test environment.
- Added a deterministic testing APP_KEY.
- Added system readiness tests for `/up`, guest login, protected dashboard, Sanctum API and FHIR metadata authentication.
- Added API rate-limiter registration tests.
- Added `scripts/phase20-acceptance.sh`, a fail-closed acceptance runner.
- The acceptance runner never executes database migrations automatically; it checks migration status only.

## 2. Automated acceptance test inventory
The project contains feature tests for:
- Patient registration and access.
- Facility isolation and approved patient transfer.
- Appointment workflow.
- Clinical encounter workflow.
- Pharmacy dispensing and stock updates.
- Specialist-role authorization.
- Procurement maker-checker.
- Payroll approval and net-pay arithmetic.
- Goods receipt and inventory/ledger posting.
- General ledger balancing and idempotency.
- Financial period closing and closed-period posting rejection.
- Data quality scan non-mutation.
- Public health threshold signal idempotency.
- Clinical alert escalation queue.
- DHIS2 payload outbox idempotency.
- SMS reminder consent gating.
- System readiness and protected API access.
- API rate-limiter registration.

**Important:** test files have been authored but have not been executed in this environment. Their presence is not evidence that they pass.

## 3. Release acceptance matrix

| Area | Acceptance evidence required | Current state |
|---|---|---|
| Composer | Reviewed lock file, strict validation, dependency audit | Blocked: Composer/lock absent |
| Laravel boot | `php artisan about` and route compilation | Not run |
| Database | Apply all migrations to clean MySQL 8.4 staging | Not run |
| SQLite tests | Full `php artisan test` suite | Not run |
| Patient registry | Create, search, duplicate prevention, facility isolation | Test source present |
| Clinical EMR | Draft, sign, amendment, encounter audit trail | Test source present |
| Appointments | Book, reschedule/status, patient/facility access | Test source present |
| Pharmacy | Prescribe, dispense, stock decrement, batch expiry | Test source present |
| Laboratory | Request, result, verify, access restrictions | Test source present; runtime pending |
| Maternal/child health | Registration, ANC, immunisation, follow-up | Test source present; runtime pending |
| Referral | Initiate, receive, status update, closed-loop referral | Test source present; runtime pending |
| Finance | Invoice, receipt, ledger, AP, payroll, reconciliation | Test source present; runtime pending |
| Procurement | Budget, PO, approval, GRN, bill matching | Test source present; runtime pending |
| Public health | Notification, threshold scan, follow-up | Test source present; runtime pending |
| FHIR | Auth, resource search, facility isolation, conformance | Partial API; conformance not run |
| DHIS2 | Mapping, queued payload, dispatch, import reconciliation | Queue tests present; external dispatch not run |
| SMS | Consent, queue, provider delivery and opt-out | Consent queue only; no provider |
| AI governance | Human review, incident and model monitoring | Register only; independent validation pending |
| Security | Role matrix, session, API rate limit, penetration test | Partial source controls; pen test absent |
| Backup/restore | Encrypted backup, restore into isolated environment, integrity validation | Crypto test string only; full drill not run |
| Performance | Load, concurrency, DB query and queue throughput | Not run |
| Clinical safety | Signed clinical workflow and hazard review | Not approved |
| Privacy | DPIA, NDPA/NDPC review, retention and breach process | Not approved |
| Release | Signed UAT, operational runbook, rollback and go/no-go | Not released |

## 4. Required execution sequence on a provisioned staging host

1. Generate the Composer lock file and review dependency versions.
2. Install locked dependencies and run Composer audit.
3. Prepare `.env` with staging-only secrets.
4. Build and start Docker services.
5. Verify MySQL health and application readiness.
6. Review `php artisan migrate:status`.
7. Take a pre-migration encrypted backup.
8. Apply migrations explicitly using `php artisan migrate --force`.
9. Run seeders only after reviewing their effects.
10. Create a named initial super-administrator using the setup command.
11. Run `scripts/phase20-acceptance.sh`.
12. Run role-by-role browser UAT at each facility.
13. Validate FHIR and DHIS2 with approved test endpoints.
14. Perform backup restore drill in an isolated environment.
15. Obtain clinical, privacy, security, finance and executive sign-offs.

## 5. Required role-based UAT
At minimum, test:
- Super administrator.
- LCDA administrator.
- LCDA medical director.
- Facility administrator.
- Medical officer.
- Nurse.
- Midwife.
- Pharmacist.
- Laboratory scientist.
- Medical records officer.
- Cashier.
- Accountant.
- Inventory officer.
- Public health officer.
- Auditor.

For each role, verify permitted actions, forbidden actions, facility boundaries, audit events and logout/session expiry.

## 6. Exit criteria
Phase 20 can be marked accepted only when:
- Composer lock is committed and audited.
- All migrations apply successfully to a clean staging database.
- Automated feature tests pass.
- Critical and high-severity defects are closed or formally accepted.
- Facility isolation and least-privilege tests pass.
- Financial ledgers reconcile and finance owners approve.
- Clinical representatives sign off workflows and safety controls.
- Privacy officer approves DPIA, retention, consent and data sharing.
- Security assessment and penetration test are complete.
- Backup restoration meets approved RPO/RTO.
- DHIS2/FHIR external conformance tests are documented.
- Signed UAT and executive go/no-go are recorded.

## 7. Current environment limitation
The current authoring environment has PHP but does not have Composer, Docker, PDO SQLite, PDO MySQL or an available staging URL. Consequently, PHP source lint and static route/schema checks can be performed, but Composer resolution, Laravel runtime, PHPUnit, MySQL migrations, Docker, external integrations and real restore drills cannot be honestly marked passed.
