Saltar a contenido

EF Core Entity Model Analysis

Fecha: 2026-03-09 Workspace analizado: C:\inetpub\wiki.kalmiazen.com Estado de verificación: parcial

Alcance

Este repositorio no contiene el código fuente .cs de la plataforma ni el DbContext real. El análisis se reconstruyó a partir de documentación técnica y reportes internos presentes en la wiki.

Fuentes principales:

  • docs/nexus/desarrollo/CALMIA-NEXUS-DEVELOPER-GUIDE.md
  • docs/nexus/features/AUDITORIA-IMPLEMENTACION-WORKSPACE.md
  • docs/nexus/agentes/CALMIA-NEXUS-AGENT-SPECIFICATION.md
  • docs/nexus/features/IDEAS-CURSOR-AI.md
  • docs/nexus/features/AUDITORIA-PROBLEMAS-A-REVISAR.md
  • schema-analysis-temp.json

Limitación crítica

No fue posible escanear clases EF Core reales porque en este workspace no existen archivos .cs, .csproj o .sln. Por tanto:

  • Lo marcado como Verificado proviene de snippets o tablas explícitas en la documentación.
  • Lo marcado como Verificado por esquema proviene de schema-analysis-temp.json, que refleja la base PostgreSQL actual.
  • Lo marcado como Inferido proviene de diagramas, descripciones o referencias indirectas.
  • La lista completa de 64+ DbSets no puede reconstruirse con precisión desde este repo.

DbContext identificado

NexusDbContext

Verificado en docs/nexus/desarrollo/CALMIA-NEXUS-DEVELOPER-GUIDE.md.

DbSets documentados explícitamente:

  • Organization
  • Project
  • User
  • DevSession
  • DevSessionMessage
  • CopilotExecution
  • CopilotStep
  • BacklogItem
  • ScheduledTask
  • Execution
  • Agent
  • RemoteAgent

La documentación indica que existen 64+ DbSets, pero solo estos 12 aparecen de forma explícita.

DbSets adicionales corroborados indirectamente por el esquema actual:

  • UserMemory
  • DocumentContextLink
  • ClickUpConfig
  • ProjectSecret
  • CommunicationChannel
  • CopilotBatchExecution
  • AgentSkill
  • AgentTrigger

OnModelCreating documentado

Configuraciones Verificadas:

  • Índice único en Organization.Slug
  • Índice único en Project.Slug
  • Índice compuesto en BacklogItem(ProjectId, Status)
  • Índice compuesto en DevSession(UserId, Status)
  • Índice compuesto en Execution(ProjectId, Status)
  • CopilotExecution.ArtifactsJson mapeado como jsonb
  • BacklogItem.MetadataJson mapeado como jsonb
  • Relación DevSession 1-N DevSessionMessage con Cascade
  • Relación CopilotExecution 1-N CopilotStep con Cascade

Configuraciones Verificadas por esquema:

  • Organization.Id usa gen_random_uuid()
  • Organization.CreatedAt y UpdatedAt tienen default SQL
  • Project.Slug tiene índice único IX_Projects_Slug
  • User.Email tiene unicidad física Users_Email_key
  • AgentSkill tiene PK compuesta (AgentId, Skill)
  • CopilotStep tiene unicidad por (ExecutionId, Order)
  • ClickUpConfig.ProjectId tiene unicidad UQ_ClickUpConfigs_ProjectId
  • ProjectSecret tiene unicidad (ProjectId, Key)
  • CopilotExecution.ArtifactsJson y WarningsJson son jsonb
  • RemoteAgent.CapabilitiesJson y ConfigJson son jsonb
  • Project.TechStack, Project.Tags, ClickUpConfig.StatusMappingJson, User.WorkspaceState son jsonb

Configuraciones Inferidas pero no verificables en código:

  • Mapeo jsonb adicional para Project.SentryConfigJson
  • Mapeos para WarningsJson, CapabilitiesJson, SystemInfo
  • Configuración de claves compuestas para AgentSkill
  • Configuración de tablas auxiliares como DocumentContextLink, ProjectSecret, CommunicationChannel

Entidades verificadas con propiedades explícitas

Organization

Estado: Verificado

Propiedades:

  • Id : Guid
  • Slug : string unique
  • Name : string
  • Description : string?
  • LogoUrl : string?
  • ThemeId : string?
  • PrimaryColor : string?
  • IsActive : bool
  • CreatedAt : DateTime
  • UpdatedAt : DateTime?

