pokemontcg-live

Imported from MartuTahir/pokemontcg-live (AGENTS.md). Install upstream with npx skills add MartuTahir/pokemontcg-live. Copyright stays with the author.

AGENTS.md — Pokémon TCG (TPI Programación III)

Reglas que cualquier agente de IA (Claude Code, Cursor, Codex, OpenCode, Copilot, Gemini CLI, Windsurf) y dev humano debe respetar al trabajar en este repo. Loadeado automáticamente al inicio de cada sesión — esto es la "constitución" del proyecto.

Este archivo es un índice + las reglas críticas mínimas. Para detalle completo, ir a los archivos de docs/ linkeados.

Contexto del proyecto

Trabajo Práctico Integrador (TPI) de Programación III — TUP, UTN-FRC. Implementar el Pokémon TCG completo, dos jugadores en tiempo real, con backend Java/Spring Boot + frontend Angular, integrando la API pública pokemontcg.io (set base xy1, 146 cartas).

Reglas del juego = XY1 Rulebook oficial (PDF adjunto al TPI) destilado en docs/game-rules.md.

Equipo: 7 personas con workflow GitFlow.

Índice de la documentación

Reglas críticas (siempre activas)

Estas son las que más fácil se olvidan o más fácil rompen el TPI. Si el usuario te pide algo que las viola, frená y confirmá antes de implementar.

1. Naming y dominio

• Pokémon TCG = nombre del producto. No decirle "el juego" en código sin contexto.
• Game Engine = motor de reglas. Vive en su propio módulo (com.pokemontcg.engine), aislado del transporte (sin imports a Spring REST/WebSocket desde adentro).
• Carta ≠ CartaEnJuego. La carta es la definición inmutable (viene de pokemontcg.io); CartaEnJuego es la instancia con estado runtime (HP actual, energías unidas, condiciones).
• Jugador ≠ Usuario. El Usuario tiene cuenta; el Jugador es su participación en una Partida.
• Tipos de carta canónicos: POKEMON_BASICO, POKEMON_FASE_1, POKEMON_FASE_2, POKEMON_EX, ENERGIA_BASICA, ENERGIA_ESPECIAL, ENTRENADOR_OBJETO, ENTRENADOR_AS_TACTICO, ENTRENADOR_PARTIDARIO, ENTRENADOR_ESTADIO, ENTRENADOR_HERRAMIENTA.

→ Detalle en docs/product.md.

2. Backend es la única fuente de verdad

• Toda decisión de juego se valida y ejecuta en el backend. Sin excepciones.
• El frontend es únicamente una capa de presentación: muestra estado, captura intentos del usuario, envía requests. Nunca decide si una acción es válida.
• La mano del oponente NUNCA se envía al cliente — solo la cantidad de cartas.
• El orden del mazo y el contenido de las cartas de Premio permanecen ocultos hasta el momento que las reglas indiquen.

→ Detalle en docs/architecture.md.

3. Reglas del juego (no negociables)

• Implementar exactamente las reglas RF-01 a RF-07 del TPI y los detalles del XY1 Rulebook.
• Set obligatorio: xy1 (XY Unlimited, 146 cartas). Otras expansiones = opcional, suma bonus.
• Restricciones del mazo: exactamente 60 cartas · máximo 4 copias del mismo nombre (excepto Energía Básica, sin límite) · al menos 1 Pokémon Básico. (La regla "máximo 1 AS TÁCTICO por mazo" NO aplica: xy1 no contiene cartas ACE SPEC. Solo aplica si se agrega opcionalmente un set que las incluya — criterio de cátedra 2026-06-04.)
• Orden de procesamiento entre turnos: (1) Envenenado → (2) Quemado → (3) Dormido → (4) Paralizado. Después chequear KO.
• Compatibilidad de condiciones: Dormido/Confundido/Paralizado son mutuamente excluyentes; Quemado y Envenenado son independientes y pueden coexistir entre sí y con cualquiera de las otras tres.
• Cálculo de daño sigue la secuencia exacta de RF-01c (base → modificadores atacante → debilidad ×2 → resistencia −20 → modificadores defensor → contadores).

→ Detalle COMPLETO en docs/game-rules.md. Es el contrato del motor.

4. Patrones de diseño obligatorios (RNF-04)

Los siguientes patrones deben estar aplicados y serán evaluados:

• State — estados del turno (DRAW, MAIN, ATTACK, BETWEEN_TURNS) y estados de partida (WAITING, SETUP, ACTIVE, FINISHED).
• Strategy — efectos de cada tipo de carta de Entrenador y efectos de cada ataque. Una EffectStrategy por tipo.
• Chain of Responsibility — pipeline de resolución de ataque (los 7 pasos de RF-01c).
• Observer — notificación de eventos vía WebSocket a ambos clientes (knockout, toma de premio, condición aplicada, fin de turno).
• Repository — capa de acceso a datos (cartas, mazos, estado de partida).
• Facade — el GameEngine expone una API interna simple al resto de la aplicación, ocultando la complejidad del motor de reglas.

El Game Engine debe estar completamente aislado e independiente del transporte (REST/WebSocket), siguiendo inversión de dependencias.

