Josep Piguillem
9236cb73c6
New app apps/mcp (NestJS + @nestjs-mcp/server 2): Streamable HTTP at POST /mcp, stateless. - 24 tools: projects (mine, public, details with settings, board, stats, analytics, activity), tickets (my work, search, details with comments and history, create, update, move, assign, release, comment, link), releases (list, upcoming, details with progress and burnup, create, publish) and users (whoami, search). Admin operations stay in the web. - No credentials of its own: each call's Authorization header (a Pireon token) is forwarded to the API; without it only public projects are read. - Typed REST client generated from apps/api/openapi.json (openapi-fetch + openapi-typescript via `nx run mcp:openapi-types`); API refusals become readable tool errors; parameters validated with zod. - Tests: the real MCP against a simulated API (token forwarding, errors, validation, writes). - Docker target `mcp` (Node 24) and an optional compose service under the `mcp` profile; zod declared as a root dependency. - Docs: chapter 9 «Servidor MCP», references in 01/06/07 and the index; Word/PDF regenerated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
67 lines
6.3 KiB
Markdown
67 lines
6.3 KiB
Markdown
# 1. Visión general
|
||
|
||
## Qué resuelve
|
||
|
||
| Necesidad | Cómo se resuelve |
|
||
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 🐛 Bugs | Tickets de tipo `BUG` con prioridad, área y etiquetas |
|
||
| 🌍 Públicos | Un proyecto público se puede leer sin iniciar sesión (web, GraphQL y REST): tablero, tickets, comentarios, releases, actividad y estadísticas; «Explorar» los lista |
|
||
| 🗑️ Borrar | El propietario borra un proyecto confirmando su clave; tickets, comentarios, releases y enlaces desde otros proyectos se borran en cascada (sagas) y la clave queda libre |
|
||
| 🧩 Configuración | Cada proyecto tiene sus estados (con categoría, color y motivo obligatorio), transiciones, tipos de ticket y áreas; lo usado se archiva, no se borra |
|
||
| 🎨 Cambios de UI | Tipo `UI_CHANGE` con enlace al frame de Figma (validado contra `figma.com`) |
|
||
| ⚙️ Features | Tipo `FEATURE` siguiendo el workflow completo |
|
||
| 🧪 QA | Por defecto, `READY_FOR_QA → IN_QA → DONE / QA_FAILED`; fallar QA exige un motivo |
|
||
| 🚀 Releases | Versiones a las que se asignan tickets; no se publican con tickets sin terminar (salvo forzando) |
|
||
| 👥 Asignaciones | Solo a miembros del proyecto; panel de carga por persona |
|
||
| 💬 Comentarios | Decisiones y explicaciones dentro del ticket; el autor edita, el admin modera |
|
||
| 🔗 Relaciones | `BLOCKS`, `DEPENDS_ON`, `TESTS`, `DUPLICATES`, `RELATES_TO`, también entre proyectos (FE ↔ BE ↔ QA) |
|
||
| 🏠 Inicio | «Mi trabajo»: mis tickets en todos los proyectos, por categoría (QA fallidos primero), lo que espera QA, próximas releases e «Ir a…» por clave |
|
||
| 📊 Seguimiento | Panel con contadores, flujo por estado, el equipo con sus tickets abiertos (enlaza a su tablero), feed de actividad e historial por ticket |
|
||
| 📈 Estadísticas | Creados vs. resueltos, flujo acumulado, burnup de releases, tiempos de ciclo y entrega, tasa de fallo en QA y resueltos por persona |
|
||
| ⚡ Tiempo real | Tablero, comentarios, actividad, releases y membresías se actualizan solos (GraphQL subscriptions) |
|
||
|
||
Los **usuarios no se gestionan aquí**: vienen del servidor de identidad **Pireon**
|
||
([Swagger](https://oauth.pireon.dev/api/documentation)). TaskStream gestiona proyectos, membresías y roles por
|
||
proyecto (`OWNER`, `ADMIN`, `MEMBER`, `VIEWER`).
|
||
|
||
## Stack
|
||
|
||
| Pieza | Tecnología |
|
||
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||
| Monorepo | Nx 23 |
|
||
| API | NestJS 11, `@nestjs/cqrs`, GraphQL (Apollo Server 5, code-first) con subscriptions `graphql-ws` |
|
||
| Escritura | PostgreSQL 17: _event store_ + tablas de lookup (TypeORM) |
|
||
| Escritura → lectura | Redis 7: Redis Stream (eventos) y pub/sub (tiempo real); también caché de sesiones |
|
||
| Lectura | MongoDB 8: vistas desnormalizadas (Mongoose) |
|
||
| Identidad | Pireon (OAuth2 / Laravel Passport) |
|
||
| Cliente | Angular 22 (standalone, zoneless, Signal Forms), NgRx Signals (plugin de eventos), Apollo Angular, `@pi/ui` |
|
||
| Tests | Jest (API), Vitest (web), e2e de la API contra Docker |
|
||
| Despliegue | Docker: imagen Node de la API y nginx para la web |
|
||
|
||
## Estructura del monorepo
|
||
|
||
```
|
||
apps/
|
||
api/ composición de la API (NestJS): config, GraphQL, conexiones, e2e
|
||
web/ composición del cliente (Angular): rutas, providers, estilos, nginx
|
||
mcp/ servidor MCP para asistentes de IA (NestJS), consume la API REST
|
||
libs/
|
||
api/{shared,identity,tracker}/{domain,application,infrastructure,presenters}
|
||
web/{shared,identity,tracker}/{domain,application,infrastructure,presenters} (+ web/shared/ui)
|
||
docs/ esta documentación
|
||
codegen.ts tipos GraphQL del cliente generados desde apps/api/schema.gql
|
||
Dockerfile tres destinos: api, web y mcp
|
||
docker-compose.yml
|
||
```
|
||
|
||
API y web comparten la misma estructura: **contexto** (`shared`, `identity`, `tracker`) × **capa** (`domain`,
|
||
`application`, `infrastructure`, `presenters`). Los imports siguen el mismo patrón:
|
||
`@task-stream/api/tracker/domain`, `@task-stream/web/tracker/application`…
|
||
|
||
### Contextos
|
||
|
||
- **shared**: piezas comunes. En la API, event store, Redis, `VersionedAggregateRoot`, errores de dominio. En la web, el
|
||
cliente GraphQL y la integración de `@pi/ui`.
|
||
- **identity**: quién es el usuario (Pireon), sesiones, inicio de sesión y autorización global.
|
||
- **tracker**: el producto (proyectos, tickets, comentarios, releases, actividad).
|