# 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](https://linear.app).

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

```bash
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.