docs(fase8): plan/arquitectura/README para migración de UI a Astro (Agro-Stack)

- Plan y tareas: nueva Fase 8 (Astro+Tailwind SPA consumiendo /api; Leaflet-draw,
Chart.js; responsive + sidebar/footer plegables; Regla de Oro de plan_replication).
- Arquitectura: nota de frontend Astro + ADR (revisa 'Shiny sobre Astro'; Shiny -> legacy).
- README: reescrito a plataforma (6 módulos, FastAPI + Supabase BYOK, UI migrando a Astro).

README.md

@@ -1,67 +1,83 @@
-# AgroVisión — MVP (Conteo por Dron)
+# AgroVisión — Plataforma de Monitoreo Agronómico
 
-MVP de [AgroVisión](docs/reference/description_proyecto_agrovision_mvp.md): UI en **Shiny for Python** + backend **FastAPI** para el conteo de plantas a partir de ortomosaicos de dron.
+Plataforma de [AgroVisión](docs/reference/description_proyecto_agrovision.md) para monitoreo agronómico de precisión: **gestión de parcelas**, **teledetección NDVI** (Sentinel-2, 5 años), **agente conversacional (RAG)** y **conteo de plantas por dron** (este último **en desarrollo**). Backend **FastAPI** (monolito modular), persistencia **Supabase (PostGIS) BYOK**, y UI en **migración de Shiny → Astro + Tailwind** (Agro-Stack).
 
-> **Estado actual — STANDBY.** El módulo de conteo arranca **deshabilitado** (`COUNTING_ENABLED=false`) hasta que el [repo del modelo](docs/reference/description_proyecto_modelo_conteo_plantas.md) publique el artefacto `agrovision-plantcount` en Hugging Face Hub. Mientras tanto, la UI muestra el aviso *"Módulo en preparación"* y el endpoint `/api/count` responde `503`.
+> **Modelo BYOK, credenciales efímeras.** Las llaves del usuario (Supabase, Copernicus, Groq) viven **solo en memoria de sesión** y se envían por cabeceras `X-User-*`; nunca se persisten. Refrescar borra todo.
 >
-> **Modelo agnóstico.** La app consume el artefacto por **contrato** vía un adaptador de inferencia (onnxruntime o `ultralytics` según la arquitectura: YOLO26/RF-DETR). **Licencia: AGPL-3.0** (app open-source).
+> **Conteo por dron — EN DESARROLLO.** Arranca deshabilitado (`COUNTING_ENABLED=false`); la cola/worker/tabla existen pero inactivos hasta que el [repo del modelo](docs/reference/description_proyecto_modelo_conteo_plantas.md) publique el artefacto `agrovision-plantcount` en Hugging Face Hub. **Licencia: AGPL-3.0.**
+
+## Módulos (6)
+
+Resumen de Campo · Creación de Parcelas · Teledetección · Conteo por Dron (en desarrollo) · Asistente Agéntico · Credenciales.
+
+## Arquitectura
+
+```
+Astro + Tailwind (UI, Fase 8)  ──HTTP /api──►  FastAPI (monolito modular)  ──►  Supabase (PostGIS) [BYOK]
+   (Shiny = legacy en /shiny)                    ├─ /api/fields    (parcelas)        ├─ Sentinel Hub / Copernicus (NDVI)
+                                                  ├─ /api/ndvi(+raster), /api/weather  ├─ Open-Meteo (clima, sin llave)
+                                                  ├─ /api/chat      (agente RAG)        └─ Groq / Llama 3 (LLM)
+                                                  └─ /api/count     (conteo, en desarrollo)
+```
 
 ## Estructura
 
 ```
-backend/    # FastAPI: config, schemas, core (detection, metrics, inference), api/count, main
-frontend/   # Shiny for Python: app.py (Conteo en standby + Credenciales efímeras)
-tests/      # unit · integration · e2e (Playwright, skip por defecto)
-models/     # artefacto .onnx (no versionado; se descarga de HF Hub)
-sample_data/# ortomosaicos de ejemplo (no versionados)
-docs/       # documentación (reference/architect/db versionados; plan/task/investigation no)
+backend/    # FastAPI: api/ (routers por dominio) · services/ (negocio) · core/ (dominio puro) · db/ (PostGIS) · main
+frontend/   # UI Shiny (legacy) → migrando a Astro + Tailwind (Fase 8)
+supabase/   # migraciones SQL (PostGIS, índices, RLS, PGMQ)
+tests/      # unit · integration (Supabase/Copernicus/Groq, skip sin llaves) · e2e
+docs/       # reference/architect/db versionados; plan/task/investigation/doc_guia no
 ```
 
