template-saas/docs/99-referencias/ONBOARDING.md

Guía de Onboarding - Template SaaS

Proyecto: template-saas Tipo: PROVIDER (L1A) Fecha: 2026-02-03 Sistema: SIMCO v4.0.0 + NEXUS v4.0

---

1. Introducción

Bienvenido a template-saas, el template base para plataformas SaaS multi-tenant. Esta guía te ayudará a familiarizarte con el proyecto y comenzar a contribuir rápidamente.

---

2. Prerrequisitos

2.1 Conocimientos Requeridos

Área	Tecnología	Nivel
Backend	NestJS, TypeScript	Intermedio
Frontend	React 19, TypeScript	Intermedio
Base de Datos	PostgreSQL, RLS	Básico
DevOps	Docker, Git	Básico

2.2 Herramientas Necesarias

• Node.js 20+ (LTS)
• PostgreSQL 15+
• Redis 7+
• Git
• Docker (opcional pero recomendado)
• IDE: VS Code o Cursor con extensiones TypeScript

---

3. Estructura del Proyecto

template-saas/
├── backend/              # NestJS Backend (L2 submodule)
│   ├── src/
│   │   ├── modules/      # 23 módulos de negocio
│   │   ├── shared/       # Código compartido
│   │   └── main.ts
│   └── tests/
├── frontend/             # React Frontend (L2 submodule)
│   ├── src/
│   │   ├── pages/        # Páginas por portal
│   │   ├── hooks/        # React Query hooks
│   │   └── stores/       # Zustand stores
│   └── tests/
├── database/             # PostgreSQL DDL (L2 submodule)
│   ├── ddl/
│   │   ├── 00-extensions/
│   │   ├── 01-schemas/
│   │   └── */            # Schema por módulo
│   └── seeds/
├── docs/                 # Documentación técnica
│   ├── 00-vision-general/
│   ├── 01-modulos/       # SAAS-XXX specs
│   ├── 02-integraciones/ # INT-XXX specs
│   └── 99-referencias/   # Referencias rápidas
├── orchestration/        # Sistema SIMCO local
│   ├── inventarios/
│   ├── tareas/
│   └── trazas/
├── .claude/              # Instrucciones Claude Code
└── CLAUDE.md             # Instrucciones principales

---

4. Configuración Inicial

4.1 Clonar el Repositorio

git clone --recurse-submodules <repo-url>
cd template-saas

4.2 Configurar Variables de Entorno

# Backend
cp backend/.env.example backend/.env

# Editar con credenciales:
# DATABASE_URL=postgresql://template_saas_user:saas_dev_2026@localhost:5432/template_saas_dev
# REDIS_URL=redis://localhost:6379

4.3 Instalar Dependencias

# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install

4.4 Crear Base de Datos

# Opción 1: Script unificado (recomendado)
wsl -d Ubuntu-24.04 -- bash scripts/database/unified-recreate-db.sh template-saas --drop

# Opción 2: Manual
psql -U postgres -c "CREATE DATABASE template_saas_dev"
psql -U postgres -d template_saas_dev -f database/ddl/00-run-all.sql

4.5 Ejecutar Aplicación

# Backend (puerto 3100)
cd backend && npm run start:dev

# Frontend (puerto 5173)
cd frontend && npm run dev

---

5. Documentos Clave para Leer

5.1 Obligatorios (Antes de Contribuir)

Documento	Ubicación	Propósito
CLAUDE.md	/CLAUDE.md	Reglas del proyecto
SIMCO-TAREA	workspace-v2/orchestration/directivas/simco/SIMCO-TAREA.md	Ciclo CAPVED
SIMCO-GIT	workspace-v2/orchestration/directivas/simco/SIMCO-GIT.md	Reglas de git
Directivas Locales	.claude/directivas/DIRECTIVAS-LOCALES.md	Reglas específicas

5.2 Recomendados

Documento	Ubicación	Propósito
Estándares Aplicados	docs/99-referencias/ESTANDARES-APLICADOS.md	14 estándares
Matriz Trazabilidad	docs/99-referencias/MATRIZ-TRAZABILIDAD.md	RF/RNF mapping
CONTEXT-MAP	orchestration/CONTEXT-MAP.yml	Contexto NEXUS
PROJECT-STATUS	orchestration/PROJECT-STATUS.md	Estado actual

