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

## 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)
```python
# 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)
```typescript
// 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
```bash
# 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
```bash
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.