# ANBT Backend — Phase 2 API Contract Forensics & Parity Report

**Audit Date:** 2026-08-28  
**Scope:** OpenAPI 3.1 Contract Validation, Bidirectional Route Parity, Error Codes, and Security Schemes

---

## 1. Executive Summary

Phase 2 verification confirms that the ANBT Backend API surface matches the OpenAPI specification with **100% bidirectional parity**:
- **OpenAPI Version:** `3.1.0`
- **Total Registered Routes:** `183` (128 Admin routes + 55 Client/Partner API routes)
- **Documented OpenAPI Operations:** `183`
- **Route → OpenAPI Missing:** `0`
- **OpenAPI → Route Missing:** `0`
- **Method & Path Mismatches:** `0`
- **Error Codes (ERR_*) Parity:** `97 / 97` (100% synced between source and `docs/ERROR_CODES.md`)
- **CI Contract Enforcement:** Added `php tools/openapi-check.php` to `.github/workflows/ci.yml`

---

## 2. Route Inventory & Parity Summary

| Category | Registered Routes | Documented in OpenAPI | Parity Status |
|---|---|---|---|
| **Admin Endpoints (`routes/admin.php`)** | 128 | 128 | 100% PASS |
| **Public & Partner Endpoints (`routes/api.php`)** | 55 | 55 | 100% PASS |
| **Total API Operations** | **183** | **183** | **100% MATCH** |

---

## 3. Security Contract Verification

- **Admin Routes (128 operations):**
  - Secured operations require `BearerAuth` (JWT) and RBAC permissions (`AuthMiddleware` + `RoutePermissionMapTest`).
  - `/admin/auth/login` and `/admin/auth/refresh` operate with public or session refresh tokens as expected.
- **Client & Partner Routes (55 operations):**
  - Authenticated operations declare `BearerAuth`.
  - Public endpoints (`/health`, `/products`, `/categories`, OTP endpoints) operate without authorization headers.
- **Unsecured Admin Operations:** `0` unauthorized exposures.

---

## 4. Error Codes (ERR_*) Inventory

- **Runtime Error Identifiers in `src/`:** `97` unique codes.
- **Documented Error Codes in `docs/ERROR_CODES.md`:** `97` unique codes (synced `ERR_BRAND_NOT_FOUND`).
- **Missing / Undocumented Codes:** `0`.

---

## 5. Automated CI & Test Gates

1. **`php tools/openapi-check.php`:** PASS (183/183 operations verified).
2. **Architecture Suite (`vendor/bin/phpunit --testsuite architecture`):** PASS (30 tests, 589 assertions).
3. **Full PHPUnit Suite (`vendor/bin/phpunit`):** PASS (197 tests, 1229 assertions).
4. **PHPStan Static Analysis (`vendor/bin/phpstan analyse`):** PASS (Level 6, 0 errors).
5. **CI Workflow Integration:** Configured in `.github/workflows/ci.yml`.
