Saltar a contenido

[NOMBRE DEL COMPONENTE/FUNCIONALIDAD]

Fecha de creación: YYYY-MM-DD Última actualización: YYYY-MM-DD Versión: 1.0.0 Autor: [Nombre del autor] Estado: Borrador | En revisión | Aprobado | Publicado

Índice de Perspectivas

Perspectiva Audiencia Ir a sección
Negocio Product Owners, Stakeholders Ver
Agentes IA Prompt Engineers, Configuradores Ver
Programación Desarrolladores Backend/Frontend Ver
Tecnologías DevOps, SREs, Infraestructura Ver
Usuario Final Usuarios de la plataforma Ver

1. Perspectiva de Negocio

Audiencia: Product Owners, Stakeholders, C-Level, Ventas Propósito: Entender el valor de negocio, ROI y casos de uso

1.1 Resumen Ejecutivo

¿Qué es? [Descripción breve y no técnica del componente]

¿Qué problema resuelve? [Problema de negocio que soluciona]

¿Cuál es el valor agregado? [Beneficio principal para el negocio/cliente]

1.2 Propuesta de Valor

Aspecto Descripción
Problema [Problema que resuelve]
Solución [Cómo lo resuelve]
Beneficio [Resultado medible]
Diferenciador [Por qué es mejor que alternativas]

1.3 Casos de Uso de Negocio

Caso de Uso 1: [Nombre]

  • Actor: [Rol del usuario]
  • Escenario: [Descripción del escenario]
  • Resultado esperado: [Qué obtiene el usuario]
  • Valor generado: [Beneficio cuantificable]

Caso de Uso 2: [Nombre]

  • Actor: [Rol del usuario]
  • Escenario: [Descripción del escenario]
  • Resultado esperado: [Qué obtiene el usuario]
  • Valor generado: [Beneficio cuantificable]

1.4 Métricas e Indicadores (KPIs)

Métrica Descripción Objetivo Actual
[Nombre KPI 1] [Qué mide] [Meta] [Valor actual]
[Nombre KPI 2] [Qué mide] [Meta] [Valor actual]
[Nombre KPI 3] [Qué mide] [Meta] [Valor actual]

1.5 ROI Estimado

Concepto Antes Después Ahorro/Ganancia
Tiempo por tarea X horas Y horas Z% reducción
Costo operativo $X/mes $Y/mes $Z ahorro
Errores/Incidentes X/mes Y/mes Z% reducción

1.6 Roadmap de Negocio

gantt
    title Roadmap del Componente
    dateFormat  YYYY-MM-DD
    section Fase 1
    MVP                 :done,    des1, 2024-01-01, 30d
    section Fase 2
    Mejoras             :active,  des2, after des1, 30d
    section Fase 3
    Optimización        :         des3, after des2, 30d

1.7 Dependencias de Negocio

  • [ ] [Dependencia 1 - ej: Aprobación de presupuesto]
  • [ ] [Dependencia 2 - ej: Contrato con proveedor X]
  • [ ] [Dependencia 3 - ej: Capacitación del equipo]

2. Perspectiva de Agentes IA

Audiencia: Prompt Engineers, Configuradores de IA, Arquitectos de Agentes Propósito: Especificar comportamiento, skills y configuración de agentes IA

2.1 Descripción del Agente

Campo Valor
Nombre [Nombre del agente]
Slug [slug-del-agente]
Propósito [Para qué sirve]
Modelo base Claude Sonnet 4 / Claude Haiku / GPT-4o
Temperatura 0.0 - 1.0
Max tokens [Límite de tokens]

2.2 System Prompt

# Identidad
Eres [nombre del agente], un asistente especializado en [dominio].

# Contexto
[Contexto del proyecto/organización]

# Capacidades
- [Capacidad 1]
- [Capacidad 2]
- [Capacidad 3]

# Restricciones
- NO [restricción 1]
- NO [restricción 2]
- SIEMPRE [regla obligatoria]

