[TASK-2026-01-24] docs: Add ET-SAAS-015, ET-SAAS-016, ET-SAAS-017 technical specs

2026-01-24 22:09:40 -06:00 · 2026-01-24 22:09:40 -06:00 · 3b654a34c8
commit 3b654a34c8
parent a6489b0caf
3 changed files with 2341 additions and 0 deletions
--- a/docs/02-especificaciones/ET-SAAS-015-oauth.md
+++ b/docs/02-especificaciones/ET-SAAS-015-oauth.md
@ -0,0 +1,758 @@
 ---
 id: "ET-SAAS-015"
 title: "Especificacion Tecnica OAuth 2.0"
 type: "TechnicalSpec"
 status: "Proposed"
 priority: "P1"
 module: "oauth"
 version: "1.0.0"
 created_date: "2026-01-24"
 updated_date: "2026-01-24"
 story_points: 5
 ---
 # ET-SAAS-015: Especificacion Tecnica - OAuth 2.0 Endpoints
 ## Metadata
 - **Codigo:** ET-SAAS-015
 - **Modulo:** Auth (extension OAuth)
 - **Version:** 1.0.0
 - **Estado:** Propuesto
 - **Fecha:** 2026-01-24
 - **Basado en:** RFC 6749, Passport.js strategies
 ---
 ## 1. Resumen Ejecutivo
 ### 1.1 Estado Actual
 El modulo de autenticacion actual incluye:
 | Componente | Estado | Limitaciones |
 |------------|--------|--------------|
 | JWT Auth | Implementado | Funcional |
 | Refresh Tokens | Implementado | Funcional |
 | Email/Password | Implementado | Funcional |
 | OAuth Connections (DDL) | Implementado | Tabla existe |
 | OAuth Endpoints | NO | Sin implementacion |
 | Passport Strategies | NO | Sin implementacion |
 | OAuth UI | NO | Sin botones/callbacks |
 ### 1.2 Propuesta v1.0
 Sistema OAuth 2.0 completo con:
 - **4 Proveedores**: Google, Microsoft, GitHub, Apple
 - **Passport.js**: Strategies oficiales para cada proveedor
 - **Flujos soportados**: Authorization Code con PKCE
 - **Vinculacion de cuentas**: Usuarios existentes pueden vincular OAuth
 - **CSRF Protection**: State parameter con validacion
 - **Token encryption**: Access/refresh tokens encriptados en BD
 ---
 ## 2. Analisis Comparativo
 ### 2.1 Proveedores OAuth
 | Proveedor | Strategy NPM | Scopes Requeridos | Notas |
 |-----------|--------------|-------------------|-------|
 | Google | passport-google-oauth20 | email, profile | Mas comun |
 | Microsoft | passport-microsoft | user.read | Azure AD |
 | GitHub | passport-github2 | user:email | Developers |
 | Apple | passport-apple | email, name | iOS users |
 ### 2.2 Flujo OAuth Comparado
 | Paso | Google | Microsoft | GitHub | Apple |
 |------|--------|-----------|--------|-------|
 | Auth URL | accounts.google.com | login.microsoftonline.com | github.com | appleid.apple.com |
 | Token URL | oauth2.googleapis.com | login.microsoftonline.com | github.com | appleid.apple.com |
 | User Info | userinfo | graph.microsoft.com | api.github.com | Token JWT |
 | Refresh | Si | Si | No | Si |
 ---
 ## 3. Arquitectura Propuesta
 ### 3.1 Diagrama de Componentes
 ```
 +------------------+     +-------------------+     +------------------+
 |    Frontend      |     | OAuthController   |     | Passport.js      |
 |  OAuth Buttons   |---->| /auth/oauth/:prov |---->| Strategies       |
 +------------------+     +-------------------+     +------------------+
                                                          |
                         +--------------------------------+
                         |
                         v
 +------------------+     +-------------------+     +------------------+
 | Google/MS/GH/AP  |---->| Callback Handler  |---->| OAuthService     |
 | Auth Servers     |     | /callback         |     | (business logic) |
 +------------------+     +-------------------+     +------------------+
                                                          |
                                                          v
                                              +-------------------+
                                              | User + Connection |
                                              | (DB operations)   |
                                              +-------------------+
 ```
 ### 3.2 Flujo Detallado
 ```
 INICIO OAUTH:
 1. Usuario click "Login con Google"
 2. Frontend GET /auth/oauth/google?redirect_uri=...
 3. Controller invoca passport.authenticate('google')
 4. Passport genera URL con state + code_verifier
 5. Redirect 302 a Google
 CALLBACK OAUTH:
 6. Usuario autoriza en Google
 7. Google redirige a /auth/oauth/google/callback?code=...&state=...
 8. Passport valida state (CSRF)
 9. Passport intercambia code por tokens
 10. Passport obtiene perfil de usuario
 11. OAuthService.handleOAuthCallback(profile, tokens)
    a. Buscar OAuthConnection por provider_user_id
    b. Si existe: obtener User vinculado
    c. Si no existe: crear User + Tenant + OAuthConnection
 12. Generar JWT tokens de sesion
 13. Redirect a frontend con tokens
 ```
 ---
 ## 4. Modelo de Datos
 ### 4.1 Tabla Existente: auth.oauth_connections
 ```sql
 -- Ya existe en DDL, sin cambios necesarios
 CREATE TABLE auth.oauth_connections (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users.users(id) ON DELETE CASCADE,
    -- Provider info
    provider auth.oauth_provider NOT NULL,
    provider_user_id VARCHAR(255) NOT NULL,
    -- Tokens (encriptados)
    access_token TEXT,
    refresh_token TEXT,
    token_expires_at TIMESTAMPTZ,
    -- Profile data
    profile_data JSONB DEFAULT '{}',
    -- Timestamps
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    -- Constraints
    UNIQUE(provider, provider_user_id),
    UNIQUE(user_id, provider)
 );
 -- RLS ya configurado
 ```
 ### 4.2 Enum Existente
 ```sql
 CREATE TYPE auth.oauth_provider AS ENUM (
    'google',
    'microsoft',
    'github',
    'apple'
 );
 ```
 ---
 ## 5. Implementacion Backend
 ### 5.1 Estructura de Archivos
 ```
 backend/src/modules/auth/
 ├── strategies/
 │   ├── google.strategy.ts
 │   ├── microsoft.strategy.ts
 │   ├── github.strategy.ts
 │   └── apple.strategy.ts
 ├── controllers/
 │   └── oauth.controller.ts
 ├── services/
 │   └── oauth.service.ts
 ├── entities/
 │   └── oauth-connection.entity.ts
 └── dto/
    ├── oauth-callback.dto.ts
    └── oauth-connection.dto.ts
 ```
 ### 5.2 Entity: OAuthConnection
 ```typescript
@Entity('oauth_connections', { schema: 'auth' })
 export class OAuthConnection {
  @PrimaryGeneratedColumn('uuid')
  id: string;
  @Column('uuid')
  userId: string;
  @ManyToOne(() => User)
  @JoinColumn({ name: 'user_id' })
  user: User;
  @Column({
    type: 'enum',
    enum: OAuthProvider,
    enumName: 'oauth_provider',
  })
  provider: OAuthProvider;
  @Column({ name: 'provider_user_id' })
  providerUserId: string;
  @Column({ name: 'access_token', nullable: true })
  accessToken: string;
  @Column({ name: 'refresh_token', nullable: true })
  refreshToken: string;
  @Column({ name: 'token_expires_at', nullable: true })
  tokenExpiresAt: Date;
  @Column({ name: 'profile_data', type: 'jsonb', default: {} })
  profileData: Record<string, any>;
  @CreateDateColumn({ name: 'created_at' })
  createdAt: Date;
  @UpdateDateColumn({ name: 'updated_at' })
  updatedAt: Date;
 }
 ```
 ### 5.3 Service: OAuthService
 ```typescript
@Injectable()
 export class OAuthService {
  constructor(
    @InjectRepository(OAuthConnection)
    private readonly oauthRepo: Repository<OAuthConnection>,
    private readonly usersService: UsersService,
    private readonly tenantsService: TenantsService,
    private readonly authService: AuthService,
    private readonly encryptionService: EncryptionService,
  ) {}
  async handleOAuthCallback(
    provider: OAuthProvider,
    profile: OAuthProfile,
    tokens: OAuthTokens,
  ): Promise<AuthResult> {
    // 1. Buscar conexion existente
    let connection = await this.oauthRepo.findOne({
      where: { provider, providerUserId: profile.id },
      relations: ['user'],
    });
    let user: User;
    let isNewUser = false;
    if (connection) {
      // Usuario existente con OAuth
      user = connection.user;
      // Actualizar tokens
      await this.updateConnectionTokens(connection, tokens);
    } else {
      // Nuevo usuario via OAuth
      const result = await this.createUserFromOAuth(provider, profile, tokens);
      user = result.user;
      connection = result.connection;
      isNewUser = true;
    }
    // Generar JWT
    const jwtTokens = await this.authService.generateTokens(user);
    return {
      ...jwtTokens,
      user: this.usersService.toDto(user),
      isNewUser,
    };
  }
  async linkOAuthToUser(
    userId: string,
    provider: OAuthProvider,
    profile: OAuthProfile,
    tokens: OAuthTokens,
  ): Promise<OAuthConnection> {
    // Verificar que no existe otra cuenta con ese provider_user_id
    const existing = await this.oauthRepo.findOne({
      where: { provider, providerUserId: profile.id },
    });
    if (existing && existing.userId !== userId) {
      throw new ConflictException(
        'This OAuth account is already linked to another user',
      );
    }
    // Verificar que el usuario no tiene ya este provider
    const userConnection = await this.oauthRepo.findOne({
      where: { userId, provider },
    });
    if (userConnection) {
      throw new ConflictException(
        `User already has a ${provider} account linked`,
      );
    }
    // Crear conexion
    return this.oauthRepo.save({
      userId,
      provider,
      providerUserId: profile.id,
      accessToken: this.encryptionService.encrypt(tokens.accessToken),
      refreshToken: tokens.refreshToken
        ? this.encryptionService.encrypt(tokens.refreshToken)
        : null,
      tokenExpiresAt: tokens.expiresAt,
      profileData: profile.raw,
    });
  }
  async unlinkOAuth(userId: string, provider: OAuthProvider): Promise<void> {
    // Verificar que el usuario tiene otra forma de login
    const user = await this.usersService.findById(userId);
    const connections = await this.oauthRepo.count({ where: { userId } });
    if (!user.passwordHash && connections <= 1) {
      throw new BadRequestException(
        'Cannot unlink last OAuth provider without password set',
      );
    }
    await this.oauthRepo.delete({ userId, provider });
  }
  async getConnections(userId: string): Promise<OAuthConnectionDto[]> {
    const connections = await this.oauthRepo.find({
      where: { userId },
      select: ['id', 'provider', 'profileData', 'createdAt'],
    });
    return connections.map((c) => ({
      provider: c.provider,
      email: c.profileData.email,
      linkedAt: c.createdAt,
    }));
  }
 }
 ```
 ### 5.4 Strategy: Google
 ```typescript
@Injectable()
 export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
  constructor(private readonly configService: ConfigService) {
    super({
      clientID: configService.get('GOOGLE_CLIENT_ID'),
      clientSecret: configService.get('GOOGLE_CLIENT_SECRET'),
      callbackURL: configService.get('GOOGLE_CALLBACK_URL'),
      scope: ['email', 'profile'],
      state: true,
    });
  }
  async validate(
    accessToken: string,
    refreshToken: string,
    profile: GoogleProfile,
    done: VerifyCallback,
  ): Promise<void> {
    const oauthProfile: OAuthProfile = {
      id: profile.id,
      email: profile.emails?.[0]?.value,
      name: profile.displayName,
      firstName: profile.name?.givenName,
      lastName: profile.name?.familyName,
      picture: profile.photos?.[0]?.value,
      raw: profile._json,
    };
    const tokens: OAuthTokens = {
      accessToken,
      refreshToken,
      expiresAt: new Date(Date.now() + 3600 * 1000), // 1h default
    };
    done(null, { profile: oauthProfile, tokens });
  }
 }
 ```
 ### 5.5 Controller: OAuthController
 ```typescript
@Controller('auth/oauth')
@ApiTags('OAuth')
 export class OAuthController {
  constructor(private readonly oauthService: OAuthService) {}
  @Get(':provider')
  @ApiOperation({ summary: 'Initiate OAuth flow' })
  @UseGuards(AuthGuard('google')) // Dynamic based on provider
  initiateOAuth(@Param('provider') provider: OAuthProvider): void {
    // Passport handles redirect
  }
  @Get(':provider/callback')
  @ApiOperation({ summary: 'OAuth callback' })
  @UseGuards(AuthGuard('google')) // Dynamic based on provider
  async oauthCallback(
    @Param('provider') provider: OAuthProvider,
    @Req() req: Request,
    @Res() res: Response,
  ): Promise<void> {
    const { profile, tokens } = req.user as OAuthCallbackData;
    const result = await this.oauthService.handleOAuthCallback(
      provider,
      profile,
      tokens,
    );
    // Redirect to frontend with tokens
    const frontendUrl = this.configService.get('FRONTEND_URL');
    const params = new URLSearchParams({
      access_token: result.accessToken,
      refresh_token: result.refreshToken,
      is_new_user: result.isNewUser.toString(),
    });
    res.redirect(`${frontendUrl}/auth/callback?${params}`);
  }
  @Post('link/:provider')
  @ApiOperation({ summary: 'Link OAuth to existing account' })
  @UseGuards(JwtAuthGuard)
  @UseGuards(AuthGuard('google')) // Dynamic
  async linkOAuth(
    @Param('provider') provider: OAuthProvider,
    @GetUser() user: User,
    @Req() req: Request,
  ): Promise<OAuthConnectionDto> {
    const { profile, tokens } = req.user as OAuthCallbackData;
    const connection = await this.oauthService.linkOAuthToUser(
      user.id,
      provider,
      profile,
      tokens,
    );
    return this.oauthService.toConnectionDto(connection);
  }
  @Delete(':provider')
  @ApiOperation({ summary: 'Unlink OAuth provider' })
  @UseGuards(JwtAuthGuard)
  async unlinkOAuth(
    @Param('provider') provider: OAuthProvider,
    @GetUser() user: User,
  ): Promise<void> {
    await this.oauthService.unlinkOAuth(user.id, provider);
  }
  @Get('connections')
  @ApiOperation({ summary: 'List OAuth connections' })
  @UseGuards(JwtAuthGuard)
  async getConnections(@GetUser() user: User): Promise<OAuthConnectionDto[]> {
    return this.oauthService.getConnections(user.id);
  }
 }
 ```
 ---
 ## 6. Implementacion Frontend
 ### 6.1 Componente: OAuthButtons
 ```tsx
 interface OAuthButtonsProps {
  mode: 'login' | 'register' | 'link';
  onSuccess?: () => void;
 }
 export const OAuthButtons: React.FC<OAuthButtonsProps> = ({ mode, onSuccess }) => {
  const { initiateOAuth, isLoading } = useOAuthLogin();
  const providers = [
    { id: 'google', name: 'Google', icon: GoogleIcon, color: '#DB4437' },
    { id: 'microsoft', name: 'Microsoft', icon: MicrosoftIcon, color: '#00A4EF' },
    { id: 'github', name: 'GitHub', icon: GitHubIcon, color: '#333' },
    { id: 'apple', name: 'Apple', icon: AppleIcon, color: '#000' },
  ];
  return (
    <div className="flex flex-col gap-3">
      {providers.map((provider) => (
        <button
          key={provider.id}
          onClick={() => initiateOAuth(provider.id)}
          disabled={isLoading}
          className="flex items-center justify-center gap-2 px-4 py-2 border rounded-lg hover:bg-gray-50"
        >
          <provider.icon className="w-5 h-5" />
          <span>
            {mode === 'link' ? 'Link' : 'Continue'} with {provider.name}
          </span>
        </button>
      ))}
    </div>
  );
 };
 ```
 ### 6.2 Hook: useOAuthLogin
 ```tsx
 export const useOAuthLogin = () => {
  const [isLoading, setIsLoading] = useState(false);
  const initiateOAuth = useCallback((provider: string) => {
    setIsLoading(true);
    const currentUrl = window.location.href;
    const redirectUri = encodeURIComponent(currentUrl);
    // Redirect to backend OAuth endpoint
    window.location.href = `/api/auth/oauth/${provider}?redirect_uri=${redirectUri}`;
  }, []);
  return { initiateOAuth, isLoading };
 };
 ```
 ### 6.3 Pagina: OAuthCallback
 ```tsx
 export const OAuthCallbackPage: React.FC = () => {
  const navigate = useNavigate();
  const { setAuth } = useAuthStore();
  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const accessToken = params.get('access_token');
    const refreshToken = params.get('refresh_token');
    const isNewUser = params.get('is_new_user') === 'true';
    const error = params.get('error');
    if (error) {
      toast.error(`OAuth failed: ${error}`);
      navigate('/login');
      return;
    }
    if (accessToken && refreshToken) {
      setAuth({ accessToken, refreshToken });
      if (isNewUser) {
        navigate('/onboarding');
      } else {
        navigate('/dashboard');
      }
    }
  }, []);
  return <LoadingSpinner message="Completing login..." />;
 };
 ```
 ---
 ## 7. Seguridad
 ### 7.1 CSRF Protection
 ```typescript
 // State parameter generado con crypto
 const generateState = (): string => {
  return crypto.randomBytes(32).toString('hex');
 };
 // Almacenar en session/cookie
 const storeState = (res: Response, state: string): void => {
  res.cookie('oauth_state', state, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    maxAge: 600000, // 10 min
    sameSite: 'lax',
  });
 };
 // Validar en callback
 const validateState = (req: Request, state: string): boolean => {
  const storedState = req.cookies.oauth_state;
  return storedState === state;
 };
 ```
 ### 7.2 Token Encryption
 ```typescript
@Injectable()
 export class EncryptionService {
  private readonly algorithm = 'aes-256-gcm';
  private readonly key: Buffer;
  constructor(configService: ConfigService) {
    this.key = Buffer.from(configService.get('ENCRYPTION_KEY'), 'hex');
  }
  encrypt(text: string): string {
    const iv = crypto.randomBytes(16);
    const cipher = crypto.createCipheriv(this.algorithm, this.key, iv);
    const encrypted = Buffer.concat([cipher.update(text), cipher.final()]);
    const tag = cipher.getAuthTag();
    return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`;
  }
  decrypt(encrypted: string): string {
    const [ivHex, tagHex, dataHex] = encrypted.split(':');
    const iv = Buffer.from(ivHex, 'hex');
    const tag = Buffer.from(tagHex, 'hex');
    const data = Buffer.from(dataHex, 'hex');
    const decipher = crypto.createDecipheriv(this.algorithm, this.key, iv);
    decipher.setAuthTag(tag);
    return decipher.update(data) + decipher.final('utf8');
  }
 }
 ```
 ---
 ## 8. Testing
 ### 8.1 Unit Tests
 ```typescript
 describe('OAuthService', () => {
  describe('handleOAuthCallback', () => {
    it('should create new user for new OAuth login', async () => {
      // ...
    });
    it('should return existing user for known OAuth account', async () => {
      // ...
    });
    it('should update tokens on existing connection', async () => {
      // ...
    });
  });
  describe('linkOAuthToUser', () => {
    it('should link OAuth to existing user', async () => {
      // ...
    });
    it('should throw if OAuth already linked to another user', async () => {
      // ...
    });
  });
  describe('unlinkOAuth', () => {
    it('should unlink OAuth provider', async () => {
      // ...
    });
    it('should throw if unlinking last auth method', async () => {
      // ...
    });
  });
 });
 ```
 ### 8.2 E2E Tests
 ```typescript
 describe('OAuth Flow (E2E)', () => {
  it('should complete Google OAuth flow', async () => {
    // Mock Google OAuth
    // Test full flow
  });
  it('should handle OAuth errors gracefully', async () => {
    // Test error scenarios
  });
 });
 ```
 ---
 ## 9. Criterios de Aceptacion
 - [ ] GET /auth/oauth/:provider redirige correctamente a cada proveedor
 - [ ] Callback procesa autorizacion y crea/vincula usuario
 - [ ] State parameter previene CSRF
 - [ ] Tokens OAuth se encriptan en BD
 - [ ] Usuario puede vincular multiples proveedores
 - [ ] Usuario puede desvincular proveedor (si tiene alternativa)
 - [ ] Frontend muestra botones OAuth en login/register
 - [ ] Frontend procesa callback correctamente
 - [ ] Tests unitarios con cobertura >70%
 - [ ] Tests E2E para flujo completo de cada proveedor
 ---
 ## 10. Riesgos y Mitigaciones
 | Riesgo | Probabilidad | Impacto | Mitigacion |
 |--------|--------------|---------|------------|
 | Proveedor no disponible | Media | Alto | Retry + mensaje amigable |
 | Token expirado | Alta | Bajo | Auto-refresh donde soportado |
 | Cuenta duplicada | Baja | Medio | Verificar email antes de crear |
 | CSRF attack | Baja | Alto | State parameter obligatorio |
 ---
 ## 11. Dependencias
 ### NPM Packages
 ```json
 {
  "@nestjs/passport": "^10.0.3",
  "passport": "^0.7.0",
  "passport-google-oauth20": "^2.0.0",
  "passport-microsoft": "^1.0.0",
  "passport-github2": "^0.1.12",
  "passport-apple": "^2.0.2"
 }
 ```
 ### Servicios Externos
 - Google Cloud Console (OAuth credentials)
 - Microsoft Azure Portal (App registration)
 - GitHub Developer Settings (OAuth App)
 - Apple Developer Portal (Sign in with Apple)
 ---
 *ET-SAAS-015 v1.0.0 - Template SaaS*
--- a/docs/02-especificaciones/ET-SAAS-016-analytics.md
+++ b/docs/02-especificaciones/ET-SAAS-016-analytics.md
@ -0,0 +1,807 @@
 ---
 id: "ET-SAAS-016"
 title: "Especificacion Tecnica Analytics Dashboard"
 type: "TechnicalSpec"
 status: "Proposed"
 priority: "P2"
 module: "analytics"
 version: "1.0.0"
 created_date: "2026-01-24"
 updated_date: "2026-01-24"
 story_points: 8
 ---
 # ET-SAAS-016: Especificacion Tecnica - Analytics Dashboard
 ## Metadata
 - **Codigo:** ET-SAAS-016
 - **Modulo:** Analytics
 - **Version:** 1.0.0
 - **Estado:** Propuesto
 - **Fecha:** 2026-01-24
 - **Basado en:** Metabase patterns, SaaS analytics best practices
 ---
 ## 1. Resumen Ejecutivo
 ### 1.1 Estado Actual
 No existe modulo de analytics implementado. Los datos para metricas existen en:
 | Fuente | Datos Disponibles | Accesibilidad |
 |--------|-------------------|---------------|
 | users.users | Total usuarios, fechas creacion | Directa |
 | billing.subscriptions | MRR, planes activos | Directa |
 | billing.invoices | Revenue por periodo | Directa |
 | auth.sessions | Usuarios activos (login) | Indirecta |
 | audit.audit_logs | Acciones por usuario | Directa |
 | storage.files | Uso de storage | Directa |
 | ai.ai_usage | Tokens AI consumidos | Directa |
 ### 1.2 Propuesta v1.0
 Dashboard de analytics con:
 - **KPIs en tiempo real**: Usuarios, MRR, uso de recursos
 - **Tendencias temporales**: Graficos de 7d, 30d, 90d, 1y
 - **Breakdowns**: Por plan, por tenant, por recurso
 - **Cache inteligente**: Metricas pre-calculadas
 - **Superadmin view**: Metricas globales agregadas
 ---
 ## 2. Metricas Definidas
 ### 2.1 Metricas de Usuarios
 | ID | Metrica | Formula | Granularidad |
 |----|---------|---------|--------------|
 | U1 | total_users | COUNT(users) | Snapshot |
 | U2 | active_users_7d | Users con login en 7 dias | Rolling |
 | U3 | active_users_30d | Users con login en 30 dias | Rolling |
 | U4 | new_users | Users creados en periodo | Period |
 | U5 | churned_users | Users inactivos > 30 dias | Period |
 | U6 | churn_rate | churned / total * 100 | Period |
 | U7 | dau | Users activos hoy | Daily |
 | U8 | mau | Users activos 30d | Monthly |
 ### 2.2 Metricas de Billing
 | ID | Metrica | Formula | Granularidad |
 |----|---------|---------|--------------|
 | B1 | mrr | SUM(subscription.price) WHERE active | Snapshot |
 | B2 | arr | MRR * 12 | Calculated |
 | B3 | revenue_period | SUM(invoices.amount) WHERE paid | Period |
 | B4 | arpu | revenue / users | Period |
 | B5 | subscriptions_active | COUNT(active subs) | Snapshot |
 | B6 | subscriptions_new | Subs creadas en periodo | Period |
 | B7 | subscriptions_churned | Subs canceladas en periodo | Period |
 | B8 | ltv | ARPU * avg_lifetime | Calculated |
 ### 2.3 Metricas de Uso
 | ID | Metrica | Formula | Granularidad |
 |----|---------|---------|--------------|
 | R1 | api_calls | COUNT(requests) | Period |
 | R2 | api_calls_by_endpoint | GROUP BY endpoint | Period |
 | R3 | storage_used_gb | SUM(file_size) / 1GB | Snapshot |
 | R4 | storage_by_type | GROUP BY mime_type | Snapshot |
 | R5 | ai_tokens | SUM(tokens_used) | Period |
 | R6 | ai_tokens_by_model | GROUP BY model | Period |
 | R7 | notifications_sent | COUNT(sent) | Period |
 | R8 | webhooks_delivered | COUNT(delivered) | Period |
 ---
 ## 3. Arquitectura
 ### 3.1 Diagrama de Componentes
 ```
 +------------------+     +-------------------+     +------------------+
 |   Data Sources   |     | MetricsCalculator |     | MetricsCache     |
 |  (users, billing |---->| Service           |---->| (Redis/DB)       |
 |   audit, etc)    |     +-------------------+     +------------------+
 +------------------+              |                        |
                                  v                        v
                    +-------------------+     +-------------------+
                    | AnalyticsService  |<----| Scheduled Jobs    |
                    | (API layer)       |     | (hourly/daily)    |
                    +-------------------+     +-------------------+
                              |
                              v
                    +-------------------+
                    | AnalyticsController|
                    | (REST endpoints)  |
                    +-------------------+
                              |
                              v
                    +-------------------+
                    | Frontend Dashboard|
                    | (React + Recharts)|
                    +-------------------+
 ```
 ### 3.2 Estrategia de Cache
 | Tipo Metrica | Calculo | Cache TTL | Storage |
 |--------------|---------|-----------|---------|
 | Snapshots | Cada hora | 1 hora | Redis |
 | Daily | Medianoche | 24 horas | PostgreSQL |
 | Weekly | Domingo | 7 dias | PostgreSQL |
 | Monthly | Dia 1 | 30 dias | PostgreSQL |
 | Real-time | On-demand | 5 min | Redis |
 ---
 ## 4. Modelo de Datos
 ### 4.1 Schema: analytics
 ```sql
 -- Crear schema
 CREATE SCHEMA IF NOT EXISTS analytics;
 -- Enum para tipos de metrica
 CREATE TYPE analytics.metric_type AS ENUM (
    'users_total',
    'users_active',
    'users_new',
    'users_churned',
    'mrr',
    'arr',
    'revenue',
    'arpu',
    'subscriptions_active',
    'api_calls',
    'storage_used',
    'ai_tokens',
    'notifications',
    'webhooks'
 );
 -- Enum para periodos
 CREATE TYPE analytics.period_type AS ENUM (
    'hourly',
    'daily',
    'weekly',
    'monthly',
    'yearly'
 );
 ```
 ### 4.2 Tabla: metrics_cache
 ```sql
 CREATE TABLE analytics.metrics_cache (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID REFERENCES tenants.tenants(id) ON DELETE CASCADE,
    -- Metric identification
    metric_type analytics.metric_type NOT NULL,
    period_type analytics.period_type NOT NULL,
    period_start TIMESTAMPTZ NOT NULL,
    period_end TIMESTAMPTZ NOT NULL,
    -- Value
    value NUMERIC NOT NULL,
    metadata JSONB DEFAULT '{}',
    -- Timestamps
    calculated_at TIMESTAMPTZ DEFAULT NOW(),
    -- Constraints
    UNIQUE(tenant_id, metric_type, period_type, period_start)
 );
 -- Indexes
 CREATE INDEX idx_metrics_cache_tenant ON analytics.metrics_cache(tenant_id);
 CREATE INDEX idx_metrics_cache_type ON analytics.metrics_cache(metric_type);
 CREATE INDEX idx_metrics_cache_period ON analytics.metrics_cache(period_start DESC);
 -- RLS
 ALTER TABLE analytics.metrics_cache ENABLE ROW LEVEL SECURITY;
 CREATE POLICY metrics_cache_tenant_isolation ON analytics.metrics_cache
    USING (
        tenant_id = current_setting('app.current_tenant_id', true)::UUID
        OR current_setting('app.is_superadmin', true)::BOOLEAN = true
    );
 COMMENT ON TABLE analytics.metrics_cache IS 'Cache de metricas pre-calculadas por tenant';
 ```
 ### 4.3 Tabla: usage_events
 ```sql
 CREATE TABLE analytics.usage_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    user_id UUID,
    -- Event info
    event_type VARCHAR(50) NOT NULL,
    event_data JSONB DEFAULT '{}',
    -- Timestamps
    created_at TIMESTAMPTZ DEFAULT NOW()
 );
 -- Partitioning por mes
 CREATE INDEX idx_usage_events_tenant_type
 ON analytics.usage_events(tenant_id, event_type, created_at);
 -- Auto-purge eventos > 90 dias
 CREATE OR REPLACE FUNCTION analytics.purge_old_events()
 RETURNS void AS $$
 BEGIN
    DELETE FROM analytics.usage_events
    WHERE created_at < NOW() - INTERVAL '90 days';
 END;
 $$ LANGUAGE plpgsql;
 COMMENT ON TABLE analytics.usage_events IS 'Eventos de uso para tracking detallado';
 ```
 ---
 ## 5. Implementacion Backend
 ### 5.1 Estructura de Archivos
 ```
 backend/src/modules/analytics/
 ├── analytics.module.ts
 ├── controllers/
 │   └── analytics.controller.ts
 ├── services/
 │   ├── analytics.service.ts
 │   ├── metrics-calculator.service.ts
 │   └── metrics-cache.service.ts
 ├── entities/
 │   ├── metrics-cache.entity.ts
 │   └── usage-event.entity.ts
 ├── dto/
 │   ├── analytics-summary.dto.ts
 │   ├── user-metrics.dto.ts
 │   ├── billing-metrics.dto.ts
 │   └── usage-metrics.dto.ts
 └── jobs/
    ├── calculate-hourly-metrics.job.ts
    └── calculate-daily-metrics.job.ts
 ```
 ### 5.2 Service: MetricsCalculatorService
 ```typescript