Navegación:

  • Projects : List<Project>
  • CommunicationChannels : List<CommunicationChannel>

Relaciones:

  • 1-N con Project Verificado por snippet y diagrama
  • 1-N con CommunicationChannel Inferido

Project

Estado: Verificado

Propiedades:

  • Id : Guid
  • Slug : string unique
  • Name : string
  • Description : string?
  • RepoPath : string?
  • Instructions : string?
  • SentryConfigJson : string?
  • EnableDocumentContextualization : bool
  • MaxDocumentsPerRequest : int
  • MinDocumentRelevance : double

Navegación:

  • Secrets : List<ProjectSecret>
  • Tasks : List<ScheduledTask>
  • Executions : List<Execution>
  • BacklogItems : List<BacklogItem>

Relaciones:

  • 1-N con ScheduledTask Verificado por snippet y diagrama
  • 1-N con Execution Verificado por snippet y diagrama
  • 1-N con BacklogItem Verificado por snippet y diagrama
  • 1-N con ProjectSecret Inferido
  • 0..1-0..1 con ClickUpConfig Inferido por diagrama
  • 1-N con DocumentContextLink Inferido por migración documentada

DevSession

Estado: Verificado

Propiedades:

  • Id : Guid
  • Name : string
  • Description : string?
  • ProjectId : Guid?
  • AgentId : string?
  • PluginId : string?
  • RemoteAgentId : Guid?
  • UserId : Guid
  • OrganizationId : Guid
  • BacklogItemId : Guid?
  • Status : string
  • MessageCount : int
  • TokensUsed : int
  • SessionInstructions : string?
  • InjectSessionInstructions : bool
  • MaxHistoryMessages : int
  • MaxHistoryTokens : int
  • AutoSummarizeHistory : bool
  • HistorySummary : string?
  • HistorySummaryGeneratedAt : DateTime?
  • HistorySummaryMessageCount : int?
  • WorkStartedAt : DateTime?
  • WorkEndedAt : DateTime?

Navegación:

  • Messages : List<DevSessionMessage>

Relaciones:

  • N-1 con Project Inferido por FK property
  • N-1 con User Verificado por diagrama e índice
  • N-1 con Organization Inferido por FK property
  • 0..1-N con BacklogItem Verificado por diagrama
  • 1-N con DevSessionMessage Verificado por Fluent API
  • 1-N con CopilotExecution Verificado por diagrama y FK en CopilotExecution
  • 0..1-N con RemoteAgent Inferido por FK property

CopilotExecution

Estado: Verificado, con inconsistencias

Propiedades explícitas del developer guide:

  • Id : Guid
  • DevSessionId : Guid
  • Objective : string
  • State : CopilotState
  • Result : CopilotResult
  • TotalSteps : int
  • CurrentStepIndex : int
  • CompletedSteps : int
  • FailedSteps : int
  • AutoApprove : bool
  • AutoContinue : bool
  • PauseOnWarning : bool
  • MaxIterations : int
  • MaxRetries : int
  • TimeoutMinutes : int
  • StepTimeoutSeconds : int
  • TotalIterations : int
  • TotalTokensUsed : int
  • TotalMessagesGenerated : int
  • TotalDurationMs : long?
  • BatchId : Guid?
  • ArtifactsJson : string?
  • WarningsJson : string?

Navegación:

  • Steps : List<CopilotStep>
  • DevSession : DevSession?

Relaciones:

  • N-1 con DevSession Verificado por property
  • 1-N con CopilotStep Verificado por Fluent API
  • N-1 con CopilotBatchExecution Inferido por diagrama

Inconsistencias documentales:

  • AUDITORIA-IMPLEMENTACION-WORKSPACE.md menciona además UserId, Plan, Config, Metrics y 13 estados.
  • El developer guide solo muestra DevSessionId, sin UserId, y enum con 8 estados visibles.

Conclusión: la entidad evolucionó y la wiki contiene al menos dos versiones del modelo.

Agent

Estado: Verificado

Propiedades:

  • Id : Guid
  • Slug : string
  • Name : string
  • Description : string?
  • Model : string
  • SystemPrompt : string
  • Source : string
  • IsActive : bool
  • CreatedAt : DateTime
  • UpdatedAt : DateTime

Navegación:

  • Skills : ICollection<AgentSkill>
  • Triggers : ICollection<AgentTrigger>
  • PluginAgents : ICollection<PluginAgent>