# Formato de respuesta
[Cómo debe estructurar las respuestas]

2.3 Skills y Capacidades

Skill 1: [Nombre del Skill]

Campo Valor
Trigger [Palabras clave que lo activan]
Descripción [Qué hace este skill]
Input esperado [Qué necesita recibir]
Output generado [Qué produce] 
# Ejemplo de configuración
skill:
  name: "[nombre]"
  trigger_words: ["palabra1", "palabra2"]
  required_context: ["variable1", "variable2"]
  output_format: "markdown|json|text"

Skill 2: [Nombre del Skill]

Campo Valor
Trigger [Palabras clave que lo activan]
Descripción [Qué hace este skill]
Input esperado [Qué necesita recibir]
Output generado [Qué produce]

2.4 Herramientas MCP Disponibles

Herramienta Descripción Permisos
mcp_tool_1 [Qué hace] read/write
mcp_tool_2 [Qué hace] read-only
mcp_tool_3 [Qué hace] admin

2.5 Flujos de Conversación

flowchart TD
    A[Usuario envía mensaje] --> B{¿Tiene contexto?}
    B -->|Sí| C[Procesar con contexto]
    B -->|No| D[Solicitar contexto]
    C --> E[Generar respuesta]
    D --> A
    E --> F{¿Necesita acción?}
    F -->|Sí| G[Ejecutar herramienta MCP]
    F -->|No| H[Mostrar respuesta]
    G --> H

2.6 Ejemplos de Interacción

Ejemplo 1: [Escenario]

Usuario: 

[Mensaje del usuario]

Agente: 

[Respuesta esperada del agente]

Ejemplo 2: [Escenario]

Usuario: 

[Mensaje del usuario]

Agente: 

[Respuesta esperada del agente]

2.7 Métricas del Agente

Métrica Descripción Target
Latencia promedio Tiempo de respuesta < 2s
Tasa de éxito Respuestas satisfactorias > 95%
Tokens promedio Consumo por interacción < 2000
Escalaciones Casos que requieren humano < 5%

2.8 Configuración de Memorias

memories:
  - type: "project_preference"
    content: "[Preferencia del proyecto]"
    scope: "project"
  - type: "user_preference"
    content: "[Preferencia del usuario]"
    scope: "user"

3. Perspectiva de Programación

Audiencia: Desarrolladores Backend, Frontend, Full-Stack Propósito: Documentación técnica de código, APIs, servicios

3.1 Arquitectura del Componente

graph TB
    subgraph "Frontend (Blazor)"
        A[Componente.razor]
        B[Servicio.cs]
    end

    subgraph "Backend (API)"
        C[Controller]
        D[Service]
        E[Repository]
    end

    subgraph "Data"
        F[(PostgreSQL)]
        G[(Redis Cache)]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    D --> G

3.2 Estructura de Archivos

📁 Componente/
├── 📁 Controllers/
│   └── ComponenteController.cs
├── 📁 Services/
│   ├── IComponenteService.cs
│   └── ComponenteService.cs
├── 📁 Repositories/
│   ├── IComponenteRepository.cs
│   └── ComponenteRepository.cs
├── 📁 Dtos/
│   ├── ComponenteCreateDto.cs
│   ├── ComponenteUpdateDto.cs
│   └── ComponenteResponseDto.cs
├── 📁 Entities/
│   └── Componente.cs
└── 📁 Tests/
    ├── ComponenteServiceTests.cs
    └── ComponenteControllerTests.cs

3.3 Entidades y Modelos

Entidad Principal

public class [NombreEntidad]
{
    public Guid Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }

    // Relaciones
    public Guid OrganizationId { get; set; }
    public Organization? Organization { get; set; }
}

DTOs

// Request DTO
public record [Nombre]CreateDto(
    string Name,
    string Description,
    Dictionary<string, object>? Metadata
);

// Response DTO
public record [Nombre]ResponseDto(
    Guid Id,
    string Name,
    string Description,
    DateTime CreatedAt
);