---

6. Módulos Principales

6.1 Core (Obligatorios)

Módulo	SAAS-ID	Descripción
auth	SAAS-001	Autenticación JWT, OAuth, MFA
tenants	SAAS-002	Multi-tenancy con RLS
users	SAAS-003	Gestión de usuarios, RBAC
billing	SAAS-004	Integración Stripe
plans	SAAS-005	Planes y límites

6.2 Comunicaciones

Módulo	SAAS-ID	Descripción
notifications	SAAS-007	Email, push, in-app, WebSocket
email	SAAS-013	SendGrid, SES, SMTP
whatsapp	SAAS-014	WhatsApp Business API

6.3 Operaciones

Módulo	SAAS-ID	Descripción
audit	SAAS-008	Auditoría de acciones
feature-flags	SAAS-009	Toggles dinámicos
webhooks	SAAS-010	Outbound con BullMQ
storage	SAAS-011	S3, R2, MinIO

6.4 Ventas (Avanzados)

Módulo	SAAS-ID	Descripción
sales	SAAS-018	Pipeline de ventas
portfolio	SAAS-019	Catálogo de productos
commissions	SAAS-020	Sistema de comisiones
mlm	SAAS-021	Marketing multinivel
goals	SAAS-022	Metas y objetivos

---

7. Flujo de Trabajo

7.1 Ciclo CAPVED

Todo cambio sigue el ciclo CAPVED:

1. Captar: Entender el requerimiento
2. Analizar: Revisar código existente, identificar dependencias
3. Planificar: Diseñar solución
4. Validar: build + lint + tests
5. Ejecutar: Implementar cambios
6. Documentar: Actualizar inventarios y docs

7.2 Antes de Implementar

1. Verificar especificación en docs/01-modulos/
2. Revisar inventarios en orchestration/inventarios/
3. Consultar catálogo compartido: workspace-v2/shared/catalog/
4. Verificar que no duplica funcionalidad

7.3 Después de Implementar

1. Ejecutar validaciones:

   # Backend
   npm run build && npm run lint && npm run test
   
   # Frontend
   npm run build && npm run lint && npm run typecheck
   

2. Actualizar inventarios:

   • BACKEND_INVENTORY.yml
   • FRONTEND_INVENTORY.yml
   • MASTER_INVENTORY.yml (si aplica)

3. Commit siguiendo convenciones:

   git add .
   git commit -m "[SAAS-XXX] feat: descripción"
   git push
   

---

8. Multi-Tenancy

8.1 Conceptos Clave

• Tenant: Organización/cliente en la plataforma
• RLS: Row Level Security - aislamiento a nivel de fila
• tenant_id: Columna obligatoria en tablas con datos de tenant

8.2 Reglas Obligatorias

1. Toda tabla con datos de tenant DEBE tener tenant_id NOT NULL
2. Toda tabla DEBE tener RLS policy
3. Entities DEBEN tener @Column() tenant_id: string
4. Services DEBEN usar TenantContext

8.3 Ejemplo

// Entity
@Entity('example')
export class Example {
  @Column()
  tenant_id: string;
}

// Service
@Injectable()
export class ExampleService {
  constructor(private tenantContext: TenantContext) {}

  async findAll() {
    return this.repo.find({
      where: { tenant_id: this.tenantContext.getTenantId() }
    });
  }
}

---

9. Testing

9.1 Ejecutar Tests

# Unit tests
npm run test

# Coverage
npm run test:cov

# E2E tests
npm run test:e2e

9.2 Cobertura Requerida

• Mínimo 70% para nuevos módulos
• Actual del proyecto: 70.5%

---

10. Recursos Adicionales

Recurso	Ubicación
ADRs	docs/architecture/adr/
Integraciones	docs/02-integraciones/
Changelog	CHANGELOG.md
Issues	GitHub Issues

---

11. Contacto y Soporte

• Documentación principal: Este proyecto
• Workspace global: workspace-v2/
• Estándares: workspace-v2/docs/40-estandares/

---

Última actualización: 2026-02-03 Actualizado por: Claude Opus 4.5 (TASK-2026-02-03-HOMOLOGACION)