# AI_GUIDE.md ## 1) Objetivo Este documento define las reglas para asistentes de IA que trabajen sobre este repositorio. Su objetivo es producir cambios **pequeños, consistentes, seguros y fáciles de revisar por el equipo**. Las propuestas de la IA deben priorizar: * claridad * impacto mínimo * compatibilidad con la arquitectura actual * facilidad de revisión en Pull Requests --- # 2) Stack oficial * **Backend:** PHP 8.3 + CodeIgniter 4.3.x * **Frontend:** TailwindCSS 4.x + JavaScript vanilla * **Base de datos:** MySQL 8 * **Infraestructura local:** Docker / Docker Compose + Apache Reglas: * No proponer frameworks o librerías fuera de este stack sin solicitud explícita. * No introducir nuevas dependencias si el problema puede resolverse con el stack actual. --- # 3) Estructura del proyecto La raíz del repositorio **no es la raíz de la aplicación**. La aplicación CodeIgniter vive dentro de: ``` project-root/ ``` Estructura principal: ``` project-root/app/Controllers project-root/app/Models project-root/app/Views project-root/public project-root/public/assets/css project-root/public/assets/css/tailwind.css project-root/public/assets/css/styles.css project-root/public/js project-root/.env ``` Reglas importantes: * No asumir que `app/`, `public/` o `spark` están en la raíz del repositorio. * Todas las rutas del proyecto deben partir desde `project-root`. La raíz web es: ``` project-root/public ``` --- # 4) Dominio funcional (modelo mental) Entidad principal de cursos: Curso / Programa → Materia → Clase → Recurso Es importante la variable id_usuario, id_suscripcion ya que se obtiene de una cookie y es vital para buscar sus datos dentro de la plataforma. Relaciones principales: Usuario → Suscripción → Avance / Calificación / Certificado Módulo comercial: Producto → Orden → Transacción → Cupón Módulo comunidad: Dudas Testimonios Tablas críticas: ``` tbl_materia tbl_clase tbl_recurso tbl_suscripcion tbl_suscripcion_pago tbl_calificacion tbl_producto tbl_orden tbl_transaccion tbl_cupon* ``` Reglas: * No inventar entidades nuevas sin necesidad funcional. * No modificar relaciones existentes sin explicar impacto. --- # 5) Reglas de análisis previo (obligatorio) Antes de proponer cambios la IA debe: 1. localizar controlador, modelo y vista involucrados 2. revisar tablas reales en la base de datos 3. identificar lógica reutilizable existente 4. analizar impacto en rutas, formularios o consultas 5. evitar asumir nombres de tablas o columnas Si no hay suficiente información, la IA debe pedir contexto antes de modificar código. --- # 6) Convenciones de código ## Base de datos Convenciones históricas: ``` tablas: tbl_* primary keys: id_* ``` Ejemplo: ``` tbl_usuario id_usuario ``` --- ## Modelos CodeIgniter Cada modelo debe definir: ``` protected $table protected $primaryKey protected $allowedFields ``` Reglas: * respetar campo `activo` cuando exista * evitar lógica SQL compleja en controladores * centralizar consultas en modelos --- ## Backend CI4 Los controladores deben: * coordinar lógica * delegar consultas a modelos No hacer: * consultas duplicadas en múltiples controladores * lógica de negocio repetida Reutilizar: * helpers existentes * utilidades del proyecto --- ## Frontend Reglas: * usar JavaScript vanilla * evitar frameworks frontend nuevos * no introducir jQuery salvo que el módulo ya lo use Preferencias: * scripts en `public/js` * evitar JS inline en vistas --- # 7) Seguridad mínima La IA debe garantizar: * validación de inputs * sanitización de datos * escape de salida HTML * uso de Query Builder o parámetros preparados Evitar: * concatenar variables en SQL * exponer información sensible * hardcodear credenciales Si el cambio afecta: * login * pagos * cupones * suscripciones * certificados debe indicar **riesgo explícito**. --- # 8) Flujo de trabajo recomendado 1. Analizar antes de editar 2. Hacer cambios pequeños 3. Validar sintaxis y consultas 4. Entregar propuesta clara Cada cambio debe tener un objetivo único. Ejemplo: * corrección de catálogo * mejora en pagos * ajuste en módulo de dudas --- # 9) Reglas para prompts a IA Los prompts deben incluir: * archivo objetivo * comportamiento esperado * restricciones * ejemplos de entrada y salida * si hay cambios en base de datos Ejemplo: ``` Modifica para lograr . No cambies . Si requiere base de datos, incluye script SQL compatible con MySQL 8. Devuelve: - diff - riesgos - pasos de validación ``` --- # 10) Formato esperado de respuesta de la IA Toda propuesta debe incluir: 1. resumen del cambio 2. archivos modificados 3. riesgos 4. SQL necesario (si aplica) 5. prueba manual mínima 6. rollback 7. diff o bloques de código --- # 11) Docker y comandos útiles Levantar entorno: ``` docker compose up -d --build ``` Build frontend: ``` npm run build ``` Modo watch: ``` npm run watch ``` Nota: El contenedor ejecuta: ``` npm install npm run build ``` al iniciar. --- # 12) Base de datos Todas las consultas deben ser compatibles con: ``` MySQL 8 ``` Si hay cambios SQL indicar: * tipo de script * creación * alteración * rollback Evitar: ``` DROP TABLE DROP COLUMN ``` salvo solicitud explícita. Si se agregan columnas indicar impacto en: * modelos * joins * formularios * vistas --- # 13) Alcance funcional actual Fuera de alcance: * eBooks * biblioteca digital * sistema de notificaciones Mantener: * cupones * testimonios Fases del proyecto: Fase 1 Core académico + comercial Fase 2 Comunidad (dudas / testimonios) --- # 14) Módulos sensibles Áreas críticas: * pagos * cupones * suscripciones * transacciones * certificados * autenticación Si la IA modifica estos módulos debe: * indicar riesgo * proponer pruebas manuales * evitar refactors grandes --- # 15) Criterios mínimos de calidad No se debe: * romper rutas existentes * cambiar contratos de respuesta * introducir tablas sin uso real * crear consultas N+1 * mezclar UI, lógica y DB en un solo cambio Toda propuesta debe incluir: * archivos modificados * riesgo * prueba manual * rollback SQL --- # 16) Qué evitar * refactors masivos * reorganizar estructura del repositorio * introducir nuevas capas innecesarias * inventar endpoints o tablas * reescribir módulos completos por bugs menores --- # Particularidades de este repositorio Este proyecto tiene características específicas: * La aplicación vive en `project-root/` * La raíz web es `project-root/public` * La infraestructura Docker puede manejarse fuera del repositorio * No asumir que `Dockerfile`, `docker-compose.yml` o `apache-config.conf` estén versionados * Diferenciar siempre entre **código fuente** e **infraestructura** --- # 17) Regla de impacto mínimo La IA debe preferir **el cambio más pequeño posible** que resuelva el problema. Si detecta deuda técnica: * documentarla * no mezclarla con el cambio principal