Relaciones:

  • 1-N con AgentSkill Verificado
  • 1-N con AgentTrigger Verificado
  • 1-N con PluginAgent Inferido

AgentSkill

Estado: Verificado

Propiedades:

  • AgentId : Guid
  • Skill : string
  • Proficiency : int
  • Agent : Agent

Relaciones:

  • N-1 con Agent

Notas:

  • La clave primaria no está mostrada.
  • Inferencia fuerte: probablemente clave compuesta AgentId + Skill.

AgentTrigger

Estado: Verificado

Propiedades:

  • Id : Guid
  • AgentId : Guid
  • TriggerType : string
  • Pattern : string
  • Priority : int
  • Agent : Agent

Relaciones:

  • N-1 con Agent

RemoteAgent

Estado: Verificado

Propiedades:

  • Id : Guid
  • Name : string
  • ApiKey : string
  • ApiKeyHash : string
  • OrganizationId : Guid
  • Status : RemoteAgentStatus
  • ConnectionId : string?
  • LastHeartbeat : DateTime?
  • SystemInfo : string?
  • AgentVersion : string?
  • DefaultWorkingDirectory : string?
  • CapabilitiesJson : string?
  • TotalCommandsExecuted : int
  • TotalErrors : int
  • TotalTokensUsed : long
  • CpuUsagePercent : int?
  • MemoryUsagePercent : int?
  • DiskUsagePercent : int?

Relaciones:

  • N-1 con Organization Inferido por FK property
  • 1-N con DevSession Inferido por FK property en DevSession

UserMemory

Estado: Verificado por esquema, pero inconsistente con documentación previa

Propiedades reales observadas en esquema:

  • Id : Guid
  • UserId : Guid
  • ProjectId : Guid?
  • Category : string
  • Content : string
  • Source : string
  • Confidence : int
  • UseCount : int
  • IsActive : bool
  • CreatedAt : DateTime
  • LastUsedAt : DateTime?

Relaciones verificadas por esquema:

  • N-1 con User ON DELETE CASCADE
  • N-1 con Project ON DELETE SET NULL

Índices verificados por esquema:

  • IX_UserMemories_UserId
  • IX_UserMemories_ProjectId
  • IX_UserMemories_UserId_Category
  • IX_UserMemories_IsActive parcial para activos

Conclusión:

  • El esquema actual respalda la variante Category/Content/Confidence/UseCount/IsActive.
  • La variante Key/Value/ConfidenceScore en IDEAS-CURSOR-AI.md quedó desactualizada o nunca llegó a producción.

BacklogItem

Estado: Verificado por esquema

Propiedades verificadas por esquema:

  • Id : Guid
  • ExecutionId : Guid?
  • ProjectId por índice compuesto
  • Title : string
  • Description : string?
  • ItemType : string?
  • Priority : string
  • Status por índice compuesto
  • MetadataJson : string?
  • HoldedTaskId : string?
  • FollowUpTaskId : Guid?
  • CreatedAt : DateTime
  • UpdatedAt : DateTime
  • ResolvedAt : DateTime?
  • ConvertedToTaskId : Guid?
  • ConvertedAt : DateTime?
  • ConversionNotes : string?
  • ProcedureId : string?
  • ProcedureName : string?
  • SuggestedProcedure : string?
  • AIAnalysisId : Guid?
  • ClickUpTaskId : string?
  • ClickUpListId : string?
  • ClickUpSyncedAt : DateTime?
  • ClickUpUrl : string?
  • SentryIssueId : string?
  • SentryPermalink : string?
  • AICategory : string?
  • AISummary : string?
  • EstimatedEffort : string?
  • Source : string?

Relaciones:

  • N-1 con Project Verificado por esquema, ON DELETE SET NULL
  • N-1 con Execution Verificado por esquema, ON DELETE SET NULL
  • 0..1-1 con ScheduledTask vía ConvertedToTaskId Verificado por esquema
  • 0..1-1 con ScheduledTask vía FollowUpTaskId Verificado por esquema
  • 0..1-1 con BacklogAIAnalysis vía AIAnalysisId Verificado por esquema
  • 0..1-N con DevSession Verificado por diagrama e índice en DevSessions.BacklogItemId

Observación:

  • El developer guide solo incluye stub public class BacklogItem { }, pero el esquema actual permite reconstruir la forma física con bastante precisión.

Entidades adicionales inferidas o parcialmente documentadas

