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

# 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

# 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

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