-## Arranque rápido (local)
+## Arranque rápido (local, sin Docker)
 
 > **Windows + OneDrive:** la carpeta está sincronizada por la nube, lo que rompe los *hardlinks* y bloquea el `.venv`. Crea el entorno **fuera** de OneDrive:
 > ```powershell
 > $env:UV_PROJECT_ENVIRONMENT = "$env:LOCALAPPDATA\agrovision-venv"
 > ```
-> (El `link-mode = "copy"` ya está fijado en `pyproject.toml`.)
+> (El `link-mode = "copy"` ya está en `pyproject.toml`.)
 
-```bash
-# 1) Dependencias (uv)
+```powershell
+# 1) Dependencias
 uv sync
 
-# 2) Backend (FastAPI) en :8000   — o usa scripts/run_backend.ps1
-uv run python -m uvicorn backend.main:app --reload --port 8000
+# 2) (una vez, si usarás parcelas) configurar DATABASE_URL en .env y aplicar migraciones
+uv run python -m backend.db.migrate
 
-# 3) UI (Shiny, ASGI) en :8001 (otra terminal) — o usa scripts/run_ui.ps1
-uv run python -m uvicorn frontend.app:app --reload --port 8001
-```
+# 3) Backend (FastAPI) en :8000  — o scripts/run_backend.ps1
+uv run python -u -m uvicorn backend.main:app --reload --port 8000 --log-level info
 
-> En Windows/OneDrive se usa `python -m uvicorn` en vez de los shims `uvicorn.exe`/`shiny.exe` (que la sincronización en la nube bloquea). La app Shiny es ASGI, así que `uvicorn frontend.app:app` equivale a `shiny run frontend/app.py`.
+# 4) UI en :8001 (otra terminal) — o scripts/run_ui.ps1
+uv run python -u -m uvicorn frontend.app:app --reload --port 8001
+# Atajo: ambos en ventanas separadas
+.\scripts\dev.ps1
+```
 
-```bash
-# Atajo: levantar backend + UI en ventanas separadas
-./scripts/dev.ps1
+Detalle completo (credenciales por módulo, migraciones, troubleshooting): **[`docs/ejecucion.md`](docs/ejecucion.md)**.
 
-# 4) Calidad y pruebas
-uv run ruff check .
-uv run ruff format --check .
-uv run pytest
-```
+## Credenciales BYOK (capa gratuita)
 
-Con Docker:
+| Servicio | Habilita | Variable(s) en `.env` |
+|----------|----------|------------------------|
+| **Supabase** (PostGIS) | Parcelas, Teledetección, Resumen | `DATABASE_URL`, `SUPABASE_URL`, `SUPABASE_ANON_KEY` |
+| **Copernicus CDSE** | NDVI satelital + heatmap | `DEV_COPERNICUS_CLIENT_ID`, `DEV_COPERNICUS_CLIENT_SECRET` |
+| **Groq** | Asistente RAG | `DEV_GROQ_API_KEY` |
+| Open-Meteo | Clima | — (sin llave) |
 
-```bash
-docker compose up --build   # api en :8000, ui en :8001
-```
+La app abre **sin** credenciales; cada módulo se activa al poner su llave (en `.env` local o en la pestaña *Credenciales*).
 
-## Activar el conteo (cuando el modelo esté publicado)
+## Calidad y pruebas
 
