proyectos/README.md

Proyectos · SAM

Frontend del módulo de gestión de proyectos de la plataforma SAM, con estética y flujo de trabajo al estilo Linear.

Es una aplicación Next.js 16 + Bootstrap 5 (App Router, TypeScript). No tiene backend propio: se apoya en SAM.API, la API compartida de SAM.

Características

• Issues: lista agrupada por estado, con filtros y edición en línea.
• Detalle: descripción, propiedades editables y comentarios.
• Tablero Kanban: arrastrar y soltar entre columnas de estado.
• Ciclos: sprints con progreso y issues asignados.
• Proyectos: agrupan issues, con lead, fechas y barra de progreso.
• Bandeja: issues abiertos asignados al usuario actual.
• Palette de comandos: Cmd/Ctrl + K para navegar y crear issues.

Requisitos

• Node.js 22+
• npm

Desarrollo

npm install
npm run dev

La app queda en http://localhost:3000.

Scripts

Comando	Descripción
npm run dev	Servidor de desarrollo
npm run build	Build de producción (standalone)
npm run start	Sirve el build de producción
npm run typecheck	Comprueba tipos sin emitir

Arquitectura

src/
├── app/                  # Rutas (App Router)
│   ├── inbox/            # Issues asignados al usuario
│   ├── issues/           # Lista de issues
│   │   └── [id]/         # Detalle de un issue
│   ├── board/            # Tablero Kanban
│   ├── cycles/           # Ciclos / sprints
│   └── projects/         # Proyectos
│       └── [id]/         # Detalle de proyecto
├── components/
│   ├── layout/           # Sidebar, Topbar, AppShell, palette
│   ├── issues/           # IssueList, IssueRow
│   ├── board/            # Tablero Kanban
│   └── ui/               # Avatar, iconos, etiquetas, progreso
├── hooks/
│   └── useIssues.ts      # Carga de issues con filtros y refresco
└── lib/
    ├── types.ts          # Modelo de dominio (contrato con SAM)
    ├── meta.ts           # Definiciones de estado/prioridad/tipo
    ├── format.ts         # Helpers de formato de fechas
    ├── seed.ts           # Datos de ejemplo (mock)
    ├── store.tsx         # Contexto de datos de referencia
    └── api/
        ├── client.ts     # Interfaz ProyectosApi
        ├── mock.ts       # Implementación en memoria
        └── index.ts      # Selección de implementación

Capa de datos

Toda la app habla contra la interfaz ProyectosApi (src/lib/api/client.ts), nunca contra una implementación concreta. Hay dos implementaciones:

• httpApi (src/lib/api/http.ts): la real, contra SAM.API. Es la que se usa por defecto.
• mockApi (src/lib/api/mock.ts): datos en memoria sobre src/lib/seed.ts, para desarrollar la UI sin backend. Se activa con NEXT_PUBLIC_USE_MOCK=true.

La selección está en src/lib/api/index.ts. Para cambiar de implementación no hay que tocar componentes, hooks ni páginas: el contrato no cambia.

Autenticación

La API key global de SAM (X-Api-Key) nunca llega al navegador.

El navegador llama a /api/proyectos/* en el mismo origen. Ese route handler (src/app/api/proyectos/[...path]/route.ts) reenvía la petición a SAM.API añadiendo la cabecera en el servidor.

La clave vive en SAM_API_KEY, sin prefijo NEXT_PUBLIC_. Next.js solo inyecta en el bundle JS las variables NEXT_PUBLIC_*, así que esta queda restringida al proceso del servidor.

Sesión de usuario

AuthProvider (src/lib/auth.tsx) guarda en localStorage el miembro devuelto por POST /api/proyectos/auth/login, que valida contra sige_sam_v3.usuario. Ese idUsuario es quien firma los comentarios y filtra la bandeja.

Nota: los tipos de src/lib/types.ts son el contrato esperado del backend. Los endpoints de SAM.API devuelven esta misma forma.

Despliegue en SAM

Sigue el patrón de módulo de SAM: frontend independiente conectado a la API compartida a través de la red sam-net.

• Dockerfile: build standalone de Next.js.
• docker-compose.module.yml: servicio proyectos-frontend con healthcheck.

Dentro de la red sam-net el frontend alcanza el backend por nombre de contenedor: SAM_API_URL=http://sam-api:5000.

SAM_API_KEY se inyecta desde el entorno del host (${SAM_API_KEY} en el compose); no se escribe en el archivo.

Variables de entorno

Variable	Quién la lee	Descripción
SAM_API_URL	servidor	URL base de SAM.API. Por defecto http://127.0.0.1:5000.
SAM_API_KEY	servidor	API key global de SAM (X-Api-Key). Sin ella el proxy responde 503.
NEXT_PUBLIC_MODULE	cliente	Identificador del módulo (informativo).
NEXT_PUBLIC_USE_MOCK	cliente	true para usar datos mock en memoria sin backend.

SAM_API_URL y SAM_API_KEY no llevan prefijo NEXT_PUBLIC_ a propósito: solo las ve el proceso del servidor, así que la clave no se empaqueta en el JavaScript que descarga el navegador.