# PRD — Scuf3D Taller: Sistema de Gestión de Taller de Consolas

**Versión:** 1.0  
**Fecha:** 2026-05-11  
**Autor:** Juan Zapata  
**Estado:** En desarrollo activo

---

## 1. Visión general

Scuf3D Taller es un ERP web especializado para talleres de reparación y modificación de consolas gaming. Cubre el ciclo completo de un servicio técnico: desde que el cliente ingresa un equipo hasta que lo retira, pasando por diagnóstico, reparación, cobro y seguimiento. Está inspirado en Gestioo y adaptado a la operativa real de un taller Scuf3D en Perú.

El sistema diferencia al taller de una solución genérica en dos capacidades: modificaciones competitivas (MODs) con control de compatibilidad de piezas, y un WMS especializado para el almacenamiento físico de consolas y componentes.

---

## 2. Usuarios y roles

| Rol | Responsabilidades principales |
|---|---|
| **Administrador** | Acceso total: configuración, usuarios, caja, analytics |
| **Técnico** | OTs, diagnósticos, tareas técnicas, inventario de repuestos |
| **Vendedor** | Clientes, OTs, productos, catálogo de servicios |
| **Logística** | Recogidas, envíos, WMS |
| **Gerente / Dueño** | Analytics, reportes, aprobación de cajas y movimientos |

Los permisos son configurables por rol y tienen overrides individuales por usuario. El sistema de roles vive en `roles`, `permisos`, `rol_permisos` y `usuario_permisos`.

---

## 3. Módulos del sistema

### 3.1 Gestión de Clientes (Agenda Unificada)

**Objetivo:** Centralizar toda la información de clientes (personas y empresas) en un único repositorio.

**Tabla principal:** `agenda_clientes` (tipo: `persona | empresa`)

**Funcionalidades:**
- Crear y editar clientes con datos completos (DNI/RUC, contacto, dirección)
- Búsqueda universal y por DNI/RUC
- Perfil de cliente con historial completo de servicios
- Registro de equipos por cliente (`equipos_clientes`)
- Múltiples direcciones por cliente (`direcciones_clientes`)
- Pre-registro para clientes que llegan sin cita
- Soft delete: `UPDATE agenda_clientes SET estado = 'eliminado'`

**Compatibilidad legacy:** `regis_clientes` es una VIEW sobre `agenda_clientes` (filtra `tipo='persona' AND estado<>'eliminado'`). Los LEFT JOIN legacy siguen funcionando. No escribir en esta view.

**Páginas clave:**
- `admin_lista_clientes_agenda.php` — listado con filtros
- `admin_crear_cliente_agenda.php` — formulario de creación
- `admin_perfil_cliente_agenda.php` — perfil detallado

---

### 3.2 Órdenes de Trabajo (OT)

**Objetivo:** Gestionar el ciclo completo de un servicio técnico desde el ingreso del equipo hasta la entrega.

**Tablas:** `ordenes_trabajo`, `servicio_trabajos`, `orden_items`, `servicios_catalogo`, `etiquetas_servicios`

**Flujo:**
1. Crear OT vinculada a cliente y equipo
2. Ejecutar diagnóstico técnico (opcional, con plantillas)
3. Agregar trabajos/servicios del catálogo
4. Agregar items (repuestos/productos) usados
5. Calcular total (subtotal + descuentos + IGV)
6. Registrar pago en caja
7. Entregar equipo y cerrar OT

**Estados de OT:** pendiente → en proceso → listo → entregado

**Funcionalidades:**
- Múltiples servicios por OT
- Catálogo de servicios con precios base (`servicios_catalogo`)
- Cálculo automático de totales
- Generación de comprobante PDF y ticket PDF
- Etiquetas/tags para categorizar OTs
- Historial de cambios por OT

**Páginas clave:**
- `admin_crear_trabajo.php` — crear OT
- `admin_lista_servicios.php` — listado con filtros y estados
- `admin_ver_servicio.php` — detalle completo

