Content
# SQLite Spreadsheet Sync
Una aplicación web interactiva que centraliza datos relacionales en una base de datos **SQLite**, ofreciendo una interfaz de usuario similar a **Excel** / **Google Sheets** para reducir la fricción en equipos de trabajo no técnicos.
Esto previene la desincronización y pérdida de información provocada por el uso de múltiples archivos de Excel locales dispersos.
## 🚀 Características
* **Pestañas por Tabla**: Navegación inmediata entre las tablas de la base de datos central.
* **Edición tipo Excel**: Edición directa de celdas con doble clic, navegación con teclado (Tab, Enter, Flechas) y autoguardado en base de datos.
* **Importación y Consolidación**: Sube archivos Excel `.xlsx` o `.csv` sueltos para crear tablas automáticamente o añadir registros en lote.
* **Exportación Directa**: Descarga cualquier tabla activa de la base de datos de vuelta a formato Excel en un clic.
* **Validación en Tiempo Real**: Evita la corrupción de datos alertando al usuario si ingresa tipos incompatibles (ej. texto en campos numéricos).
* **Gestión de Estructura**: Crea tablas nuevas y añade columnas directamente desde la interfaz gráfica.
---
## 📚 Documentación
* [Especificación de la API REST](docs/API.md) — endpoints, autenticación, validación y errores.
* [Servidor MCP](docs/MCP.md) — integración con asistentes (Claude, etc.) vía Model Context Protocol.
* [Modelo de Seguridad](docs/SECURITY.md) — defensas implementadas y hardening de despliegue.
* [Guía de Contribución](CONTRIBUTING.md) — puesta en marcha, smoke test y convenciones.
* [`.env.example`](.env.example) — variables de entorno de configuración.
---
## 🛠️ Requisitos
* [Node.js](https://nodejs.org/) (Versión 18 o superior recomendada).
---
## 💻 Instalación y Configuración
Sigue estos pasos sencillos para poner en marcha el proyecto localmente o en un servidor de red:
1. **Instalar todas las dependencias** (servidor y cliente en un solo comando):
```bash
npm run install-all
```
2. **Iniciar en modo desarrollo** (corre tanto la API Express como el cliente Vite en paralelo):
```bash
npm run dev
```
3. **Acceder a la aplicación**:
* Abre tu navegador en [http://localhost:3000](http://localhost:3000)
*Nota: La API del backend se ejecuta en el puerto `3001` y el frontend se comunica de manera transparente mediante un Proxy.*
---
## 🔒 Despliegue en Producción
Recomendamos usar **Docker Compose** para despliegues de producción, ya que incluye persistencia automática de volumen y una imagen *multi-stage* optimizada.
1. **Levantar el servicio**:
```bash
docker compose up -d --build
```
2. **Variables de entorno (`.env`)**:
Si vas a exponer el sistema en una red local o en internet, **debes activar la seguridad** usando el archivo `.env`:
```env
API_KEY=tu_contraseña_secreta_super_segura
ALLOWED_ORIGIN=https://tu-dominio-frontend.com
DB_PATH=/data/data.db
UPLOADS_DIR=/data/uploads/
```
- `API_KEY`: Activa la autenticación en todos los endpoints de la API.
- `ALLOWED_ORIGIN`: Restringe el acceso CORS. Por defecto es `http://localhost:3000`.
- `DB_PATH` y `UPLOADS_DIR`: Configuradas por defecto en el Dockerfile para apuntar al volumen montado `/data`, asegurando que la base de datos y archivos temporales sobrevivan a reinicios del contenedor.
---
## 📁 Estructura del Proyecto
```
sqlite-spreadsheet-sync/
├── package.json # Dependencias y scripts globales de ejecución
├── server.js # API REST en Express para operaciones SQLite e Import/Export
├── database.js # Módulo de base de datos SQLite y helpers relacionales
├── data.db # Archivo físico de la base de datos SQLite (se genera auto)
└── frontend/ # Código fuente de la interfaz React + Vite
├── package.json # Dependencias del cliente
├── vite.config.js # Proxy de comunicación configurado
├── index.html # Plantilla principal HTML
└── src/
├── main.jsx # Entrada de ejecución React
├── App.jsx # Componentes de UI, modales y lógica de comunicación
└── App.css # Estilos premium, animaciones y temas oscuros
```
---
## 📝 Comandos Útiles
* **Instalar backend**: `npm install`
* **Instalar frontend**: `npm run install-frontend`
* **Iniciar backend solo**: `npm run server` (http://localhost:3001)
* **Iniciar frontend solo**: `npm run client` (http://localhost:3000)
* **Ejecutar todo junto (Recomendado)**: `npm run dev`
* **Servidor MCP (stdio)**: `npm run mcp` (ver [docs/MCP.md](docs/MCP.md))
