From 8fb3b2d9b807b3af7837d80ca7936067716946a2 Mon Sep 17 00:00:00 2001 From: santidev21 Date: Wed, 30 Sep 2026 15:53:46 -0500 Subject: [PATCH] chore(docs): drop session logs, add ADR home and a doc policy - Delete docs/progress.md and docs/implementation-plan.md (phase narration) - Add docs/adr/ (decisions already live in docs/specs/decisions.md) - Add Documentation Policy to AGENTS.md; forbid phase reports and progress logs - Point roadmap to known-issues for the pending hardening items - Remove stale progress.md references in specs and the plan --- AGENTS.md | 13 +++- docs/adr/README.md | 12 ++++ docs/implementation-plan.md | 111 --------------------------------- docs/progress.md | 74 ---------------------- docs/specs/folder-structure.md | 3 +- docs/specs/roadmap.md | 9 ++- 6 files changed, 33 insertions(+), 189 deletions(-) create mode 100644 docs/adr/README.md delete mode 100644 docs/implementation-plan.md delete mode 100644 docs/progress.md diff --git a/AGENTS.md b/AGENTS.md index 236a14f..3dae4b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ Billard-system/ ├─ frontend/ # Angular 22 application (src/app: core, features, shared) ├─ camera-bridge/ # Local LAN camera bridge (Node): discovery + CORS proxy for go2rtc ├─ deploy/ # Nginx config, deployment guide -├─ docs/ # Guides, screenshots, specs (docs/specs/) +├─ docs/ # Guides, specs, ADRs (docs/specs/, docs/adr/) ├─ .opencode/ # AI home: agent/, command/, skills/ (tracked; local plugin scaffold ignored) ├─ .github/ # CI/CD workflows ├─ Dockerfile # Multi-stage single-image build @@ -59,6 +59,17 @@ Angular 22 SPA in `frontend/src/app` (`core/` auth/API/SignalR/models, `features - `opencode.json` holds instructions, MCP servers and permissions. Skills, agents and commands need no config — opencode auto-discovers `.opencode/`. - `AGENTS.md` is the single source of truth; `docs/specs/` holds details. +## Documentation Policy + +Docs capture decisions and current state, never session narration. + +- **Allowed:** `README` (how to run), `docs/adr/NNN-*.md` (one decision: context, options, decision, + consequences), `docs/specs/*.md` (current design and business rules), runbooks (`DEPLOY.md`, …) + and any current audit/security doc. +- **Forbidden:** phase reports, progress logs, "what I did" narration and per-session summaries. + When a change needs a durable record, update the relevant spec or add an ADR — do not create a + report file. This applies to AI output too. + ## Working Rules For This Repo - Language: all code, comments, XML docs, tests, commit messages, PR titles/descriptions, docs (`README`, `docs/`, `AGENTS.md`), and AI output must be in English. Only user-facing UI strings may be in Spanish (via i18n files), never hardcoded Spanish in code/comments. - Prefer small, focused changes. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..c4ca571 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,12 @@ +# Architecture Decision Records + +One file per irreversible or costly decision: `NNN-title.md` with **Context**, **Options**, +**Decision** and **Consequences**. Written by the human, in a few paragraphs — not generated as a +report. + +Use an ADR when a choice is hard to reverse or future-you needs the *why* (token strategy, schema, +real-time transport, deployment). For everyday changes, update the relevant [spec](../specs/) and +the code instead. + +To backfill: the opaque 30-day sliding token sessions (vs JWT) and the SQLite domain model / EF +outbox shape are good first candidates. diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md deleted file mode 100644 index 1becfb9..0000000 --- a/docs/implementation-plan.md +++ /dev/null @@ -1,111 +0,0 @@ -# Plan de Arquitectura e Implementación: Sistema de Administración de Mesas de Billar Tres Bandas (V3 - Con Documentación AI) - -Este documento presenta el diseño de software profesional, arquitectura limpia y plan de implementación detallado para el **Sistema de Administración de Mesas de Billar Tres Bandas**, incorporando el sistema de documentación técnica incremental para IA en `/ai-content`, auditoría, arquitectura orientada a eventos (Event Bus), resiliencia offline, catálogo dinámico de productos, dashboard administrativo, buffer de video configurable y soporte para desarrollo/producción. - ---- - -## 1. Documentación Técnica Incremental para IA (`/ai-content`) - -Todo el proyecto contará con una carpeta de contexto vivo en la raíz de la solución: `c:\Dev\Billard-system\ai-content`. Esta documentación se mantendrá actualizada continuamente con cada avance para permitir que cualquier sesión de IA o desarrollador continúe el proyecto sin perder contexto. - -``` -/ai-content -├── 00-project-overview.md -├── 01-architecture.md -├── 02-tech-stack.md -├── 03-folder-structure.md -├── 04-database.md -├── 05-api-endpoints.md -├── 06-signalr-events.md -├── 07-domain-events.md -├── 08-business-rules.md -├── 09-authentication.md -├── 10-video-buffer.md -├── 11-testing.md -├── 12-deployment.md -├── 13-roadmap.md -├── 14-known-issues.md -├── 15-decisions-log.md -└── progress.md -``` - ---- - -## 2. Modos de Ejecución del Sistema - -1. **Modo Desarrollo (Dev Mode)**: - - **Frontend (Angular 19+)**: Ejecutándose de forma independiente con `ng serve` (puerto 4200) con Hot-Reload y Proxy (`proxy.conf.json`) hacia la API. - - **Backend (.NET API)**: Ejecutándose en `http://localhost:5000` con CORS habilitado para `localhost:4200` y Swagger UI habilitado. -2. **Modo Producción (Prod Mode - "Single Binary Launch")**: - - La aplicación Angular se compila a archivos estáticos (`dist/billiard-frontend/browser`). - - El proyecto ASP.NET Core API sirve los archivos estáticos mediante middleware `UseStaticFiles()` y fallback SPA routing (`MapFallbackToFile("index.html")`). - - **Resultado**: El cliente ejecuta una sola aplicación `.exe` en Windows y todo funciona sin instalar Node.js ni IIS. - ---- - -## 3. Arquitectura de Software: Clean Architecture + Event-Driven (Event Bus) - -```mermaid -graph TD - UI[Player & Admin Apps - Angular] -->|Commands & SignalR| API[BilliardSystem.API Controllers & Hubs] - API --> Application[Application Use Cases / MediatR] - Application --> EventBus[Event Bus / Domain Event Publisher] - - EventBus --> DBHandler[DB Audit & State Handler] - EventBus --> SignalRHandler[SignalR Real-Time Broadcaster] - EventBus --> StatsHandler[Stats & Metrics Aggregator] - - DBHandler --> Infrastructure[BilliardSystem.Infrastructure - EF Core / SQLite] - SignalRHandler --> UI -``` - -### Domain Events -`SessionStartedEvent`, `PlayerScoredEvent`, `PlayerNameChangedEvent`, `ConsumptionAddedEvent`, `WaiterRequestedEvent`, `CheckRequestedEvent`, `ReplayRequestedEvent`, `SessionEndedEvent`, `AuditLoggedEvent`. - ---- - -## 4. Módulos Clave del Sistema - -1. **Configuración Global**: Tarifas por defecto, duración de buffer de replay (30s a 5m), calidad de video, branding (nombre, logo, colores, idioma), catálogo de productos y mesas. -2. **Usuarios, Roles y Auditoría**: Roles `Administrador` y `Empleado`. Auditoría de cada acción (`AuditLogs`). -3. **Dashboard Administrativo**: KPIs en vivo (mesas libres/ocupadas, total ventas hoy, tiempo promedio), gráfica de productos más vendidos y monitor de mesas. -4. **Resiliencia Offline**: Cola de comandos en `IndexedDB`/`LocalStorage` con deduplicación por GUID al restablecer conexión SignalR. -5. **Historial Enriquecido**: Guardado completo con versión del sistema, quien cerró la partida, carambolas totales, desglose de tiempo y consumos. -6. **Buffer Circular Configurable**: Retención en memoria RAM de fragmentos de video (30s a 5m) sin interrumpir la grabación de la cámara USB. - ---- - -## 5. Modelo de Datos (EF Core / SQLite) - -Tablas: `Tables`, `Users`, `AuditLogs`, `Settings`, `Categories`, `Products`, `MatchHistories`, `MatchScoreLogs`, `MatchConsumptions`. - ---- - -## 6. Plan de Trabajo e Implementación por Fases - -### Fase 0: Inicialización & Estructuración de Documentación IA (`/ai-content`) -- [ ] Crear la estructura inicial completa de la carpeta `ai-content/` (00 al 15 + progress.md). -- [ ] Registrar las decisiones iniciales en `15-decisions-log.md` y establecer `progress.md`. - -### Fase 1: Backend Architecture, Event Bus & Base de Datos (.NET 8/9) -- [ ] Solución .NET en 4 proyectos (`Domain`, `Application`, `Infrastructure`, `API`). -- [ ] Implementar Event Bus interno y Domain Events. -- [ ] EF Core + SQLite con entidades de Auditoría, Configuración, Historial Enriquecido y Catálogo. -- [ ] SignalR Hub (`TableHub`) para broadcast en tiempo real. -- [ ] Controladores REST (Auth, Tables, Products, Matches, Settings, Audit, Dashboard). -- [ ] Actualización de documentación en `/ai-content`. - -### Fase 2: Frontend Angular (19+) Dev/Prod & Módulos -- [ ] Proyecto Angular con Standalone Components, Signals, RxJS y Proxy de desarrollo. -- [ ] **Player App**: Marcador de 3 bandas (Blanco/Amarillo), cronómetro reactivo, lista de consumos, campana y pedido de cuenta. -- [ ] **Cámara & Replay Configurable**: Buffer circular de 30s a 5m sin parar la grabación. -- [ ] **Modo Libre**: Long-Press (3s) + Modal Slide to Confirm. -- [ ] **Resiliencia Offline**: Client Command Queue con deduplicación por Transaction GUID. -- [ ] **Admin App & Dashboard**: Grid de mesas, métricas en vivo, catálogo de productos, gestión de usuarios, visor de auditoría. -- [ ] **Historial Enriquecido**: Consulta con detalle completo. -- [ ] Actualización de documentación en `/ai-content`. - -### Fase 3: Pruebas Automatizadas, Empaquetado Prod & Cierre -- [ ] Pruebas unitarias backend (xUnit) y frontend (Jasmine). -- [ ] Configurar build en modo producción (Servidor SPA `.exe`). -- [ ] Actualización final de `/ai-content` (`progress.md`, `testing.md`, `deployment.md`). diff --git a/docs/progress.md b/docs/progress.md deleted file mode 100644 index c07d19a..0000000 --- a/docs/progress.md +++ /dev/null @@ -1,74 +0,0 @@ -# Estado de Progreso del Proyecto (Progress) - -## Resumen de Avance -- **Porcentaje Estimado**: 5% -- **Fase Actual**: Fase 0 completada | Esperando aprobación para Fase 1 (Backend Architecture & Event Bus). -- **Último Cambio**: Inicialización completa de la suite de documentación técnica incremental para IA en `/ai-content` (Fase 0). - ---- - -## Detalle por Fases - -### Fase 0: Inicialización y Documentación IA (`/ai-content`) -- [x] Estructuración y creación de 17 archivos de contexto en `/ai-content`. -- [x] Registro de decisiones iniciales de arquitectura (ADR-001 a ADR-006). - -### Fase 1: Backend Architecture, Event Bus & Base de Datos (.NET 9) -- [ ] Solución .NET en 4 proyectos (`Domain`, `Application`, `Infrastructure`, `API`). -- [ ] Implementar Event Bus e `IDomainEvent`. -- [ ] Modelo de datos EF Core con SQLite (Entidades, Migraciones, Auditoría, Settings, MatchHistory enriquecido). -- [ ] Hub de SignalR (`TableHub`) para tiempo real. -- [ ] Endpoints REST (Auth, Tables, Matches, Products, Settings, Audit, Dashboard). -- [ ] Pruebas unitarias e integración con xUnit. - -### Fase 2: Frontend Angular (19+) Dev/Prod & Módulos -- [ ] Proyecto Angular 19+ con Standalone Components, Signals y Proxy Dev. -- [ ] Player App (Marcador 3 bandas blanco/amarillo, cronómetro, consumos, campana, pedido de cuenta). -- [ ] Módulo de Cámara & Replay Configurable (30s a 5m) en RAM. -- [ ] Modo Libre con seguridad anti-alcohol (Long-press 3s + Modal Slide). -- [ ] Resiliencia Offline y Cola de Comandos IndexedDB. -- [ ] Admin App (Grid mesas, métricas dashboard, productos, auditoría en vivo). -- [ ] Historial de partidas enriquecido. - -### Fase 3: Pruebas Automatizadas y Empaquetado Prod -- [ ] Pruebas de integración frontend y backend. -- [ ] Compilación SPA servida por API Kestrel (Ejecutable `.exe` único). - ---- - -## Siguiente Tarea Recomendada -Presentar el diseño técnico detallado de la **Fase 1 (Backend Architecture, Event Bus & Base de Datos)** al usuario para su revisión y aprobación antes de generar el código. ---- - -## Actualizacion 2026-08-04 - Fase 1 iniciada -- **Porcentaje estimado actualizado**: 18%. -- **Estado**: backend base compilable y probado. -- **Implementado**: - - Entidades de dominio para mesas, usuarios, auditoria, settings, catalogo, historial, scores y consumos. - - Eventos de dominio principales e interfaces `IDomainEvent`, `IDomainEventDispatcher`, `IDomainEventHandler`. - - `BilliardDbContext` con EF Core SQLite, seed inicial y `EnsureCreatedAsync`. - - `TableHub` SignalR con grupos `table:{tableId}`. - - Endpoints iniciales: `/api/health`, `/api/tables`, `/api/products`, `/api/settings`, `/api/dashboard/summary`. - - Tests xUnit iniciales para reglas de inicio de sesion de mesa. -- **Verificacion**: - - `dotnet build C:\Dev\Billard-system\backend\BilliardSystem.slnx` compila. - - `dotnet test C:\Dev\Billard-system\backend\BilliardSystem.slnx` pasa 2/2 tests fuera del sandbox. -- **Siguiente tarea recomendada**: implementar comandos de partida con auditoria e idempotencia por `TransactionId`. - -## Actualizacion 2026-08-08 - Arranque fijo, login por clave y cambio de clave -- **Arranque**: la API escucha siempre en `http://localhost:5000` (appsettings `Urls` + lauchSettings sincronizado), coincidiendo con el proxy de Vite. Nuevo `C:\Dev\Billard-system\start-dev.bat` que levanta API + frontend en dos ventanas. -- **Login simplificado**: solo "clave de ingreso" (sin usuario); primer login crea `AdminPassword`; `POST /api/auth/change-password` actualiza la clave con validacion de la clave actual. Modal "Cambiar clave" en el panel admin. -- Ver `09-authentication.md`, `05-api-endpoints.md`, `14-known-issues.md`. - -## Actualizacion 2026-08-07 - End-to-end funcional + real-time + fixes -- **Estado**: Fase 2 avanzada. Frontend (Player + Admin) y backend REST comunicados de extremo a extremo. 8/8 tests xUnit pasan. -- **Real-time**: broadcasts SignalR emitidos desde los endpoints REST; Player y Admin reaccionan a `TableStateUpdated` (fuente de verdad) y actualizan en vivo sin recargar (ver `06-signalr-events.md`). -- **Fixes**: - - Consumo total que solo mostraba el ultimo item (faltaba `.Include(Consumptions)` en el endpoint). - - Repeticion de video en gris (se conserva el chunk 0 = segmento WebM de inicializacion). - - Login primer uso (se removio `AdminPassword` residual de la BD). - - Altura de la pantalla del jugador completa (cadena `:host` flex + `.shell` min-height 0). -- **Tarifas globales**: `PUT /api/tables/rate/all` aplica una tarifa por hora a todas las mesas; el dashboard muestra una tarjeta "Tarifa por hora" con boton "Cambiar tarifa". -- **Historial de rondas**: `GET /api/tables/{id}/rounds` expone ronda por ronda (ganador/puntos) y el conteo de rondas ganadas por cada jugador; el jugador tiene el boton "Historial de Rondas". -- **Optimizacion de rendimiento**: camara a 720p/24fps/1.5Mbps, buffer default 30s, dashboard con debounce (350ms) y `Promise.all` para cargas paralelas. -- **Pendiente**: Autenticacion JWT real (token simple por ahora), paginacion/filtros de historial y auditoria, pruebas de integracion frontend. diff --git a/docs/specs/folder-structure.md b/docs/specs/folder-structure.md index 958d60b..10c4f0f 100644 --- a/docs/specs/folder-structure.md +++ b/docs/specs/folder-structure.md @@ -6,8 +6,7 @@ c:\Dev\Billard-system\ │ ├── 00-project-overview.md │ ├── 01-architecture.md │ ├── 02-tech-stack.md -│ ├── ... -│ └── progress.md +│ └── ... ├── backend/ # Solución C# / .NET 9 │ ├── BilliardSystem.sln │ ├── src/ diff --git a/docs/specs/roadmap.md b/docs/specs/roadmap.md index ae42ec3..61835d8 100644 --- a/docs/specs/roadmap.md +++ b/docs/specs/roadmap.md @@ -7,7 +7,14 @@ - Promedio de carambolas por partida y tacada máxima. - Gráficas de rendimiento histórico por jugador y por mesa. - Tiempos de ocupación pico por día, semana y mes. -2. **Integración con Cámaras IP y Múltiples Ángulos**: + +2. **Hardening pendiente** (ver [known-issues.md](known-issues.md)): + - Autenticación JWT real (hoy token opaco). + - Paginación/filtros de historial y auditoría. + - Pruebas de integración frontend. + - Pasar `EnsureCreatedAsync` a migraciones EF. + +3. **Integración con Cámaras IP y Múltiples Ángulos**: - Soporte para transmisión RSTP / WebRTC desde cámaras de red IP. - Selección de múltiples cámaras por mesa (ej. cámara superior + cámara lateral). - _Estado 2026-09-30_: primera versión en LAN (descubrimiento + WebRTC + auto-H.264) en [ip-cameras.md](ip-cameras.md). Pendiente: bridge por HTTPS para usarlo desde otros dispositivos y selección por mesa.