feat: modulo de proyectos frontend (Next 16 + Bootstrap 5)
This commit is contained in:
Nurfog committed
commit
2dc41ed4fa
43 files changed
+5894
No files matched your search
@@ -0,0 +1,132 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user