Getting started — Enterprise AI Platform (Finance)¶

Guía práctica para alguien nuevo en el repo: entender el flujo, correr local, desplegar a DEV y validar.

Estás en el paso 1 de la ruta

Después de esta guía: Arquitectura Azure → Guion de demo.

flowchart LR
  A[Clonar] --> B[Arquitectura]
  B --> C{¿Local?}
  C -->|Sí| D[API + Web local]
  C -->|Azure| E[rama deployment]
  E --> F[Pipelines]
  F --> G[Smoke portal]
  G --> H[Entra + APIM]

1. Prerrequisitos¶

Git, Python 3.11+, Node 20+, Azure CLI (para scripts Entra / smoke)
Acceso al proyecto ADO Enterprise-AI-Platform y suscripción DEV
Lectura recomendada: architecture.md, azure-prerequisites.md

2. Flujo de negocio (Finance)¶

sequenceDiagram
  actor R as Reviewer
  participant W as finance-web
  participant G as APIM
  participant A as finance-api

  R->>W: Cola / factura
  W->>G: Bearer JWT
  G->>A: REST
  A-->>W: invoice + HITL flags
  R->>W: approve / reject
  R->>W: chat
  W->>A: POST /chat
  A-->>W: guardrail o Foundry+tools

Reglas: data-model.md · Demo: demo-script.md.

3. Desarrollo local¶

3.1 Finance API¶

cd services/rule-engine
python -m pytest -q

cd ../finance-api
pip install -r requirements.txt
python -m pytest tests/test_chat_guardrails.py tests/test_agent_tools.py -q
uvicorn app.main:app --reload --port 8001

Swagger: http://127.0.0.1:8001/docs
Guardrails: POST /api/finance/chat con “dame un hello world en HTML” → mode: guardrail

Más: local-dev.md.

3.2 Finance Web¶

cd apps/finance-web
copy .env.example .env.local
# FINANCE_API_BASE_URL=http://127.0.0.1:8001
npm install
npm run dev

Sin NEXT_PUBLIC_ENTRA_CLIENT_ID / config runtime vacía → modo demo (sin login).
Con Entra configurado → gate MSAL. Detalle: apps/finance-web/README.md.

4. Despliegue DEV (pipeline-only)¶

flowchart LR
  DEV["git push origin deployment"] --> PATH{Path filters}
  PATH -->|apps/finance-web| WEB["eai-finance-web-deploy"]
  PATH -->|services/finance-api| API["eai-finance-api-deploy"]
  PATH -->|infra/**| TF["eai-terraform-dev"]
  TF --> PLAN[Plan + artifact]
  PLAN --> MV[ManualValidation]
  MV -->|Resume| APPLY[Apply]
  MV -->|Reject| STOP[Sin cambios Azure]

Reglas:

Cambios de código app → pipelines de imagen (web/api).
Cambios de infra → Terraform con revisión manual del plan.
No uses Portal/az como flujo oficial de config (salvo scripts documentados de Entra).

Detalle: deployment.md, terraform-pipeline.md, azure-i2-deploy.md.

5. Identidad (Entra) y gateway (APIM)¶

flowchart TB
  subgraph AuthN["Autenticación — Entra"]
    SPA["eai-finance-web-dev"]
    APIAPP["eai-finance-api-dev<br/>scope access_as_user"]
    G1["Finance.Reviewer"]
    G2["Finance.User"]
  end

  subgraph AuthZ["Autorización"]
    GATE["Assignment required?<br/>Enterprise app → Users and groups"]
    APIMJ["APIM validate-jwt<br/>issuer + audience"]
    APPZ["Grupos en JWT<br/>User|Reviewer · HITL=Reviewer"]
  end

  SPA --> APIAPP
  G1 --> GATE
  G2 --> GATE
  GATE --> SPA
  SPA -->|JWT| APIMJ
  APIMJ --> APPZ

Crear/actualizar apps: scripts/create_entra_finance_apps.ps1
Admin consent en portal Entra
Opcional: Assignment required = Yes + asignar grupos
Terraform: enable_apim=true + client id / audience
Web usa APIM_GATEWAY_URL + Bearer

Guía completa: entra-apim-finance.md.

6. Agente Foundry¶

Instrucciones: agents/finance-agent/instructions.md
Publicar versión: python scripts/create_finance_foundry_agent.py
Runtime API: guardrail local + policy prefix + tool loop

Ver finance-agent-foundry.md.

7. Checklist de smoke en Azure¶

[ ] Abrir portal por Front Door (edge-front-door.md)
[ ] Health API OK (/api/platform/health)
[ ] Portal carga cola HITL
[ ] Factura con blob muestra PDF (no mensaje de endpoint no publicado)
[ ] Chat off-topic rechazado
[ ] Chat de negocio usa tools (toolsUsed)
[ ] Con Entra ON: login obligatorio; con APIM ON: llamadas vía gateway
[ ] Developer Portal APIM carga APIs (apim-developer-portal.md)

8. Dónde mirar si algo falla¶

Síntoma	Revisar
PDF “no disponible”	Proxy GET documento; `hasBlob`; deploy web
Chat genera HTML	Deploy api + agent v3 / guardrails
Login loop / AADSTS	Redirect URI (incl. AFD), consent, Assignment required
Portal OK en ACA pero no en AFD	edge-front-door.md; purge; Entra redirect; WAF rate limit
401 en API vía APIM	Audience JWT = `api://{api-app-id}`, policy APIM
Terraform apply inesperado	Artifact `plan.txt` + ManualValidation

Siguiente paso¶

Continuar con Arquitectura Azure (as-built) y luego el guion de demo.