service_manager/backend

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

• FastAPI app con configuración async
• Pydantic Settings para configuración
• SQLAlchemy 2.0 async
• Structured logging con structlog
• JWT authentication con refresh tokens
• 2FA con TOTP
• Multi-tenancy middleware

API

• Health checks (/health, /health/detailed)
• Authentication endpoints básicos
• Middleware de correlation ID y tenant
• Error handling centralizado
• CORS configurado

Seguridad

• Argon2 password hashing
• JWT con algoritmos seguros
• TOTP 2FA implementation
• Validation con Pydantic v2

Quick Start

# 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

# 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

# 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

• Password hashing con Argon2
• JWT con secret keys seguras
• CORS restrictivo
• Input validation con Pydantic
• SQL injection protection (SQLAlchemy)
• Rate limiting (TODO: implementar)
• File upload validation (TODO: implementar)
• 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