3.4 Servicios

Interface

public interface I[Nombre]Service
{
    Task<[Nombre]ResponseDto> GetByIdAsync(Guid id);
    Task<IEnumerable<[Nombre]ResponseDto>> GetAllAsync(int page, int pageSize);
    Task<[Nombre]ResponseDto> CreateAsync([Nombre]CreateDto dto);
    Task<[Nombre]ResponseDto> UpdateAsync(Guid id, [Nombre]UpdateDto dto);
    Task<bool> DeleteAsync(Guid id);
}

Implementación

public class [Nombre]Service : I[Nombre]Service
{
    private readonly I[Nombre]Repository _repository;
    private readonly ILogger<[Nombre]Service> _logger;

    public [Nombre]Service(
        I[Nombre]Repository repository,
        ILogger<[Nombre]Service> logger)
    {
        _repository = repository;
        _logger = logger;
    }

    public async Task<[Nombre]ResponseDto> GetByIdAsync(Guid id)
    {
        var entity = await _repository.GetByIdAsync(id)
            ?? throw new NotFoundException($"[Nombre] {id} not found");

        return MapToDto(entity);
    }

    // ... más métodos
}

3.5 API Endpoints

Método Endpoint Descripción Auth
GET /api/v1/[nombre] Lista todos Bearer
GET /api/v1/[nombre]/{id} Obtiene uno Bearer
POST /api/v1/[nombre] Crea nuevo Bearer
PUT /api/v1/[nombre]/{id} Actualiza Bearer
DELETE /api/v1/[nombre]/{id} Elimina Bearer + Admin

Ejemplo de Request/Response

POST /api/v1/[nombre]

Request: 

{
  "name": "Ejemplo",
  "description": "Descripción del ejemplo",
  "metadata": {
    "key": "value"
  }
}

Response (201 Created): 

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Ejemplo",
  "description": "Descripción del ejemplo",
  "createdAt": "2024-01-15T10:30:00Z"
}

3.6 Validaciones

public class [Nombre]CreateDtoValidator : AbstractValidator<[Nombre]CreateDto>
{
    public [Nombre]CreateDtoValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty().WithMessage("Name is required")
            .MaximumLength(100).WithMessage("Name max 100 characters");

        RuleFor(x => x.Description)
            .MaximumLength(500);
    }
}

3.7 Manejo de Errores

Código Significado Cuándo ocurre
400 Bad Request Validación fallida
401 Unauthorized Token inválido/expirado
403 Forbidden Sin permisos
404 Not Found Recurso no existe
409 Conflict Duplicado
500 Server Error Error interno

3.8 Tests

Unit Test Example

[Fact]
public async Task GetByIdAsync_WhenExists_ReturnsDto()
{
    // Arrange
    var id = Guid.NewGuid();
    var entity = new [Nombre] { Id = id, Name = "Test" };
    _repositoryMock.Setup(r => r.GetByIdAsync(id))
        .ReturnsAsync(entity);

    // Act
    var result = await _service.GetByIdAsync(id);

    // Assert
    result.Should().NotBeNull();
    result.Id.Should().Be(id);
    result.Name.Should().Be("Test");
}

3.9 Dependencias de Código

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="FluentValidation" Version="11.9.0" />
<PackageReference Include="Serilog" Version="3.1.1" />

4. Perspectiva de Tecnologías

Audiencia: DevOps, SREs, Administradores de Infraestructura Propósito: Configuración, deployment, monitoreo y operaciones

4.1 Stack Tecnológico

Capa Tecnología Versión
Runtime .NET 9.0
Framework ASP.NET Core 9.0
Frontend Blazor Server 9.0
Database PostgreSQL 16+
Cache Redis 7.0+
Mensajería RabbitMQ 3.12+
Contenedor Docker 24+
Orquestación Docker Compose / K8s -

4.2 Variables de Entorno

