# 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

## Utilidades Administrativas

Para gestión y debugging de la base de datos, usa el script consolidado:

```bash
# Ver todos los comandos disponibles
python scripts/db_utils.py --help

# Listar todos los usuarios
python scripts/db_utils.py list-users

# Verificar información de un usuario
python scripts/db_utils.py check-user admin@example.com

# Resetear contraseña de un usuario
python scripts/db_utils.py reset-password admin@example.com --password admin123

# Listar últimos 10 tickets
python scripts/db_utils.py list-tickets --limit 10

# Verificar información de un ticket específico
python scripts/db_utils.py check-ticket <TICKET_ID>

# Filtrar por tenant
python scripts/db_utils.py list-users --tenant-id <TENANT_UUID>
python scripts/db_utils.py list-tickets --tenant-id <TENANT_UUID>
```

**💡 Alternativas para debugging:**
- **PostgreSQL directo**: Conectarte con pgAdmin, DBeaver o `psql`
- **Python Shell**: `python -m asyncio` desde el directorio backend
- **Tests**: Crear tests específicos en `backend/tests/`
- **API Docs**: Usar Swagger UI en http://localhost:8000/docs

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

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