@Injectable()
 export class MetricsCalculatorService {
  constructor(
    @InjectRepository(User) private usersRepo: Repository<User>,
    @InjectRepository(Subscription) private subsRepo: Repository<Subscription>,
    @InjectRepository(Invoice) private invoicesRepo: Repository<Invoice>,
    @InjectRepository(Session) private sessionsRepo: Repository<Session>,
    @InjectRepository(AuditLog) private auditRepo: Repository<AuditLog>,
    @InjectRepository(File) private filesRepo: Repository<File>,
    @InjectRepository(AiUsage) private aiUsageRepo: Repository<AiUsage>,
  ) {}
  async calculateUserMetrics(
    tenantId: string,
    startDate: Date,
    endDate: Date,
  ): Promise<UserMetrics> {
    const [
      totalUsers,
      activeUsers7d,
      activeUsers30d,
      newUsers,
    ] = await Promise.all([
      this.usersRepo.count({ where: { tenantId } }),
      this.getActiveUsers(tenantId, 7),
      this.getActiveUsers(tenantId, 30),
      this.usersRepo.count({
        where: {
          tenantId,
          createdAt: Between(startDate, endDate),
        },
      }),
    ]);
    const churnedUsers = await this.getChurnedUsers(tenantId, 30);
    const churnRate = totalUsers > 0 ? (churnedUsers / totalUsers) * 100 : 0;
    return {
      total: totalUsers,
      active7d: activeUsers7d,
      active30d: activeUsers30d,
      new: newUsers,
      churned: churnedUsers,
      churnRate: Math.round(churnRate * 100) / 100,
    };
  }
  async calculateBillingMetrics(
    tenantId: string,
    startDate: Date,
    endDate: Date,
  ): Promise<BillingMetrics> {
    const activeSubscriptions = await this.subsRepo.find({
      where: { tenantId, status: 'active' },
      relations: ['plan'],
    });
    const mrr = activeSubscriptions.reduce(
      (sum, sub) => sum + sub.plan.priceMonthly,
      0,
    );
    const revenue = await this.invoicesRepo
      .createQueryBuilder('i')
      .select('SUM(i.amount)', 'total')
      .where('i.tenant_id = :tenantId', { tenantId })
      .andWhere('i.status = :status', { status: 'paid' })
      .andWhere('i.paid_at BETWEEN :start AND :end', {
        start: startDate,
        end: endDate,
      })
      .getRawOne();
    const totalUsers = await this.usersRepo.count({ where: { tenantId } });
    const arpu = totalUsers > 0 ? revenue.total / totalUsers : 0;
    return {
      mrr,
      arr: mrr * 12,
      revenue: revenue.total || 0,
      arpu: Math.round(arpu * 100) / 100,
      subscriptionsActive: activeSubscriptions.length,
    };
  }
  async calculateUsageMetrics(
    tenantId: string,
    startDate: Date,
    endDate: Date,
  ): Promise<UsageMetrics> {
    const [storageUsed, aiTokens] = await Promise.all([
      this.filesRepo
        .createQueryBuilder('f')
        .select('SUM(f.size)', 'total')
        .where('f.tenant_id = :tenantId', { tenantId })
        .getRawOne(),
      this.aiUsageRepo
        .createQueryBuilder('a')
        .select('SUM(a.tokens_used)', 'total')
        .where('a.tenant_id = :tenantId', { tenantId })
        .andWhere('a.created_at BETWEEN :start AND :end', {
          start: startDate,
          end: endDate,
        })
        .getRawOne(),
    ]);
    return {
      storageUsedGb: Math.round((storageUsed.total || 0) / 1024 / 1024 / 1024 * 100) / 100,
      aiTokens: aiTokens.total || 0,
    };
  }
  private async getActiveUsers(tenantId: string, days: number): Promise<number> {
    const since = new Date();
    since.setDate(since.getDate() - days);
    return this.sessionsRepo
      .createQueryBuilder('s')
      .select('COUNT(DISTINCT s.user_id)', 'count')
      .where('s.tenant_id = :tenantId', { tenantId })
      .andWhere('s.created_at > :since', { since })
      .getRawOne()
      .then((r) => parseInt(r.count, 10));
  }
  private async getChurnedUsers(tenantId: string, inactiveDays: number): Promise<number> {
    const since = new Date();
    since.setDate(since.getDate() - inactiveDays);
    // Users with no session in last N days
    return this.usersRepo
      .createQueryBuilder('u')
      .where('u.tenant_id = :tenantId', { tenantId })
      .andWhere(
        `NOT EXISTS (
          SELECT 1 FROM auth.sessions s
          WHERE s.user_id = u.id AND s.created_at > :since
        )`,
        { since },
      )
      .getCount();
  }
 }
 ```
 ### 5.3 Service: AnalyticsService
 ```typescript
