TECNASIC

Diccionario de Datos • Base de Datos APIREST

Volver al Visor

DICCIONARIO DE DATOS & GUÍA DE CONSULTA

MODELO DE DATOS SQL SERVER PARA INTEGRACIONES EXTERNAS (BI / ETL / SISTEMAS)

Base de Datos: APIREST
Servidor: SRVINTRANET.TSA.INT
Versión: 2.2 (Septiembre 2026)
Clasificación: Técnico - Corporativo
1. Arquitectura y Premisa de Operación

La base de datos APIREST almacena la información consolidada de proyectos, programas y dotación de horas hombre (HH) sincronizados desde Oracle Primavera Cloud (OPC).

Premisa Fundamental de Disponibilidad de Datos: La base de datos se mantiene permanentemente poblada con los últimos datos sincronizados mientras no se ejecute un nuevo ciclo. Al momento de sincronizar (a las 06:00 AM y 18:00 PM o de forma manual), se actualizan los datos mediante operaciones transaccionales tipo UPSERT (sin borrado previo destructivo). Si la conexión a Oracle Cloud falla, los datos en la base de datos se conservan 100% intactos para consultas externas.
Servidor SQL Server (Host)
SRVINTRANET.TSA.INT
Base de Datos
APIREST
Puerto TCP
1433
Esquema Principal
dbo
Usuario Aplicación (Lectura/Escritura)
apirest_app
Contraseña Usuario Aplicación
apirest2026!
Rol Usuario Aplicación
db_owner (Full Control)
Modo Aislamiento Recomendado
READ UNCOMMITTED / (NOLOCK)

Creación de Usuario de Solo Consulta (db_datareader)

¿Se puede generar un usuario de solo consulta? Sí, absolutamente. Es la mejor práctica recomendada para conectar herramientas de Business Intelligence (Power BI, Excel, Tableau) o servicios de reportería externa. Este usuario tiene permisos exclusivos de lectura (SELECT) y tiene estrictamente bloqueadas operaciones de modificación (INSERT, UPDATE, DELETE, DROP o TRUNCATE).

Para habilitarlo, un Administrador de Base de Datos (DBA) o cuenta con permisos sysadmin / securityadmin en SQL Server Management Studio (SSMS) debe ejecutar el siguiente script T-SQL:

T-SQL: Crear Login y Usuario de Solo Consulta en Base de Datos APIREST
USE [master];
GO

-- 1. Crear el Login a nivel del servidor SQL Server
IF NOT EXISTS (SELECT name FROM sys.server_principals WHERE name = 'apirest_readonly')
BEGIN
    CREATE LOGIN [apirest_readonly] 
    WITH PASSWORD = N'Tecnasic2026.Readonly!', 
         DEFAULT_DATABASE = [APIREST], 
         CHECK_EXPIRATION = OFF, 
         CHECK_POLICY = ON;
END
GO

USE [APIREST];
GO

-- 2. Crear el Usuario mapeado dentro de la base de datos APIREST
IF NOT EXISTS (SELECT name FROM sys.database_principals WHERE name = 'apirest_readonly')
BEGIN
    CREATE USER [apirest_readonly] FOR LOGIN [apirest_readonly];
END
GO

-- 3. Asignar el rol estándar de solo lectura (db_datareader)
ALTER ROLE [db_datareader] ADD MEMBER [apirest_readonly];
GO
Credenciales resultantes para herramientas externas:
• Usuario: apirest_readonly
• Contraseña: Tecnasic2026.Readonly! (o la definida por el administrador)
• Permisos: Solo lectura en todas las tablas y vistas existentes y futuras de APIREST.

Cadenas de Conexión de Ejemplo

Cadena ADO.NET / C# (.NET Core)
Server=SRVINTRANET.TSA.INT;Database=APIREST;User Id=apirest_readonly;Password=Tecnasic2026.Readonly!;TrustServerCertificate=True;MultipleActiveResultSets=true;
Python (pyodbc / SQLAlchemy)
import pyodbc

connection_string = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=SRVINTRANET.TSA.INT;"
    "DATABASE=APIREST;"
    "UID=apirest_readonly;"
    "PWD=Tecnasic2026.Readonly!;"
    "TrustServerCertificate=yes;"
)
conn = pyodbc.connect(connection_string)
Power BI / Excel (Power Query M)
let
    // Conexión directa a SQL Server con rol de lectura
    Origen = Sql.Database("SRVINTRANET.TSA.INT", "APIREST", [CreateNavigationProperties=false])
