service_manager/README.md

# ServiceManagerWeb - Mesa de Ayuda B2B

Sistema multi-tenant de Mesa de Ayuda/Soporte Técnico empresarial para Aduanasoft.

## Arquitectura

- **Frontend**: SvelteKit + TypeScript (portal clientes + panel interno)
- **Backend**: Python FastAPI + Pydantic v2 
- **Workers**: Celery + Redis (notificaciones, SLAs, jobs)
- **BD**: PostgreSQL + Alembic migrations
- **Auth**: JWT + Refresh tokens + 2FA opcional (TOTP)
- **Infra**: Docker Compose local, preparado para producción

## Estructura del Monorepo

```
ServiceManagerWeb/
├── backend/               # FastAPI app
├── frontend-client/       # SvelteKit app para clientes
├── frontend-internal/     # SvelteKit app para staff interno
├── workers/              # Celery tasks
├── db/                   # Migrations y esquemas
├── docker/               # Dockerfiles específicos
├── docs/                 # Documentación adicional
├── scripts/              # Scripts de desarrollo/despliegue
├── docker-compose.yml    # Orquestación completa
└── .env.example          # Variables de entorno
```

## Stack Tecnológico

### Backend (Python)
- FastAPI (async)
- Pydantic v2
- SQLAlchemy 2.0 (async)
- Alembic (migrations)
- Argon2 (hashing passwords)
- PyJWT
- Celery + Redis

### Frontend (JavaScript/TypeScript)
- SvelteKit
- TypeScript
- TailwindCSS
- shadcn/ui o similar
- Zod (validación)

### Infraestructura
- PostgreSQL 15+
- Redis 7+
- Docker & Docker Compose
- Nginx (reverse proxy)

## Dominios del Sistema

1. **Auth**: Usuarios, roles, permisos, 2FA
2. **Tenants**: Multi-tenancy, organizaciones
3. **Tickets**: Gestión de tickets, estados, SLAs
4. **Notifications**: Email, plantillas, logs
5. **Audit**: Bitácora de acciones

## Roles de Usuario

### Internos (Staff)
- `ADMIN`: Control total del sistema
- `SUPPORT_MANAGER`: Gestión de equipos y SLAs
- `AGENT`: Atención de tickets
- `AUDITOR`: Solo lectura para auditoría

### Clientes
- `CLIENT_ADMIN`: Gestión de organización cliente
- `CLIENT_USER`: Creación y seguimiento de tickets

## Quick Start

```bash
# Clonar y configurar
git clone <repo>
cd ServiceManagerWeb
cp .env.example .env

# Levantar servicios
docker-compose up -d

# Verificar estado
docker-compose ps
```

## URLs por Defecto

- Frontend Clientes: http://localhost:3000
- Frontend Interno: http://localhost:3001  
- API Backend: http://localhost:8000
- API Docs: http://localhost:8000/docs
- Adminer (DB): http://localhost:8080

## Scripts de Desarrollo

```bash
# Backend
cd backend
python -m uvicorn app.main:app --reload --port 8000

# Frontend Cliente
cd frontend-client
npm run dev -- --port 3000

# Frontend Interno  
cd frontend-internal
npm run dev -- --port 3001

# Workers
cd workers
celery -A app.worker worker --loglevel=info
celery -A app.worker beat --loglevel=info
```

## Testing

```bash
# Backend tests
cd backend
pytest

# Frontend tests
cd frontend-client
npm test
cd ../frontend-internal
npm test
```

## Troubleshooting

### Error 500 en Login / Proxy Error

**Síntoma**: Error 500 al intentar hacer login, o error de proxy de Vite "connect ECONNREFUSED".

**Causa**: Configuración incorrecta de la comunicación entre servicios de Docker.

**Solución**:
1. En desarrollo con Docker, los servicios usan nombres de servicio (no `localhost`)
2. Verificar `vite.config.js`: el proxy debe apuntar a `http://backend:8000`
3. Verificar `docker-compose.yml`: `PUBLIC_API_URL` debe ser `http://backend:8000`
4. Después de cambios, reiniciar contenedor: `docker-compose restart frontend-internal`

**Nota**: Para desarrollo local sin Docker, cambiar el proxy a `http://localhost:8000`.

### Tenant Slug Incorrecto

**Síntoma**: Error de autenticación incluso con credenciales correctas.

**Causa**: El `tenant_slug` en el login no coincide con los tenants en la BD.

**Solución**:
1. Verificar tenants existentes: `docker exec servicemanager-backend python check_tenants.py`
2. Actualizar el tenant_slug en el código de login
3. Tenants por defecto: `aduanasoft-demo`, `test-tenant`

### Credenciales de Prueba

```
Email: admin@aduanasoft.com
Password: admin123
Tenant: aduanasoft-demo
Role: ADMIN
```

## Contribución

1. Fork del proyecto
2. Crear feature branch (`git checkout -b feature/nueva-funcionalidad`)
3. Commit cambios (`git commit -am 'Agregar nueva funcionalidad'`)
4. Push a branch (`git push origin feature/nueva-funcionalidad`)
5. Crear Pull Request

## Licencia

Propietario - Aduanasoft © 2026