livrare lot 2

backend/BUILD_AND_SCRIPTS.md

@@ -0,0 +1,124 @@
+# DIDI Backend — Build, Scripturi, Env & Seed (index operațional)
+
+> Răspunde la: *cum ridic platforma pe o mașină nouă, ce script rulez, ce env pun, de unde iau seed-ul.*
+> Topologia curentă = **totul local pe mașina de deployment** (fără cluster extern). Vezi `services/*/INDEX.md` pentru detalii per serviciu.
+
+---
+
+## 1. Build curat pe o mașină nouă (calea recomandată)
+
+```bash
+cd backend/production
+./build-local.sh [hostname]        # implicit: hostname-ul mașinii
+```
+
+`build-local.sh` ridică TOATĂ stiva local, în ordinea corectă: network → data-layer (PG+seed, Redis,
+RabbitMQ, MinIO, Keycloak) → Kong → framework + sync-redis → agent-v3 + workeri → dashboard.
+**Seed-ul se importă automat** la primul boot al `didi-postgres` (montat ca init script).
+
+**Precondiții** (nu-s în git — se aduc manual pe mașina nouă):
+1. `.env` completate pentru fiecare serviciu (copiază din `.env.example`, pune secretele — vezi §4).
+2. Seed-ul `services/data-layer/didiDatabase/DIDI_full_export_2026-07-02.sql` prezent (vezi §5).
+
+---
+
+## 2. Ce docker-compose rulează per serviciu (evită confuzia `.local.yml`)
+
+| Serviciu | Compose CANONIC (rulează) | Notă |
+|---|---|---|
+| **data-layer** (PG, Redis, RabbitMQ, MinIO, Keycloak) | `services/data-layer/docker-compose.local.yml` | AICI `.local.yml` = cel activ (PG+Keycloak local) |
+| **didiFramework** | `services/orchestration-layer/didiFramework/docker-compose.yml` | `.yml` are `${DB_HOST:-didi-postgres}` — local by default, overridable |
+| **agent-v3 + workeri** | `services/orchestration-layer/agent-v3/docker-compose.yml` | idem |
+| **Kong** | `docker run` din `build-local.sh` (DBless) | config `didiKong/declarative/kong.yml.didi11-local` |
+| **admin dashboard** | imagine `didi-admin:latest` (`docker run`) | vezi build-local.sh Faza 7 |
+| observabilitate (opțional) | `observability/docker-compose.yml` | Prometheus/Grafana/Loki/OTel |
+
+> `data-layer/docker-compose.yml` (fără `.local`) = stiva veche de staging (`staging-dataLayer-*`) — nefolosită pentru DB principal în modul local.
+> Cele 2 `.local.yml` redundante ale framework/agent au fost arhivate (erau acoperite integral de `.yml`).
+
+---
+
+## 3. Inventar scripturi
+
+| Script | Ce face | Stare |
+|---|---|---|
+| `production/build-local.sh` | **Build complet local** (recomandat) | ✅ curent |
+| `production/full-build.sh` | Build pe topologie cluster (PG/Kong externe) | legacy — doar dacă revii la cluster |
+| `production/migrate-to-cluster.sh` | Mută DB-urile Kong/Keycloak pe cluster | legacy |
+| `services/data-layer/didiQueue/init-queues.sh` | Creează exchange + cozi + DLQ în RabbitMQ | util la nevoie (topologia se face și dinamic de workeri) |
+| `services/data-layer/didiStorage/init-buckets.sh` | Creează bucket-urile MinIO | rulat de build-local.sh |
+| `services/gateway-auth-layer/didiKong/entrypoint.sh` | Entrypoint container Kong | intern |
+| `services/orchestration-layer/agent-v3/scale-workers.sh` | Scalare workeri (status/set/auto pe metrici) | operațional |
+| `services/orchestration-layer/didiFramework/scripts/bulk_insert_*.sh` | Insert bulk indicatori/reguli tehnici | one-off (datele sunt deja în seed) |
+| `services/orchestration-layer/scripts/redis-switch.sh` | Comută Redis/RabbitMQ local ↔ cluster | operațional |
+| `services/orchestration-layer/scripts/minio-switch.sh` | Comută MinIO local ↔ cluster | operațional |
+| `scripts/api/api_probe.py` (repo root) | Inventar + probă live a tuturor endpoint-urilor | testare/recepție |
+| `scripts/api/generate_openapi.py` (repo root) | Generează `openapi.yaml` din inventar + probe | testare/recepție |
+| `scripts/ci/health-check.sh` (repo root) | Health-gate post-deploy | CI/CD |
+
+---
+
+## 4. Fișiere .env (unde stau, ce pui)
+
+Fiecare serviciu are `.env` (gitignored, cu secrete) + `.env.example` (în git, șablon fără secrete).
+Pe mașină nouă: `cp .env.example .env` și completează valorile `CHANGE_ME`.
+
+| Serviciu | `.env` | Secrete de completat |
+|---|---|---|
+| `services/orchestration-layer/agent-v3/` | infra + LLM + **URL-uri Lot 1** | OPENROUTER/OPENAI/GROQ/ANTHROPIC/GOOGLE keys, M17 token, MinIO keys |
+
+**Lot 1 (platforma AI) — configurabil 100% din env.** agent-v3 cheamă serviciile AI prin URL-uri
+din `.env` (nu hardcodate). Pe o mașină nouă cu Lot 1 propriu, setezi doar host-urile în
+`agent-v3/.env` (bloc marcat „Lot 1 — Platforma AI"):
+
+| Env var | Serviciu Lot 1 |
+|---|---|
+| `LLM_ROUTER_URL` | llm-inference (Qwen text/OCR) |
+| `VISION_LLM_URL` | Qwen Vision (fallback: `LLM_ROUTER_URL`) |
+| `DIDI_BRAIN_URL` | brain (verification cache + RAG) |
+| `VIDEO_ANALYSIS_URL` | video/BusterX deepfake |
+| `EXTRACTORS_URL` | extractors (EXIF/ELA/NER/YOLO/OCR) |
+| `FORENSIC_API_URL` | forensic m25-m29 |
+| `M17_WHISPER_URL` | transcriere audio |
+| `M17_WEB_API_URL` | web search (claims/source) |
+| `DOMAIN_CHECK_API_URL` | domain check |
+
+Fiecare are și fallback în `docker-compose.yml` (`${VAR:-default}`): dacă Lot 1 rulează pe aceeași
+rețea Docker, merge cu numele de container (ex. `didiAI-extractors`); dacă e pe alt host, pui IP-ul în `.env`.
+| `admin-dashboard/` | Keycloak + URL-uri | de regulă doar hostname-uri |
+| `production/` | Redis/Keycloak/Kong | REDIS/KEYCLOAK passwords, Kong secrets |
+| `services/data-layer/`, `didiCache/`, `didiQueue/`, `didiStorage/` | infra | credențiale local (redis123/rabbitmq123/minio123 în staging) |
+| `services/orchestration-layer/didiFramework/` | DB + Keycloak + MinIO | DB_PASSWORD, KEYCLOAK_ADMIN_PASSWORD |
+| `observability/` | Grafana | GRAFANA admin |
+
+> `services/orchestration-layer/scripts/.cluster-credentials.env` (gitignored) = credențialele cluster,
+> folosit doar de `redis-switch.sh --cluster` / `minio-switch.sh cluster`. Irelevant pentru build local.
+
+---
+
+## 5. Seed-ul bazei de date
+
+- **Fișier canonic:** `services/data-layer/didiDatabase/DIDI_full_export_2026-07-02.sql` (23 MB, pg_dump
+  complet: schema + date + toate migrațiile 001–017). Restore curat → 4 scheme `bos_*`, 97 tabele.
+- **NU e în git** (untracked, prea mare). Pe o mașină nouă trebuie adus manual (copiere / stick / scp)
+  în directorul de mai sus ÎNAINTE de `build-local.sh`.
+- **Redis NU se seed-uiește** — e cache derivat din PostgreSQL. După restore: `POST /api/sync-redis`
+  (build-local.sh o face automat). Rețetă completă: `didiDatabase/REBUILD.md`.
+- Arhivat în afara repo-ului (`/home/admin365/didi_seed_archive_2026-07-08/`): seed-ul vechi
+  `2026-03-22` (fără migrații) + pachetul demo (abandonat — livrarea folosește doar full seed).
+
+---
+
+## 6. Verificare rapidă după build
+
+```bash
+# health toate serviciile
+docker exec didi-postgres pg_isready -U bos_interface
+docker exec didi-cache redis-cli -a redis123 --no-auth-warning ping
+docker exec didi-framework wget -qO- http://127.0.0.1:3005/health
+docker exec didi-agent-v3 wget -qO- http://localhost:24803/api/v3/health
+# chei framework în Redis (după sync)
+docker exec didi-cache redis-cli -a redis123 --no-auth-warning keys 'didi:framework:*' | wc -l   # aștept 8
+# API docs (dacă rulează containerul didi-api-docs)
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8089/
+```