@Injectable()
 export class AnalyticsService {
  constructor(
    private readonly metricsCalculator: MetricsCalculatorService,
    private readonly metricsCache: MetricsCacheService,
  ) {}
  async getSummary(
    tenantId: string,
    period: '7d' | '30d' | '90d' | '1y',
  ): Promise<AnalyticsSummary> {
    const { startDate, endDate } = this.getPeriodDates(period);
    // Try cache first
    const cached = await this.metricsCache.get(tenantId, 'summary', period);
    if (cached && !this.isStale(cached)) {
      return cached.value;
    }
    // Calculate fresh
    const [users, billing, usage] = await Promise.all([
      this.metricsCalculator.calculateUserMetrics(tenantId, startDate, endDate),
      this.metricsCalculator.calculateBillingMetrics(tenantId, startDate, endDate),
      this.metricsCalculator.calculateUsageMetrics(tenantId, startDate, endDate),
    ]);
    // Calculate trends
    const previousPeriod = this.getPreviousPeriodDates(period);
    const [prevUsers, prevBilling] = await Promise.all([
      this.metricsCalculator.calculateUserMetrics(tenantId, previousPeriod.startDate, previousPeriod.endDate),
      this.metricsCalculator.calculateBillingMetrics(tenantId, previousPeriod.startDate, previousPeriod.endDate),
    ]);
    const trends = {
      usersGrowth: this.calculateGrowth(users.total, prevUsers.total),
      mrrGrowth: this.calculateGrowth(billing.mrr, prevBilling.mrr),
    };
    const summary = { period, users, billing, usage, trends };
    // Cache result
    await this.metricsCache.set(tenantId, 'summary', period, summary);
    return summary;
  }
  async getTimeseries(
    tenantId: string,
    metric: string,
    period: '7d' | '30d' | '90d' | '1y',
    granularity: 'daily' | 'weekly' | 'monthly',
  ): Promise<TimeseriesData[]> {
    const { startDate, endDate } = this.getPeriodDates(period);
    const intervals = this.generateIntervals(startDate, endDate, granularity);
    const data = await Promise.all(
      intervals.map(async (interval) => {
        const value = await this.getMetricForInterval(
          tenantId,
          metric,
          interval.start,
          interval.end,
        );
        return {
          date: interval.start.toISOString().split('T')[0],
          value,
        };
      }),
    );
    return data;
  }
  private getPeriodDates(period: string): { startDate: Date; endDate: Date } {
    const endDate = new Date();
    const startDate = new Date();
    switch (period) {
      case '7d':
        startDate.setDate(startDate.getDate() - 7);
        break;
      case '30d':
        startDate.setDate(startDate.getDate() - 30);
        break;
      case '90d':
        startDate.setDate(startDate.getDate() - 90);
        break;
      case '1y':
        startDate.setFullYear(startDate.getFullYear() - 1);
        break;
    }
    return { startDate, endDate };
  }
  private calculateGrowth(current: number, previous: number): number {
    if (previous === 0) return current > 0 ? 100 : 0;
    return Math.round(((current - previous) / previous) * 100 * 10) / 10;
  }
 }
 ```
 ### 5.4 Controller: AnalyticsController
 ```typescript
