# MI PANEL — Documento maestro de arquitectura (V1)

**Estado:** diseño funcional y arquitectura aprobados; implementación pendiente.  
**Plataforma inicial:** Windows local; publicación posterior por HTTPS.  
**Tecnologías:** PHP 7.4+, MySQL 8.0+, HTML5, CSS3 y JavaScript sin framework obligatorio.  
**Zona horaria de interfaz:** configurable; por defecto `America/Mexico_City`. Guardar instantes técnicos en UTC cuando corresponda.

## 1. Objetivo
Aplicación web responsive para gestionar tareas, notas y proyectos personales o compartidos, desde distintos dispositivos. El prototipo visual aprobado es referencia de diseño, no código productivo ni persistencia real.

## 2. Funcionalidad V1
- Inicio/cierre de sesión; cuenta de usuario (nombre, correo, contraseña con hash, tema system/light/dark).
- Dashboard: tareas vencidas, de hoy, importantes sin fecha, estadísticas de pendientes, proyectos y notas; nombre del usuario y tema claro/oscuro.
- Proyectos privados por defecto; propietario y colaboradores con permisos; compartir el **proyecto completo**, no subcarpetas.
- Tareas: título, descripción, prioridad low/medium/high, estado pending/completed, fecha/hora opcionales, proyecto opcional; edición, eliminación lógica y control de versiones.
- Notas: título, contenido de texto seguro, fijar, proyecto opcional, edición, eliminación lógica y control de versiones.
- Búsqueda global por acción explícita (Enter o botón), filtrada por permisos, con paginación/límites.
- Invitaciones por correo a cuentas existentes o registro posterior; token seguro de un solo uso con caducidad. Si no se configura correo SMTP, ofrecer enlace de invitación copiable **solo al invitador autorizado** y no fingir envío de correo.
- Interfaz adaptable a PC, móvil y tablet.

## 3. Exclusiones V1
Sin subcarpetas, adjuntos, notificaciones push, sincronización en tiempo real, polling, calendario externo, IA, subtareas, ni modo sin conexión con escritura. PWA posterior.

## 4. Arquitectura
- Front controller `public/index.php`, rutas explícitas y controladores delgados.
- `app/Core`: router, sesión/autenticación, autorización, CSRF, validación, PDO y respuesta JSON.
- `app/Models`: acceso a datos con consultas parametrizadas; `app/Views`: plantillas escapadas.
- `public/assets`: CSS y JS locales con caché/versionado; no depender de CDN para funcionamiento básico.
- `config`: configuración no pública desde variables de entorno. `storage`: logs y archivos no públicos.
- DocumentRoot de Apache apuntando **solo a `public/`**; no exponer `app`, `config`, `database`, `.env`, ni `storage`.
- Evitar framework pesado, pero usar separación de responsabilidades, validación y pruebas.

## 5. Modelo de datos
Archivo fuente: `database/schema.sql`. Seis tablas: `users`, `projects`, `project_members`, `project_invitations`, `tasks`, `notes`.
- `projects.owner_id` es el propietario; no duplicarlo como miembro.
- `project_members` contiene solo administradores, editores y lectores.
- `tasks.user_id` y `notes.user_id` son autores; si `project_id IS NULL`, solo el autor accede; si hay proyecto, manda la membresía/propiedad vigente del proyecto.
- `version` en tareas/notas permite actualización optimista: actualizar con `WHERE id = ? AND version = ?`, incrementar versión y devolver HTTP 409 si hay conflicto.
- Borrado lógico mediante `deleted_at` y filtros consistentes; proyectos eliminados no deben mostrar contenido a miembros.
- Nunca aceptar `user_id`/`owner_id` arbitrarios desde cliente como identidad autenticada.

## 6. Matriz de permisos
| Acción | Propietario | Admin | Editor | Lector |
|---|---|---|---|---|
| Ver proyecto y contenido | Sí | Sí | Sí | Sí |
| Crear/editar/completar/eliminar lógicamente tareas y notas | Sí | Sí | Sí | No |
| Invitar/retirar lectores y editores | Sí | Sí | No | No |
| Nombrar/retirar administradores | Sí | No | No | No |
| Modificar proyecto (nombre, descripción) | Sí | Sí | No | No |
| Archivar/eliminar proyecto | Sí | No | No | No |
| Cambiar propietario | No en V1 | No | No | No |