Estas entidades aparecen en diagramas, tablas de migración, servicios o navegación, pero sin definición completa en este repo:

  • User
  • DevSessionMessage
  • ScheduledTask
  • Execution
  • ProjectSecret
  • CommunicationChannel
  • DocumentContextLink
  • Plugin
  • PluginAgent
  • PluginSkill
  • PluginCommand
  • PluginProcedure
  • ClickUpConfig
  • CopilotBatchExecution
  • WellnessRecord
  • SystemMetrics

ScheduledTask

Estado: Verificado por esquema

Propiedades verificadas por esquema:

  • Id, Slug, Name, TaskType, ProcedureId, ProjectId, CronExpression, ManualPrompt, AgentId
  • Enabled, Description, CreatedAt, UpdatedAt, LastRun, NextRun
  • SourceBacklogItemId, SourceExecutionId, PluginId, SelectedSkills, SuggestedByAI
  • ExecuteImmediately, OutputFormat, CommandId, UseOrchestratorSecrets, TimeoutMinutes
  • RequiresApproval, IncludeStructuredFooter, FooterIncludeBacklogItems, FooterIncludeTasks, FooterIncludeNotifications
  • ScheduledAtUtc, IsOneTimeExecution, Priority, PriorityOrder
  • DelayMinutes, NotBeforeUtc, NotAfterUtc, MaxRetries, RetryDelayMinutes, CurrentRetryCount
  • RetryStrategy, DependsOnTaskId, DependsOnStatus, WaitForDependency

Relaciones verificadas por esquema:

  • N-1 con Project ON DELETE SET NULL
  • N-1 con Agent ON DELETE SET NULL
  • 0..1-1 con BacklogItem vía SourceBacklogItemId
  • 0..1-1 con Execution vía SourceExecutionId
  • 1-N con Execution Inferido por FK inversa Executions.TaskId

Índices verificados por esquema:

  • IX_ScheduledTask_Slug unique
  • IX_ScheduledTask_ProjectId
  • IX_ScheduledTask_AgentId
  • IX_ScheduledTask_Priority
  • IX_ScheduledTask_ProcedureId
  • IX_ScheduledTask_CommandId
  • IX_ScheduledTask_SourceBacklogItemId
  • IX_ScheduledTask_SourceExecutionId

Notas:

  • La tabla física actual es ScheduledTask en singular, mientras la documentación de EF usa DbSet<ScheduledTask> ScheduledTasks.
  • AUDITORIA-PROBLEMAS-A-REVISAR.md afirma 73 propiedades, pero el esquema actual muestra 45.

Execution

Estado: Verificado por esquema

Propiedades verificadas por esquema:

  • Id, TaskId, TaskName, ProcedureId, ProjectId, StartedAt, CompletedAt
  • DurationMinutes, Status, Source, Success, ErrorMessage, OutputSummary, OutputFull
  • HoldedTaskId, CreatedAt, HasStructuredOutput, StructuredOutputJson, ResultType
  • MetricsJson, IssuesFound, IssuesResolved, BacklogItemsGenerated, TriggeredBy, TriggeredByUser
  • PromptPayloadJson

Relaciones verificadas por esquema:

  • N-1 con Project DELETE behavior no extraído aquí
  • N-1 con ScheduledTask vía TaskId
  • 1-N con BacklogItem vía BacklogItems.ExecutionId

Índices verificados por esquema:

  • IX_Executions_ProjectId
  • IX_Executions_Status
  • IX_Executions_TaskId
  • IX_Executions_StartedAt
  • IX_Executions_ResultType
  • IX_Executions_TriggeredBy
  • IX_Executions_HasStructuredOutput

Estado: Verificado por esquema, con divergencia de nombres

Campos verificados por esquema:

  • Id
  • ProjectId
  • Keywords
  • DocumentPath
  • Description
  • RelevanceWeight
  • MaxTokens
  • Category
  • IsActive
  • UsageCount
  • LastUsedAt
  • CreatedAt
  • UpdatedAt
  • LastDiscoveredAt
  • FeedbackScore

Relación:

  • N-1 con Project

Índices verificados por esquema:

  • IX_DocumentContextLinks_ProjectId
  • IX_DocumentContextLinks_Category
  • IX_DocumentContextLinks_IsActive parcial
  • IX_DocumentContextLinks_FeedbackScore compuesto parcial

Nota:

  • La documentación previa usa FilePath y Relevance; el esquema actual usa DocumentPath y RelevanceWeight.

Relaciones consolidadas

