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

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

### 4.2 Configurar Variables de Entorno

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

```bash
# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install
```

### 4.4 Crear Base de Datos

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

```bash
# 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. **C**aptar: Entender el requerimiento
2. **A**nalizar: Revisar código existente, identificar dependencias
3. **P**lanificar: Diseñar solución
4. **V**alidar: build + lint + tests
5. **E**jecutar: Implementar cambios
6. **D**ocumentar: 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:
   ```bash
   # 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:
   ```bash
   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

```typescript
// 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

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