Modularización de GKACHELE SaaS

memoria/SISTEMA_ROLES.md

@@ -0,0 +1,77 @@
+# 🔐 Sistema de Roles y Permisos - GKACHELE™
+
+**© 2025 GKACHELE™. Todos los derechos reservados.**
+
+## 📋 Arquitectura Basada en Base de Datos
+
+Todo el sistema de roles y permisos está **100% en la base de datos**, sin lógica hardcodeada.
+
+### Tabla: `users`
+
+**Campos relacionados con roles:**
+- `role` (TEXT): Rol del usuario
+  - Valores posibles: `administrator`, `editor`, `author`, `subscriber`
+  - Default: `subscriber`
+- `status` (TEXT): Estado del usuario
+  - Valores: `active`, `inactive`, `suspended`
+  - Default: `active`
+
+### Jerarquía de Roles
+
+```
+administrator (nivel 4) - Acceso total
+    ↓
+editor (nivel 3) - Puede editar contenido
+    ↓
+author (nivel 2) - Puede crear contenido
+    ↓
+subscriber (nivel 1) - Solo lectura
+```
+
+### Funciones Helper
+
+#### `user_has_role(user_id, required_role)`
+Verifica si un usuario tiene un rol específico o superior.
+
+**Uso:**
+```python
+if user_has_role(session['user_id'], 'administrator'):
+    # Usuario es admin o superior
+```
+
+#### `user_can(user_id, capability)`
+Verifica si un usuario tiene una capacidad específica.
+
+**Uso:**
+```python
+if user_can(session['user_id'], 'manage_users'):
+    # Usuario puede gestionar usuarios
+```
+
+### Rutas Protegidas
+
+Todas las rutas administrativas verifican el rol desde la base de datos:
+
+```python
+@app.route('/admin')
+def admin():
+    if not user_has_role(session['user_id'], 'administrator'):
+        return "Solo administradores", 403
+    # ...
+```
+
+### Creación de Usuario Administrador
+
+El primer usuario (ID=1) se crea automáticamente como `administrator`:
+- Email: `admin@gkachele.com`
+- Password: `admin123` (cambiar después)
+- Role: `administrator`
+
+### Migración Automática
+
+Si la tabla `users` no tiene las columnas `role` y `status`, se añaden automáticamente al iniciar la aplicación.
+
+---
+
+**Última actualización:** 14 Enero 2025  
+**Hash:** `gkachele-roles-db-20250114`