133 lines
5.3 KiB
Markdown
133 lines
5.3 KiB
Markdown
# 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.
|