---

### 3.3 Diagnósticos Técnicos

**Objetivo:** Registrar el estado inicial del equipo antes de iniciar cualquier intervención.

**Tablas:** `diagnostico_chequeos`, `diagnostico_grupos`, `diagnostico_respuestas`, `plantillas_diagnostico`

**Funcionalidades:**
- Plantillas reutilizables por tipo de equipo
- Chequeos agrupados (hardware, software, accesorios)
- Registro de respuestas (ok, falla, no aplica)
- Vinculación a OT

**Páginas clave:**
- `admin_crear_diagnostico.php`
- `admin_ver_diagnostico.php`

---

### 3.4 Modificaciones Competitivas (MODs)

**Objetivo:** Gestionar pedidos de modificaciones de controladores gaming (sticks magnéticos, botones, carcasas) con control de compatibilidad.

**Tablas:** `mod_piezas`, `mod_pedido`, `mod_pedido_pieza`, `tech_compatibility`, `tech_compatibility_category`, `saved_mods`, `mod_config_scuf`

**Funcionalidades:**
- Catálogo de piezas disponibles con precios
- Creación de pedidos de MOD con piezas seleccionadas
- Motor de compatibilidad: valida qué piezas funcionan en qué controladores
- Guardado de MODs personalizadas por cliente
- Integración con OTs (los MODs se registran como servicios)
- Exportación del catálogo

**Páginas clave:**
- `admin_mod_piezas.php` — gestión de piezas
- `admin_mods_pedidos.php` — listado de pedidos
- `admin_ver_pedido.php` — detalle de pedido
- `admin_saved_mods.php` — MODs guardadas

---

### 3.5 Inventario y WMS

**Objetivo:** Controlar el stock de productos, repuestos y componentes con trazabilidad por serial.

**Tablas:** `items`, `item_category`, `item_subcategory`, `item_serials`, `item_movements`, `inventory_receipts`, `inventory_receipt_lines`, `inventory_counts`, `inventory_count_lines`, `inv_productos`

**Funcionalidades:**
- CRUD de items con SKU y categorías
- Ingreso de mercadería con comprobante (`inventory_receipts`)
- Control de seriales por unidad individual
- Historial de movimientos (Kardex)
- Rotación FIFO automática
- Recuentos periódicos con comparación vs sistema
- Reportes de rotación (`v_item_rotacion`)

**WMS (Warehouse Management):**
- Bloques de almacén (`wms_bloques`)
- Movimientos de consolas entre ubicaciones
- WMS especializado para consolas (`wms_consolas_*`)
- Historial de posición por unidad

**Páginas clave:**
- `admin_inv_productos.php` — inventario
- `admin_wms_inicio.php` — dashboard WMS
- `admin_wms_consolas_inicio.php` — WMS consolas

---

### 3.6 Gestión de Caja

**Objetivo:** Control diario de ingresos y egresos con cuadre al cierre.

**Tablas:** `cuadres_caja`, `cuadre_ingresos`, `cuadre_egresos`, `movimientos_post_cierre`

**Flujo:**
1. Abrir caja al inicio del día
2. Registrar ingresos (pagos de clientes, otros)
3. Registrar egresos (gastos operativos, cambios, etc.)
4. Al cierre: sistema calcula saldo esperado automáticamente
5. Cajero ingresa monto real en caja
6. Si hay diferencia: permite movimientos post-cierre con justificación
7. Gerente aprueba o rechaza movimientos post-cierre
8. Cierre definitivo

**Funcionalidades:**
- Pagos observados que requieren aprobación (`caja_pagos_observados`)
- Vista histórica de cuadres
- Reportes de cierre diario

**Páginas clave:**
- `admin_cuadre_caja.php` — dashboard de caja
- `admin_cuadre_ver.php` — historial
- `admin_movimientos_post_cierre.php` — flujo de aprobación

