% Raport de testare API — DiDi Lot 2 (Backend)
% PNRR DIGI150 · contract 11.1.i3.c9
% Data testării: 2026-07-08

---

# 1. Obiect și scop

Prezentul raport documentează testarea completă a interfețelor de programare (API) ale
**Lotului 2 — Backend**, respectiv cele două servicii software livrate:

- **Agent V3** (motor de analiză, port 24803);
- **didiFramework** (management parametri, port 3005).

Testarea acoperă **strict Lotul 2**. Serviciile de inteligență artificială (Lotul 1) sunt
testate separat, prin testele de integrare rulate pe mediul unde este instalat Lotul 1.

Raportul constituie dovada pentru criteriul 6 din caietul de sarcini („Implementare &
transfer": OpenAPI/Swagger + set minim de teste API) și însoțește specificațiile
`openapi.yaml` ale celor două servicii.

---

# 2. Metodologie

1. **Inventar din codul sursă** — toate definițiile de rute au fost extrase automat din cod
   (nu din documentație), cu un script reproductibil. S-a verificat separat absența rutelor
   definite dinamic, a mount-urilor cu prefix nescanate și a generatoarelor CRUD active —
   toate verificările au ieșit goale, deci inventarul static este complet.
2. **Probă live** — fiecare endpoint a fost apelat pe mediul de testare, cu token JWT real
   emis de Keycloak. Strategie **non-distructivă**: cererile GET au fost apelate real; cererile
   POST/PUT/PATCH/DELETE au fost apelate cu identificatori inexistenți sau body gol (răspunsul
   400/404 dovedește că ruta este cablată, fără a modifica date). Endpoint-urile idempotente
   (dry-run, sync-redis, check-credits) au fost rulate real; cele cu efect mutativ real au
   fost verificate manual și consemnate separat.
3. **Verificare de integritate** — s-a capturat un instantaneu al bazei de date (7 contoare)
   înainte și după rularea completă: **identic**, confirmând că testarea nu a alterat datele.

---

# 3. Rezultate

| Metric | Valoare |
|---|---|
| Endpoint-uri inventariate | **374** |
| — Agent V3 | 87 |
| — didiFramework | 287 |
| Endpoint-uri cablate (răspund cu handler propriu) | **374 / 374** |
| Rute moarte (`Cannot GET/POST …`) | **0** |

**Distribuția codurilor de răspuns:**

| Cod HTTP | Nr. | Semnificație |
|---|---|---|
| 200 | 135 | răspuns corect |
| 400 | 102 | validare de input (comportament corect pe body/ID de test) |
| 401 | 4 | necesită autentificare (extension API-key) — corect |
| 403 | 2 | necesită rol (moderare) — separare de roluri funcțională |
| 404 | 118 | resursă inexistentă (ID de test) — comportament corect |
| 409 | 9 | conflict (ex. duplicat) — comportament corect |
| 500 | 4 | vezi §5 (probleme cunoscute, neblocante) |

Toate codurile 401/403 reflectă **comportament de securitate corect**, nu erori: rutele de
extensie cer `X-API-Key`; operațiile de moderare (claim/resolve) cer rol
`moderator`/`senior_moderator`, pe care contul de test (admin) nu îl deține.

---

# 4. Corectări efectuate în urma testării

Testarea a identificat 4 defecte reale (toate de tip ordonare de rute / validare de input),
reparate și re-testate:

| Endpoint | Defect | Corecție |
|---|---|---|
| `GET /api/validation-rules/stats` | 500 — umbrit de ruta `/:id` declarată înainte | reordonare rute |
| `DELETE /api/indicators/by-technique/:techniqueId` | inaccesibil — umbrit de `/:techniqueId/:indicatorId` | reordonare rute |
| `POST /api/sync-analysis/batch` | umbrit de `/:sessionId` | reordonare rute |
| `GET /api/weights/multipliers/type/:type` | 500 pe input non-numeric | validare → 400 |

Suplimentar, s-a rulat un scan sistematic de umbriri de rute pe ambele servicii — **zero
umbriri rămase**.

---

# 5. Verificări de securitate

| Verificare | Rezultat |
|---|---|
| Cerere fără token JWT pe rută protejată (prin gateway) | **401** |
| Cerere cu token JWT forjat | **401** |
| Cerere cu token JWT valid | **200** |
| Enforcement JWT la gateway — Agent V3 | **DA** |
| Enforcement JWT la gateway — didiFramework | **DA** |
| Verificare criptografică JWT în backend (apărare în adâncime) | **DA** (ambele servicii) |
| Separare de roluri (RBAC pe moderare) | **DA** (403 fără rol) |

---

# 6. Probleme cunoscute (neblocante)

1. **`/api/waitlist/*` → 500** — funcționalitatea de listă de așteptare depinde de o bază de
   date de staging separată, neprezentă în deployment-ul standard. Funcție marginală
   (înscriere pre-lansare), marcată `deprecated` în specificația OpenAPI.
2. **`GET /api/v3/pipeline/history/admin/:id`** — răspunde 500 (în loc de 400) când
   identificatorul nu are format UUID; cu UUID valid răspunde corect. Diferență cosmetică de
   validare.
3. Endpoint-uri legacy marcate `deprecated` în OpenAPI: `domain/*` (înlocuit de
   source-assessment), `sync-analysis/*` (persistență directă în PostgreSQL), `prompts/*` pe
   fișiere (sursa operațională este baza de date).

---

# 7. Artefacte și reproducere

| Artefact | Locație |
|---|---|
| Specificație OpenAPI 3.0.3 — Agent V3 (87 operații) | `services/orchestration-layer/agent-v3/openapi.yaml` |
| Specificație OpenAPI 3.0.3 — didiFramework (287 operații) | `services/orchestration-layer/didiFramework/openapi.yaml` |
| Script de probă (reproductibil) | `scripts/api/api_probe.py` |
| Generator de specificație | `scripts/api/generate_openapi.py` |
| Rezultate brute ale probei | `scripts/api/probe_results_2026-07-08.json` |
| Interfață Swagger UI | container `didi-api-docs` (ambele specificații) |

Ambele specificații OpenAPI au fost **validate** cu `openapi-spec-validator` (rezultat: OK).
Fiecare operație poartă adnotarea `x-tested` cu codul HTTP observat la probă.

---

# 8. Concluzie

Toate cele **374 de endpoint-uri** ale Lotului 2 sunt cablate și funcționale (374/374), fără
rute moarte. Securitatea (autentificare JWT la gateway și în backend, autorizare pe roluri)
este verificată și funcțională. Cele 4 defecte identificate au fost corectate. Problemele
rămase sunt marginale și documentate. Pachetul de API al Lotului 2 este **conform și
verificabil**.