DICCIONARIO DE DATOS & GUÍA DE CONSULTA
MODELO DE DATOS SQL SERVER PARA INTEGRACIONES EXTERNAS (BI / ETL / SISTEMAS)
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).
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:
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
• 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
Server=SRVINTRANET.TSA.INT;Database=APIREST;User Id=apirest_readonly;Password=Tecnasic2026.Readonly!;TrustServerCertificate=True;MultipleActiveResultSets=true;
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)
let
// Conexión directa a SQL Server con rol de lectura
Origen = Sql.Database("SRVINTRANET.TSA.INT", "APIREST", [CreateNavigationProperties=false])
in
Origen
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.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. |
A continuación se presentan las consultas SQL optimizadas para ser ejecutadas desde Power BI, Python, Excel o aplicaciones externas.
-- 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;
-- 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;
-- 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;
-- 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;
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:
-- 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