Variable Descripción Requerida Ejemplo
ConnectionStrings__NexusDb PostgreSQL connection Sí Host=localhost;...
ANTHROPIC_API_KEY API key de Claude Sí sk-ant-...
REDIS_CONNECTION Redis connection string No localhost:6379
RABBITMQ_HOST Host de RabbitMQ No localhost
SENTRY_DSN DSN de Sentry No https://...@sentry.io/...

4.3 Docker Configuration

Dockerfile

FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY ["Project.csproj", "."]
RUN dotnet restore
COPY . .
RUN dotnet build -c Release -o /app/build

FROM build AS publish
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "Project.dll"]

Docker Compose

version: '3.8'
services:
  api:
    build: ./Orchestrator/src/Orchestrator.Api
    ports:
      - "5000:80"
    environment:
      - ConnectionStrings__NexusDb=${NEXUS_DB_CONNECTION}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: nexus
      POSTGRES_USER: nexus
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

4.4 Health Checks

Endpoint Descripción Intervalo
/health Health general 30s
/health/ready Readiness (DB, Cache) 10s
/health/live Liveness 5s

Configuración

builder.Services.AddHealthChecks()
    .AddNpgSql(connectionString, name: "postgres")
    .AddRedis(redisConnection, name: "redis")
    .AddRabbitMQ(rabbitConnection, name: "rabbitmq");

4.5 Logging y Monitoreo

Configuración de Serilog

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "PostgreSQL",
        "Args": {
          "connectionString": "...",
          "tableName": "Logs"
        }
      }
    ]
  }
}

Métricas Prometheus

Métrica Tipo Descripción
http_requests_total Counter Total de requests HTTP
http_request_duration_seconds Histogram Latencia de requests
active_sessions Gauge Sesiones activas
ai_tokens_used_total Counter Tokens de IA consumidos

4.6 Alertas

Alerta Condición Severidad Acción
HighErrorRate error_rate > 5% por 5min Critical PagerDuty
HighLatency p99 > 2s por 10min Warning Slack
DatabaseDown health_check failed Critical PagerDuty
LowDiskSpace disk_usage > 80% Warning Slack

4.7 Runbook de Operaciones

Despliegue

# 1. Pull última imagen
docker pull registry.example.com/calmia-nexus:latest

# 2. Aplicar migraciones
dotnet ef database update --project Orchestrator.Api

# 3. Desplegar
docker-compose up -d

# 4. Verificar health
curl http://localhost:5000/health

Rollback

# 1. Identificar versión anterior
docker images | grep calmia-nexus

# 2. Cambiar a versión anterior
docker-compose down
docker tag registry.example.com/calmia-nexus:v1.2.3 calmia-nexus:latest
docker-compose up -d

# 3. Verificar
curl http://localhost:5000/health

Troubleshooting Común

Síntoma Causa probable Solución
502 Bad Gateway API no responde Reiniciar contenedor API
Timeout en DB Conexiones agotadas Verificar pool, reiniciar
Alto uso de memoria Memory leak Reiniciar, revisar logs
Errores de auth Token expirado Regenerar tokens

4.8 Backups

Recurso Frecuencia Retención Destino
PostgreSQL Diario 2am 30 días S3
Redis Cada 6h 7 días S3
Logs Streaming 90 días CloudWatch 
# Backup manual de PostgreSQL
pg_dump -h localhost -U nexus -d nexus > backup_$(date +%Y%m%d).sql

# Restaurar
psql -h localhost -U nexus -d nexus < backup_20240115.sql

4.9 Escalado

Componente Tipo de escalado Trigger
API Horizontal (replicas) CPU > 70%
Workers Horizontal (replicas) Queue depth > 100
PostgreSQL Vertical Conexiones > 80%
Redis Cluster (sharding) Memory > 70%

5. Perspectiva de Usuario Final

Audiencia: Usuarios de la plataforma, clientes Propósito: Guías de uso, tutoriales, FAQs para wiki.kalmiazen.com

5.1 Introducción

¿Qué es [Nombre del Componente]?

