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

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

# 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

# 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

# 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