betting-analytics/AGENTS.md

---
id: "AGENTS-BA"
title: "Guia para Agentes IA - Betting Analytics"
project: "betting-analytics"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---

# AGENTS.md - Betting Analytics

Guia de trabajo para agentes de IA en el proyecto Betting Analytics.

---

## 1. INFORMACION DEL PROYECTO

| Campo | Valor |
|-------|-------|
| **Nombre** | Betting Analytics |
| **Prefijo** | BA |
| **Estado** | Planificacion |
| **Stack Backend** | NestJS + TypeORM + PostgreSQL |
| **Stack Frontend** | React + Vite + TypeScript |
| **Stack ML** | Python + FastAPI |
| **Repositorio** | betting-analytics |

---

## 2. UBICACIONES CLAVE

### Codigo Fuente

```
apps/
├── backend/          # API NestJS (Puerto 3090)
│   └── src/
│       ├── modules/  # Modulos de negocio
│       ├── config/   # Configuracion
│       └── shared/   # Tipos compartidos
├── frontend/         # Aplicacion React (Puerto 80)
└── ml/               # Servicio ML Python (Puerto 3093)
```

### Documentacion

```
docs/
├── 00-vision-general/           # Vision y arquitectura
├── 01-fase-alcance-inicial/     # EPICs MVP
│   └── BA-001-fundamentos/      # EPIC fundamentos
├── 04-fase-backlog/             # DoR, DoD, backlog
├── 90-transversal/              # Inventarios, arquitectura
├── 95-guias-desarrollo/         # Guias dev
├── 96-quick-reference/          # Cheatsheets
├── 97-adr/                      # ADRs
├── planning/                    # Board, config, tasks
└── archivados/                  # Historicos
```

### Orchestration

```
orchestration/
├── agents/           # Configuracion de agentes
├── contexto/         # Contexto del proyecto
├── directivas/       # Directivas especificas
└── templates/        # Templates del proyecto
```

---

## 3. NOMENCLATURA

### Prefijos por Tipo

| Tipo | Prefijo | Ejemplo |
|------|---------|---------|
| EPIC | BA-NNN | BA-001-fundamentos |
| Requerimiento | RF-BA-NNN | RF-BA-001 |
| Especificacion | ET-BA-NNN | ET-BA-001 |
| Historia Usuario | US-BA-NNN | US-BA-001 |
| Tarea | TASK-BA-NNN | TASK-BA-001 |
| Bug | BUG-BA-NNN | BUG-BA-001 |
| ADR | ADR-NNN | ADR-001 |

### Modulos Identificados

| Modulo | Sufijo | Descripcion |
|--------|--------|-------------|
| AUTH | AUTH | Autenticacion y autorizacion |
| DATA | DATA | Ingestion de datos |
| ANALYTICS | AN | Analisis estadistico |
| PREDICTIONS | PRED | Modelos predictivos ML |
| REPORTING | REP | Reportes y visualizaciones |

---

## 4. FLUJO DE TRABAJO

### Tomar una Tarea

1. Revisar `docs/planning/Board.md` - columna "Por Hacer"
2. Leer archivo TASK correspondiente en `docs/planning/tasks/`
3. Actualizar YAML front-matter:
   ```yaml
   status: "In Progress"
   assignee: "@NombreAgente"
   ```
4. Commit: `Start TASK-BA-XXX: [descripcion]`

### Completar una Tarea

1. Verificar criterios de aceptacion cumplidos
2. Actualizar YAML front-matter:
   ```yaml
   status: "Done"
   completed_date: "YYYY-MM-DD"
   actual_hours: X
   ```
3. Mover tarea en Board.md a "Hecho"
4. Commit: `Complete TASK-BA-XXX: [descripcion]`

### Reportar un Bug

1. Crear archivo en `docs/planning/bugs/BUG-BA-XXX.md`
2. Incluir YAML front-matter completo
3. Agregar a Board.md en seccion de bugs
4. Commit: `Report BUG-BA-XXX: [descripcion]`

---

## 5. FORMATO YAML REQUERIDO

### Historia de Usuario

```yaml
---
id: "US-BA-001"
title: "Titulo descriptivo"
type: "User Story"
status: "To Do"
priority: "Alta"
epic: "BA-001"
story_points: 5
labels: ["modulo", "feature"]
created_date: "YYYY-MM-DD"
updated_date: "YYYY-MM-DD"
---
```

### Tarea

```yaml
---
id: "TASK-BA-001"
title: "Descripcion tarea"
type: "Task"
status: "To Do"
priority: "P1"
parent_us: "US-BA-001"
estimated_hours: 4
assignee: ""
created_date: "YYYY-MM-DD"
---
```

### Bug

```yaml
---
id: "BUG-BA-001"
title: "Descripcion bug"
type: "Bug"
status: "Open"
severity: "P1"
priority: "Alta"
affected_module: "Backend"
steps_to_reproduce:
  - "Paso 1"
  - "Paso 2"
expected_behavior: "..."
actual_behavior: "..."
created_date: "YYYY-MM-DD"
---
```

---

## 6. ESTADOS VALIDOS

### User Stories

| Estado | Descripcion |
|--------|-------------|
| Backlog | No planificada |
| To Do | Planificada para sprint |
| In Progress | En desarrollo |
| In Review | En revision |
| Done | Completada |

### Tasks

| Estado | Descripcion |
|--------|-------------|
| To Do | Pendiente |
| In Progress | En desarrollo |
| Blocked | Bloqueada |
| Done | Completada |

### Bugs

| Estado | Descripcion |
|--------|-------------|
| Open | Reportado |
| In Progress | En investigacion |
| Fixed | Corregido |
| Done | Verificado |
| Won't Fix | No se corregira |

---

## 7. CONVENCIONES DE CODIGO

### Backend (NestJS)

- Modulos en `src/modules/{nombre}/`
- Entidades con decorador `@Entity()`
- DTOs con decoradores class-validator
- Servicios inyectables con `@Injectable()`

### Frontend (React)

- Componentes en PascalCase
- Hooks con prefijo `use`
- Estado global con Zustand (pendiente)

### Base de Datos

- Tablas en snake_case
- PKs: `id` tipo UUID
- Timestamps: `created_at`, `updated_at`
- Soft delete: `deleted_at`

---

## 8. COMANDOS UTILES

### Backend

```bash
cd apps/backend
npm run start:dev       # Desarrollo
npm run build           # Build produccion
npm run test            # Tests unitarios
npm run lint            # Linter
```

### Docker

```bash
docker-compose up -d    # Levantar servicios
docker-compose logs -f  # Ver logs
docker-compose down     # Detener servicios
```

---

## 9. REFERENCIAS

- **Documentacion:** `docs/README.md`
- **Mapa Navegacion:** `docs/_MAP.md`
- **Board Activo:** `docs/planning/Board.md`
- **Configuracion:** `docs/planning/config.yml`
- **ADRs:** `docs/97-adr/`

---

## 10. CONTACTO

| Rol | Responsable |
|-----|-------------|
| **Product Owner** | @PO-Agent |
| **Backend Lead** | @Backend-Agent |
| **Frontend Lead** | @Frontend-Agent |
| **ML Lead** | @ML-Agent |

---

**Generado:** 2026-01-04
**Sistema:** NEXUS v3.4 + SIMCO + SCRUM
**Uso:** Guia de trabajo para agentes IA