171 lines
4.4 KiB
Markdown
171 lines
4.4 KiB
Markdown
# 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 |