# 📖 Documentación del Proyecto - GKACHELE™

**© 2025 GKACHELE™. Todos los derechos reservados.**

## 🎯 ¿Qué Estamos Construyendo?

Un **SaaS (Software as a Servicio)** para que clientes creen y gestionen sus propios sitios web, similar a sistemas populares pero mejorado y personalizado.

### Funcionalidad Principal:
- Clientes se registran → Crean su sitio → Lo personalizan → Lo publican
- Todo desde una interfaz web simple
- Sistema multi-tenant (todos los clientes en una sola base de datos)

---

## 🏗️ Arquitectura Técnica

### ¿Por qué Python/Flask y NO Docker?

**Sí, es por la Raspberry Pi:**
- Raspberry Pi tiene recursos limitados
- Docker consume más memoria y CPU
- Python directo es más ligero y eficiente
- Más fácil de depurar y mantener
- **En VPS podrías usar Docker si quieres**, pero Python directo también funciona perfecto

### Stack Tecnológico:
- **Backend:** Flask (Python 3)
- **Base de Datos:** SQLite (`main.db` - multi-tenant)
- **Frontend:** HTML, CSS, JavaScript
- **Servidor Web:** Nginx (reverse proxy)
- **Hosting:** Raspberry Pi 3 (actual) / VPS (recomendado para producción)

---

## 🗄️ Base de Datos

### Estructura Multi-tenant:
**TODO en una sola base de datos (`main.db`):**
- `users` - Todos los usuarios/clientes
- `sites` - Todos los sitios (filtrados por `user_id`)
- `menus` - Menús dinámicos
- `widgets` - Widgets dinámicos
- `content` - Contenido
- `settings` - Configuraciones
- `requests` - Solicitudes de publicación
- `media` - Archivos subidos

### Acceso a Base de Datos:
- **Tu acceso:** Panel `/admin` (solo rol `administrator`)
- **Acceso clientes:** Solo ven SUS datos (filtrado por `user_id`)
- **Herramientas:** DB Browser for SQLite, scripts Python (`ver_usuarios.py`, `limpiar_db.py`)

---

## 👥 Sistema de Usuarios y Roles

### Roles (desde Base de Datos):
- `administrator` - Acceso total (tú)
- `editor` - Puede editar contenido
- `author` - Puede crear contenido
- `subscriber` - Solo lectura

### Admin para Clientes:
- **Panel `/dashboard`** - Cliente ve SUS sitios
- **Panel `/customizer/{site_id}`** - Personalizar sitio
- **Panel `/dashboard/admin`** - Admin del cliente (media, config)

---

## 🔒 Limitaciones por Plan

### Sistema Actual:
- **Planes:** `base`, `premium`, etc. (campo en tabla `users`)
- **Limitaciones posibles:**
  - Número de sitios
  - Subida de fotos (tamaño, cantidad)
  - Modificaciones (frecuencia, tipo)
  - Funcionalidades avanzadas

### Implementación:
- Verificar plan antes de acciones
- Contar recursos usados vs. límites del plan
- Bloquear acciones si excede límite

---

## 📊 Detección de Movimientos

### Sistema Actual:
- **No hay detección automática** de movimientos aún
- **Registros disponibles:**
  - `created_at` - Fecha de creación
  - `updated_at` - Fecha de actualización
  - Logs del servidor (journalctl)

### Posibles Mejoras:
- Tabla `activity_log` para registrar acciones
- Notificaciones de cambios
- Historial de modificaciones
- Auditoría de cambios

---

## 🚀 VPS vs Raspberry Pi

### Raspberry Pi (Actual):
- ✅ Bajo costo
- ✅ Suficiente para desarrollo/pruebas
- ❌ Recursos limitados
- ❌ Puede ser lento con muchos clientes

### VPS (Recomendado para Producción):
- ✅ Más recursos (CPU, RAM, disco)
- ✅ Mejor rendimiento
- ✅ Más confiable
- ✅ Mejor para escalar
- ✅ Puedes usar Docker si quieres
- ✅ Mismo código funciona (solo cambiar configuración)

### Migración a VPS:
1. Copiar código completo
2. Instalar Python3, Nginx
3. Copiar configuración
4. Cambiar dominio
5. Configurar SSL (Let's Encrypt)
6. **Mismo código, más potencia**

---

## 🔄 Flujo Completo del Sistema

```
1. Cliente → Landing Page
2. Cliente → Registro (/register)
   ├── Crea usuario en `users`
   ├── Crea sitio automático en `sites`
   └── Crea menús por defecto en `menus`
3. Cliente → Login (/login)
   └── Redirige a `/customizer/{site_id}` (directo)
4. Cliente → Customizer
   ├── Personaliza contenido
   ├── Cambia colores, tipografía
   └── Gestiona menús y widgets
5. Cliente → Envía para aprobación
   └── Crea solicitud en `requests`
6. Admin → Aprueba desde `/admin`
   └── Cambia status a `published`
7. Sitio → Público en `/site/{slug}`
```

---

## 📁 Estructura del Proyecto

```
c:\word\
├── demo/                    # Código principal
│   ├── app.py              # Flask backend (TODO aquí)
│   ├── database/
│   │   └── main.db         # Base de datos multi-tenant
│   ├── themes/             # Templates
│   │   ├── _gkachele/      # Sistema modular (header.php, footer.php, sidebar.php)
│   │   └── {tema}/         # Temas específicos
│   ├── templates/          # HTML templates
│   └── static/             # CSS, JS
├── memoria/                 # 📚 TODA LA DOCUMENTACIÓN
└── backups/                 # Backups automáticos
```

---

## 🎯 Estado Actual

### ✅ Funcionando:
- Registro de clientes
- Login (redirige a customizer)
- Dashboard del cliente
- Customizer (personalización)
- Sistema de menús y widgets
- Panel admin (ver/eliminar usuarios)
- Sistema de roles basado en DB

### ⚠️ Pendiente:
- Limitaciones por plan
- Detección de movimientos/actividad
- Mejorar landing page
- Integración Gitea
- UI completa para gestionar menús

---

## 🔐 Seguridad

- Passwords hasheados (Werkzeug)
- Sesiones Flask
- Filtrado por `user_id` (cada cliente solo ve sus datos)
- Roles desde base de datos (no hardcodeados)
- Verificación de permisos en cada ruta

---

## 📝 Próximos Pasos

1. **Implementar limitaciones por plan**
2. **Sistema de actividad/logs**
3. **Mejorar UI del customizer**
4. **Optimizar para VPS**
5. **Añadir más funcionalidades**

---

**Última actualización:** 14 Enero 2025  
**Hash:** `gkachele-documentacion-completa-20250114`

---

**© 2025 GKACHELE™. Todos los derechos reservados.**