Initial commit

backend/DATABASE_README.md

@@ -0,0 +1,155 @@
+# 📦 Restaurar la base de datos en otra computadora
+
+Este directorio contiene un **dump completo de la BD** para que cualquier persona pueda replicar el estado actual de la base de datos en su propia máquina.
+
+---
+
+## 📁 Archivos clave
+
+| Archivo | Tamaño | Descripción |
+|---------|--------|-------------|
+| `database_dump.sql` | ~209 KB | Dump SQL completo (schema + 1,216 INSERTs) |
+| `restore_db.py` | — | Script Python que aplica el dump |
+| `mi_ruta_limpia.db` | ~266 KB | (Opcional) Base de datos SQLite ya hidratada |
+
+---
+
+## 🚀 Restaurar en otra máquina (paso a paso)
+
+### Opción 1 (Recomendada): con Python
+
+```bash
+# 1. Clona o copia el proyecto en la otra máquina
+cd backend
+
+# 2. Activa el venv si no lo has hecho
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# 3. Restaura la BD desde el dump
+python restore_db.py
+```
+
+Verás:
+```
+✅ BASE DE DATOS RESTAURADA EXITOSAMENTE
+  ✓ users                      202/202
+  ✓ addresses                  302/302
+  ✓ reports                    280/280
+  ✓ operational_reports        150/150
+  ✓ service_ratings            220/220
+  ✓ trucks                      62/62
+```
+
+### Opción 2: con `sqlite3` (sin Python)
+
+Si solo tienes `sqlite3` instalado (sin Python):
+
+```bash
+cd backend
+rm -f mi_ruta_limpia.db
+sqlite3 mi_ruta_limpia.db < database_dump.sql
+```
+
+### Opción 3 (más rápida): copiar el `.db` directamente
+
+Si simplemente quieres llevarte la BD ya hecha:
+
+```bash
+# Solo asegúrate de incluir mi_ruta_limpia.db al copiar/clonar
+# SQLite es un solo archivo, portable a cualquier OS
+```
+
+---
+
+## ✅ Verificar después de restaurar
+
+Una vez restaurado, arranca el backend:
+
+```bash
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Y prueba el login con cualquiera de los 3 usuarios demo:
+
+| Rol | Email | Contraseña |
+|-----|-------|-----------|
+| 🧑 Ciudadano | `demo@celaya.gob.mx` | `Celaya2026` |
+| 👮 Empleado | `empleado@celaya.gob.mx` | `Empleado2026` |
+| 🛡️ Admin | `admin@celaya.gob.mx` | `Admin2026` |
+
+Test rápido con curl:
+```bash
+curl -X POST http://localhost:8000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@celaya.gob.mx","password":"Admin2026"}'
+```
+Debe responder con un token JWT y `"role":"ADMIN"`.
+
+---
+
+## 📊 Contenido de la BD restaurada
+
+| Tabla | Registros |
+|-------|----------:|
+| `users` | **202** (185 ciudadanos · 14 empleados · 3 admins) |
+| `addresses` | **302** (con `route_id` ya asignado por geo-routing) |
+| `reports` | **280** reportes ciudadanos con folios reales |
+| `operational_reports` | **150** reportes operativos de empleados |
+| `service_ratings` | **220** calificaciones 1-5 estrellas |
+| `trucks` | **62** camiones (CEL-001 a CEL-062) |
+| **TOTAL** | **1,216 registros** |
+
+Los datos cubren ~60 días hacia atrás con timestamps realistas.
+
+---
+
+## 🔄 Regenerar el dump (solo si modificaste la BD original)
+
+Si haces cambios en tu BD local y quieres actualizar el dump:
+
+```bash
+cd backend
+sqlite3 mi_ruta_limpia.db .dump > database_dump.sql
+```
+
+Eso reemplaza el archivo. Después haz commit del nuevo `database_dump.sql`.
+
+---
+
+## 🆘 Troubleshooting
+
+### "no such table" al restaurar
+Borra la BD existente y reintenta:
+```bash
+rm mi_ruta_limpia.db
+python restore_db.py
+```
+
+### Las contraseñas no funcionan después de restaurar
+Las contraseñas están hasheadas con bcrypt. Verifica que tienes la versión correcta:
+```bash
+pip install 'bcrypt==4.0.1'
+```
+
+### El archivo `database_dump.sql` está vacío o corrupto
+Pide a tu equipo el original o, si tienes acceso a la BD original:
+```bash
+sqlite3 mi_ruta_limpia.db .dump > database_dump.sql
+wc -l database_dump.sql   # Debe ser >1000 líneas
+```
+
+---
+
+## 💡 Alternativa: generar datos nuevos (no restaurar)
+
+Si prefieres datos generados aleatoriamente en vez de los exactos del original:
+
+```bash
+python seed_massive.py
+```
+
+Esto crea cantidades similares pero con seed determinístico (mismo resultado siempre, pero diferente al dump).
+
+> Las credenciales demo son las mismas en ambos métodos.