@Controller('analytics')
@ApiTags('Analytics')
@UseGuards(JwtAuthGuard)
 export class AnalyticsController {
  constructor(private readonly analyticsService: AnalyticsService) {}
  @Get('summary')
  @ApiOperation({ summary: 'Get analytics summary' })
  async getSummary(
    @GetTenant() tenantId: string,
    @Query('period') period: '7d' | '30d' | '90d' | '1y' = '30d',
  ): Promise<AnalyticsSummary> {
    return this.analyticsService.getSummary(tenantId, period);
  }
  @Get('users')
  @ApiOperation({ summary: 'Get user metrics' })
  async getUserMetrics(
    @GetTenant() tenantId: string,
    @Query('period') period: '7d' | '30d' | '90d' | '1y' = '30d',
    @Query('granularity') granularity: 'daily' | 'weekly' | 'monthly' = 'daily',
  ): Promise<UserMetricsResponse> {
    return this.analyticsService.getUserMetrics(tenantId, period, granularity);
  }
  @Get('billing')
  @ApiOperation({ summary: 'Get billing metrics' })
  async getBillingMetrics(
    @GetTenant() tenantId: string,
    @Query('period') period: '7d' | '30d' | '90d' | '1y' = '30d',
  ): Promise<BillingMetricsResponse> {
    return this.analyticsService.getBillingMetrics(tenantId, period);
  }
  @Get('usage')
  @ApiOperation({ summary: 'Get usage metrics' })
  async getUsageMetrics(
    @GetTenant() tenantId: string,
    @Query('period') period: '7d' | '30d' | '90d' | '1y' = '30d',
  ): Promise<UsageMetricsResponse> {
    return this.analyticsService.getUsageMetrics(tenantId, period);
  }
  @Get('trends')
  @ApiOperation({ summary: 'Get trends data' })
  async getTrends(
    @GetTenant() tenantId: string,
    @Query('metrics') metrics: string,
    @Query('period') period: '30d' | '90d' | '1y' = '30d',
  ): Promise<TrendsResponse> {
    const metricsList = metrics.split(',');
    return this.analyticsService.getTrends(tenantId, metricsList, period);
  }
  @Get('export')
  @ApiOperation({ summary: 'Export analytics data' })
  async exportData(
    @GetTenant() tenantId: string,
    @Query('period') period: '7d' | '30d' | '90d' | '1y' = '30d',
    @Query('format') format: 'json' | 'csv' = 'json',
    @Res() res: Response,
  ): Promise<void> {
    const data = await this.analyticsService.exportData(tenantId, period);
    if (format === 'csv') {
      res.setHeader('Content-Type', 'text/csv');
      res.setHeader('Content-Disposition', 'attachment; filename=analytics.csv');
      res.send(this.convertToCsv(data));
    } else {
      res.json(data);
    }
  }
 }
 ```
 ### 5.5 Scheduled Jobs
 ```typescript
