ITECEL ADM — Wiki Técnica

Appearance

Roadmap del Proyecto — ITECEL ADM ​

Sistema Integral de Administración Condominal y Financiera
Documento oficial de arquitectura, ciclo de vida de producto y planificación estratégica.

Versión: v2.3
Leyenda de estados: ✅ Completada · ⏸️ Cerrada temporalmente (Pendiente de pruebas) · 🔄 EN CURSO · 📅 Siguiente / Post-Validación · 💭 Futura / En estudio

Índice ​

1. Visión General del Producto ​

ITECEL ADM es una plataforma SaaS integral para la gestión operativa, contable, financiera y de convivencia en condominios, edificios residenciales y complejos habitacionales.

Su propósito central: transparencia financiera total, automatización de cobranza, trazabilidad bancaria rigurosa y empoderamiento de residentes y directivas a través de interfaces modernas, seguras y de baja fricción.

  • Infraestructura: React + Tailwind CSS + Supabase (PostgreSQL, Auth, Storage, Edge Functions) + Vercel (despliegue) + Resend (correos transaccionales) + dominio propio itecelgs.com (aplicación en adm.itecelgs.com, correos desde notificaciones@itecelgs.com).
  • Modelo de negocio: licencias operativas por correo (1 correo = 1 licencia = 1 condominio administrado). Cada condominio es una suscripción independiente. Superadmin con Panel de Control / Cockpit centralizado.

2. Estado de las Fases de Desarrollo ​

FaseDenominaciónEstadoHitos Clave
Fase 1Núcleo Operativo + Persistencia Blindada✅ CompletadaViviendas, cuotas, adeudos, egresos, bancos, estados de cuenta + motor unificado de persistencia.
Fase 2Automatización, Identidad, Cobranza y Dominio✅ CompletadaSupabase Auth + RBAC, Resend + Edge Functions, cobranza masiva, extractos "Al día", dominio corporativo.
Fase 2-bCorrecciones del Primer Uso Real✅ CompletadaNomenclatura de pagos por recibo, selección → PDF parcial, branding, Error Boundary, trazabilidad.
Fase 2-cHistorial de Acciones + Auto-Sync✅ CompletadaPuntos de restauración locales + auto-sync en segundo plano con estados visibles.
Fase 4Cambio de Paradigma: Licencias + Multi-Contexto + Cockpit✅ CompletadaIdentidad unificada por correo, licencias por condominio, RLS real, respaldos centrales del proveedor, Cockpit Panel de Control.
Fase 5-VISUALErgonomía de Navegación, Paletas y Modo Oscuro✅ CompletadaNavbar sólido con color dinámico, paletas ITECEL Clásica / Índigo / Esmeralda / Púrpura Ejecutivo, Dark Mode estándar WCAG AA.
Fase ActualValidación en Producción (El Piloto)🔄 EN CURSOLanzamiento 21/09. 2 condominios reales en producción (~2 meses). Reconciliación contable y estabilidad.
Fase 6Módulos Residenciales Paralelos⏸️ CERRADA TEMPORALMENTEPendiente de pruebas en producción. 6.1 Feed de Comunicaciones (Markdown en vivo, avisos prioritarios, orden cronológico estricto) + 6.2 Documentos y Actas (Storage, descarga directa, vinculación).
Fase 7El Embudo Comercial: Tienda de Licencias + Demo Freemium🔄 EN CURSOPágina comercial pública (catálogo/planes/vitrina), Demo Freemium limitada con verificación de email, Tienda de licencias con activación manual y conversión sin pérdida de datos.
Post-ValidaciónEcosistema Comercial📅 PlanificadaPasarelas de pago ecuatorianas (Payphone/Kushki/Stripe), WhatsApp Business API, Facturación electrónica.
Fases FuturasEscalamiento y Plataformas💭 En estudioPortal del residente ampliado, App Android (Capacitor), PWA / LTSC Windows (Tauri+SQLite), pg_cron real.

3. Detalle por Fase ​

Fases Históricas Completadas ​

Fase 1: Núcleo Operativo + Persistencia Blindada (Completada) ​

  • Gestión condominal: perfil institucional, cuentas bancarias, alícuotas y fondos.
  • Padrón de viviendas y propietarios: coeficientes, contactos de propietarios y arrendatarios.
  • Motor de cuotas y adeudos: plantillas recurrentes, generación masiva por período, captura manual con validación de duplicados.
  • Tesorería y bancos: cuentas, ingresos, egresos por partidas presupuestarias, proveedores.
  • Estados de cuenta: saldos por vivienda, comprobantes PDF con folios y desglose de movimientos.
  • Persistencia blindada: motor unificado de serialización (11 entidades), sincronización con Supabase en lotes + reconciliación de referencias.

