# Raport testare API — 2026-07-08

> Dovadă pentru criteriul 6 din caietul de sarcini („Implementare & transfer": OpenAPI/Swagger +
> set minim teste API). Documentul-pereche: `API_TESTING_GUIDE.md` (ghid de testare manuală) și
> specificațiile `agent-v3/openapi.yaml` + `didiFramework/openapi.yaml`.

## Metodă

1. **Inventar din cod, nu din documentație**: toate definițiile de rute Express au fost extrase
   automat din sursă (`scripts/api/api_probe.py`). S-a verificat separat că nu există rute definite
   dinamic (variabile/template literals), mount-uri cu prefix nescanate sau generatoare CRUD active —
   toate cele 4 verificări au ieșit goale, deci inventarul static este complet.
2. **Probă live pe didi11**: fiecare endpoint apelat cu token Keycloak real (user `api-test`,
   realm `didi-admins`, rol `admin`). Strategie non-distructivă: GET real; POST/PUT/PATCH/DELETE cu
   body gol sau ID inexistent (răspunsul 400/404 dovedește cablarea fără a muta date). Excepții
   idempotente rulate real: `dry-run`, `sync-redis`, `check-credits`. Endpoint-urile cu efect real
   pe body gol (email de test, credit-reset, use-credit) sunt consemnate ca verificate manual și
   excluse din rulările automate.
3. **Verificare integritate**: snapshot pe 7 contoare DB înainte/după rularea finală — identic
   (800 indicatori / 621 reguli / 166 tehnici / 23 modele / 83 assignments / sesiuni / utilizatori).

## Rezultat

| Metric | Valoare |
|---|---|
| Endpoint-uri inventariate | **374** (87 agent-v3 + 287 didiFramework) |
| Cablate (răspund cu handler propriu) | **374 / 374** |
| Rute moarte (`Cannot GET/POST …`) | **0** |
| Distribuție status finală | 200×135 · 400×102 · 401×4 · 403×2 · 404×118 · 409×9 · 500×4 |

Cele 401/403 sunt comportament CORECT (extension cere `X-API-Key`; claim/resolve moderare cer rol
`moderator`/`senior_moderator`, pe care admin nu îl are — separare de roluri funcțională).

## Buguri găsite și REPARATE în această sesiune

| Endpoint | Problemă | Fix |
|---|---|---|
| `GET /api/validation-rules/stats` | 500 — umbrit de ruta `/:id` (declarată înainte) | reordonare rute (`validation-rules.ts`) |
| `DELETE /api/indicators/by-technique/:techniqueId` | inaccesibil — umbrit de `/:techniqueId/:indicatorId` | reordonare rute (`indicators.ts`) |
| `POST /api/sync-analysis/batch` | umbrit de `/:sessionId` (legacy, reparat oricum) | reordonare rute (`sync-analysis.ts`) |
| `GET /api/weights/multipliers/type/:type` | 500 pe input non-numeric (coloana e integer) | validare → 400 (`weights.ts`) |

S-a rulat și un scan sistematic de umbriri de rute pe ambele servicii — zero umbriri rămase.

## Probleme cunoscute, deschise (consemnate, ne-blocante)

1. **`/api/waitlist/*` → 500**: cere `STAGING_DB_HOST` + containerul `staging-dataLayer-postgres`
   (absent pe didi11). Feature pre-lansare, marcat `deprecated` în spec. Remediere: setare env +
   pornire container, sau eliminarea rutelor.
2. **`GET /api/v3/pipeline/history/admin/:id`** răspunde 500 (în loc de 400) dacă `:id` nu e UUID —
   gap cosmetic de validare în agent-v3; cu UUID valid răspunde corect (`Session not found` / 200).
3. Endpoint-uri legacy marcate `deprecated` în spec: `domain/*` (înlocuit de source-assessment),
   `sync-analysis/*` (agent-v3 persistă direct în PG), `prompts/*` pe fișiere (sursa operațională
   e DB via `/api/providers/prompts`).

## Artefacte

| Artefact | Locație |
|---|---|
| Spec OpenAPI 3.0.3 agent-v3 (87 operații) | `backend/services/orchestration-layer/agent-v3/openapi.yaml` |
| Spec OpenAPI 3.0.3 didiFramework (287 operații) | `backend/services/orchestration-layer/didiFramework/openapi.yaml` |
| Script probă (reproductibil la recepție) | `scripts/api/api_probe.py` |
| Generator spec din inventar + probe | `scripts/api/generate_openapi.py` |
| Rezultate brute probă | `scripts/api/probe_results_2026-07-08.json` |
| Swagger UI live | `http://10.11.10.11:8089` (container `didi-api-docs`, servește ambele spec-uri) |

Ambele spec-uri sunt **validate** cu `openapi-spec-validator` (OK). Fiecare operație poartă
adnotarea `x-tested` cu statusul HTTP observat la probă și data testării.

## Reproducere

```bash
# 1. Probă completă (necesită serviciile pornite + Keycloak local)
python3 scripts/api/api_probe.py x /tmp/probe_results.json

# 2. Regenerare spec-uri
python3 scripts/api/generate_openapi.py /tmp/probe_results.json \
  backend/services/orchestration-layer/agent-v3/openapi.yaml \
  backend/services/orchestration-layer/didiFramework/openapi.yaml

# 3. Validare
docker run --rm -v $PWD/backend/services/orchestration-layer:/s python:3.12-alpine \
  sh -c 'pip install -q openapi-spec-validator && \
         python -m openapi_spec_validator /s/agent-v3/openapi.yaml && \
         python -m openapi_spec_validator /s/didiFramework/openapi.yaml'
```

User de test recepție: `api-test` / `ApiTest2026x` (realm `didi-admins`, rol `admin`;
cont PG auto-creat `api-test@didi.local`, internet_user_id 90001).