@Injectable()
 export class CalculateMetricsJob {
  constructor(
    private readonly metricsCalculator: MetricsCalculatorService,
    private readonly metricsCache: MetricsCacheService,
    private readonly tenantsService: TenantsService,
  ) {}
  @Cron('0 * * * *') // Every hour
  async calculateHourlyMetrics(): Promise<void> {
    const tenants = await this.tenantsService.findAll();
    for (const tenant of tenants) {
      await this.calculateAndCacheMetrics(tenant.id, 'hourly');
    }
  }
  @Cron('0 0 * * *') // Every day at midnight
  async calculateDailyMetrics(): Promise<void> {
    const tenants = await this.tenantsService.findAll();
    for (const tenant of tenants) {
      await this.calculateAndCacheMetrics(tenant.id, 'daily');
    }
  }
  private async calculateAndCacheMetrics(
    tenantId: string,
    periodType: 'hourly' | 'daily',
  ): Promise<void> {
    const endDate = new Date();
    const startDate = new Date();
    if (periodType === 'hourly') {
      startDate.setHours(startDate.getHours() - 1);
    } else {
      startDate.setDate(startDate.getDate() - 1);
    }
    const metrics = await this.metricsCalculator.calculateAllMetrics(
      tenantId,
      startDate,
      endDate,
    );
    await this.metricsCache.store(tenantId, periodType, startDate, metrics);
  }
 }
 ```
 ---
 ## 6. Implementacion Frontend
 ### 6.1 Dashboard Component
 ```tsx
 export const AnalyticsDashboard: React.FC = () => {
  const [period, setPeriod] = useState<'7d' | '30d' | '90d' | '1y'>('30d');
  const { data: summary, isLoading } = useAnalyticsSummary(period);
  const { data: trends } = useAnalyticsTrends(['users', 'mrr'], period);
  if (isLoading) return <DashboardSkeleton />;
  return (
    <div className="space-y-6">
      {/* Period Selector */}
      <div className="flex justify-between items-center">
        <h1 className="text-2xl font-bold">Analytics</h1>
        <PeriodSelector value={period} onChange={setPeriod} />
      </div>
      {/* KPI Cards */}
      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
        <MetricCard
          title="Total Users"
          value={summary.users.total}
          change={summary.trends.usersGrowth}
          icon={<UsersIcon />}
        />
        <MetricCard
          title="MRR"
          value={formatCurrency(summary.billing.mrr)}
          change={summary.trends.mrrGrowth}
          icon={<DollarIcon />}
        />
        <MetricCard
          title="API Calls"
          value={formatNumber(summary.usage.apiCalls)}
          icon={<ApiIcon />}
        />
      </div>
      {/* Trend Chart */}
      <Card>
        <CardHeader>
          <CardTitle>Trends</CardTitle>
        </CardHeader>
        <CardContent>
          <TrendChart data={trends} height={300} />
        </CardContent>
      </Card>
      {/* Usage Breakdown */}
      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
        <UsageBreakdownCard
          title="Users by Plan"
          data={summary.users.byPlan}
        />
        <UsageBreakdownCard
          title="Storage by Type"
          data={summary.usage.storageByType}
        />
      </div>
    </div>
  );
 };
 ```
 ### 6.2 TrendChart Component
 ```tsx
 import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
 interface TrendChartProps {
  data: TimeseriesData[];
  height?: number;
 }
 export const TrendChart: React.FC<TrendChartProps> = ({ data, height = 300 }) => {
  return (
    <ResponsiveContainer width="100%" height={height}>
      <LineChart data={data}>
        <CartesianGrid strokeDasharray="3 3" />
        <XAxis dataKey="date" />
        <YAxis />
        <Tooltip />
        <Line
          type="monotone"
          dataKey="value"
          stroke="#3B82F6"
          strokeWidth={2}
          dot={false}
        />
      </LineChart>
    </ResponsiveContainer>
  );
 };
 ```
 ### 6.3 Hooks
 ```typescript
 export const useAnalyticsSummary = (period: string) => {
  return useQuery({
    queryKey: ['analytics', 'summary', period],
    queryFn: () => analyticsApi.getSummary(period),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
 };
 export const useAnalyticsTrends = (metrics: string[], period: string) => {
  return useQuery({
    queryKey: ['analytics', 'trends', metrics, period],
    queryFn: () => analyticsApi.getTrends(metrics.join(','), period),
    staleTime: 5 * 60 * 1000,
  });
 };
 ```
 ---
 ## 7. Criterios de Aceptacion
 - [ ] Dashboard muestra KPIs de usuarios, billing, uso
 - [ ] Selector de periodo funciona (7d, 30d, 90d, 1y)
 - [ ] Graficos de tendencias renderizan con Recharts
 - [ ] Cache de metricas reduce queries a BD
 - [ ] Jobs programados calculan metricas hourly/daily
 - [ ] Superadmin puede ver metricas globales
 - [ ] Exportacion de datos funciona (JSON, CSV)
 - [ ] Performance < 500ms para dashboard load
 - [ ] Tests unitarios con cobertura >70%
 ---
 ## 8. Riesgos y Mitigaciones
 | Riesgo | Probabilidad | Impacto | Mitigacion |
 |--------|--------------|---------|------------|
 | Queries lentas | Alta | Alto | Indexes + cache + jobs |
 | Cache stale | Media | Medio | TTLs cortos + invalidation |
 | Datos incorrectos | Baja | Alto | Tests + validacion cruzada |
 | Alto uso CPU | Media | Medio | Jobs en horarios off-peak |
 ---
 *ET-SAAS-016 v1.0.0 - Template SaaS*
--- a/docs/02-especificaciones/ET-SAAS-017-reports.md
+++ b/docs/02-especificaciones/ET-SAAS-017-reports.md
@ -0,0 +1,776 @@
 ---
 id: "ET-SAAS-017"
 title: "Especificacion Tecnica Reports Generation"
 type: "TechnicalSpec"
 status: "Proposed"
 priority: "P2"
 module: "reports"
 version: "1.0.0"
 created_date: "2026-01-24"
 updated_date: "2026-01-24"
 story_points: 5
 ---
 # ET-SAAS-017: Especificacion Tecnica - Sistema de Reportes
 ## Metadata
 - **Codigo:** ET-SAAS-017
 - **Modulo:** Reports
 - **Version:** 1.0.0
 - **Estado:** Propuesto
 - **Fecha:** 2026-01-24
 - **Basado en:** PDFKit, ExcelJS best practices
 ---
 ## 1. Resumen Ejecutivo
 ### 1.1 Estado Actual
 No existe sistema de reportes implementado.
 | Capacidad | Estado | Notas |
 |-----------|--------|-------|
 | Export PDF | NO | Sin implementacion |
 | Export Excel | NO | Sin implementacion |
 | Export CSV | NO | Sin implementacion |
 | Templates | NO | Sin templates definidos |
 | Email delivery | Parcial | Email module existe |
 ### 1.2 Propuesta v1.0
 Sistema de reportes con:
 - **3 Formatos**: PDF (formateado), Excel (tabular), CSV (crudo)
 - **6 Tipos de reporte**: Users, Billing, Invoices, Audit, Usage, Subscriptions
 - **Templates predefinidos**: Diseño profesional con branding
 - **Filtros avanzados**: Fecha, status, plan, usuario
 - **Delivery**: Descarga directa + envio por email
 ---
 ## 2. Tipos de Reportes
 ### 2.1 Catalogo de Reportes
 | ID | Nombre | Formatos | Descripcion |
 |----|--------|----------|-------------|
 | R01 | Users List | PDF, Excel, CSV | Lista completa de usuarios |
 | R02 | Active Users | PDF, Excel | Usuarios activos en periodo |
 | R03 | Billing Summary | PDF | Resumen de facturacion |
 | R04 | Invoices List | PDF, Excel | Facturas emitidas |
 | R05 | Audit Log | CSV | Log de auditoría |
 | R06 | Subscriptions | Excel | Estado de suscripciones |
 | R07 | Usage Report | Excel | Uso de recursos |
 | R08 | Revenue Report | PDF, Excel | Ingresos detallados |
 ### 2.2 Campos por Reporte
 **R01 - Users List**
 ```
 | Name | Email | Role | Plan | Status | Created | Last Login |
 ```
 **R03 - Billing Summary**
 ```
 Period: January 2026
 MRR: $45,000
 Revenue: $52,000
 New Subscriptions: 15
 Canceled: 3
 Top Plan: Pro (65%)
 ```
 **R05 - Audit Log**
 ```
 | Timestamp | User | Action | Resource | IP | Details |
 ```
 ---
 ## 3. Arquitectura
 ### 3.1 Diagrama de Componentes
 ```
 +------------------+     +-------------------+     +------------------+
 |   Frontend UI    |     | ReportsController |     | ReportsService   |
 |  Report Config   |---->| /reports/:type    |---->| (orchestration)  |
 +------------------+     +-------------------+     +------------------+
                                                          |
                         +--------------------------------+
                         |                |               |
                         v                v               v
               +-------------+  +-------------+  +-------------+
               | PdfGenerator|  |ExcelGenerator|  |CsvGenerator |
               | (PDFKit)    |  | (ExcelJS)   |  | (manual)    |
               +-------------+  +-------------+  +-------------+
                         |                |               |
                         v                v               v
               +---------------------------------------------------+
               |                    Response                        |
               |  - Stream (download) or Email (attachment)        |
               +---------------------------------------------------+
 ```
 ### 3.2 Flujo de Generacion
 ```
 1. Usuario configura reporte (tipo, filtros, formato)
   |
 2. Frontend POST /reports/generate
   |
 3. ReportsService.generate(config)
   |
 4. DataService.fetchData(type, filters)
   |
 5. Select generator by format:
   |-- PDF: PdfGeneratorService
   |-- Excel: ExcelGeneratorService
   |-- CSV: CsvGeneratorService
   |
 6. Generator produces file buffer
   |
 7. Response:
   |-- Download: Stream to client
   |-- Email: Queue email with attachment
   |
 8. AuditLog: Register report generation
 ```
 ---
 ## 4. Implementacion Backend
 ### 4.1 Estructura de Archivos
 ```
 backend/src/modules/reports/
 ├── reports.module.ts
 ├── controllers/
 │   └── reports.controller.ts
 ├── services/
 │   ├── reports.service.ts
 │   ├── pdf-generator.service.ts
 │   ├── excel-generator.service.ts
 │   └── csv-generator.service.ts
 ├── templates/
 │   ├── pdf/
 │   │   ├── users-report.template.ts
 │   │   ├── billing-summary.template.ts
 │   │   └── invoices-report.template.ts
 │   └── excel/
 │       ├── users-report.template.ts
 │       └── usage-report.template.ts
 └── dto/
    ├── generate-report.dto.ts
    └── report-config.dto.ts
 ```
 ### 4.2 DTOs
 ```typescript
 export class GenerateReportDto {
  @IsEnum(ReportType)
  type: ReportType;
  @IsEnum(ReportFormat)
  format: ReportFormat;
  @IsOptional()
  @IsDateString()
  startDate?: string;
  @IsOptional()
  @IsDateString()
  endDate?: string;
  @IsOptional()
  @IsObject()
  filters?: Record<string, any>;
 }
 export class SendReportEmailDto extends GenerateReportDto {
  @IsArray()
  @IsEmail({}, { each: true })
  recipients: string[];
  @IsOptional()
  @IsString()
  subject?: string;
  @IsOptional()
  @IsString()
  message?: string;
 }
 export enum ReportType {
  USERS = 'users',
  ACTIVE_USERS = 'active_users',
  BILLING_SUMMARY = 'billing_summary',
  INVOICES = 'invoices',
  AUDIT_LOG = 'audit_log',
  SUBSCRIPTIONS = 'subscriptions',
  USAGE = 'usage',
  REVENUE = 'revenue',
 }
 export enum ReportFormat {
  PDF = 'pdf',
  EXCEL = 'excel',
  CSV = 'csv',
 }
 ```
 ### 4.3 Service: ReportsService
 ```typescript
@Injectable()
 export class ReportsService {
  constructor(
    private readonly pdfGenerator: PdfGeneratorService,
    private readonly excelGenerator: ExcelGeneratorService,
    private readonly csvGenerator: CsvGeneratorService,
    private readonly dataService: ReportDataService,
    private readonly emailService: EmailService,
    private readonly auditService: AuditService,
  ) {}
  async generate(
    tenantId: string,
    userId: string,
    config: GenerateReportDto,
  ): Promise<ReportResult> {
    // 1. Validate limits
    await this.validateLimits(tenantId, config);
    // 2. Fetch data
    const data = await this.dataService.fetchData(tenantId, config);
    // 3. Generate report
    let buffer: Buffer;
    let mimeType: string;
    let extension: string;
    switch (config.format) {
      case ReportFormat.PDF:
        buffer = await this.pdfGenerator.generate(config.type, data);
        mimeType = 'application/pdf';
        extension = 'pdf';
        break;
      case ReportFormat.EXCEL:
        buffer = await this.excelGenerator.generate(config.type, data);
        mimeType = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
        extension = 'xlsx';
        break;
      case ReportFormat.CSV:
        buffer = await this.csvGenerator.generate(config.type, data);
        mimeType = 'text/csv';
        extension = 'csv';
        break;
    }
    // 4. Audit log
    await this.auditService.log({
      tenantId,
      userId,
      action: 'report_generated',
      resource: 'report',
      details: { type: config.type, format: config.format, rows: data.length },
    });
    const filename = this.generateFilename(config.type, extension);
    return { buffer, mimeType, filename };
  }
  async sendByEmail(
    tenantId: string,
    userId: string,
    config: SendReportEmailDto,
  ): Promise<void> {
    const report = await this.generate(tenantId, userId, config);
    await this.emailService.sendWithAttachment({
      to: config.recipients,
      subject: config.subject || `${config.type} Report`,
      body: config.message || 'Please find the attached report.',
      attachment: {
        filename: report.filename,
        content: report.buffer,
        contentType: report.mimeType,
      },
    });
    await this.auditService.log({
      tenantId,
      userId,
      action: 'report_emailed',
      resource: 'report',
      details: { type: config.type, recipients: config.recipients },
    });
  }
  private async validateLimits(
    tenantId: string,
    config: GenerateReportDto,
  ): Promise<void> {
    const count = await this.dataService.countRecords(tenantId, config);
    if (count > 10000) {
      throw new BadRequestException(
        `Report exceeds limit of 10,000 records (found ${count}). Please narrow your filters.`,
      );
    }
  }
  private generateFilename(type: string, extension: string): string {
    const date = new Date().toISOString().split('T')[0];
    return `${type}-report-${date}.${extension}`;
  }
 }
 ```
 ### 4.4 Service: PdfGeneratorService
 ```typescript
@Injectable()
 export class PdfGeneratorService {
  async generate(type: ReportType, data: any[]): Promise<Buffer> {
    return new Promise((resolve, reject) => {
      const doc = new PDFDocument({ margin: 50 });
      const chunks: Buffer[] = [];
      doc.on('data', (chunk) => chunks.push(chunk));
      doc.on('end', () => resolve(Buffer.concat(chunks)));
      doc.on('error', reject);
      // Header
      this.addHeader(doc, type);
      // Content based on type
      switch (type) {
        case ReportType.USERS:
          this.generateUsersReport(doc, data);
          break;
        case ReportType.BILLING_SUMMARY:
          this.generateBillingSummary(doc, data);
          break;
        case ReportType.INVOICES:
          this.generateInvoicesReport(doc, data);
          break;
        default:
          this.generateGenericTable(doc, data);
      }
      // Footer
      this.addFooter(doc);
      doc.end();
    });
  }
  private addHeader(doc: PDFKit.PDFDocument, type: ReportType): void {
    doc.fontSize(20).text(this.getTitle(type), { align: 'center' });
    doc.moveDown(0.5);
    doc.fontSize(10).fillColor('#666').text(`Generated: ${new Date().toLocaleString()}`, { align: 'center' });
    doc.moveDown(2);
    doc.fillColor('#000');
  }
  private generateUsersReport(doc: PDFKit.PDFDocument, users: any[]): void {
    // Summary
    doc.fontSize(14).text('Summary');
    doc.fontSize(12).text(`Total Users: ${users.length}`);
    doc.text(`Active: ${users.filter((u) => u.status === 'active').length}`);
    doc.moveDown(2);
    // Table
    const headers = ['Name', 'Email', 'Role', 'Plan', 'Status', 'Created'];
    const rows = users.map((u) => [
      u.name,
      u.email,
      u.role,
      u.plan,
      u.status,
      new Date(u.createdAt).toLocaleDateString(),
    ]);
    this.drawTable(doc, headers, rows);
  }
  private generateBillingSummary(doc: PDFKit.PDFDocument, data: any): void {
    doc.fontSize(14).text('Billing Summary');
    doc.moveDown();
    const metrics = [
      ['MRR', `$${data.mrr.toLocaleString()}`],
      ['ARR', `$${data.arr.toLocaleString()}`],
      ['Revenue (Period)', `$${data.revenue.toLocaleString()}`],
      ['Active Subscriptions', data.subscriptionsActive.toString()],
      ['New Subscriptions', data.subscriptionsNew.toString()],
      ['Churned', data.subscriptionsChurned.toString()],
    ];
    metrics.forEach(([label, value]) => {
      doc.fontSize(12).text(`${label}: `, { continued: true });
      doc.fontSize(12).fillColor('#3B82F6').text(value);
      doc.fillColor('#000');
    });
  }
  private drawTable(
    doc: PDFKit.PDFDocument,
    headers: string[],
    rows: string[][],
  ): void {
    const startX = 50;
    const startY = doc.y;
    const colWidth = (doc.page.width - 100) / headers.length;
    const rowHeight = 20;
    // Headers
    doc.font('Helvetica-Bold').fontSize(10);
    headers.forEach((header, i) => {
      doc.text(header, startX + i * colWidth, startY, { width: colWidth });
    });
    // Rows
    doc.font('Helvetica').fontSize(9);
    rows.forEach((row, rowIndex) => {
      const y = startY + (rowIndex + 1) * rowHeight;
      if (y > doc.page.height - 100) {
        doc.addPage();
      }
      row.forEach((cell, colIndex) => {
        doc.text(cell || '-', startX + colIndex * colWidth, y, {
          width: colWidth,
          ellipsis: true,
        });
      });
    });
  }
  private addFooter(doc: PDFKit.PDFDocument): void {
    const pages = doc.bufferedPageRange();
    for (let i = 0; i < pages.count; i++) {
      doc.switchToPage(i);
      doc.fontSize(8).fillColor('#999').text(
        `Page ${i + 1} of ${pages.count}`,
        50,
        doc.page.height - 50,
        { align: 'center' },
      );
    }
  }
  private getTitle(type: ReportType): string {
    const titles: Record<ReportType, string> = {
      [ReportType.USERS]: 'Users Report',
      [ReportType.ACTIVE_USERS]: 'Active Users Report',
      [ReportType.BILLING_SUMMARY]: 'Billing Summary',
      [ReportType.INVOICES]: 'Invoices Report',
      [ReportType.AUDIT_LOG]: 'Audit Log',
      [ReportType.SUBSCRIPTIONS]: 'Subscriptions Report',
      [ReportType.USAGE]: 'Usage Report',
      [ReportType.REVENUE]: 'Revenue Report',
    };
    return titles[type] || 'Report';
  }
 }
 ```
 ### 4.5 Service: ExcelGeneratorService
 ```typescript
@Injectable()
 export class ExcelGeneratorService {
  async generate(type: ReportType, data: any[]): Promise<Buffer> {
    const workbook = new ExcelJS.Workbook();
    workbook.creator = 'Template SaaS';
    workbook.created = new Date();
    const sheet = workbook.addWorksheet(this.getSheetName(type));
    switch (type) {
      case ReportType.USERS:
        this.generateUsersSheet(sheet, data);
        break;
      case ReportType.INVOICES:
        this.generateInvoicesSheet(sheet, data);
        break;
      case ReportType.USAGE:
        this.generateUsageSheet(sheet, data);
        break;
      default:
        this.generateGenericSheet(sheet, data);
    }
    return workbook.xlsx.writeBuffer() as Promise<Buffer>;
  }
  private generateUsersSheet(sheet: ExcelJS.Worksheet, users: any[]): void {
    sheet.columns = [
      { header: 'Name', key: 'name', width: 25 },
      { header: 'Email', key: 'email', width: 30 },
      { header: 'Role', key: 'role', width: 15 },
      { header: 'Plan', key: 'plan', width: 15 },
      { header: 'Status', key: 'status', width: 12 },
      { header: 'Created', key: 'createdAt', width: 15 },
      { header: 'Last Login', key: 'lastLoginAt', width: 15 },
    ];
    // Style header row
    sheet.getRow(1).font = { bold: true };
    sheet.getRow(1).fill = {
      type: 'pattern',
      pattern: 'solid',
      fgColor: { argb: 'FF3B82F6' },
    };
    sheet.getRow(1).font = { bold: true, color: { argb: 'FFFFFFFF' } };
    // Add data
    users.forEach((user) => {
      sheet.addRow({
        name: user.name,
        email: user.email,
        role: user.role,
        plan: user.plan,
        status: user.status,
        createdAt: new Date(user.createdAt),
        lastLoginAt: user.lastLoginAt ? new Date(user.lastLoginAt) : null,
      });
    });
    // Date formatting
    sheet.getColumn('createdAt').numFmt = 'yyyy-mm-dd';
    sheet.getColumn('lastLoginAt').numFmt = 'yyyy-mm-dd';
  }
  private generateUsageSheet(sheet: ExcelJS.Worksheet, data: any): void {
    sheet.columns = [
      { header: 'Resource', key: 'resource', width: 20 },
      { header: 'Usage', key: 'usage', width: 15 },
      { header: 'Unit', key: 'unit', width: 10 },
      { header: 'Limit', key: 'limit', width: 15 },
      { header: '% Used', key: 'percent', width: 10 },
    ];
    sheet.getRow(1).font = { bold: true };
    const resources = [
      { resource: 'API Calls', usage: data.apiCalls, unit: 'calls', limit: data.apiLimit },
      { resource: 'Storage', usage: data.storageGb, unit: 'GB', limit: data.storageLimit },
      { resource: 'AI Tokens', usage: data.aiTokens, unit: 'tokens', limit: data.aiLimit },
    ];
    resources.forEach((r) => {
      sheet.addRow({
        ...r,
        percent: r.limit > 0 ? Math.round((r.usage / r.limit) * 100) : 0,
      });
    });
  }
  private getSheetName(type: ReportType): string {
    return type.replace(/_/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase());
  }
 }
 ```
 ### 4.6 Controller: ReportsController
 ```typescript
@Controller('reports')
@ApiTags('Reports')
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin', 'owner')
 export class ReportsController {
  constructor(private readonly reportsService: ReportsService) {}
  @Post('generate')
  @ApiOperation({ summary: 'Generate and download report' })
  async generateReport(
    @GetTenant() tenantId: string,
    @GetUser() user: User,
    @Body() dto: GenerateReportDto,
    @Res() res: Response,
  ): Promise<void> {
    const report = await this.reportsService.generate(tenantId, user.id, dto);
    res.setHeader('Content-Type', report.mimeType);
    res.setHeader('Content-Disposition', `attachment; filename="${report.filename}"`);
    res.send(report.buffer);
  }
  @Post('send-email')
  @ApiOperation({ summary: 'Generate and send report by email' })
  async sendReportByEmail(
    @GetTenant() tenantId: string,
    @GetUser() user: User,
    @Body() dto: SendReportEmailDto,
  ): Promise<{ message: string }> {
    await this.reportsService.sendByEmail(tenantId, user.id, dto);
    return { message: 'Report sent successfully' };
  }
  @Get('types')
  @ApiOperation({ summary: 'Get available report types' })
  getReportTypes(): ReportTypeInfo[] {
    return [
      { type: 'users', name: 'Users List', formats: ['pdf', 'excel', 'csv'] },
      { type: 'active_users', name: 'Active Users', formats: ['pdf', 'excel'] },
      { type: 'billing_summary', name: 'Billing Summary', formats: ['pdf'] },
      { type: 'invoices', name: 'Invoices', formats: ['pdf', 'excel'] },
      { type: 'audit_log', name: 'Audit Log', formats: ['csv'] },
      { type: 'subscriptions', name: 'Subscriptions', formats: ['excel'] },
      { type: 'usage', name: 'Usage Report', formats: ['excel'] },
      { type: 'revenue', name: 'Revenue Report', formats: ['pdf', 'excel'] },
    ];
  }
 }
 ```
 ---
 ## 5. Implementacion Frontend
 ### 5.1 ReportGenerator Component
 ```tsx
 export const ReportGenerator: React.FC = () => {
  const [reportType, setReportType] = useState<string>('users');
  const [format, setFormat] = useState<string>('pdf');
  const [dateRange, setDateRange] = useState<DateRange>({
    start: subDays(new Date(), 30),
    end: new Date(),
  });
  const [isLoading, setIsLoading] = useState(false);
  const [showEmailModal, setShowEmailModal] = useState(false);
  const { data: reportTypes } = useReportTypes();
  const handleDownload = async () => {
    setIsLoading(true);
    try {
      const blob = await reportsApi.generate({
        type: reportType,
        format,
        startDate: dateRange.start.toISOString(),
        endDate: dateRange.end.toISOString(),
      });
      downloadBlob(blob, `${reportType}-report.${format === 'excel' ? 'xlsx' : format}`);
      toast.success('Report downloaded');
    } catch (error) {
      toast.error('Failed to generate report');
    } finally {
      setIsLoading(false);
    }
  };
  return (
    <div className="space-y-6">
      <h1 className="text-2xl font-bold">Generate Report</h1>
      <Card>
        <CardContent className="space-y-4 pt-6">
          {/* Report Type */}
          <div>
            <Label>Report Type</Label>
            <Select value={reportType} onValueChange={setReportType}>
              <SelectTrigger>
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                {reportTypes?.map((rt) => (
                  <SelectItem key={rt.type} value={rt.type}>
                    {rt.name}
                  </SelectItem>
                ))}
              </SelectContent>
            </Select>
          </div>
          {/* Format */}
          <div>
            <Label>Format</Label>
            <Select value={format} onValueChange={setFormat}>
              <SelectTrigger>
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                {reportTypes
                  ?.find((rt) => rt.type === reportType)
                  ?.formats.map((f) => (
                    <SelectItem key={f} value={f}>
                      {f.toUpperCase()}
                    </SelectItem>
                  ))}
              </SelectContent>
            </Select>
          </div>
          {/* Date Range */}
          <div>
            <Label>Date Range</Label>
            <DateRangePicker value={dateRange} onChange={setDateRange} />
          </div>
          {/* Actions */}
          <div className="flex gap-2 pt-4">
            <Button onClick={handleDownload} disabled={isLoading}>
              {isLoading ? <Spinner /> : <DownloadIcon />}
              Download
            </Button>
            <Button variant="outline" onClick={() => setShowEmailModal(true)}>
              <MailIcon />
              Send by Email
            </Button>
          </div>
        </CardContent>
      </Card>
      <ReportEmailModal
        open={showEmailModal}
        onClose={() => setShowEmailModal(false)}
        reportConfig={{ type: reportType, format, dateRange }}
      />
    </div>
  );
 };
 ```
 ---
 ## 6. Criterios de Aceptacion
 - [ ] Generar PDF de usuarios con formato profesional
 - [ ] Generar Excel de usuarios con datos tabulares
 - [ ] Generar CSV de audit log
 - [ ] Filtros por fecha funcionan correctamente
 - [ ] Limite de 10,000 registros se respeta
 - [ ] Envio por email funciona con adjunto
 - [ ] Solo admins pueden generar reportes
 - [ ] Cada generacion se registra en audit log
 - [ ] Performance < 5s para reportes de 5000 registros
 - [ ] Tests unitarios con cobertura >70%
 ---
 ## 7. Dependencias
 ### NPM Packages
 ```json
 {
  "pdfkit": "^0.15.0",
  "exceljs": "^4.4.0"
 }
 ```
 ---
 *ET-SAAS-017 v1.0.0 - Template SaaS*