Fase 2 / 2-b / 2-c: Identidad, Cobranza, Historial y Estabilidad (Completadas) ​

  • Auth + RBAC: Supabase Auth con roles (admin, committee, resident), resolución dual de roles y recuperación de credenciales.
  • Aprovisionamiento y cobranza masiva: Edge Functions (send-invitation, send-statement) + Resend corporativo en dominio itecelgs.com.
  • Finanzas y reportes: desglose por recibo en 2 niveles, exportación PDF selectiva, Error Boundary global.
  • Historial de acciones: snapshots locales por diseño con puntos de restauración y deshacer; auto-sync con feedback honesto de estado.

Fase 4: Licencias, Multi-Contexto y Gobernanza Central (Completada) ​

  • Identidad unificada por correo: 1 correo = 1 licencia = 1 condominio administrado.
  • Selector multi-contexto: activado exclusivamente para correos con múltiples registros de acceso.
  • Cockpit / Panel de Control del superadmin: gestión centralizada de licencias, estados de sincronización y respaldos del proveedor.
  • Gobernanza de respaldos centrales: copias centrales gestionadas por el proveedor en base de datos para emergencias catastróficas.

Fase 5-VISUAL: Ergonomía, Paletas Dinámicas y Modo Oscuro (Completada) ​

  • Navbar siempre de color sólido con adaptación cromática dinámica según el tema seleccionado.
  • Paletas calibradas: ITECEL Clásica (sobria sin contrastes estridentes), Índigo Tech, Esmeralda Corporativo y Púrpura Ejecutivo ajustado.
  • Modo oscuro refinado en todos los módulos con tarjetas estandarizadas (bg-slate-900 border-slate-800), alto contraste WCAG AA y documentos de impresión estrictamente en fondo blanco.

FASE ACTUAL — VALIDACIÓN EN PRODUCCIÓN (EL PILOTO) ​

  • Lanzamiento oficial: 21/09 — el piloto corre activamente en producción.
  • Condominio #1 (socio-administrador): Reconciliación de cierre de mes contra su sistema anterior — los números cuadran = producto validado.
  • Condominio #2 (colaboradora): Estreno de la nueva arquitectura — operación desde cero, SIN respaldos locales del usuario, con respaldos centrales del proveedor.
  • Período de validación: ~2 meses de operación real de ambos pilotos. Al segundo mes se evalúa la viabilidad de escalar incorporando hasta a 3 colaboradores adicionales (3 condominios más) al proyecto.
  • REGLA DE LA FASE: Los bugs del piloto se clasifican estrictamente:
    • Pérdida / integridad de datos: Atención inmediata y prioritaria (excepción sagrada).
    • Otros reportes / mejoras: Van al backlog del piloto.
  • CONGELAMIENTO DEL NÚCLEO: El núcleo contable y financiero queda CONGELADO para cambios estructurales o nuevas funcionalidades durante toda la validación. El desarrollo en esta fase se centrará exclusivamente en bug-fixes reportados por el piloto.

FASE 6 — MÓDULOS RESIDENCIALES PARALELOS (CERRADA TEMPORALMENTE — PENDIENTE DE PRUEBAS) ​

Estado: ⏸️ Cerrada temporalmente, pendiente de batería final de pruebas en el entorno de producción real. Contexto estratégico: Construcción en paralelo a la validación de módulos NUEVOS y AUTOCONTENIDOS que NO tocan el núcleo contable (el ecosistema contable actual permanece intacto y aislado). Al culminar con éxito la validación del piloto, la apertura comercial arrancará con el catálogo de funcionalidades residenciales ya construido.

Regla de aislamiento:

  1. Los módulos nuevos no modifican ni interfieren con las tablas, lógica ni vistas del núcleo contable en pruebas.
  2. Si surge un bug de pérdida o integridad de datos en el piloto → se congela de inmediato esta Fase 6 y se atiende la urgencia del piloto.