-1. Publicar `agrovision-plantcount-vX.Y.Z.onnx` en Hugging Face Hub (repo del modelo).
-2. Descomentar el bloque `hf_hub_download` en [`backend/Dockerfile`](backend/Dockerfile).
-3. Poner `COUNTING_ENABLED=true` y `MODEL_ARCHITECTURE` (`yolo26n`/`rfdetr_nano`).
-4. Implementar el decode correspondiente en [`backend/core/inference.py`](backend/core/inference.py).
+```powershell
+uv run ruff check .
+uv run python -m pytest                 # unit + integración (skip sin llaves)
+uv run python -m pytest tests/unit -q   # solo unitarias (rápidas)
+```
 
 ## Documentación
 
-- Spec funcional: [`docs/reference/description_proyecto_agrovision_mvp.md`](docs/reference/description_proyecto_agrovision_mvp.md)
-- Arquitectura: [`docs/architect/architecture_agrovision_mvp.md`](docs/architect/architecture_agrovision_mvp.md)
+- Definición: [`docs/reference/description_proyecto_agrovision.md`](docs/reference/description_proyecto_agrovision.md)
+- Arquitectura: [`docs/architect/architecture_agrovision.md`](docs/architect/architecture_agrovision.md)
+- Diseño de BD: [`docs/db/diseno_db.md`](docs/db/diseno_db.md)
+- Ejecución (runbook): [`docs/ejecucion.md`](docs/ejecucion.md)

docs/architect/architecture_agrovision.md

@@ -7,6 +7,8 @@
 >
 > **Módulos de UI (6):** Resumen de Campo · **Creación de Parcelas** (nuevo: dibujo del polígono) · Teledetección (solo gráficos + heatmap NDVI) · Conteo por Dron (**en desarrollo / standby**) · Asistente Agéntico · Credenciales.
 >
+> **Frontend (Fase 8 — Agro-Stack):** la UI migra de **Shiny** a **Astro + Tailwind** (SPA estática, hash-routing, responsive, sidebar/footer plegables) que replica el [mockup](../investigation/agrovisi_n_spa_prototype.html) y consume `/api/*` directo (Leaflet-draw para el mapa, Chart.js para NDVI/clima). El gateway **FastAPI sirve el build estático en `/`** y mantiene `/api`. **Shiny queda como _legacy_** (opcional en `/shiny`). Sigue la "Regla de Oro" de [`plan_replication.md`](../doc_guia/plan_replication.md) (una página, hash, rutas relativas, CSS inline).
+>
 > **Estado del Conteo:** el módulo de visión arranca **en desarrollo** (`COUNTING_ENABLED=false`); se construye **todo lo demás** ahora. La tabla `plant_counts`, la cola PGMQ y el worker se crean pero quedan inactivos hasta publicar el modelo.
 
 ---
@@ -261,3 +263,4 @@ flowchart LR
 | **NDVI por defecto a 5 años con agregación mensual** | Rango corto fijo / sin agregación (todas las escenas) | Da histórico útil para "Resumen de campo" y el agente, y mantiene el volumen bajo el límite de Supabase Free; el backfill incremental evita recalcular. |
 | **Heatmap NDVI satelital (~10 m/px) on-demand, sin persistir** | Persistir rásters NDVI / heatmap cm/px desde RGB | El ráster es pesado y efímero (se regenera); cm/px exige dron multiespectral (NIR), no disponible con RGB → se difiere con el módulo de Conteo. |
 | **Conteo por dron arranca EN DESARROLLO (toda la infra creada, inactiva)** | Bloquear la plataforma hasta tener el modelo | Permite entregar parcelas/teledetección/agente ya; la cola/worker/tabla existen para activarse con solo `COUNTING_ENABLED=true` cuando el repo del modelo publique el artefacto. |
+| **(Fase 8) UI migra a Astro + Tailwind (Agro-Stack); Shiny → legacy** | Mantener Shiny como UI principal / shell híbrido con iframe | La UI Shiny por defecto se ve básica; el objetivo es replicar el mockup (estética, **responsive**, plegables). Astro+Tailwind+JS (Leaflet/Chart.js) consumiendo `/api` da control total del look y deploy estático. **Revisa el ADR previo** ("Shiny sobre Astro"): el problema de enrutamiento SPA se mitiga con la **Regla de Oro** (una página, hash-routing, rutas relativas, CSS inline). Shiny se conserva como *legacy* (`/shiny`) por si se requiere reactividad Python. |