BlissTracker SaaS
Task tracker multi-tenant para agencias. Cada cliente opera en su propio workspace en cliente.blisstracker.app.
Última actualización de este README: 16 ago 2026. La referencia de arquitectura completa y siempre al día es CLAUDE.md.
Stack
| Capa | Tecnología |
|---|
| Backend | Node.js · Express · Prisma · PostgreSQL |
| Frontend | React 18 · Vite · Tailwind CSS · React Router v6 |
| Auth | JWT (12h) · Google OAuth 2 |
| AI | Claude Haiku (Anthropic) |
| Billing | Stripe (Checkout + Customer Portal + Webhooks) |
| Email | Resend (HTTP API — sin SMTP) |
| Tests | Jest + Supertest (backend) · Vitest + React Testing Library (frontend) |
| Deploy | Railway (backend + BD) · Vercel Pro (frontend, wildcard subdomain) |
Desarrollo local
Requisitos
- Node.js 18+
- PostgreSQL 14+
1. Backend
cd backend
cp .env.example .env # completar variables (ver abajo)
npm install
npm run db:migrate:dev -- --name init
npm run db:seed # crea workspace "bliss" + usuario admin
npm run dev # puerto 3001
Variables de entorno requeridas:
DATABASE_URL=postgresql://user:pass@localhost:5432/team_tracker
JWT_SECRET=<string largo y aleatorio>
RESEND_API_KEY=re_xxxxxxxxxxxx
EMAIL_FROM=BlissTracker <[email protected]>
APP_DOMAIN=blisstracker.app
FRONTEND_URL=http://localhost:5173
GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=<client secret del OAuth app de Google Cloud>
ANTHROPIC_API_KEY=sk-ant-...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID=price_...
ENCRYPTION_KEY=<64 chars hex — AES-256-GCM para cifrar tokens OAuth en DB>
BACKEND_URL=http://localhost:3001
PAGESPEED_API_KEY=<API key de Google Cloud para PageSpeed Insights>
SERP_API_KEY=<API key de SerpAPI (serpapi.com) — snapshots SERP, features y competidores>
META_APP_ID=<App ID de Meta — Instagram Business Login y Facebook Pages>
META_APP_SECRET=<App Secret de esa misma app>
META_ADS_APP_ID=<App ID de Meta — SOLO Meta Ads, app distinta a la de arriba>
META_ADS_APP_SECRET=<App Secret de esa app de Ads>
TIKTOK_CLIENT_KEY=<TikTok App Key — TikTok for Developers>
TIKTOK_CLIENT_SECRET=<TikTok App Secret>
Credenciales tras el seed:
2. Frontend
cd frontend
npm install
npm run dev # puerto 5173
# frontend/.env.development
VITE_API_URL=http://localhost:3001
VITE_GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
Comandos útiles
# Backend
npm run dev # servidor con hot reload
npm run db:migrate:dev -- --name <name> # nueva migración
npm run db:migrate # aplicar migraciones (producción)
npm run db:seed # seed inicial
npx prisma studio # explorador visual de DB
npm test # Jest
# Frontend
npm run dev # dev server
npm run build # build producción
npm run test:run # Vitest
Arquitectura multi-tenant
Cada request al API incluye el header X-Workspace: <slug>. El middleware resolveWorkspace resuelve el slug a un Workspace en la DB e inyecta req.workspace. Los datos de cada workspace están aislados por workspaceId en todas las tablas relevantes.
cliente.blisstracker.app
→ frontend extrae slug → envía X-Workspace: cliente
→ backend resolveWorkspace → req.workspace = { id, name, slug, ... }
→ controllers filtran por req.workspace.id
El JWT incluye { userId, workspaceId, role, teamRole }. Al cambiar de workspace se re-emite un nuevo JWT para ese contexto.
Roles en workspace (WorkspaceMember.role):
| Rol | Permisos |
|---|
owner | Puede eliminar el workspace, todo lo de admin |
admin | Gestión de equipo, proyectos, configuración |
member | Acceso a sus proyectos y tareas |
Gestión del equipo
Los miembros se incorporan exclusivamente por invitación por email. El admin envía la invitación desde Admin → Equipo y el invitado recibe un link con token de 7 días.
- Si el invitado ya tiene cuenta en BlissTracker (en otro workspace), acepta y se incorpora directamente.
- Si es nuevo, completa nombre y contraseña al aceptar.
Los admins pueden editar el rol de equipo (DESIGNER, CM, etc.) y los permisos (miembro/admin) de cada persona. Nunca se gestiona la contraseña desde el panel de admin.
Registro de workspace
Nuevo workspace desde https://blisstracker.app/register:
- Nombre del workspace + slug (subdominio)
- Datos del owner (nombre, email, contraseña)
- Se crea workspace en trial de 14 días
- El owner queda con rol
owner
- Se crea un Stripe Customer de forma asíncrona (no bloquea el registro)
Facturación (Billing)
- Trial: 14 días gratuitos con acceso completo. Cron diario a las 03:00 ART marca como
past_due los trials vencidos.
- Upgrade: admin/owner ve botón "Suscribirse ahora" en
/billing. Redirige a Stripe Checkout. Al completar, webhook actualiza status → active.
- Gestión: link "Gestionar suscripción" abre el Customer Portal de Stripe (facturas, método de pago, cancelación).
- Banner:
TrialBanner aparece en el navbar cuando quedan ≤ 7 días de trial o hay un pago pendiente.
bliss workspace: exento de billing, siempre status = active. No pasa por Stripe.- Webhook URL:
https://<railway-url>/api/billing/webhook
Estructura del proyecto
team-tracker/
├── backend/
│ ├── prisma/
│ │ ├── schema.prisma # Modelos de base de datos
│ │ ├── migrations/ # Historial de migraciones SQL
│ │ └── seed.js # Workspace "bliss" + usuario admin + roles
│ └── src/
│ ├── app.js # Express app (sin listen)
│ ├── index.js # Punto de entrada: listen + crons
│ ├── middleware/
│ │ ├── auth.js # JWT auth
│ │ └── workspace.js # resolveWorkspace + workspaceAdminOnly
│ ├── config/
│ │ └── featureFlags.js # Catálogo de flags — agregar aquí, se auto-crean en DB
│ ├── controllers/
│ │ ├── auth.controller.js
│ │ ├── workspace.controller.js # CRUD workspace, invitaciones, eliminación
│ │ ├── workdays.controller.js
│ │ ├── tasks.controller.js
│ │ ├── projects.controller.js
│ │ ├── profile.controller.js
│ │ ├── insights.controller.js
│ │ ├── roleExpectations.controller.js
│ │ ├── reports.controller.js
│ │ ├── realtime.controller.js
│ │ ├── notifications.controller.js
│ │ ├── roles.controller.js
│ │ ├── billing.controller.js # getStatus, createCheckout, createPortal
│ │ ├── geo.controller.js # runAudit, listAudits, getAudit
│ │ └── superadmin.controller.js # stats, workspaces, billing overview, email logs
│ ├── routes/
│ │ ├── workspace.routes.js
│ │ ├── billing.routes.js
│ │ ├── marketing.routes.js
│ │ ├── superadmin.routes.js
│ │ └── ...
│ ├── webhooks/
│ │ └── stripe.webhook.js # maneja eventos Stripe (raw body)
│ ├── scripts/
│ │ ├── create-test-user.js # Crea usuario de prueba para verificación Google OAuth
│ │ └── insert-meta-ads-token.js # Inserta System User Token de Meta Ads en DB
│ └── services/
│ ├── email.service.js # Resend + log a EmailLog
│ ├── weeklyReport.service.js # Cron viernes 14:00 ART
│ ├── insightMemory.service.js # Cron sábado 00:00 ART
│ ├── geoAudit.service.js # Fetch + cheerio + Claude → GeoAudit
│ ├── tokenRefresh.service.js # Refresca access tokens de Google OAuth
│ ├── instagram.service.js # API calls a graph.instagram.com
│ ├── instagramSnapshot.service.js # Snapshots mensuales de Instagram
│ ├── metaTokenRefresh.service.js # Extiende long-lived tokens de Meta
│ ├── tiktok.service.js # API calls a TikTok v2 (PKCE, 4 scopes)
│ ├── tiktokTokenRefresh.service.js # Refresca access tokens de TikTok v2
│ └── tiktokSnapshot.service.js # Snapshots mensuales de TikTok
└── frontend/
└── src/
├── context/
│ ├── AuthContext.jsx # user, login, logout, switchWorkspace
│ ├── WorkspaceContext.jsx # workspace actual + trialDaysLeft + isSubscriptionActive
│ └── ThemeContext.jsx
├── hooks/
│ └── useFeatureFlag.js # hook con cache en memoria por sesión
├── pages/
│ ├── Login2.jsx
│ ├── Register.jsx # Crear nuevo workspace
│ ├── Join.jsx # Aceptar invitación
│ ├── Dashboard.jsx
│ ├── MyProjects.jsx
│ ├── ProjectDetail.jsx # Tab "Info" con websiteUrl + redes sociales
│ ├── MyReports.jsx
│ ├── RealTime.jsx
│ ├── Marketing.jsx # Tabs GEO, Web (GA4+PageSpeed) y RRSS (Instagram, TikTok, Meta Ads)
│ ├── OAuthResult.jsx # Puente OAuth: postMessage al opener y cierra popup
│ ├── Billing.jsx # Estado trial/plan, upgrade, portal Stripe
│ ├── Reports.jsx # Admin
│ ├── Admin.jsx # Panel admin (deep link ?tab=)
│ ├── Productivity.jsx # Admin
│ ├── RRHH.jsx # Admin — Recursos Humanos
│ ├── MyProfile.jsx
│ ├── Preferences.jsx
│ ├── Docs.jsx
│ └── SuperAdmin.jsx # Panel interno (solo isSuperAdmin)
├── components/
│ ├── Navbar.jsx # Nav items con fuente única (links/adminSublinks/profileSections)
│ ├── TrialBanner.jsx # Banner trial ≤7d o past_due
│ ├── ProjectInfoTab.jsx # websiteUrl + conexiones sociales + botones de conexión OAuth
│ ├── marketing/
│ │ ├── GeoTab.jsx # Selector proyecto, audit panel, score, items, historial
│ │ ├── WebTab.jsx # GA4 dashboard + snapshots IA + PageSpeed Insights
│ │ ├── InstagramTab.jsx # Métricas Instagram + snapshots + gráficos evolución
│ │ ├── TikTokTab.jsx # Métricas TikTok + snapshots + estado de verificación
│ │ ├── MetaAdsTab.jsx # Métricas Meta Ads + desglose por campaña
│ │ └── InformesTab.jsx # GA4 overview + canales + top páginas
│ ├── admin/
│ │ ├── TeamTab.jsx # Solo invitaciones por email
│ │ ├── EmpresaTab.jsx # Perfil de empresa + logo/banner + brandColors/brandFonts
│ │ └── ...
│ └── ...
└── api/client.js # Axios: inyecta JWT + X-Workspace header
Modelos de base de datos
| Modelo | Descripción |
|---|
Workspace | Tenant: slug, timezone, status (trialing/active/past_due/suspended/cancelled), stripeCustomerId. Perfil de empresa: companyName, companyDescription, industry, companyWebsite. Logo y banner como bytes en DB. Paleta de colores y fuentes de marca. disabledFeatureKeys para opt-out de feature flags. |
WorkspaceMember | Membresía usuario↔workspace: role (owner/admin/member), teamRole, preferencias IA |
Subscription | Plan y facturación por workspace: stripeSubId, seats, periodStart/End |
User | Cuenta global: email único, datos personales, avatar |
UserRole | Roles de equipo por workspace (ej: DESIGNER, CM) |
WorkspaceInvitation | Invitaciones por email con token de 7 días |
WorkspaceDeletionRequest | Solicitud de eliminación con 48h de gracia |
FeatureFlag | Flags de funcionalidad: enabledGlobally o por lista de workspaceIds |
WorkDay | Jornada laboral por usuario/workspace/día |
Task | Tarea con estado, starred, backlog, sesiones de tiempo |
TaskSession | Sesiones de cronómetro por tarea |
TaskComment | Comentarios con @menciones |
Project | Proyectos/clientes: websiteUrl (GEO), connections (JSON redes sociales) |
ProjectLink | Links útiles por proyecto (Drive, Figma, etc.) |
GeoAudit | Análisis GEO por proyecto: score, 6 componentes, items, señales negativas |
ProjectIntegration | Tokens OAuth por proyecto (GA4, Instagram, TikTok, Meta Ads): cifrados con AES-256-GCM |
AnalyticsSnapshot | Resumen mensual de GA4 por proyecto: sesiones, usuarios, páginas, canales |
AnalyticsInsight | Análisis IA mensual generado con Claude Haiku (deltas, tendencias, recomendaciones) |
PageSpeedResult | Resultados de PageSpeed Insights API: score, métricas CWV, oportunidades, diagnósticos |
Navegación
Menú de navegación — fuente única
Los arrays links, adminSublinks y profileSections en Navbar.jsx son la fuente única de verdad para los ítems del navbar. Cualquier cambio ahí aplica automáticamente en desktop (dropdown) y mobile (panel hamburguesa). No hay listas duplicadas.
Usuario común
| Pantalla | Ruta |
|---|
| Dashboard | / |
| Mis Proyectos | /my-projects |
| Detalle de proyecto | /my-projects/:id |
| Mis Reportes | /my-reports |
| Actividad | /realtime |
| Marketing | /marketing — requiere feature flag marketing. Tabs: GEO, Web, SEO, Keywords, Canibalización, Instagram, TikTok, Meta Ads, Google Ads, Salud, Informes |
| Contenido | /contenido — requiere feature flag contenido. Calendario de contenido: vistas Calendario, Tabla y Kanban, con aprobación del cliente desde el portal |
| Perfil | /profile |
| Preferencias | /preferences |
| Facturación | /billing |
| Docs | /docs |
Administrador (más)
| Pantalla | Ruta |
|---|
| Reportes | /reports |
| Panel Admin | /admin?tab= |
| Productividad | /admin/productivity |
| RRHH | /admin/rrhh |
| EOS | /admin/eos — requiere feature flag eos. 7 tabs: Visión, Personas, Datos, Asuntos, Procesos, Tracción, Evaluación |
Tabs del panel Admin (query param ?tab=): projects, team, services, roles, role-ai, empresa. La pestaña Empresa (EmpresaTab.jsx) gestiona el perfil de la empresa (nombre, descripción, industria, sitio web), logo, banner, paleta de colores de marca y tipografías.
Super Admin interno (solo isSuperAdmin)
| Pantalla | Ruta |
|---|
| Panel Super Admin | /superadmin |
El panel super admin tiene sidebar con: Dashboard (stats + workspaces + edición del límite mensual de tokens IA), Billing (MRR/ARR + tabla de suscripciones), Pagos (invoices reales de Stripe), AI Tokens (uso de tokens IA por workspace), Feedback, Emails, Announcements, Avatares, Feature Flags, Legal (edición de Términos de servicio y Política de privacidad).
Los workspace admins también pueden hacer opt-out de módulos habilitados desde Preferencias → Módulos adicionales (usa PATCH /api/workspaces/current/features/:key).
Deploy en producción
Backend (Railway)
- Variables de entorno en Railway:
DATABASE_URL, JWT_SECRET, RESEND_API_KEY, EMAIL_FROM, APP_DOMAIN, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, ANTHROPIC_API_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_ID, ENCRYPTION_KEY, BACKEND_URL, PAGESPEED_API_KEY, SERP_API_KEY, META_APP_ID, META_APP_SECRET, META_ADS_APP_ID, META_ADS_APP_SECRET, TIKTOK_CLIENT_KEY, TIKTOK_CLIENT_SECRET
- Railway ejecuta
npm run db:migrate automáticamente al deployar
- Seed manual una vez desde Railway Shell
Frontend (Vercel Pro)
- Root:
/frontend
- Agregar
*.blisstracker.app como Custom Domain (requiere Vercel Pro para wildcard)
- Variables:
VITE_API_URL, VITE_GOOGLE_CLIENT_ID
vercel.json ya incluye rewrites para SPA routing
DNS (Cloudflare)
A blisstracker.app → VercelA *.blisstracker.app → Vercel (wildcard)
Marketing — GEO Audit
El módulo GEO (Generative Engine Optimization) analiza qué tan bien posicionado está el sitio de un proyecto para aparecer en respuestas de ChatGPT, Perplexity, Claude y Google AI Overviews.
- Configuración: el owner/admin carga la URL del sitio en la pestaña Info del proyecto.
- Análisis: backend hace fetch del sitio con axios + cheerio, verifica robots.txt (23 crawlers: citation, training y broad), llms.txt, JSON-LD schema, luego llama a Claude para scoring.
- Score: 0–100 con 4 bandas (Crítico 0–35 / Base 36–67 / Bueno 68–85 / Excelente 86–100).
- 6 componentes: Citabilidad IA, Autoridad de Marca, E-E-A-T, Técnico, Schema, Plataformas IA.
- Items unificados: lista de hallazgos + señales negativas con severidad/prioridad.
- Crear tarea: desde cualquier item se puede crear una tarea en el proyecto con prefijo "GEO - ".
- Feature flag: requiere
marketing activado en SuperAdmin → Feature Flags.
Marketing — Salud, SEO y Canibalización
Salud (Health Score)
Pestaña Salud (SaludTab.jsx): score compuesto que agrega el último audit GEO, posiciones promedio de keywords del mes actual, deltas del último snapshot GA4 y resultados de PageSpeed (mobile + desktop) en un único indicador. No persiste — se calcula en cada request a GET /api/marketing/projects/:id/health-score.
SEO (Google Search Console)
Pestaña SEO (SeoTab.jsx): conecta Google Search Console con OAuth y muestra impresiones, clicks, CTR y posición promedio. Análisis IA mensual con Claude Haiku. Snapshots persistidos en SEOSnapshot.
Keywords (SERP Tracking)
Pestaña Keywords (KeywordsTab.jsx): tracking de keywords con ranking histórico (Google Search Console) y snapshots SERP completos (SerpAPI: posición, features del SERP, competidores, "People Also Ask"). Snapshot reciente reutilizado si <24h; refresh manual con cooldown de 15min.
Canibalización
Pestaña Canibalización (CanibalizacionTab.jsx): detecta páginas del sitio compitiendo por la misma keyword usando datos de Search Console + análisis Claude. Reportes persistidos con detalle, eliminables individualmente.
Marketing — RRSS (Instagram · TikTok · Meta Ads)
Tab RRSS en Marketing: conecta redes sociales y muestra métricas de audiencia y engagement.
Instagram
- Conexión OAuth: usa Instagram Business Login (
instagram.com/oauth/authorize) con scope instagram_business_basic.
- Token exchange: short-lived → long-lived (60 días) vía
api.instagram.com/oauth/access_token + graph.instagram.com/access_token.
- Métricas en tiempo real: seguidores, engagement rate, likes promedio, comentarios promedio, posts por semana (media últimas 4 semanas), últimas publicaciones.
- Snapshots mensuales: cron automático cada 1° del mes a las 04:30 ART guarda snapshot histórico.
- Gráficos SVG: evolución de seguidores y engagement por mes.
- Token expirado: cuando el token expira (>60 días sin renovar), se muestra estado "Sesión expirada" con botón para reconectar.
TikTok
- Conexión OAuth v2 PKCE:
code_verifier generado en backend, almacenado en state JWT; code_challenge = base64url(sha256(verifier)).
- Scopes:
user.info.basic, user.info.profile, user.info.stats, video.list.
- Métricas en tiempo real: seguidores, likes totales, engagement rate, videos totales, últimos 20 videos.
- Arquitectura resiliente: cada scope hace su propio call en try/catch — si un scope no está aprobado, solo esos campos retornan
null sin romper toda la integración.
- Snapshots mensuales: cron automático cada 1° del mes a las 05:00 ART.
- Estado de verificación: badge con estado de la app (en revisión, activa) si aplica.
Meta Ads
- Conexión OAuth: scope
ads_read vía facebook.com/dialog/oauth. Requiere Business Verification de Meta para uso en producción.
- Workaround System User Token: mientras Business Verification está pendiente, insertar token permanente generado desde Business Manager → System Users → Generate Token (Never expiry) usando el script
backend/scripts/insert-meta-ads-token.js.
- Métricas: gasto total, impresiones, clics, CTR, CPC, CPM por período (7/30/90 días).
- Desglose por campaña: tabla de campañas activas con métricas individuales.
- Nota:
ads_read requiere aprobación del Developer Token de Google Ads y Business Verification antes de funcionar en producción con OAuth estándar.
Patrón común de expiración de tokens
Todas las integraciones siguen el mismo patrón:
- Token expirado o inválido → backend retorna HTTP 400 con
{ code: 'TOKEN_EXPIRED' } (nunca 401 — evita cerrar sesión del usuario).
- La integración se marca como
status: 'expired' en DB.
- El frontend muestra estado "Sesión expirada" con botón para reconectar.
Marketing — Web (GA4 + PageSpeed)
Tab Web en Marketing: conecta Google Analytics 4 y muestra métricas de performance del sitio.
Google Analytics 4
- Conexión OAuth: botón "Conectar GA4" en ProjectInfoTab abre un popup OAuth. El token se cifra con AES-256-GCM y se guarda en
ProjectIntegration.
- Dashboard: sesiones, usuarios activos, nuevos usuarios, pageviews, bounce rate, duración promedio. Rangos: este mes, mes anterior, últimos 90 días, o rango personalizado.
- Top páginas: las 10 páginas más visitadas con pageviews y usuarios.
- Canales: desglose de tráfico por canal (Organic, Direct, Social, etc.).
- Snapshots IA: botón "Guardar snapshot" persiste el resumen mensual en DB; "Analizar con IA" genera análisis con Claude Haiku mostrando deltas vs mes anterior, tendencias y recomendaciones accionables.
- Crear tarea: desde cada recomendación de IA se puede crear una tarea con prefijo "Analytics - ".
- Cron automático: cada 1° del mes a las 02:00 ART se guarda el snapshot del mes anterior para todos los proyectos con GA4 conectado.
PageSpeed Insights
- Análisis manual: botón "Analizar" en la sección Performance corre PageSpeed Insights API (mobile/desktop).
- Score: 0–100 con colores (verde ≥ 90, naranja ≥ 50, rojo < 50).
- Core Web Vitals: LCP, FCP, TBT, CLS, Speed Index, TTFB con valores y rating por métrica.
- Oportunidades: mejoras estimadas con ahorro en ms (p.ej. eliminar JS no usado).
- Diagnósticos: audits fallidos adicionales que afectan la performance.
- Crear tarea: desde cualquier oportunidad o diagnóstico se puede crear una tarea con prefijo "Perf - ".
- Historial: badges con el score de los últimos N análisis.
- Cron automático: cada 1° del mes a las 03:30 ART corre análisis mobile + desktop para todos los proyectos con websiteUrl.
Contenido — calendario con aprobación del cliente
Módulo tipo Airtable (/contenido, feature flag contenido) para coordinar la producción de contenido de redes sociales y que el cliente apruebe las piezas sin salir del sistema.
- Vistas: Calendario, Tabla (edición inline estilo Airtable) y Kanban (drag & drop), más un modal de detalle por pieza.
- Workflow fijo: cada pieza pasa por 9 estados (idea → producción → revisión interna → esperando aprobación → aprobado/cambios pedidos → programado → publicado, o archivado), definidos en un catálogo de código, no en la base de datos.
- Assets: imágenes (hasta 15 MB) y video (hasta 150 MB) se suben directo desde el navegador a Cloudflare R2 con URL prefirmada — el backend nunca recibe los bytes, solo valida el archivo real al confirmar la subida.
- Aprobación del cliente: desde el mismo portal de cliente que ya sirve los informes mensuales (
/report/:slug), en un tab "Contenido". El cliente entra con un código por email (sin contraseña), ve solo las piezas listas para revisar y puede aprobar o pedir cambios con un comentario. El equipo recibe un email y una notificación in-app al instante, y ve el cambio reflejado en vivo (WebSocket) sin recargar.
- Portal multi-contacto: el portal de cliente ahora admite varios contactos autorizados por proyecto (antes era un solo email), cada uno con permiso propio para aprobar o no.
- Tareas: una pieza se puede "enviar al dashboard" como una
Task normal para su responsable; completarla avanza la pieza automáticamente al siguiente estado.
Ver CLAUDE.md — conceptos "Contenido" y "Portal de cliente (multi-contacto)" — para el detalle completo de modelos, endpoints y reglas de negocio.
Scripts de utilidad
Scripts en backend/scripts/:
| Script | Uso |
|---|
create-test-user.js | Crea/actualiza usuario [email protected] en workspace monethx10 para verificación de Google OAuth |
insert-meta-ads-token.js | Inserta un System User Token de Meta Ads directo en DB (workaround Business Verification pendiente) |
# Crear usuario de prueba (requiere DATABASE_URL de producción)
DATABASE_URL="postgresql://..." node scripts/create-test-user.js
# Insertar token Meta Ads
DATABASE_URL="..." ENCRYPTION_KEY="..." SYSTEM_TOKEN="EAF..." AD_ACCOUNT_ID="act_..." PROJECT_ID=62 \
node scripts/insert-meta-ads-token.js
Sistema de IA
Presupuesto de tokens por workspace
Cada workspace tiene un monthlyTokenLimit (default 1.000.000 tokens/mes, 0 = ilimitado). Toda llamada a Claude se valida primero contra el presupuesto vía assertTokenBudget(workspaceId); si está superado, el endpoint responde 429 con code: TOKEN_BUDGET_EXCEEDED. El consumo se calcula sumando inputTokens + outputTokens de AiTokenLog del mes calendario. El componente TokenBudgetBanner lo muestra en la app cuando el uso supera el 90%. Los SuperAdmins editan el límite desde SuperAdmin → Dashboard → Token limit o vía PATCH /api/superadmin/workspaces/:id/token-limit.
Insight diario
Generado por Claude Haiku al abrir el Dashboard. Cacheado una vez por día. Incluye: estado real de las tareas, memoria de productividad histórica, expectativas del rol y análisis GTD. El usuario puede refrescarlo (cooldown 1h) y dar feedback 👍/👎.
Memoria de productividad
Generada cada sábado 00:00 ART. Analiza las últimas 4 semanas: tendencias, fortalezas, áreas de atención, estadísticas. Se inyecta en el prompt del insight diario y el resumen semanal.
Resumen semanal por email
Enviado cada viernes 14:00 ART. Incluye análisis de la semana, patrones, recomendaciones y tareas de rol omitidas. Puede dispararse manualmente desde Preferencias.
Productividad, asistencia y RRHH
Productividad (/admin/productivity, admin) — métricas determinísticas por persona y por proyecto, sin IA en el cálculo:
- Δ horas (métrica principal): horas registradas ÷ horas disponibles (días hábiles esperados × jornada
workEndTime − workStartTime). El encabezado de la sección muestra el Δ horas del equipo ponderado por horas.
- Tareas / Horas / Tasa / Estado por persona, comparación contra la mediana del equipo (
▲/▼ vs equipo), y en la fila expandida un gráfico de líneas de las últimas 12 semanas de horas registradas.
- Período: "Mes en curso" (mes a la fecha vs los mismos días del mes anterior) o "Mes cerrado" (último mes completo vs el anterior).
- Aviso semanal por mail a admins/owners (lunes 08:00 ART) sólo si hay personas en alerta. Toggles
productivityEnabled / productivityDigestEnabled.
Asistencia y horarios — WorkspaceMember.workStartTime / workEndTime por persona habilitan el cálculo de horas disponibles y de tardanzas (primer login vs horario + lateToleranceMins). El bloque de asistencia de RRHH se enciende/apaga con Workspace.attendanceTrackingEnabled. Email automático opcional por acumulación de tardanzas en 30 días (lateNotify*).
RRHH (/admin/rrhh) — legajos con formulario configurable por workspace (legajoFields + campos custom), historial de logins (editable), vacaciones/licencias, snapshots mensuales de métricas (RrhhMetricSnapshot) y People Analyzer (score GWC del equipo).
Ver CLAUDE.md para el detalle completo de cálculos y modelos.
Email logging
Todos los emails enviados quedan registrados en EmailLog con: workspace, destinatario, asunto, tipo y estado (enviado/fallido). Visibles en el panel Super Admin → sección Emails.
Tipos de email: passwordReset · welcome · weeklySummary · testSettings · invitation · deletionWarning
Fotos de perfil
Los avatares se almacenan en la DB (modelo Avatar: imageData + mimeType) y se sirven vía GET /api/avatars/img/:filename. Avatar por defecto: 2bee.png. La validación al cambiar de avatar verifica que el filename exista en la tabla Avatar y esté active. Se administran desde SuperAdmin → Avatares (subir/renombrar/reordenar/activar/eliminar). Clickear en cualquier avatar abre un lightbox fullscreen.
El seed inicial (backend/prisma/seeds/seedAvatarsIfEmpty.js, automático en Railway si la tabla está vacía; o avatarSeed.js manual) carga los PNGs de backend/prisma/seeds/perfiles/.
Páginas públicas
- Landing (
Landing.jsx): se muestra en el dominio raíz blisstracker.app cuando no hay subdominio de workspace.
- Términos de servicio (
/condiciones) y Política de privacidad (/privacidad): renderizan documentos guardados en LegalDocument, editables desde SuperAdmin → Legal.
- OAuth helpers:
/oauth (OAuthPopup), /auth (AuthCallback) y /oauth-result (OAuthResult) — utilizadas en flujos de Google/Meta/TikTok.
- Informe público de cliente:
/report/:token (ReportPublic) — informe mensual identificado por token UUID, sin auth.
Documentación técnica detallada
Ver CLAUDE.md — referencia completa de arquitectura, modelos, rutas API y convenciones para desarrollo con Claude Code.
