stock-manager/README.md

# Stock Manager Home

Sistema de gestión de inventario y asignación de activos desarrollado con Next.js 15, Prisma, PostgreSQL y NextAuth.

## 📋 Descripción

Stock Manager es una aplicación web completa para la gestión de inventarios, activos y asignaciones de equipamiento. Permite controlar tanto ítems genéricos (gestionados por cantidad) como activos serializados (con número de serie único), registrar movimientos de stock, y gestionar asignaciones a destinatarios por departamentos.

## ✨ Características principales

### Gestión de Inventario

- **Ítems genéricos**: Productos sin número de serie, gestionados por cantidad en stock
- **Activos serializados**: Equipos individuales con número de serie único
- **Categorías**: Organización jerárquica de productos
- **Control de stock**: Niveles mínimos/máximos, alertas de stock bajo (WIP)
- **Estados múltiples**: Disponible, Asignado, Reservado, En reparación, Averiado, Robado, Dado de baja

### Gestión de Destinatarios

- Registro de empleados/destinatarios por departamento
- Información de contacto (email, teléfono)
- Historial de asignaciones por destinatario

### Sistema de Asignaciones

- Asignación de ítems genéricos (por cantidad)
- Asignación de activos individuales (uno a uno)
- Seguimiento de fechas de asignación y devolución
- Notas y detalles de cada asignación
- Registro del usuario que realiza cada asignación

### Movimientos e Historial

- Registro completo de todos los movimientos de stock
- Tipos de movimiento: IN, OUT, ASSIGNMENT, RETURN, ADJUSTMENT, DELETED
- Trazabilidad completa con stock previo y nuevo
- Auditoría de todos los cambios con usuario y fecha

### Importación de Datos

- Importación masiva vía CSV
- Plantilla descargable para importaciones
- Validación de datos en el proceso de importación

### Sistema de Autenticación y Roles

- Autenticación segura con NextAuth v5
- 4 roles de usuario: ADMIN, MANAGER, STAFF, VIEWER
- Permisos diferenciados según rol
- Contraseñas hasheadas con bcrypt

## 🚀 Tecnologías

- **Framework**: Next.js 15 (App Router)
- **Base de datos**: PostgreSQL 18
- **ORM**: Prisma 6
- **Autenticación**: NextAuth v5
- **UI**: React 19, Tailwind CSS, Shadcn
- **Validación**: Zod
- **Formularios**: React Hook Form
- **Runtime**: Bun (recomendado)
- **Containerización**: Docker + Docker Compose

## 🔨 Desarrollo en entorno DevContainer

Este proyecto incluye configuración para desarrollo en contenedor usando [DevContainer](https://containers.dev/).

1. Abre el proyecto en VS Code y selecciona "Reopen in Container".
2. El entorno instalará dependencias automáticamente (bun i) y lanzará el servidor de desarrollo (bun run dev).
3. El puerto 3000 estará disponible para acceder a la app desde tu navegador.

## 🔨 Desarrollo local

### Prerrequisitos

- Node.js 18+ o Bun
- PostgreSQL 13+ (o usar Docker Compose)
- Git

1. Clonar el repositorio:

```bash
git clone <repo-url>
cd stock-manager
```

2. Instalar dependencias:

```bash
bun install
# o
npm install
```

3. Configurar variables de entorno:

```bash
cp .env.example .env
```

Editar `.env` con tus configuraciones:

```env
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/stockmanager"
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=stockmanager
POSTGRES_HOST=db
POSTGRES_PORT=5432

# NextAuth
NODE_ENV=development
DEMO_MODE=false
AUTH_SECRET="your-secret-key-here"
AUTH_TRUST_HOST=true
DOMAIN=localhost:3000
```

4. Ejecutar migraciones de base de datos:

```bash
bun run db:migrate
# o generar el cliente Prisma
bun run db:generate
```

5. (Opcional) Ejecutar seed para datos iniciales:

```bash
bun run db:seed
```

6. Iniciar el servidor de desarrollo:

```bash
bun run dev
```

Abrir [http://localhost:3000](http://localhost:3000) en el navegador.

## 🐳 Despliegue con Docker

### Producción

```bash
docker-compose -f compose.yaml up -d
```

Con Traefik (reverse proxy):

```bash
docker-compose -f compose.yaml -f compose.traefik.yaml up -d
```

## 📜 Scripts disponibles

```bash
# Desarrollo
bun run dev              # Inicia servidor de desarrollo con Turbopack
bun run build            # Construye para producción
bun run start            # Inicia servidor de producción

# Linting y formato
bun run lint             # Ejecuta ESLint
bun run lint:fix         # Corrige errores de ESLint automáticamente
bun run format           # Formatea código con Prettier

# Base de datos
bun run db:push          # Sincroniza schema sin migraciones
bun run db:migrate       # Crea y ejecuta migraciones
bun run db:migrate:reset # Resetea BD y ejecuta migraciones
bun run db:deploy        # Ejecuta migraciones en producción
bun run db:generate      # Genera cliente Prisma
bun run db:studio        # Abre Prisma Studio (GUI para BD)
```

## 📁 Estructura del proyecto

```
src/
├── app/                    # App Router de Next.js
│   ├── (auth)/            # Rutas de autenticación
│   │   └── login/
│   ├── (dashboard)/       # Rutas del dashboard
│   │   ├── (home)/        # Página principal
│   │   ├── assignments/   # Gestión de asignaciones
│   │   ├── import/        # Importación de datos
│   │   ├── inventory/     # Gestión de inventario
│   │   │   ├── assets/    # Activos serializados
│   │   │   ├── categories/# Categorías
│   │   │   └── items/     # Ítems genéricos
│   │   ├── movements/     # Historial de movimientos
│   │   └── recipients/    # Gestión de destinatarios
│   └── api/               # API routes
│       ├── auth/          # Endpoints de autenticación
│       └── db/            # Endpoints de base de datos
├── components/            # Componentes React
│   ├── auth/             # Componentes de autenticación
│   ├── common/           # Componentes comunes
│   ├── forms/            # Componentes de formularios
│   ├── layout/           # Componentes de layout
│   └── ui/               # Componentes UI (Radix)
├── lib/                   # Utilidades y configuración
│   ├── actions/          # Server Actions
│   ├── schemas/          # Schemas de validación Zod
│   └── types/            # Tipos TypeScript
├── services/             # Servicios de lógica de negocio
├── prisma/               # Schema y migraciones Prisma
│   ├── schema.prisma     # Definición del modelo de datos
│   ├── migrations/       # Historial de migraciones
│   └── seed.ts           # Datos iniciales
└── styles/               # Estilos globales
```

## 🔐 Seguridad

- Autenticación mediante JWT
- Contraseñas hasheadas con bcrypt
- Validación de datos con Zod en cliente y servidor
- Protección de rutas según roles
- Variables de entorno para secretos
- Sanitización de inputs

## 🗃️ Modelo de datos

El sistema gestiona las siguientes entidades principales:

- **Users**: Usuarios del sistema con roles y permisos
- **Recipients**: Destinatarios/empleados que reciben asignaciones
- **Categories**: Categorías de productos
- **Items**: Ítems genéricos (sin número de serie)
- **Assets**: Activos individuales (con número de serie)
- **Assignments**: Asignaciones de ítems/activos a destinatarios
- **Movements**: Registro de todos los movimientos de inventario

Ver `src/prisma/schema.prisma` para el esquema completo.