# JAIR OT — Guía de instalación / actualización en jair.cl (cPanel) Sistema de Órdenes de Trabajo para JAIR: los técnicos llenan el formulario, sacan fotos y hacen firmar al cliente desde el celular (funciona sin internet y se sincroniza solo); tú administras clientes, equipos, formularios y OT desde el computador. Este documento cubre dos casos: - **Instalación nueva** (primera vez, servidor vacío). - **Actualización** de la instalación que ya tienes funcionando en `ot.jair.cl` (agrega formularios renombrados, firma opcional, sucursales con carga masiva de equipos por CSV, un listado global de activos, categorías de equipo, logos, edición de OT completadas, geolocalización, selección de sucursal y varios equipos al crear una OT, el PDF rediseñado, y ahora la **pauta/formulario por equipo** dentro de una OT). **Si tu ot.jair.cl ya tiene aplicadas las migraciones v2 y v3** y solo te falta la más reciente — la de asignar un formulario a cada equipo y llenar su pauta uno por uno desde el celular —, puedes ir directo al **Paso 4c** más abajo: solo te falta correr `db/migration_v4.mysql.sql` y reemplazar los archivos de este paquete. ## Si ya tienes el sistema funcionando en ot.jair.cl (ACTUALIZACIÓN) Sigue estos pasos en orden — no te saltes el de la base de datos. ### 1. Respaldo rápido (recomendado) En cPanel → Administrador de archivos → entra a la carpeta de `ot.jair.cl` → selecciona todo → Comprimir → descarga ese zip a tu computador por si acaso. También puedes exportar la base de datos desde phpMyAdmin (pestaña Exportar) antes de continuar. ### 2. Sube los archivos nuevos — SIN tocar `uploads/` Sube y reemplaza las carpetas `admin/`, `api/`, `tecnico/` y `db/` de este paquete sobre las que ya existen en el servidor. **MUY IMPORTANTE:** NO reemplaces la carpeta `uploads/` que ya está en el servidor — ahí están guardadas las fotos y firmas reales de tus OT. Si tu método de subida pregunta si quieres sobrescribir `uploads/`, dile que NO (o simplemente no la incluyas al subir). ### 3. Vuelve a poner tus datos de conexión en `api/config.php` Este paquete trae un `api/config.php` nuevo (con los nuevos límites de fotos/logos ya configurados), pero con valores de ejemplo en la conexión a la base de datos. Ábrelo con el editor de archivos de cPanel y reemplaza estas 3 líneas con los mismos datos que ya tenías (los de tu base de datos `jairclyt_ot`): ```php define('DB_NAME', getenv('APP_DB_NAME') ?: 'jairclyt_ot'); define('DB_USER', getenv('APP_DB_USER') ?: 'jairclyt_ot'); define('DB_PASS', getenv('APP_DB_PASS') ?: 'TU_CLAVE_REAL_AQUI'); ``` No hace falta que cambies `APP_SECRET` — el valor que trae este archivo es nuevo, pero como ya tienes un administrador creado, no lo vas a volver a usar (`install.php` ya lo tenías borrado del servidor, como se indicó la primera vez). ### 4a. Ejecuta la migración v2 (sáltala si ya la corriste antes) En cPanel → phpMyAdmin → selecciona tu base de datos (`jairclyt_ot`) → pestaña **SQL** → abre el archivo `db/migration_v2.mysql.sql` de este paquete, copia todo su contenido, pégalo ahí → **Continuar**. Esto agrega las tablas y columnas nuevas (sucursales, logos, firma opcional, ubicación GPS) sin borrar nada de lo que ya tienes cargado. Si ya la habías corrido antes, vas a ver errores tipo "Duplicate column name" — está bien, significa que esa parte ya estaba aplicada, sigue con el siguiente paso. ### 4b. Ejecuta la migración v3 (una sola vez) Mismo lugar — phpMyAdmin → tu base de datos → pestaña **SQL** → abre `db/migration_v3.mysql.sql`, copia todo su contenido, pégalo → **Continuar**. Esto agrega la posibilidad de elegir **sucursal** y **varios equipos** al crear una OT (antes una OT solo podía tener un equipo asociado). Si alguna OT ya tenía un equipo cargado a la forma antigua, esta migración lo traspasa solo, sin que se pierda nada. ### 4c. Ejecuta la migración v4 (una sola vez) Mismo lugar — phpMyAdmin → tu base de datos → pestaña **SQL** → abre `db/migration_v4.mysql.sql`, copia todo su contenido, pégalo → **Continuar**. Esto agrega la posibilidad de asignar un **formulario/pauta** a cada equipo (al crearlo o editarlo manualmente, no al subirlo por CSV), y que el técnico llene esa pauta **equipo por equipo** desde el celular antes de poder firmar y cerrar la OT completa. No borra ni modifica ningún dato existente. ### 5. Vuelve a entrar Como cambiaron las claves de sesión guardadas en el navegador, tanto el panel de administración como la app de los técnicos van a pedir iniciar sesión de nuevo (es normal, no se pierde nada). En el celular del técnico puede convenir cerrar la app y volver a abrirla para que tome la versión nueva. ### Qué cambió (resumen para ti) - "Checklists" ahora se llaman **Formularios** en todo el panel. - Al crear un formulario ya no se pide tipo de equipo/servicio, y las subtareas ya no tienen casillero de "obligatorio" — **todas** las subtareas que agregues son obligatorias automáticamente. - Cada OT nueva tiene un check **"Requiere firma del cliente"** (marcado por defecto); si lo desmarcas, esa OT se puede cerrar sin firma. - Cada cliente puede tener **sucursales** (editables y eliminables desde su ficha), y cada equipo se puede asociar a una sucursal y a una categoría. Tanto en la ficha del cliente como dentro de cada sucursal hay un botón para descargar/subir sus equipos como planilla CSV (se abre bien en Excel). Columnas: Cliente, Sucursal, Tipo Equipo, Marca, Modelo, Serie, Ubicación, Categoria — si subes el CSV sin elegir cliente (desde Configuración → Activos) puedes cargar equipos de varios clientes y sucursales a la vez, creando las sucursales que falten automáticamente. - **Configuración → Activos**: un listado de todos los equipos de todos los clientes en un solo lugar, con buscador, edición en línea y descarga/ carga masiva de CSV global. - Al crear una OT ahora puedes elegir la **sucursal** del cliente y marcar, con casilleros (con botón "Seleccionar todos"), **varios equipos** de esa sucursal para agregarlos juntos a la OT — antes solo se podía asociar un equipo por OT. Esto también se puede corregir después desde el detalle de la OT. - Cada OT exige **al menos 1 foto y hasta 10** para poder completarse. - Cada cliente puede tener un logo pequeño (ficha del cliente), y tu propia empresa también (menú **Configuración**) — ambos aparecen en el PDF. - Los usuarios (técnicos/admins) ahora se pueden **editar** desde el panel (nombre, email, teléfono, rol, contraseña). - El nombre del técnico en la OT siempre es el de su cuenta — nunca se pregunta aparte (esto ya funcionaba así antes, no cambió nada acá). - Una OT completada **desaparece de la lista del técnico**; desde el panel puedes **"Reabrir OT"** para que vuelva a aparecerle y pueda corregirla o volver a firmarla. - Las OT completadas se pueden **editar desde el panel**: cambiar respuestas del formulario, subir fotos nuevas o borrar fotos. - Al firmar, la app le pide permiso de ubicación al técnico y guarda las coordenadas junto con la OT (se ven en el detalle y en el PDF, como texto + link a Google Maps). - El PDF quedó más compacto (normalmente 1 página): encabezado con ambos logos, datos en 2 columnas, ya no muestra "Completada" ni la dirección/ teléfono del cliente, trae una sección **Equipos** que lista tipo/marca/ modelo/N° de serie y la **ubicación** de cada equipo de la OT, y las fotos van en grilla de hasta 4 por fila, comprimidas. - **Pauta por equipo (novedad de esta actualización):** al crear o editar un equipo **manualmente, uno por uno** (no al subirlo por CSV) ahora puedes elegir qué **formulario/pauta** le corresponde, tanto desde la ficha de un cliente como desde Configuración → Activos. - Cuando una OT tiene varios equipos, el técnico ya no llena un único formulario para toda la OT: en el celular ve la lista de equipos de la OT y entra a cada uno para llenar y **cerrar su propia pauta**. Solo cuando **todos** los equipos quedan cerrados aparece la sección para que el cliente firme y el botón para enviar la OT. Un equipo sin formulario asignado simplemente se marca como "revisado", sin pauta que llenar. - En el panel, el detalle de cada OT con equipos muestra ahora una tarjeta "Pauta de cada equipo" (una sub-tarjeta de respuestas por equipo) para que puedas corregir cualquiera de ellas si hace falta. - El PDF trae una sección de formulario **separada por cada equipo** (antes era una sola sección para toda la OT). --- ## Instalación nueva (servidor vacío) ## Qué vas a necesitar de tu hosting (cPanel) - Acceso a cPanel de jair.cl. - Crear un subdominio (ej. `ot.jair.cl`). - Acceso a Administrador de archivos o FTP para subir los archivos. - Acceso a phpMyAdmin (viene incluido en cPanel) para importar el esquema. - Una base de datos MySQL propia para esta app (créala en cPanel → Bases de datos MySQL, junto con un usuario con todos los privilegios sobre ella). ## Paso 1 — Crear el subdominio En cPanel → **Dominios** → **Crear un nuevo dominio** → escribe el dominio completo `ot.jair.cl` en el campo "Dominio". Deja el "Directorio raíz del documento" con el valor que sugiere por defecto. Todo el contenido de esta carpeta (`admin/`, `api/`, `tecnico/`, `uploads/`) se sube DENTRO de esa carpeta raíz del subdominio. ## Paso 2 — Crear la base de datos e importar el esquema En cPanel → **Bases de datos MySQL**: crea una base de datos y un usuario con todos los privilegios sobre ella. Anota nombre de la base, usuario y clave. Luego en **phpMyAdmin**: selecciona esa base de datos → pestaña **Importar** → selecciona el archivo `db/schema.mysql.sql` (está en esta carpeta) → Ejecutar. Deberías ver las tablas `ot_users`, `ot_clients`, `ot_client_branches`, `ot_equipment`, `ot_checklist_templates`, `ot_checklist_template_items`, `ot_work_orders`, `ot_work_order_equipment`, `ot_work_order_checklist_answers`, `ot_work_order_photos`, `ot_auth_tokens`, `ot_settings`. Esta instalación nueva ya incluye todo (sucursales, activos, varios equipos por OT, pauta por equipo, etc.) — **no necesitas correr `migration_v2.mysql.sql`, `migration_v3.mysql.sql` ni `migration_v4.mysql.sql`**, esos archivos son solo para actualizar una instalación existente. ## Paso 3 — Subir los archivos Sube TODO el contenido de esta carpeta (menos `INSTALL.md` y `db/`, que no necesita estar en el servidor web) a la raíz del subdominio. ``` ot.jair.cl/ ├── admin/ (panel para el computador) ├── api/ (backend) ├── tecnico/ (app para el celular) └── uploads/ (fotos, firmas y logos — necesita permisos de escritura) ``` Asegúrate que la carpeta `uploads/` tenga permisos 755 (o 775 si tu hosting lo requiere). ## Paso 4 — Configurar la conexión a la base de datos Abre `api/config.php` con el editor de archivos de cPanel y completa con los datos reales de la base de datos que creaste en el Paso 2: ```php define('DB_NAME', getenv('APP_DB_NAME') ?: 'TU_BASE_DE_DATOS'); define('DB_USER', getenv('APP_DB_USER') ?: 'TU_USUARIO'); define('DB_PASS', getenv('APP_DB_PASS') ?: 'TU_CLAVE'); ``` `APP_SECRET` ya viene generado con un valor aleatorio único — no hace falta cambiarlo. ## Paso 5 — Crear el usuario administrador Visita en el navegador (reemplaza `TU_APP_SECRET` por el valor de `APP_SECRET` que quedó en `api/config.php`, y los datos del admin que quieras usar): ``` https://ot.jair.cl/api/install.php?key=TU_APP_SECRET&email=admin@jair.cl&password=unaClaveSegura&name=Tu+Nombre ``` Debería responder `{"ok":true,...}`. Este script solo funciona **una vez** (mientras no exista ningún administrador). Por seguridad, después de usarlo: **Borra el archivo `api/install.php` del servidor.** ## Paso 6 — Probar - Entra a `https://ot.jair.cl/admin/` con el email/clave del Paso 5. - Ve a **Configuración** y sube el logo de tu empresa. - Crea un usuario técnico, un cliente (con su logo y sucursales si corresponde), sus equipos, un formulario, y una OT de prueba asignada al técnico. - Desde el celular del técnico, entra a `https://ot.jair.cl/tecnico/` e inicia sesión ("Agregar a pantalla de inicio" para que quede como app). Prueba a poner el celular en modo avión, llenar y firmar una OT (con al menos 1 foto), y reactivar los datos: debería subirse sola. - Descarga el PDF de esa OT desde el panel una vez completada. ## Notas de seguridad - `api/config.php` tiene la contraseña de la base de datos — no lo compartas ni lo subas a repositorios públicos. - Las fotos, firmas y logos quedan en `uploads/`, protegido para que no se pueda ejecutar código ahí, pero las imágenes SÍ son accesibles por URL directa si alguien adivina la ruta exacta. - Los tokens de sesión duran 30 días. Se puede ajustar en `api/config.php` (`TOKEN_TTL_DAYS`). ## Si algo falla - Pantalla en blanco o error 500: revisa `api/config.php` (datos de la base de datos correctos) y que el hosting tenga PHP 8.0+ con las extensiones PDO MySQL y GD habilitadas (son estándar en cPanel). - "No autenticado" constantemente: revisa que el reloj del servidor esté correcto. - Fotos no se guardan: revisa permisos de escritura de la carpeta `uploads/`. - El botón "Descargar PDF" solo aparece cuando la OT está en estado "Completada".