---

### 3.7 Logística

**Objetivo:** Gestionar recogidas de equipos en domicilio y envíos a clientes.

**Tablas:** `recojos_equipos`, `ordenes_envios`, `empresas_envio`, `envio_imagenes`

**Funcionalidades:**
- Crear y gestionar recogidas con dirección del cliente
- Órdenes de envío con empresas de courier (Olva, Fedex, etc.)
- Subida de imágenes de empaque a S3
- Estados de envío: pendiente → despachado → entregado
- Importación masiva de envíos por Excel
- Tiempo de ciclo por orden (`v_orden_tiempo_ciclo`)

**Páginas clave:**
- `admin_gestion_recogidas.php`
- `admin_ordenes_envios.php`
- `admin_lista_envios.php`

---

### 3.8 Tareas y Proyectos Internos

**Objetivo:** Gestión de trabajo interno del equipo (no OTs de cliente).

**Tablas:** `tareas`, `subtareas`, `tareas_comentarios`, `tareas_historial`, `tareas_recordatorios`, `proyectos`

**Funcionalidades:**
- Creación de tareas con asignación a trabajadores
- Vista Kanban (columnas por estado)
- Vista Gantt (línea de tiempo)
- Subtareas y porcentaje de avance
- Comentarios e historial de cambios
- Recordatorios
- Agrupación en proyectos

**Páginas clave:**
- `admin_dashboard_tareas.php` — Kanban + Gantt
- `admin_lista_tareas.php`
- `admin_ver_proyecto.php`

---

### 3.9 Chat Interno

**Objetivo:** Comunicación en tiempo real entre trabajadores del taller.

**Tablas:** `chat_mensajes`, `chat_grupos`, `chat_grupo_miembros`, `chat_mensajes_grupo`, `chat_mensajes_grupo_lecturas`, `chat_estado_conversaciones`

**Funcionalidades:**
- Conversaciones 1-a-1 entre trabajadores
- Grupos predefinidos: Global, Logística, Vendedores, Técnicos
- Contador de mensajes no leídos
- Historial de conversaciones
- Sincronización de grupos según rol

**Páginas clave:**
- `admin_chat.php`
- `admin_sync_grupos_chat.php`

---

### 3.10 Buzón de Solicitudes / Notas de Servicio

**Objetivo:** Canal formal para solicitudes internas y notas vinculadas a servicios.

**Tablas:** `nota_tipos`, `servicio_notas`, `servicio_historial`

**Funcionalidades:**
- Tipos de solicitud configurables (`admin_notas_tipos.php`)
- Solicitudes dirigidas a roles específicos
- Estados: pendiente → respondido → procesado
- Métricas de respuesta por usuario y rol
- Historial de interacciones

**Páginas clave:**
- `admin_buzon.php`
- `admin_notas_tipos.php`
- `api/buzon.php`

---

### 3.11 Analytics y Reportes

**Objetivo:** Visibilidad completa de la operación con métricas accionables.

**Módulos de analytics:**

| Módulo | KPIs principales |
|---|---|
| Resumen | Servicios activos, ingresos del período, clientes nuevos |
| Finanzas | Ingresos, egresos, margen por categoría, tendencia |
| Servicios | OTs por estado, tiempo de ciclo, productividad por técnico |
| Clientes | Recurrencia, CLV, clientes nuevos vs recurrentes |
| Equipos | Equipos más reparados, fallas frecuentes |
| Inventario | Rotación, stock bajo, valorizados |
| Logística | Tiempos de entrega, envíos por empresa |
| MODs | Modificaciones más solicitadas, piezas más usadas |
| Personas | Desempeño por usuario/técnico |
| Contable | Resumen financiero consolidado |

**Funcionalidades:**
- Filtros por período (día, semana, mes, año, custom)
- Drill-down por KPI (`api/analytics/kpi_drill.php`)
- Gráficos interactivos con Chart.js
- Exportación a Excel y PDF

