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 .

Configuración de IA Especializada

Prioridades de Asistencia

1. Seguridad primero: Siempre implementar autenticación/autorización en nuevos endpoints
2. Multi-tenancy: Verificar aislamiento de datos entre tenants en toda nueva funcionalidad
3. Performance: Considerar impacto en bases de datos grandes (índices, paginación, caching)
4. Auditabilidad: Registrar acciones sensibles en el sistema de audit
5. Escalabilidad: Código preparado para crecimiento empresarial

Patrones Preferidos

Backend (FastAPI)

# Estructura de endpoint típica
@router.post("/", response_model=schemas.TicketResponse)
async def create_ticket(
    ticket: schemas.TicketCreate,
    current_user: models.User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db)
):
    # 1. Validar permisos multi-tenant
    # 2. Procesar lógica de negocio
    # 3. Audit log
    # 4. Return response

Frontend (SvelteKit)

// Store pattern con Zod validation
import { z } from 'zod';
import { writable } from 'svelte/store';

const TicketSchema = z.object({
  title: z.string().min(5),
  priority: z.enum(['LOW', 'MEDIUM', 'HIGH', 'URGENT'])
});

Contexto de Archivos Clave

Backend Core

• app/core/security.py: JWT, permissions, rate limiting
• app/middleware/tenant.py: Multi-tenant context
• app/models/: SQLAlchemy models con relationships
• app/api/v1/endpoints/: Endpoints REST por dominio

Frontend Routing

• frontend-internal/: Panel administrativo interno
• frontend-client/: Portal de clientes
• Ambos usan SvelteKit con layout compartido

Workers/Tasks

• workers/app/tasks/: Tareas Celery asíncronas
• email_tasks.py: Notificaciones y plantillas
• sla_tasks.py: Monitoreo de SLAs automático

Troubleshooting Común

Database Issues

# Reset migrations
docker-compose exec backend alembic downgrade base
docker-compose exec backend alembic upgrade head

Multi-tenant Debug

• Verificar tenant_context middleware
• Headers: X-Tenant-ID en requests
• Queries siempre filtrar por tenant_id

Frontend Build Errors

cd frontend-internal && npm run build
cd frontend-client && npm run build

Convenciones de Desarrollo

Naming

• Models: PascalCase (User, Ticket, TenantOrganization)
• Endpoints: kebab-case (/api/v1/user-management/)
• Components: PascalCase.svelte (TicketCard.svelte)
• Stores: camelCase (ticketStore.ts)

Error Handling

• Backend: HTTPException con status codes apropiados
• Frontend: Toast notifications para UX
• Logs: Structured logging con correlation IDs

Testing Strategy

• Unit: Lógica de negocio y validaciones
• Integration: Endpoints completos con DB
• E2E: Flujos críticos multi-tenant

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