service_manager/.github/copilot-instructions.md

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

# 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.