Initial commit

2026-01-12 08:17:17 -07:00
commit de5b6feef4
104 changed files with 12925 additions and 0 deletions
--- a/backend/README.md
+++ b/backend/README.md
@@ -0,0 +1,171 @@
+# ServiceManagerWeb Backend
+
+FastAPI backend para el sistema de Mesa de Ayuda B2B multi-tenant.
+
+## Estructura
+
+```
+backend/
+├── app/
+│   ├── main.py              # FastAPI app principal
+│   ├── core/                # Configuración y utilidades core
+│   │   ├── config.py        # Configuración con Pydantic Settings
+│   │   ├── database.py      # SQLAlchemy async setup
+│   │   ├── security.py      # JWT, hashing, 2FA
+│   │   └── logging.py       # Structured logging
+│   ├── models/              # Modelos SQLAlchemy
+│   │   ├── tenant.py        # Modelo de tenant (multi-tenancy)
+│   │   ├── user.py          # Modelo de usuario
+│   │   └── ...              # Otros modelos
+│   ├── api/                 # API routes
+│   │   └── v1/              # API version 1
+│   │       ├── router.py    # Router principal
+│   │       └── endpoints/   # Endpoints por dominio
+│   ├── middleware/          # Custom middleware
+│   ├── services/            # Business logic
+│   ├── repositories/        # Data access layer
+│   ├── schemas/             # Pydantic schemas
+│   └── utils/               # Utilidades compartidas
+├── tests/                   # Tests unitarios e integración
+├── migrations/              # Migraciones Alembic
+├── requirements.txt         # Dependencias Python
+└── pyproject.toml          # Configuración del proyecto
+```
+
+## Características Implementadas
+
+### Core
+- [x] FastAPI app con configuración async
+- [x] Pydantic Settings para configuración
+- [x] SQLAlchemy 2.0 async
+- [x] Structured logging con structlog
+- [x] JWT authentication con refresh tokens
+- [x] 2FA con TOTP
+- [x] Multi-tenancy middleware
+
+### API
+- [x] Health checks (/health, /health/detailed)
+- [x] Authentication endpoints básicos
+- [x] Middleware de correlation ID y tenant
+- [x] Error handling centralizado
+- [x] CORS configurado
+
+### Seguridad
+- [x] Argon2 password hashing
+- [x] JWT con algoritmos seguros
+- [x] TOTP 2FA implementation
+- [x] Validation con Pydantic v2
+
+## Quick Start
+
+```bash
+# Instalar dependencias
+pip install -r requirements.txt
+
+# Variables de entorno (copiar desde raíz del proyecto)
+cp ../.env.example .env
+
+# Ejecutar en desarrollo
+uvicorn app.main:app --reload --port 8000
+
+# O usar Docker
+docker-compose up backend
+```
+
+## Testing
+
+```bash
+# Ejecutar tests
+pytest
+
+# Con coverage
+pytest --cov=app tests/
+
+# Solo tests unitarios
+pytest -m "unit"
+
+# Solo tests de integración
+pytest -m "integration"
+```
+
+## Code Quality
+
+```bash
+# Linting
+ruff check .
+
+# Formateo
+black .
+
+# Type checking
+mypy .
+
+# Fix automático
+ruff check . --fix
+black .
+```
+
+## Desarrollo
+
+### Agregar nuevos endpoints
+
+1. Crear schema en `app/schemas/`
+2. Crear endpoint en `app/api/v1/endpoints/`
+3. Registrar router en `app/api/v1/router.py`
+4. Agregar tests en `tests/`
+
+### Modelos de base de datos
+
+1. Crear modelo en `app/models/`
+2. Importar en `app/models/__init__.py`
+3. Crear migración: `alembic revision --autogenerate -m "descripción"`
+4. Aplicar migración: `alembic upgrade head`
+
+### Variables de entorno
+
+Todas las configuraciones están en `app/core/config.py` usando Pydantic Settings.
+
+Ver `.env.example` para todas las variables disponibles.
+
+## Arquitectura
+
+### Clean Architecture
+
+- **Presentation**: FastAPI endpoints y schemas
+- **Application**: Services y casos de uso
+- **Domain**: Entidades y reglas de negocio
+- **Infrastructure**: Repositorios, DB, external APIs
+
+### Patrones implementados
+
+- Repository pattern para acceso a datos
+- Dependency injection con FastAPI Depends
+- Unit of Work para transacciones
+- Command/Query separation
+
+## Monitoring
+
+- Structured logging con correlation IDs
+- Health checks para load balancer
+- Métricas con Prometheus (TODO)
+- Error tracking (TODO)
+
+## Security Checklist
+
+- [x] Password hashing con Argon2
+- [x] JWT con secret keys seguras
+- [x] CORS restrictivo
+- [x] Input validation con Pydantic
+- [x] SQL injection protection (SQLAlchemy)
+- [x] Rate limiting (TODO: implementar)
+- [x] File upload validation (TODO: implementar)
+- [x] XSS protection (headers en nginx)
+
+## Próximos pasos
+
+1. Implementar repositorios y services
+2. Completar autenticación con base de datos
+3. Agregar endpoints de users y tickets
+4. Implementar rate limiting
+5. Agregar métricas y monitoring
+6. Tests de integración completos