[Descripción simple y amigable de qué es y para qué sirve, sin jerga técnica]

¿Para quién es?

  • [Rol 1]: [Cómo les ayuda]
  • [Rol 2]: [Cómo les ayuda]
  • [Rol 3]: [Cómo les ayuda]

5.2 Primeros Pasos

Requisitos Previos

  • [ ] Cuenta activa en Calmia Nexus
  • [ ] Acceso al módulo [nombre]
  • [ ] [Otro requisito]

Acceder al Componente

  1. Inicia sesión en [URL de la aplicación]
  2. En el menú lateral, haz clic en [Nombre del módulo]
  3. Selecciona [Opción específica]

5.3 Guía Paso a Paso

Crear un nuevo [elemento]

Paso 1: Hacer clic en el botón "+ Nuevo"

Paso 2: Completar el formulario

Campo Descripción Ejemplo
Nombre Nombre descriptivo "Mi primer elemento"
Descripción Detalle opcional "Descripción del elemento"
Categoría Clasificación "General"

Paso 3: Guardar los cambios

Haz clic en Guardar para crear el elemento.

Listo!

Tu elemento ha sido creado exitosamente.

Editar un [elemento] existente

  1. Localiza el elemento en la lista
  2. Haz clic en el icono de lápiz (editar)
  3. Modifica los campos necesarios
  4. Haz clic en Guardar cambios

Eliminar un [elemento]

Atención

Esta acción no se puede deshacer.

  1. Localiza el elemento en la lista
  2. Haz clic en el icono de papelera (eliminar)
  3. Confirma la acción en el diálogo

5.4 Funcionalidades Avanzadas

[Funcionalidad 1]

[Descripción de la funcionalidad avanzada]

Cómo usarla:

  1. [Paso 1]
  2. [Paso 2]
  3. [Paso 3]

Consejo

[Consejo útil para aprovechar mejor esta funcionalidad]

[Funcionalidad 2]

[Descripción de la funcionalidad avanzada]

5.5 Atajos de Teclado

Atajo Acción
Ctrl + N Crear nuevo
Ctrl + S Guardar
Ctrl + F Buscar
Esc Cerrar diálogo
? Mostrar ayuda

5.6 Preguntas Frecuentes (FAQ)

¿Cómo puedo [pregunta común 1]?

[Respuesta detallada a la pregunta]

¿Por qué [pregunta común 2]?

[Respuesta detallada a la pregunta]

¿Es posible [pregunta común 3]?

[Respuesta detallada a la pregunta]

¿Qué hago si [problema común]?

[Pasos para resolver el problema]

5.7 Solución de Problemas

El componente no carga

Posibles causas: - Conexión a internet inestable - Sesión expirada - Permisos insuficientes

Solución: 1. Verifica tu conexión a internet 2. Refresca la página (F5) 3. Si persiste, cierra sesión y vuelve a iniciar 4. Contacta a soporte si el problema continúa

Los cambios no se guardan

Posibles causas: - Campos obligatorios vacíos - Error de validación - Problema temporal del servidor

Solución: 1. Revisa que todos los campos requeridos estén completos 2. Verifica los mensajes de error en pantalla 3. Espera unos segundos e intenta nuevamente

5.8 Contacto y Soporte

Canal Uso Disponibilidad
Chat en app Preguntas rápidas 24/7
Email soporte@kalmiazen.com 24-48h respuesta
Wiki wiki.kalmiazen.com Autoservicio
Teléfono Urgencias Lun-Vie 9-18h

Apéndice A: Glosario

Término Definición
[Término 1] [Definición]
[Término 2] [Definición]
[Término 3] [Definición]

Apéndice B: Historial de Cambios

Versión Fecha Autor Cambios
1.0.0 YYYY-MM-DD [Autor] Versión inicial
1.1.0 YYYY-MM-DD [Autor] [Descripción del cambio]

Documento generado con: Calmia Nexus Documentation Generator Plantilla versión: 1.0.0 Compatible con: MkDocs Material Theme