Relaciones Verificadas:

  • Organization 1-N Project
  • Project 1-N BacklogItem
  • Project 1-N ScheduledTask
  • Project 1-N Execution
  • User 1-N DevSession
  • DevSession 1-N DevSessionMessage
  • DevSession 1-N CopilotExecution
  • CopilotExecution 1-N CopilotStep
  • Agent 1-N AgentSkill
  • Agent 1-N AgentTrigger
  • User 1-N UserMemory
  • Project 1-N DocumentContextLink
  • Project 1-N ProjectSecret
  • Project 0..1-1 ClickUpConfig
  • Organization 1-N CommunicationChannel
  • Organization 1-N RemoteAgent
  • Execution 1-N BacklogItem
  • ScheduledTask 1-N Execution

Relaciones Inferidas:

  • Organization 1-N User
  • Organization 1-N DevSession
  • DevSession 0..1-N BacklogItem
  • DevSession 0..1-N RemoteAgent
  • Plugin 1-N PluginAgent
  • Plugin 1-N PluginSkill
  • Plugin 1-N PluginCommand
  • Plugin 1-N PluginProcedure

Configuración de proveedor y runtime

Verificado en documentación:

  • EF Core usa PostgreSQL
  • Se usa UseNpgsql(...)
  • La base tiene columnas jsonb
  • Existe NexusDbContextFactory para design-time

No verificable en código:

  • Estrategia de naming conventions
  • Configuraciones globales de precision, enum mapping, converters
  • ApplyConfigurationsFromAssembly(...)
  • Split de configuraciones con IEntityTypeConfiguration<T>

Hallazgos de revisión

Alta severidad

  1. Falta el código fuente EF Core real en este repositorio. Impacto: no es posible completar un inventario confiable de entidades, claves, constraints, owned types, converters y DbSets reales.

  2. La documentación del modelo está desalineada con el esquema PostgreSQL actual. Ejemplos:

  3. CopilotExecution aparece con dos versiones distintas.
  4. UserMemory aparece con dos esquemas incompatibles, y el esquema respalda solo uno.
  5. DocumentContextLink documenta FilePath/Relevance, pero la base usa DocumentPath/RelevanceWeight.
  6. ScheduledTask aparece como conjunto plural en EF/documentación, pero la tabla física actual está en singular. Impacto: alto riesgo de generar documentación incorrecta o migraciones erróneas si se toma una sola fuente como verdad.

Media severidad

  1. El DbContext documentado expone 64+ DbSets, pero solo 12 están visibles en snippets y el esquema real contiene bastantes más tablas relacionadas. Impacto: el mapa del dominio queda incompleto para cualquier análisis de integridad o dependencia.

  2. Varias entidades relevantes solo existen como nombres o diagramas. Ejemplos: User, DevSessionMessage, CopilotBatchExecution, CommunicationChannel. Impacto: no se pueden validar nullability, cardinalidades exactas ni delete behaviors.

Baja severidad

  1. La documentación no muestra claves primarias/compuestas, restricciones de longitud, defaults SQL ni nombres de tablas. Impacto: limita diseño físico y revisión de performance, aunque no impide un mapa conceptual.

Tests que faltan

Dado el estado documental, faltan al menos estas verificaciones automatizadas en el código fuente real:

  • Test que compare los DbSet del NexusDbContext contra la documentación publicada.
  • Test de mapeo para jsonb en CopilotExecution, BacklogItem y cualquier entidad con payload JSON.
  • Test de delete behavior para DevSession -> DevSessionMessage y CopilotExecution -> CopilotStep.
  • Test de unicidad para Organization.Slug y Project.Slug.
  • Test de índices compuestos para consultas frecuentes.
  • Test de snapshot de migraciones para detectar drift entre documentación y modelo real.

Resumen ejecutivo

Se identificó un NexusDbContext documentado para PostgreSQL con al menos 12 DbSet explícitos y evidencia de 64+ conjuntos totales. Se pudieron reconstruir con buen nivel de confianza las entidades Organization, Project, DevSession, CopilotExecution, Agent, AgentSkill, AgentTrigger y RemoteAgent, y además el esquema actual permitió verificar físicamente UserMemory, BacklogItem, ScheduledTask, Execution y DocumentContextLink.

El resultado es útil como mapa documental del dominio, pero no como inventario definitivo de EF Core. Para completar el análisis de forma correcta hace falta el repositorio de la plataforma que contiene Shared.Admin/Entities/, Shared.Admin/Data/NexusDbContext.cs y las migraciones SQL reales.