Módulo 6.1 — FEED DE COMUNICACIONES (Blog del Condominio) ​

  • Publicación del administrador: Avisos, noticias, comunicados oficiales (título, contenido enriquecido, fecha de publicación, imagen adjunta opcional).
  • Editor con Split-Screen: Barra de herramientas Markdown completa con vista previa en vivo lado a lado en tiempo real.
  • Tratamiento de avisos prioritarios: Fijación preferente al tope del feed con distintivo y borde visual de alerta.
  • Orden cronológico estricto: Visualización ordenada por fecha_publicacion DESC (y created_at DESC para resolver publicaciones del mismo día sin colisión).
  • Lectura comunitaria: Residentes y miembros del directorio visualizan los comunicados en su vista en formato de feed cronológico interactivo.
  • Persistencia y seguridad: Tabla posts autocontenida con políticas RLS propias (escritura solo admin / lectura para usuarios del condominio).
  • Acceso independiente (sin contaminación del ecosistema contable): Acceso alternativo e independiente desde el navbar con botón expandible al hover (#navbar-quick-communications-btn), dejando el panel contable libre de saturación.

Módulo 6.2 — DOCUMENTOS Y ACTAS (Supabase Storage) ​

  • Carga y gestión: El administrador sube actas de asambleas, reglamentos internos, documentos legales y normativas.
  • Almacenamiento: Bucket condo-community en Supabase Storage (lectura directa pública por URL, sin listado anónimo público, escritura autenticada).
  • Organización y consulta: Documentos clasificados por fecha y categoría, consultables y descargables desde el repositorio de documentos y vinculables directamente a publicaciones del feed.
  • Persistencia: Tabla documents autocontenida con políticas RLS propias.
  • Diferido (documentado para escalón 2): Integración con Google Drive del cliente (OAuth individual por administrador para guardar archivos directamente en su propia nube de Google). Se evaluará si un cliente corporativo lo exige; la versión base prioriza Supabase Storage por simplicidad y control.

FASE 7 — EL EMBUDO COMERCIAL: TIENDA DE LICENCIAS + DEMO FREEMIUM (NUEVA — EN CURSO) ​

Contexto: La Fase 4 completa habilitó el modelo comercial (licencias por correo, panel del superadmin, multi-contexto). Esta fase abre la PUERTA COMERCIAL: página pública de venta, demo gratuita limitada para probar, y tienda de licencias con activación manual del proveedor.

Modelo Comercial Definido: ​

  • Precios de Licenciamiento:
    • Licencia 1 mes: $20 USD
    • Licencia 3 meses: $50 USD
    • Licencia 1 año: $120 USD (precio promocional de apertura, a la larga desaparecerá)
  • Modelo de pago en v1: Pago por transferencia/depósito/pasarela manual + comprobante + envío de comprobante por WhatsApp, Telegram o correo → ACTIVACIÓN MANUAL del superadmin desde el Panel de Licencias (la automatización del cobro mediante pasarelas automatizadas es fase posterior, cuando la demanda la justifique).
  • Demo gratuita: 1 condominio, con limitaciones de módulos, vigencia limitada de 30 días, con conversión transparente a licencia completa sin perder datos.

Alcance Detallado de la Fase 7: ​

  1. PÁGINA COMERCIAL PÚBLICA (accesible sin login, desde "¿No tienes cuenta? Prueba gratis hoy" en la pantalla de login):

    • Explicación de qué es ITECEL ADM, catálogo de características y módulos.
    • Tabla comparativa de planes con precios y ahorros calculados.
    • Presentación de la demo gratuita.
    • Formulario de registro con DOS rutas claras: Comprar licencia / Demo gratuita.
    • Vitrina comercial de ITECEL con branding institucional completo.

  2. DEMO FREEMIUM (La conversión de prueba):

    • Formulario de captura: nombre completo, correo electrónico, teléfono y nombre del condominio.
    • VERIFICACIÓN DEL CORREO antes de crear el espacio: Link de validación enviado al email (el antídoto indispensable contra registros basura/bots).
    • Aprovisionamiento post-verificación: al verificar, se crea SU condominio en blanco + SU licencia tipo 'demo' + correo de invitación para definir contraseña y acceder a su espacio privado.
    • LAS LIMITACIONES DE DEMO (El sabor del producto sin los módulos pesados):
      • ❌ SIN Invitaciones y Accesos de Residentes
      • ❌ SIN Cobranza Masiva
      • ❌ SIN Subida de Documentos al repositorio
      • ✅ CON Feed de comunicaciones oficial (postear, adjuntar imágenes)
      • ✅ CON Logo y ficha institucional del condominio
      • ✅ CON Su estado de cuenta en modo lectura
    • Vigencia de la demo: [30 días calendario] → al vencer: pantalla digna "Su demo ha finalizado — contacte a ITECEL" (reutilizando el patrón probado de suspensión de licencias).

  3. TIENDA DE LICENCIAS (La compra):

    • Selección del plan (1 mes, 3 meses, 1 año) → captura de datos del cliente → instrucciones de pago por transferencia/depósito bancario → envío de comprobante (vía formulario, WhatsApp, Telegram o correo).
    • El registro queda en el Panel de Licencias del superadmin como "pendiente de activación".
    • El superadmin valida el pago y activa la licencia completa directamente desde el panel.
    • Estructura en licenses: campos tipo ('demo' | 'completa') + plan ('mensual' | 'trimestral' | 'anual') + fecha de vencimiento (valid_until).

  4. LA CONVERSIÓN DEMO → COMPLETA (Sin perder datos):

    • Gestionada directamente desde el Panel de Licencias del superadmin: al recibir el pago, se conmuta el tipo de licencia a 'completa', se asigna el plan y se actualiza la vigencia.
    • El usuario pasa inmediatamente de limitado a completo SIN perder su carga previa, configuraciones ni registros.

  5. GOBERNANZA DE REGISTROS Y EMBUDO VISIBLE:

    • Registros de demo y compras pendientes consolidados en el Panel de Licencias del superadmin (embudo comercial visible: demos activas, demos vencidas, conversiones, compras pendientes de activación).
    • Verificación estricta de correo en el registro como filtro activo contra registros fantasma.

Reglas Intocables del Proyecto: ​

El núcleo contable, RLS, auth, el piloto #1, el estreno del condominio #2, el motor de historial, los respaldos centrales y el módulo de comunicaciones permanecen INTOCABLES. Nada del sistema existente se toca salvo: la página pública nueva, el formulario de demo/registro, los campos nuevos en licenses y el panel extendido del superadmin.

FASES POST-VALIDACIÓN (EL ECOSISTEMA COMERCIAL) ​

Orden de ejecución estratégica según demanda al abrir la comercialización:

  1. Ecosistema de pagos en línea:
    • Pasarelas de pago locales ecuatorianas primero (Payphone / Kushki) y Stripe según alcance internacional.
    • Botón "Pagar ahora" integrado en estados de cuenta y en el portal del residente.
    • Webhook de confirmación segura vía Edge Function (payment-webhook).
    • Flujo automático completo: paga → registra abono → aplica a adeudo → notifica comprobante.
    • Gobernanza financiera: La cuenta bancaria receptora es exclusivamente LA DEL CONDOMINIO (el proveedor ITECEL jamás intermedia ni custodia fondos de terceros).
  2. WhatsApp Business API:
    • Envío de notificaciones y recordatorios de cobro mediante plantillas preaprobadas por Meta.
    • Constituye el canal con mayor tasa de apertura y lectura real del mercado.
  3. Facturación electrónica:
    • Emisión de comprobantes autorizados y generación de código QR validador para formalización fiscal ante la entidad tributaria.

FASES FUTURAS (SEGÚN DEMANDA POST-ESTRENO) ​

  • Portal del residente completo: Canales comunitarios, reserva de áreas sociales con bloqueo por mora, buzón de solicitudes/tickets y visualización de actas (aprovechando la base de roles y estilos ya consolidada).
  • App Móvil Android (Capacitor): Empaquetado del portal web con notificaciones push nativas — gatillado por demanda real de los residentes del piloto.
  • PWA offline y/o versión LTSC Windows: Aplicación de escritorio / local mediante Tauri + SQLite embebido + licencia criptográfica Ed25519 offline (producto gemelo para clientes con requisitos de conectividad cero o aislamiento bajo demanda pagada: "dos cuerpos, un cerebro").
  • Respaldos automatizados pg_cron: Programación de respaldos centrales programados independientes de la interacción del usuario en Supabase antes del escalado masivo de clientes.
  • Panel → Edge Functions server-side: Arquitectura multi-superadmin con autorización delegada a nivel de servidor.
  • Sincronización diferencial exacta: Mecanismo optimizado para condominios de alta densidad volumétrica.
  • Modo oscuro refinado + paleta personalizable: Ajustes estéticos incrementales según feedback de usuarios.
  • Limpieza legacy final: Depuración de código remanente de prototipos tempranos una vez estabilizado el catálogo.

4. Economía del Proyecto ​

  • Invertido a la fecha: ~$40 USD (Dominio institucional $15 + AI Pro $15/3 meses + créditos y herramientas $10).
  • En curso: Suscripción AI Pro activa hasta diciembre (monitoreo continuo de consumo y cuotas).
  • Siguiente gasto previsto: Configuración de pg_cron / mantenimiento de infraestructura al comenzar el escalamiento de nuevos condominios.
  • Meta comercial: Captación de los primeros clientes de pago al concluir la validación del piloto → la inversión y costos operativos se amortizan íntegramente con las primeras licencias comercializadas.

5. Lecciones Institucionalizadas (Intocables del Método) ​

  1. Doble-despliegue: El push al repositorio/Vercel NO actualiza Edge Functions ni esquema SQL en Supabase — requiere ejecución manual en el dashboard.
  2. Ciclo de prueba humano: Cada turno de desarrollo requiere validación y batería de pruebas manuales antes del siguiente ciclo.
  3. Forense antes de instrucción: Ante cualquier error, auditar primero URL, Consola, Network y Table Editor antes de proponer cambios.
  4. Seguridad de credenciales: Claves y secretos de servicio jamás se exponen en chat ni código cliente; se gestionan en variables de entorno seguras.
  5. Verificación en base de datos: "Se ve bien en la interfaz" ≠ registro correcto en el Table Editor de Supabase (post-sync verificado).
  6. Autoridad del servidor: El servidor y la base de datos mandan; el almacenamiento local es exclusivamente contingencia y optimización de render.
  7. Reanudación metódica: Prompt de reanudación siempre listo: auditar primero el estado real, continuar después.
  8. Pruebas con datos reales: El operador y tester con información real de condominios es el detector más certero de inconsistencias de producción.
  9. Respeto a lo estable: Prohibido modificar o "refactorizar" componentes que funcionan correctamente sin requerimiento explícito.
  10. Instrucciones con ejemplos concretos: Describir cambios con el contraste antes/después para eliminar ambigüedades interpretativas.
  11. Construcción paralela a la validación: Solo se desarrollan módulos NUEVOS y autocontenidos — el núcleo contable en pruebas de piloto permanece estrictamente congelado para cambios.
  12. Veracidad en el feedback del sistema: Los mensajes y estados en la interfaz deben reflejar fielmente la operación real ejecutada (lección del falso restaurativo).
  13. Separación de identidad vs. campos descriptivos: Los datos institucionales y de contacto del condominio son descriptivos y no deben mezclarse con la identidad y credenciales de acceso de la cuenta de usuario (la regla de la ficha institucional).

6. Control de Cambios y Versiones ​

VersiónFechaAutor / RolDescripción
v1.0.02026-08Equipo NúcleoNúcleo contable y condominal.
v1.1.02026-09Testing & QAResend, Edge Functions, branding ITECEL.
v1.2.02026-09Testing & QAUX en Finanzas/Estados/Envíos + Roadmap oficial.
v1.2.12026-09Testing & QAF2 jerárquico, C1 doble logotipo, sync PDF.
v2.0.02026-09Dirección estratégicaConsolidación definitiva: modelo de licencias por correo, Piloto Real como fase de facturación, paradigma multi-contexto definido con estreno del condominio #2, lecciones institucionalizadas (1-10).
v2.1.02026-09Dirección estratégicaFase 4-F/4-G: Reorganización de navegación, Panel de Control del superadmin, gobernanza de respaldos centrales, historial local por diseño y limpieza forense.
v2.2.02026-09Dirección estratégicaClausura formal de Fases 4 y 5-VISUAL. Apertura oficial de la Fase Actual de Validación en Producción (Piloto 21/09 con congelamiento del núcleo contable). Incorporación de la Fase 6 (Módulos Residenciales Paralelos: Feed de Comunicaciones y Documentos/Actas vía Storage). Definición de Ecosistema Comercial Post-Validación (Pagos en línea, WhatsApp API, Facturación), desglose de Economía del Proyecto e institucionalización de lecciones 11, 12 y 13.
v2.3.02026-09Dirección estratégicaCierre temporal de la Fase 6 (pendiente de pruebas). Apertura formal de la Fase 7 en curso (El Embudo Comercial: Tienda de Licencias + Demo Freemium). Modelo de precios ($20 / $50 / $120), validación previa de correos anti-spam, flujo de compra v1 con activación manual de superadmin, limitaciones de demo y conversión transparente sin pérdida de datos.

Wiki Técnica Oficial — ITECEL ADM

Acceso Restringido · Cloudflare Zero Trust