betting-analytics/AGENTS.md

id	title	project	version	created_date	updated_date
AGENTS-BA	Guia para Agentes IA - Betting Analytics	betting-analytics	1.0.0	2026-01-04	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:

   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:

   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

---
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

---
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

---
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

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

Docker

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