# ServiceManagerWeb - Mesa de Ayuda B2B Copilot Instructions

Este proyecto es un sistema multi-tenant de Mesa de Ayuda/Soporte Técnico empresarial.

## Contexto del Proyecto

- **Empresa**: Aduanasoft (B2B)
- **Sistema**: Mesa de Ayuda multi-tenant
- **Arquitectura**: Modular Monolith con Clean Architecture
- **Target**: MVP enterprise-grade

## Stack Tecnológico

### Backend
- Python FastAPI (async)
- Pydantic v2 para validación
- SQLAlchemy 2.0 (async ORM)
- PostgreSQL como base de datos principal
- Redis para cache y broker Celery
- Celery para tareas asíncronas
- Alembic para migraciones
- Argon2/Bcrypt para hash de passwords
- PyJWT para autenticación

### Frontend
- SvelteKit + TypeScript
- Dos aplicaciones: cliente e interna
- TailwindCSS para estilos
- Zod para validación del lado cliente

### DevOps
- Docker + Docker Compose
- Nginx como reverse proxy
- Variables de entorno para configuración
- Healthchecks para servicios

## Dominios del Sistema

1. **auth**: Autenticación, usuarios, roles, 2FA
2. **tenants**: Multi-tenancy, organizaciones cliente
3. **tickets**: Core del sistema - tickets, estados, SLAs
4. **notifications**: Email, plantillas, comunicaciones
5. **audit**: Bitácora de acciones para compliance

## Roles de Usuario

- **ADMIN**: Control total (usuarios internos)
- **SUPPORT_MANAGER**: Gestión equipos y SLAs
- **AGENT**: Atención de tickets
- **AUDITOR**: Solo lectura para auditoría
- **CLIENT_ADMIN**: Gestión organización cliente
- **CLIENT_USER**: Creación/seguimiento tickets

## Reglas de Desarrollo

### Seguridad
- Siempre validar inputs con Pydantic
- Rate limiting en endpoints críticos
- Sanitizar archivos adjuntos
- Correlation ID en logs
- CORS restrictivo

### Código
- Clean Architecture por dominios
- Async/await en toda la aplicación
- Type hints obligatorios
- Docstrings en funciones públicas
- Tests unitarios + integración

### Base de Datos
- Migrations solo con Alembic
- Constraints a nivel de BD
- Índices para queries frecuentes
- Soft deletes cuando aplique

### API
- OpenAPI bien documentado
- Versionado con prefijo /v1/
- Paginación en listados
- Responses consistentes

## Comandos Útiles

```bash
# Setup inicial
docker-compose up -d
alembic upgrade head

# Desarrollo backend
uvicorn app.main:app --reload

# Testing
pytest --cov=app tests/

# Linting
ruff check . --fix
black .
mypy .
```

Cuando trabajes en este proyecto, siempre considera la naturaleza multi-tenant y empresarial del sistema.