**Páginas clave:** `admin_analytics_*.php` (11 páginas)

---

### 3.12 Configuración y Administración

**Funcionalidades:**
- Datos del taller (nombre, logo, dirección, RUC)
- Credenciales AWS S3 para subida de archivos
- Gestión de usuarios y contraseñas
- Gestión de roles y permisos granulares
- Dashboard personalizable por rol (drag & drop de cards)
- Toggle de tema dark/light con persistencia
- Áreas de servicio configurables

---

## 4. Arquitectura técnica

### Stack

| Capa | Tecnología |
|---|---|
| Backend | PHP 8.4 |
| Base de datos | MariaDB 11.4 (utf8mb4) |
| Frontend | Bootstrap 5.3.3 + Vanilla JS |
| Gráficos | Chart.js |
| Alertas UI | SweetAlert2 |
| PDFs | TCPDF |
| Excel | PHPSpreadsheet |
| Email | PHPMailer |
| Almacenamiento archivos | AWS S3 |
| Hosting | cPanel (servidor compartido) |

### Estructura de directorios

```
taller_scufpe/
├── admin_scripts/      # POST handlers (acciones backend)
├── api/                # Endpoints REST que devuelven JSON
├── assets/
│   ├── css/            # Sistema JD Crimson (4 archivos CSS)
│   ├── js/             # theme-manager.js, s3_uploader.js
│   └── fonts/          # MazzardH-Bold
├── components/         # Partials PHP (header, sidebar)
├── includes/           # permisos.php, upload_tipos.php
├── sql/                # Scripts SQL de cambios estructurales
├── vendor/             # Dependencias Composer
├── BASE_DE_DATOS.sql   # Dump completo de referencia
└── conexion.php        # Conexión mysqli
```

### Convenciones de BD

- Conexión: `conexion.php` (mysqli, utf8mb4, timezone `America/Lima`)
- Queries: prepared statements obligatorios, nunca concatenación
- Borrado lógico: `UPDATE tabla SET estado = 'eliminado'` (nunca DELETE excepto logs)
- FK de cliente: `agenda_cliente_id` en tablas relacionadas
- Cambios estructurales: archivo `.sql` nuevo en `sql/`, ejecutado manualmente en PHPMyAdmin

### Subida de archivos

1. Frontend pide URL firmada a `admin_scripts/firmar_subida.php`
2. `firmar_subida.php` genera presigned POST usando AWS SDK
3. Frontend sube directamente a S3 via `assets/js/s3_uploader.js`
4. Tipos permitidos: `nota_servicio` (video hasta 2GB), `imagen_producto` (hasta 5MB), `imagen_envio` (hasta 8MB), `imagen_item` (5MB), `foto_usuario` (5MB)

### API (formato de respuesta)

```json
{ "ok": true, "datos": { ... } }
{ "ok": false, "error": "Mensaje legible" }
```

---

## 5. Sistema de diseño (JD Crimson)

### Archivos CSS (4 archivos, siempre en este orden para páginas admin)

```html
<link rel="stylesheet" href="assets/css/jd-crimson-core.css">
<link rel="stylesheet" href="assets/css/jd-crimson-dark.css">
<link rel="stylesheet" href="assets/css/jd-crimson-light.css">
<link rel="stylesheet" href="assets/css/jd-crimson-theme-bridge.css">
```

Páginas públicas/cliente: solo `jd-crimson-dark.css`.

### Mecanismo de temas

- Dark (por defecto): body sin clase
- Light: `<body class="jd-light-theme">`
- El bridge (`jd-crimson-theme-bridge.css`) remapea todas las variables cuando se activa el tema light
- Persistencia: `localStorage['jd-theme']` + columna `usuarios.tema` en BD
- Switch UI: `#theme-switch` en `components/admin_sidebar.php`

### Variables CSS clave