in
    Origen
2. Diagrama Entidad - Relación (ERD)
erDiagram
    Workspaces ||--o{ Projects : "WorkspaceId (1:N)"
    Projects ||--o{ ProjectRoleHoursWeekly : "ProjectId (1:N)"
    Projects ||--o{ ProjectRoleHoursHistorical : "ProjectId (1:N)"
    SyncLogs ||--o{ ProjectRoleHoursHistorical : "SyncLogId (1:N)"

    Workspaces {
        int WorkspaceId PK
        nvarchar_200 WorkspaceName
        datetime2 LastSync
    }

    Projects {
        int ProjectId PK
        nvarchar_50 ProjectCode
        nvarchar_500 ProjectName
        int WorkspaceId FK
        nvarchar_200 ProjectManager
        datetime2 PlannedFinish
        nvarchar_50 Status
        datetime2 LastSync
    }

    ProjectRoleHoursWeekly {
        bigint Id PK
        int ProjectId FK
        nvarchar_100 PrimaryRole
        nvarchar_10 WeekKey
        date WeekStartDate
        decimal_12_2 Hours
        datetime2 SyncDate
    }

    ProjectRoleHoursHistorical {
        bigint Id PK
        int SyncLogId FK
        int ProjectId FK
        nvarchar_100 PrimaryRole
        nvarchar_10 WeekKey
        date WeekStartDate
        decimal_12_2 Hours
        datetime2 SyncDate
    }

    Programs {
        int ProgramId PK
        nvarchar_200 ProgramCode
        nvarchar_500 ProgramName
        int WorkspaceId
        nvarchar_max LinkedProjectIdsJson
        datetime2 LastSync
    }

    SyncLogs {
        int Id PK
        datetime2 StartedAt
        datetime2 FinishedAt
        int ProjectsProcessed
        nvarchar_50 Status
        nvarchar_2000 ErrorMessage
    }

    SystemConfigs {
        nvarchar_100 ConfigKey PK
        nvarchar_max ConfigValue
        datetime2 UpdatedAt
    }
        
3. Diccionario Detallado de Tablas

3.1. Tabla: dbo.Workspaces

Espacios de trabajo en Oracle Primavera Cloud. Agrupan proyectos bajo una misma unidad operativa o cliente.

Campo Tipo SQL Nulo Clave Descripción y Reglas de Negocio
WorkspaceId int NO PK Identificador único del Workspace provisto por Oracle Primavera Cloud REST API.
WorkspaceName nvarchar(200) NO - Nombre descriptivo del Workspace (ej. "Proyectos Asignados", "División Minería").
LastSync datetime2 SÍ - Fecha y hora UTC de la última sincronización exitosa de este registro.

3.2. Tabla: dbo.Projects

Catálogo maestro de proyectos. Contiene los metadatos contractuales, administrador y estado de cada faena.

Campo Tipo SQL Nulo Clave Descripción y Reglas de Negocio
ProjectId int NO PK Identificador único del proyecto asignado por Oracle Primavera Cloud.
ProjectCode nvarchar(50) NO IDX Código comercial / interno (ej: OT3173_ACTUAL, 4600030554).
ProjectName nvarchar(500) NO - Nombre completo de la faena o contrato de construcción / montaje.
WorkspaceId int NO FK Referencia a dbo.Workspaces(WorkspaceId) con eliminación en cascada.
ProjectManager nvarchar(200) NO - Nombre del Administrador de Contrato o Jefe de Proyecto asignado en OPC.
PlannedFinish datetime2 SÍ - Fecha estimada de término del proyecto según la línea base vigente.
Status nvarchar(50) NO - Estado operativo en OPC (ej: Active, Planned, Complete).
LastSync datetime2 SÍ - Fecha y hora UTC de la última sincronización de este proyecto.

3.3. Tabla: dbo.ProjectRoleHoursWeekly (Tabla Central de Horas)

Almacena la matriz activa de Horas Hombre (Labor) asignadas por proyecto, disciplina y semana calendario.

Campo Tipo SQL Nulo Clave Descripción y Reglas de Negocio
Id bigint NO PK Identificador numérico autoincremental (IDENTITY(1,1)).
ProjectId int NO FK Referencia al proyecto en dbo.Projects(ProjectId).
PrimaryRole nvarchar(100) NO IDX Disciplina o especialidad asignada (ej: Eléctrico, Mecánico, Civil).
WeekKey nvarchar(10) NO IDX Clave estándar de semana en formato canónico YYYY-Sxx (ej. 2026-S37).
WeekStartDate date NO - Fecha del lunes de inicio de la semana correspondiente (tipo fecha pura sin hora).
Hours decimal(12,2) NO - Cantidad total de Horas Hombre (HH) planificadas para dicha semana y rol.
SyncDate datetime2 NO - Marca de tiempo UTC en que se calculó y guardó la asignación.

Índice Único: IX_ProjectRoleHoursWeekly_ProjectId_PrimaryRole_WeekKey (Impide duplicados de una misma disciplina en la misma semana para un proyecto).

3.4. Tabla: dbo.ProjectRoleHoursHistorical

Histórico acumulativo (auditoría / congelamiento). Permite comparar cómo varió la dotación proyectada entre una sincronización y otra.

Campo Tipo SQL Nulo Clave Descripción y Reglas de Negocio
Id bigint NO PK Identificador autonumérico de la captura histórica.
SyncLogId int NO IDX ID de la ejecución registrado en dbo.SyncLogs(Id).
ProjectId int NO FK Referencia a dbo.Projects(ProjectId).
PrimaryRole nvarchar(100) NO - Disciplina o rol profesional.
WeekKey nvarchar(10) NO - Clave de la semana consultada (YYYY-Sxx).
WeekStartDate date NO - Fecha del día lunes de inicio de la semana.
Hours decimal(12,2) NO - Horas Hombre congeladas al momento de ejecutar la sincronización.
SyncDate datetime2 NO - Fecha y hora UTC del snapshot.

3.5. Tabla: dbo.Programs

Agrupaciones de programas de proyectos sincronizadas desde Primavera Cloud.

Campo Tipo SQL Nulo Clave Descripción y Reglas de Negocio
ProgramId int NO PK Identificador único del Programa en OPC.
ProgramCode nvarchar(200) NO - Código del programa en Primavera Cloud.
ProgramName nvarchar(500) NO - Nombre descriptivo del programa.
WorkspaceId int NO - ID del Workspace al que pertenece.
LinkedProjectIdsJson nvarchar(max) NO - Arreglo JSON serializado con los IDs de proyectos vinculados (ej. [101, 104, 108]).
LastSync datetime2 SÍ - Fecha y hora UTC de la última sincronización.

3.6. Tabla: dbo.SyncLogs

Bitácora de auditoría y monitoreo de las sincronizaciones ejecutadas por el sistema.

Campo Tipo SQL Nulo Clave Descripción y Reglas de Negocio
Id int NO PK Identificador autonumérico de la sesión de sincronización.
StartedAt datetime2 NO - Fecha y hora UTC de inicio de la tarea programada.
FinishedAt datetime2 SÍ - Fecha y hora UTC de término (nulo si está en ejecución).
ProjectsProcessed int NO - Cantidad total de proyectos procesados durante el ciclo.
Status nvarchar(50) NO - Estado final del proceso: Running, Completed, Error.
ErrorMessage nvarchar(2000) SÍ - Detalle del error en caso de fallo técnico de conexión o parsing.

3.7. Tabla: dbo.SystemConfigs

Parámetros operativos clave-valor modificables desde el panel administrativo.

Campo Tipo SQL Nulo Clave Descripción y Reglas de Negocio
ConfigKey nvarchar(100) NO PK Clave identificadora (ej: PrimaveraUsername, PrimaveraPassword).
ConfigValue nvarchar(max) NO - Valor textual o JSON configurado.
UpdatedAt datetime2 NO - Fecha y hora UTC del último cambio de configuración.
4. Recetario de Consultas SQL para Integraciones Externas

A continuación se presentan las consultas SQL optimizadas para ser ejecutadas desde Power BI, Python, Excel o aplicaciones externas.

Consulta 1: Catálogo de Proyectos con Workspace y Estado
-- Consulta de Proyectos activos con fecha de última sincronización
SELECT 
    p.ProjectId,
    p.ProjectCode,
    p.ProjectName,
    ISNULL(w.WorkspaceName, 'Proyectos Asignados') AS WorkspaceName,
    p.ProjectManager,
    p.PlannedFinish,
    p.Status,
    DATEADD(hour, -3, p.LastSync) AS LastSync_HoraChile -- Conversión de UTC a Chile
FROM dbo.Projects p WITH (NOLOCK)
LEFT JOIN dbo.Workspaces w WITH (NOLOCK) ON p.WorkspaceId = w.WorkspaceId
WHERE p.Status = 'Active'
ORDER BY p.ProjectCode;
Consulta 2: Horas Hombre (Labor) Semanales por Proyecto y Disciplina
-- Detalle semanal de horas planificadas por especialidad
SELECT 
    p.ProjectCode,
    p.ProjectName,
    h.PrimaryRole AS Especialidad,
    h.WeekKey AS CodigoSemana,
    h.WeekStartDate AS FechaLunesSemana,
    h.Hours AS HorasHombre,
    DATEPART(year, h.WeekStartDate) AS Anio,
    DATEPART(month, h.WeekStartDate) AS Mes
FROM dbo.ProjectRoleHoursWeekly h WITH (NOLOCK)
INNER JOIN dbo.Projects p WITH (NOLOCK) ON h.ProjectId = p.ProjectId
WHERE h.Hours > 0
ORDER BY p.ProjectCode, h.PrimaryRole, h.WeekStartDate;
Consulta 3: Resumen Mensualizado para Power BI / Excel
-- Agrupación mensual de horas por proyecto y rol (ideal para gráficos de barras y curvas de dotación)
SELECT 
    p.ProjectCode,
    p.ProjectName,
    h.PrimaryRole AS Especialidad,
    FORMAT(h.WeekStartDate, 'yyyy-MM') AS PeriodoMes,
    SUM(h.Hours) AS TotalHorasMensuales,
    ROUND(SUM(h.Hours) / 180.0, 1) AS DotacionEquivalentePersonas -- Estimación a 180 hrs/mes
FROM dbo.ProjectRoleHoursWeekly h WITH (NOLOCK)
INNER JOIN dbo.Projects p WITH (NOLOCK) ON h.ProjectId = p.ProjectId
GROUP BY p.ProjectCode, p.ProjectName, h.PrimaryRole, FORMAT(h.WeekStartDate, 'yyyy-MM')
ORDER BY p.ProjectCode, PeriodoMes;
Consulta 4: Programas y Proyectos Vinculados (Extracción JSON)
-- Desanidar los proyectos asociados a cada programa usando OPENJSON
SELECT 
    prog.ProgramCode,
    prog.ProgramName,
    p.ProjectCode,
    p.ProjectName,
    p.Status AS EstadoProyecto
FROM dbo.Programs prog WITH (NOLOCK)
CROSS APPLY OPENJSON(prog.LinkedProjectIdsJson) AS j
INNER JOIN dbo.Projects p WITH (NOLOCK) ON CAST(j.value AS int) = p.ProjectId
ORDER BY prog.ProgramCode, p.ProjectCode;
5. Vistas SQL Recomendadas (DDL)

Si se desea simplificar el acceso a analistas de Power BI o Excel sin necesidad de escribir JOINs complejos, se recomienda crear las siguientes vistas estándar en la base de datos APIREST:

Script DDL: Creación de Vistas Estándar de Integración
-- 1. Vista de Proyectos con Workspace
CREATE OR ALTER VIEW dbo.vw_BI_Proyectos
AS
SELECT 
    p.ProjectId,
    p.ProjectCode,
    p.ProjectName,
    ISNULL(w.WorkspaceName, 'Proyectos Asignados') AS WorkspaceName,
    p.ProjectManager,
    p.PlannedFinish,
    p.Status,
    p.LastSync
FROM dbo.Projects p WITH (NOLOCK)
LEFT JOIN dbo.Workspaces w WITH (NOLOCK) ON p.WorkspaceId = w.WorkspaceId;
GO

-- 2. Vista de Horas Semanales Desnormalizadas
CREATE OR ALTER VIEW dbo.vw_BI_HorasSemanales
AS
SELECT 
    h.Id,
    p.ProjectCode,
    p.ProjectName,
    h.PrimaryRole,
    h.WeekKey,
    h.WeekStartDate,
    h.Hours,
    h.SyncDate
FROM dbo.ProjectRoleHoursWeekly h WITH (NOLOCK)
INNER JOIN dbo.Projects p WITH (NOLOCK) ON h.ProjectId = p.ProjectId;
GO

-- 3. Vista de Estado de Última Sincronización
CREATE OR ALTER VIEW dbo.vw_BI_UltimaSincronizacion
AS
SELECT TOP 1
    Id,
    StartedAt,
    FinishedAt,
    ProjectsProcessed,
    Status,
    ErrorMessage
FROM dbo.SyncLogs WITH (NOLOCK)
ORDER BY StartedAt DESC;
GO