- Admin no puede cambiar permisos de otros administradores ni del propietario.
- Invitaciones verificadas contra usuario/correo autenticado, token hash y fecha de expiración, con aceptación transaccional y sin reutilización.
- Revocación de acceso efectiva en la siguiente petición, incluso si la interfaz conserva datos en memoria.
- **No es colaboración en tiempo real:** cambios de otros usuarios se ven al pulsar Actualizar o volver a consultar una vista.

## 7. Política de red (obligatoria)
- **Cero polling**: no `setInterval` para refrescar datos, no consultas en segundo plano recurrentes, no WebSocket permanente en V1.
- Solicitudes únicamente por apertura/navegación necesaria, búsqueda explícita, acciones CRUD y botón Actualizar.
- Guardar datos consultados en memoria durante la sesión, invalidar caché tras mutaciones pertinentes; no almacenar contenido sensible en cachés compartidas.
- Tras CRUD actualizar UI localmente usando respuesta mínima; evitar recarga completa de página o de todas las tablas.
- Búsquedas paginadas y limitadas; no buscar en cada tecla.
- Archivos estáticos comprimidos y cacheables con versión; JSON privado `Cache-Control: no-store` cuando proceda.
- Prueba de aceptación: 2 horas con dashboard inactivo = 0 peticiones de datos adicionales.

## 8. Seguridad mínima
- PDO y prepared statements; privilegios SQL mínimos; nunca concatenar parámetros SQL sin validación.
- `password_hash()` y `password_verify()`, regenerar ID de sesión tras login; cookie HttpOnly, SameSite=Lax/Strict y Secure al usar HTTPS; expiración de sesión.
- CSRF en operaciones que modifican datos; control de autorización por registro en servidor en **todas** las rutas.
- Escapar salida HTML; renderizar notas como texto seguro en V1; prohibir HTML arbitrario y SQL inyectado.
- Limitar intentos de login, validar inputs, evitar exposición de errores/credenciales y registrar eventos de seguridad sin datos secretos.
- Token de invitación generado con `random_bytes`, guardar solo hash, comparar de forma segura, expirar y consumir atómicamente.
- Respaldos y restauración probados; no guardar contraseñas en notas de ejemplo.

## 9. Contrato de interfaz
- Diseño aprobado: menú lateral en escritorio, navegación compacta móvil, resumen de pendientes/importantes/proyectos/notas, listas Hoy/Próximamente/Proyectos/Notas recientes.
- Selector claro/oscuro en barra superior; nombre e iniciales del usuario autenticado (no hardcodear nombres).
- Tareas vencidas siempre visibles; fechas calculadas según zona horaria configurada.
- Indicadores de error/guardado y confirmación antes de eliminar; accesibilidad básica con teclado y etiquetas.

## 10. Criterios de aceptación V1
1. Usuario A no puede consultar ni editar datos privados de B modificando IDs en URL o JSON.
2. Proyecto privado solo visible al dueño hasta invitación aceptada.
3. Editor modifica tareas/notas del proyecto; lector recibe HTTP 403 al intentarlo.
4. Admin gestiona lectores/editores pero no administradores ni propietario.
5. Edición simultánea devuelve conflicto 409 y no sobrescribe silenciosamente.
6. Datos persisten tras cerrar y abrir navegador; tema persiste por usuario.
7. Dashboard inactivo no genera tráfico periódico.
8. Todas las pantallas esenciales son utilizables desde 320px hasta escritorio.
9. `schema.sql` importa en MySQL 8 limpio; la aplicación usa conexión por variables de entorno.
10. DocumentRoot apunta a `public` y rutas privadas no son accesibles por HTTP.

## 11. Orden de implementación
Fase 0: entorno Windows y verificación SQL. Fase 1: bootstrap, autenticación, seguridad. Fase 2: Dashboard/tema. Fase 3: proyectos y permisos/invitaciones. Fase 4: tareas y notas. Fase 5: búsqueda, rendimiento, pruebas y documentación.

## 12. Convenciones
- Código y nombres de tablas en inglés; interfaz y documentación para usuario en español.
- Migraciones futuras incrementales; nunca borrar datos reales al actualizar el esquema.
- Registrar avances, pruebas, decisiones y bloqueos en `PROGRESS.md` al final de cada fase.
- No crear repositorio Git ni ejecutar operaciones Git sin autorización explícita.