# Plan de Implementación — sigueobras.cl ### Plataforma de seguimiento de obras de construcción (multi-rol) > Documento base para desarrollo con agentes de IA (Google Antigravity / Claude Code). > Divide el trabajo en fases pequeñas; no pegar todo el documento como un solo prompt — usar cada fase como una tarea independiente, entregando el contexto fijo (roles + modelo de datos) en cada una. --- ## 1. Descripción del producto Plataforma web (www.sigueobras.cl) para el seguimiento de obras de construcción. El **Arquitecto** cumple además el rol de **Administrador único de la plataforma**: es quien crea las obras, crea los usuarios y controla todo el sistema. Sobre cada obra interactúan los roles: **Arquitecto/Administrador** (1, controla todo), **Propietarios** (2 a 3 personas), **Constructores** (3 a 4 personas), **ITO** — Inspector Técnico de Obras (2 a 3 personas) y **Externo** (colaboradores puntuales sin necesidad de acceso completo). La plataforma permite subir planos en distintas versiones, gestionar solicitudes de información (RFIs), ver avances fotográficos, revisar carta Gantt, registrar reuniones de obra y mantener trazabilidad completa del proyecto. --- ## 2. Flujo de acceso (nuevo): Obra → Rol Este es el cambio central de este documento: **el orden de entrada es primero la obra, después el rol** — no un login genérico de usuario/contraseña como primera pantalla. ### 2.1 Pantalla de entrada (pública) 1. La persona llega a sigueobras.cl y ve un selector de **obras activas** (nombre + dirección/miniatura, sin datos sensibles). 2. Al elegir una obra, se despliegan los **roles disponibles para esa obra** que ya tienen al menos un usuario creado (ej. "Propietarios", "Constructores", "ITO", "Externo"). El rol "Arquitecto/Administrador" no aparece en este listado público — tiene su propio acceso (ver 2.3). 3. Al elegir un rol, se pide **correo + contraseña** de la persona (cada persona tiene su propia cuenta individual, aunque comparta rol con otras 2-3 personas del mismo tipo). 4. Si la persona no tiene cuenta creada todavía para esa obra/rol, no puede "auto-registrarse" — ve un mensaje del tipo *"Tu acceso debe ser creado por el administrador de la obra"*, sin opción de crear cuenta libremente (evita accesos no controlados). ### 2.2 Creación de obras y usuarios (solo Arquitecto/Administrador) - Solo el Arquitecto/Administrador puede **crear una obra nueva** (nombre, dirección, fecha inicio, estado). - Dentro de cada obra, el Arquitecto/Administrador **crea las cuentas de usuario** para Propietarios, Constructores, ITO y Externo: - Define nombre, correo, rol y (si corresponde) sub-tipo dentro del rol (ej. "Constructor - Jefe de obra", "Propietario 1"). - El sistema envía una invitación al correo para que la persona defina su propia contraseña (igual que en la versión anterior del plan) — el Arquitecto no define la contraseña de otros, solo crea el acceso. - Estados de usuario: `invitado` (aún no definió contraseña) / `activo`. - El Arquitecto puede tener **varias obras en paralelo**; al entrar por su acceso especial (2.3) elige primero la obra sobre la que quiere trabajar, igual que los demás roles, pero sin restricción — ve todas las obras que ha creado. ### 2.3 Acceso del Arquitecto/Administrador - Entrada separada (ej. `/admin` o botón discreto en la pantalla de entrada, no un rol más del listado público del paso 2.1). - Login con correo + contraseña propios (con 2FA recomendado dado que administra todo). - Una vez dentro, ve el selector de **todas sus obras**, puede crear una nueva, y entrar a cualquiera para administrar usuarios, subir planos, revisar todo. ### 2.4 Panel oculto de administración (visibilidad de usuarios y credenciales) Pediste una página oculta donde tú, como Arquitecto/Administrador, puedas ver los roles y contraseñas de los demás usuarios. Una aclaración técnica importante antes de construir esto: - **Buena práctica de seguridad**: las contraseñas nunca deberían quedar almacenadas de forma que se puedan "mostrar" tal cual — se guardan con hash (irreversible), tanto por seguridad de las personas como por responsabilidad legal si hay una filtración. - Lo que sí es perfectamente viable y te da el mismo control práctico que buscas es un **panel oculto** (ej. `/admin/obra/:id/usuarios`) donde puedas: - Ver el listado completo de usuarios por obra: nombre, correo, rol, sub-tipo, estado (`invitado`/`activo`), fecha de creación, último acceso. - **Forzar el reseteo de contraseña** de cualquier usuario (le llega un link a su correo) o **generar una contraseña temporal** que tú puedas comunicarle directamente (por WhatsApp, en persona, etc.), sin que quede visible permanentemente en el sistema. - Desactivar o reactivar un acceso al instante (útil si alguien deja la obra). - Esto te da control total y visibilidad, sin guardar contraseñas reales en texto plano en la base de datos (lo cual además suele ser requisito para poder alojar el sitio en Vercel/Supabase sin infringir sus políticas). Si de todas formas quieres la opción de "contraseña temporal visible una sola vez" para pasársela tú mismo a alguien sin depender de que revisen su correo, es completamente posible — lo importante es que no quede como un campo consultable indefinidamente, sino como una acción puntual ("generar clave temporal" → se muestra una vez → se hashea al guardar). --- ## 3. Roles y permisos (RBAC multi-tenant por obra) Cada obra es un "workspace" independiente. Los roles se asignan por obra, no de forma global (excepto el Arquitecto/Administrador, que tiene acceso a todas las obras que crea). | Rol | Cantidad típica por obra | Puede | No puede | |---|---|---|---| | **Arquitecto/Administrador** | 1 (el mismo en todas sus obras) | Crear obras, crear/gestionar usuarios de todos los roles, subir planos (arquitectura y especialidades) en distintas versiones, responder RFIs, participar en reuniones, ver y editar todo | — | | **Propietarios** | 2 a 3 | Ver todo (planos, fotos, gantt, RFIs, reuniones, estados), comentar, aprobar hitos | Editar planos, cerrar RFIs técnicos, editar actas | | **Constructores** | 3 a 4 | Subir avances, fotos, gantt, responder RFIs, solicitar info al Arquitecto, subir actas de reuniones que organicen | Aprobar sus propios hitos, editar planos | | **ITO (Inspector Técnico)** | 2 a 3 | Subir inspecciones, generar RFIs a Constructores/Arquitecto, aprobar/rechazar entregables, crear reuniones y subir actas, ver todo | Editar planos de arquitectura | | **Externo** | Variable (según necesidad puntual) | Ver documentos y secciones específicas que el Arquitecto le habilite (ej. un ingeniero de especialidad revisando solo su set de planos, o un proveedor viendo solo el Gantt), comentar en lo habilitado | Ver el resto de la obra fuera de lo habilitado, aprobar, editar, cerrar RFIs | > Nota sobre "Externo": a diferencia de los `invitados_externos` del módulo de Reuniones (que son solo un nombre y cargo sin cuenta, para marcar asistencia), el rol **Externo** aquí sí tiene cuenta propia con correo y contraseña, pero con **permisos acotados por el Arquitecto** al crear su acceso (ej. solo ve el módulo de Documentos, o solo una carpeta de planos de especialidad). Conviene definir esto como permisos granulares por módulo/carpeta, no como un rol de "todo o nada". **Autenticación individual con usuario y contraseña por persona** (no por rol genérico): cada persona, sin importar su rol, tiene su propia cuenta con correo y contraseña. Incluye: - Registro por invitación (el Arquitecto/Administrador invita por correo; la persona define su propia contraseña al aceptar — ver 2.2). - **Recuperación de contraseña**: flujo de "olvidé mi contraseña" vía correo, con link de reseteo de un solo uso y expiración. Esto aplica a Propietarios, Constructores, ITO y Externo — todos pueden auto-recuperar su clave sin depender del Arquitecto, salvo que prefieran pedirle un reseteo manual desde el panel oculto (2.4). - Opción de cambiar contraseña desde el perfil una vez logueado. - (Opcional Fase 2) Autenticación de dos factores para roles con más responsabilidad (ITO, Arquitecto/Administrador). --- ## 4. Dashboards por rol Cada rol tiene su propio dashboard al entrar a una obra (mismo dato base, distinta vista según permisos): - **Arquitecto/Administrador**: KPIs generales de la obra + acceso a gestión de usuarios de esa obra + subida/versionado de planos + accesos rápidos a todos los módulos. - **Propietarios**: KPIs de avance (% avance, próximas reuniones, RFIs abiertos), galería de fotos, acceso de solo lectura a planos y actas, botón de aprobación de hitos. - **Constructores**: RFIs pendientes de responder, carta Gantt editable, subida de fotos de avance, subida de actas de reuniones propias. - **ITO**: RFIs generados por ellos y su estado, checklist de inspecciones, calendario de reuniones que han creado, entregables pendientes de aprobar/rechazar. - **Externo**: vista mínima, limitada a los módulos/carpetas que el Arquitecto haya habilitado para esa cuenta específica. --- ## 5. Módulos funcionales ### MVP (Fase 1) - Flujo de acceso Obra → Rol (sección 2) + panel oculto de administración (2.4) - Gestión de usuarios por obra (invitación por correo) desde el Arquitecto/Administrador - Repositorio de documentos: planos de arquitectura y especialidades (versionado), subidos por el Arquitecto - Módulo de **RFI / Solicitud de Información** (estado: pendiente, respondido, cerrado) - Galería de fotos de avance con fecha y etiqueta - Dashboard con KPIs por rol (documentos, RFIs abiertos, % avance, próximas reuniones) ### Fase 2 - **Módulo de Reuniones de obra** (detallado abajo) - Carta Gantt (Frappe Gantt o importación desde MS Project/Excel) - Inspecciones ITO con checklist y firma digital - Notificaciones (email / WhatsApp API) por RFI nuevo, vencido, o reunión agendada - Permisos granulares por módulo/carpeta para el rol Externo ### Fase 3 - Reportes exportables en PDF (estado de obra, historial de RFIs, actas) - App móvil o PWA para subir fotos/actas desde terreno - Bitácora de obra digital (libro de obra) --- ## 6. Módulo de Reuniones Registro de todas las reuniones que se realizan durante el desarrollo de la obra (de coordinación, de avance, con propietarios, etc.). ### Funcionalidad - **Crear reunión**: fecha, hora, lugar (o "remota"), tipo de reunión (coordinación / avance / propietarios / técnica), tabla de temas (agenda) - **Asistentes**: seleccionar de la lista de usuarios de la obra (con su rol), marcar asistencia real (asistió / no asistió / justificado), posibilidad de agregar invitados externos puntuales (nombre y cargo, sin cuenta en el sistema — distinto del rol "Externo" con cuenta propia, ver nota en sección 3) - **Subida de acta**: - Como **archivo Word (.docx)** — se guarda versionado, descargable - Como **fotografía(s)** del acta firmada en papel (una o varias imágenes, con opción de generar un PDF combinado automáticamente) - Campo de texto opcional para resumen rápido de acuerdos, visible sin tener que descargar el archivo - **Acuerdos y compromisos**: lista de pendientes que salen de la reunión, cada uno con responsable y fecha comprometida — estos pueden vincularse automáticamente a un RFI si corresponde - **Historial**: listado cronológico de todas las reuniones de la obra, filtrable por tipo y por asistente - **Notificación**: al crear una reunión, notificar a los asistentes seleccionados; al subir el acta, notificar a todos los que asistieron ### Modelo de datos del módulo ``` Reunion ├── id ├── obra_id ├── fecha, hora, lugar, tipo ├── agenda (texto) ├── asistentes [] (usuario_id, rol, asistio: bool) ├── invitados_externos [] (nombre, cargo) # sin cuenta, solo para asistencia ├── acta_archivo (docx o imagen[], url en storage) ├── resumen_texto (opcional) ├── acuerdos [] (descripcion, responsable_id, fecha_compromiso, rfi_vinculado_id?) └── creado_por, fecha_creacion ``` ### Consideraciones técnicas - Las fotos de actas deben pasar por compresión/optimización al subir (evitar archivos de 10+ MB desde celular) - Aceptar múltiples fotos por acta y combinarlas en un solo PDF (usar librería tipo `pdf-lib` o `sharp` + `pdfkit`) - Los `.docx` se almacenan tal cual (no requieren conversión), pero mostrar un preview o al menos ícono + nombre + botón de descarga - Buscar dentro del texto de resumen de acuerdos (full-text search) para que los Propietarios puedan encontrar rápido en qué reunión se decidió algo --- ## 7. Modelo de datos general (resumen) ``` Obra ├── id, nombre, direccion, fecha_inicio, estado ├── creado_por (arquitecto_id) ├── Usuarios (ver detalle abajo) ├── Documentos (tipo: plano_arq/plano_esp, version, autor, fecha) ├── RFIs (de, para, asunto, estado, fecha_limite, adjuntos) ├── Fotos_avance (fecha, etiqueta, autor) ├── Inspecciones (checklist_items, resultado, ITO_id, fecha) ├── Gantt_items (tarea, inicio, fin, %avance, dependencias) ├── Reuniones (ver detalle sección 6) └── Comentarios (referencia a documento/foto/RFI/reunion, autor, texto) Usuario ├── id, nombre, correo, password_hash ├── obra_id ├── rol (arquitecto_admin / propietario / constructor / ito / externo) ├── sub_tipo (ej. "Propietario 1", "Constructor - Jefe de obra"; opcional) ├── permisos_granulares [] (solo aplica a rol externo: módulo/carpeta habilitada) ├── estado (invitado / activo / desactivado) ├── fecha_creacion, ultimo_acceso └── reset_password_token, reset_password_expira (para flujo de recuperación) ``` > El Arquitecto/Administrador es la única entidad que puede existir sin `obra_id` fijo — su cuenta está asociada a **N obras** (tabla intermedia `arquitecto_obras` si maneja más de una). --- ## 8. Stack técnico recomendado - **Frontend:** Next.js (React) + Tailwind - **Backend:** Next.js API routes (o NestJS si se espera escalar mucho) - **Base de datos:** PostgreSQL - **Storage de archivos:** S3 o Cloudflare R2 (planos, fotos, actas, docx) - **Auth:** Auth.js (NextAuth) o Clerk, con: - Selector de obra como primer paso de la sesión (contexto `obra_id` antes de resolver el rol) - Roles por obra + rol especial "arquitecto_admin" transversal a varias obras - Flujo de recuperación de contraseña vía correo (token de reseteo de un solo uso) y cambio de contraseña desde el perfil - Contraseñas siempre con hash (ej. bcrypt/argon2) — nunca en texto plano, ni siquiera para el panel oculto del Arquitecto (ver sección 2.4) - **Procesamiento de imágenes/PDF:** `sharp` (compresión) + `pdf-lib` o `pdfkit` (combinar fotos de actas en PDF) - **Hosting:** Vercel (frontend) + Supabase o Railway (Postgres + storage) - **Dominio:** sigueobras.cl apuntado vía DNS a Vercel --- ## 9. Cómo trabajar este plan con Antigravity - Antigravity ofrece una Vista de Editor para tareas puntuales y una Superficie de Manager para lanzar varios agentes en paralelo sobre distintos módulos, cada uno generando "Artifacts" (plan de tareas, capturas, grabaciones) que permiten verificar el trabajo sin revisar línea por línea. - **No pegar todo este documento como un solo prompt.** Usar cada sección de módulo (flujo de acceso, documentos, RFIs, reuniones, gantt) como una tarea separada. - **Dar siempre como contexto fijo**: la tabla de roles (sección 3), el flujo Obra → Rol (sección 2) y el modelo de datos general (sección 7), para que el agente no reinvente el esquema en cada módulo nuevo. - Pedir explícitamente **migraciones versionadas** (Prisma o Drizzle), no cambios directos al schema. - Pedir **tests de permisos por endpoint** además de tests funcionales — es donde más fallan este tipo de apps multi-rol, especialmente con el rol Externo y sus permisos granulares. - Para el flujo de acceso, pedir pruebas específicas de: (a) que un rol sin usuarios creados no aparezca en el listado público de la obra, (b) que un usuario no pueda "adivinar" su entrada a una obra en la que no fue invitado, (c) que el panel oculto del Arquitecto solo sea accesible por su cuenta. - Para el módulo de reuniones, pedir específicamente pruebas del flujo de subida de foto → conversión a PDF, y docx → almacenamiento, ya que son los dos casos con más probabilidad de bugs. --- ## 10. Roadmap de fases (sugerido) | Semanas | Entregable | |---|---| | 1-2 | Flujo de acceso Obra → Rol, panel oculto de admin, auth + roles + estructura de proyecto/obra + layout de dashboards por rol | | 3-4 | Módulo de documentos (planos, versionado, subida por Arquitecto) | | 5-6 | Módulo de RFIs con notificaciones | | 7-8 | Módulo de Reuniones (agenda, asistentes, actas foto/docx, acuerdos) | | 9-10 | Galería de fotos de avance + inspecciones ITO | | 11-12 | Carta Gantt + reportes exportables + permisos granulares para rol Externo | | 13+ | Pulido, PWA/móvil, bitácora digital | --- ## 11. Próximos pasos sugeridos 1. Validar este documento con los roles reales (Propietarios/Constructores/ITO) antes de programar. 2. Decidir el criterio final para el panel oculto del Arquitecto: ¿reseteo/clave temporal (recomendado) o alguna otra forma de control que necesites revisar antes de construirlo? 3. Usar la sección 9 como instrucción inicial para Antigravity, empezando por Fase 1 (flujo Obra → Rol + auth + roles + layout). 4. Definir plantilla de acta estándar (para el caso de subida en Word) para facilitar el parseo o al menos un formato consistente. 5. Definir, obra por obra, qué permisos granulares tendrá cada cuenta "Externo" (no es un rol fijo de "todo o nada").