- Acento: `--jd-crimson` (#ff4d6d), `--jd-crimson-dark` (#c9184a)
- Fondos: `--jd-bg-body`, `--jd-bg-main`, `--jd-bg-card`
- Texto: `--jd-text-primary`, `--jd-text-secondary`, `--jd-text-muted`
- Radios: `--jd-radius-sm` (8px) → `--jd-radius-xl` (16px)
- Espaciado: `--jd-spacing-xs` (10px) → `--jd-spacing-xl` (30px)

Regla: siempre usar `var(--jd-...)`, nunca hardcodear valores.

---

## 6. Seguridad

- Sesión admin: `admin_check_session.php` incluido en todas las páginas admin
- Permisos: `requerir_permiso('slug.accion')` antes de operaciones sensibles
- Queries: prepared statements en toda interacción con BD
- Upload: validación de tipo y tamaño en `includes/upload_tipos.php`, archivos a S3
- Sin alerts nativos: solo modales Bootstrap o SweetAlert2
- Sin hardcoding de credenciales: AWS y BD en `taller_config` y `db_config.php`

---

## 7. Integraciones externas

| Integración | Uso | Config |
|---|---|---|
| AWS S3 | Almacenamiento de archivos (imágenes, videos) | `taller_config` → `admin_config_aws.php` |
| Olva / Fedex / otros | Empresas de envío (referencial, no API) | `empresas_envio` |
| PHPMailer | Envío de emails (notificaciones, promos) | Config en `taller_config` |

---

## 8. Funcionalidades pendientes / roadmap

> Esta sección debe actualizarse conforme el desarrollo avance.

- [ ] Portal del cliente (seguimiento de OT online)
- [ ] Notificaciones push / WhatsApp para el cliente
- [ ] Integración con API de SUNAT (validación RUC/DNI en tiempo real)
- [ ] Módulo de facturación electrónica (boleta/factura SUNAT)
- [ ] App móvil para técnicos (ver y actualizar OTs en campo)
- [ ] Integración con pasarelas de pago (Yape, PagoEfectivo)
- [ ] Sistema de garantías con seguimiento post-servicio
- [ ] Módulo de cotizaciones formales (previo a OT)

---

## 9. Decisiones de diseño relevantes

| Decisión | Razón |
|---|---|
| `agenda_clientes` como tabla central | Unificar personas y empresas en una sola entidad; eliminar duplicación de `regis_clientes` |
| `regis_clientes` como VIEW | Compatibilidad con código legacy sin reescritura inmediata |
| Soft delete universal | Integridad referencial: no romper historial ni relaciones al "eliminar" |
| AWS S3 para archivos | Servidor cPanel compartido no es adecuado para almacenar archivos grandes |
| 4 archivos CSS (no 1) | Separación de responsabilidades: core / dark / light / bridge; permite extender sin romper |
| Sin frameworks JS | Simplicidad de deployment en cPanel; Bootstrap ya cubre necesidades de UI |
| Prepared statements obligatorios | Prevención de SQL injection; política de seguridad no negociable |
| Archivos SQL en `sql/` (no scripts PHP DDL) | El desarrollador ejecuta manualmente en PHPMyAdmin; más control y revisión |

---

## 10. Glosario

| Término | Definición |
|---|---|
| **OT** | Orden de Trabajo — unidad principal de servicio técnico |
| **MOD** | Modificación competitiva — personalización de controladores gaming |
| **WMS** | Warehouse Management System — módulo de gestión de almacén |
| **Cuadre** | Proceso de cierre diario de caja con conciliación |
| **Soft delete** | Borrado lógico (`estado = 'eliminado'`) sin eliminar el registro |
| **JD Crimson** | Sistema de diseño propio del proyecto (dark + light) |
| **Presigned POST** | URL temporal firmada por AWS para subida directa al S3 desde el browser |
| **Agenda Unificada** | Módulo de clientes centralizado que reemplazó la tabla `regis_clientes` |