→ Detalle en docs/architecture.md.

5. Componentes core del Game Engine (testeables independientes)

• RuleValidator — valida toda acción contra las reglas. Cobertura ≥ 90%.
• DamageCalculator — implementa la secuencia de cálculo de daño. Cobertura ≥ 90%.
• StatusEffectManager — aplica y procesa condiciones especiales. Cobertura ≥ 90%.
• VictoryConditionChecker — chequea las 3 condiciones de victoria + muerte súbita.
• TurnManager — orquesta las fases del turno y transiciones de estado.

Cada uno en su propia clase, con interface, mockeable. Sin acoplamiento entre ellos por implementación.

6. Out of scope (NO implementar)

• Cualquier set de cartas que no sea xy1 (otras expansiones = mejora opcional).
• Sistema de cuentas con login social, perfiles públicos, amistades.
• Trading / intercambio de cartas entre usuarios.
• Compras / monetización / lootboxes.
• Modo offline / single-player vs IA.

Si el usuario pide alguno → frená y confirmá.

7. Quality gates (antes de cada commit)

Backend (Java/Maven):

Comando canónico: ./mvnw (Maven Wrapper), no mvn. El wrapper fija Maven 3.9.9 para todo el equipo y el CI, sin depender del Maven instalado localmente. En Windows usar mvnw.cmd.

1. ./mvnw clean verify → tests verdes + JaCoCo report generado.
2. Cobertura global ≥ 80%. Cobertura RuleValidator/DamageCalculator/StatusEffectManager ≥ 90%.
3. Sin warnings de compilación. Sin vulnerabilidades CRITICAL/HIGH (./mvnw dependency-check:check).
4. Swagger/OpenAPI actualizado si se agregan/modifican endpoints.

Frontend (Angular):

1. ng lint → 0 errores.
2. ng build --configuration=production → build verde.
3. ng test --watch=false --code-coverage → tests verdes.
4. TypeScript estricto (strict: true en tsconfig). Sin any salvo justificado en comentario.

Antes del PR:

5. Tests E2E del flujo cubierto pasan.
6. README de la feature actualizado si aplica.

→ Detalle en docs/workflow.md y docs/testing.md.

8. GitFlow y PRs

• Workflow obligatorio: GitFlow (main ← develop ← feature/*, release/*, hotfix/*).
• Nadie pushea directo a develop ni main.
• Una rama por feature. Naming: feature/<scope>-<descripción-kebab> (ej feature/engine-damage-calculator).
• PR contra develop con mínimo 2 approves (somos 7, podemos darnos el lujo). Squash and merge.
• Code review obligatorio. Los componentes del Game Engine requieren approve de al menos 1 dev distinto al autor.
• Cambios no triviales → ciclo SDD opcional con /sdd-new <name> (gentle-ai). Recomendado para Game Engine y WebSockets.
• Si modificás AGENTS.md, docs/game-rules.md o docs/api-contract.md → reviewer aprueba explícitamente la modificación del contrato.

→ Detalle en docs/workflow.md.

9. Memoria persistente

Engram MCP (si está configurado) guarda decisiones bajo --project pokemon-tcg-tpi. Es local por dev/máquina — para decisiones team-wide, escribirlas en docs/ y commitear.

Decisiones críticas que SIEMPRE van a docs/ (no a Engram):

• Cambios en docs/game-rules.md (interpretaciones de las reglas oficiales).
• Cambios en docs/api-contract.md (contratos REST/WebSocket).
• Cambios en docs/architecture.md (capas, patrones, módulos).

→ Detalle en docs/architecture.md.

Tecnologías obligatorias (del TPI)

• Backend: Java 21+ · Spring Boot 3.x · Maven · JUnit 5 · Mockito · JaCoCo · Swagger/OpenAPI.
• Frontend: Angular 21+ · TypeScript estricto · RxJS.
• Base de datos: PostgreSQL (preferida) o MySQL.
• Comunicación en tiempo real: WebSockets sobre Spring (spring-boot-starter-websocket).
• API externa: pokemontcg.io v2 (con caché local obligatorio).
• Control de versiones: Git + GitHub + GitFlow.

Setup desde una máquina nueva

git clone <REPO_URL>
cd pokemon-tcg-tpi

# Backend
cd backend
./mvnw clean install
./mvnw spring-boot:run

# Frontend (en otra terminal)
cd ../frontend
npm install
npm start

→ Onboarding completo en CONTRIBUTING.md.

Estado actual del roadmap

• Fase 0 — Setup del repo, monorepo backend+frontend, DB, CI básico.
• Fase 1 — Modelado del dominio + integración pokemontcg.io con caché.
• Fase 2 — Game Engine core (RuleValidator + DamageCalculator + StatusEffectManager).
• Fase 3 — Deck Builder (backend + frontend).
• Fase 4 — Persistencia de partida + matchmaking.
• Fase 5 — WebSockets + sincronización de estado.
• Fase 6 — Tablero interactivo (frontend) + drag & drop.
• Fase 7 — Testing + cobertura + documentación.
• Fase 8 — Bonus opcionales (Megaevolución, animaciones, chat, ranking).

→ Detalle por fase en docs/roadmap.md.