MBS/Dashboards MARMOTECH/Documentacion_MarmotechBI.md

# Documentación de la base de datos **MarmotechBI**
### Guía para el desarrollo de dashboards en Power BI

| | |
|---|---|
| **Servidor** | `192.168.40.8` (SQL Server 2016) |
| **Base de datos** | `MarmotechBI` |
| **Origen de los datos** | Se actualiza en vivo desde los sistemas operativos de la empresa |
| **Naturaleza** | Capa semántica de **vistas** (54 vistas + 2 tablas). No almacena datos propios salvo 2 tablas de carga manual |
| **Propósito** | Esquema estrella para que usuarios de negocio armen sus propios dashboards con nombres de negocio |
| **Fecha de este documento** | 2026-08-25 |

> **Idea clave:** casi todo en `MarmotechBI` es una **vista** que presenta la información con nombres de negocio (`vwFactVentas`, `vwDimProducto`, etc.). Como son vistas, **no existen llaves foráneas físicas**: las relaciones son *lógicas* y hay que **crearlas manualmente en Power BI** (ver la sección [Relaciones para Power BI](#relaciones-recomendadas-en-power-bi)).

---

## 1. Cómo conectarse desde Power BI

1. **Obtener datos → SQL Server**.
2. Servidor: `192.168.40.8`  ·  Base de datos: `MarmotechBI`.
3. Modo: **Import** (recomendado para tableros publicados) o **DirectQuery** si se necesita tiempo real.
4. Seleccionar las vistas del área que se va a analizar (ej. `vwFactVentas` + sus dimensiones `vwDim*`).
5. En la vista **Modelo**, crear las relaciones según la sección 6.

> **Permisos:** el acceso es por login de Windows con rol de lectura (`db_datareader`) sobre `MarmotechBI`. Solicitarlo a Tecnología con el usuario de dominio.

---

## 2. Convenciones de nombres

| Prefijo | Significado | Rol en el modelo |
|---|---|---|
| `vwDim…` | **Dimensión** — describe (quién, qué, dónde, cuándo) | Tabla de "look up" |
| `vwFact…` / `VWFACT…` | **Hecho** — mide (cuánto, cuántos) | Tabla central de valores |
| `vwBridge…` | **Puente** — resuelve relaciones muchos-a-muchos | Entre dimensiones |
| `VW_DIM_…` / `VW_HECHOS_…` | Esquema del **Balanced Scorecard / Indicadores** (área independiente) | Dim / Hecho de gestión |
| Sin prefijo (`ventas_facturas`, `estadoResultado`, `item_conteo_ciclico`…) | **Vistas planas de reporte** — ya vienen denormalizadas | Se usan solas, no requieren relaciones |
| `…_usuario` (`_cdelacruz`, `_jisa`, `_mpuig`…) | **Copias personales** filtradas por vendedor/supervisor | Uso individual, no para el modelo general |

**Claves compuestas** — se repiten en casi todo el modelo:

- **Producto** = `cod_n` + `cod_grupo` + `cod_tipo` + `cod_sec` (4 columnas). En `vwDimProducto` existe también `producto_id` que las concatena como texto (`cod_n-cod_grupo-cod_tipo-cod_sec`).
- **Cliente** = `tipo_cliente` + `sec_cliente` (2 columnas).

---

## 3. Áreas temáticas (subject areas)

| # | Área | Hecho(s) principal(es) | Dimensiones que usa |
|---|---|---|---|
| A | **Comercial / Ventas** | `vwFactVentas`, `VWFACTCOTIZACIONES`, `vwfactPipeline`, `vwFactPresupuesto` | Fecha, Cliente, Vendedor, EquipoVentas, Producto, Categoría, Provincia, Zona, TipoVenta |
| B | **Cuentas por Cobrar** | `vwFactCxC_Base`, `vwFactCxC_Real` | Cliente, Vendedor, TipoVenta |
| C | **Despacho / Pendientes** | `vwOrdenesPendientesDespacho`, `vwReqCotizaciones`, `vwProductoDisponible` | Cliente, Vendedor, Producto |
| D | **Producción** | `vwProduccion_pub` | DepartamentoProducción, Producto |
| E | **Contabilidad / Finanzas** | `vwFactContabilidad`, `estadoResultado` | (Departamento, Cuenta — internas) |
| F | **Inventario** | `vwRotacionInventario_pub`, `vwRotacionInventarioPorBodega_pub`, `item_conteo_ciclico` | (planas, autocontenidas) |
| G | **Indicadores / Balanced Scorecard** | `VW_HECHOS_INDICADORES`, `VW_HECHOS_DOWNTIME`, `VW_HECHOS_TICKETS` | Calendario, Departamentos, Indicadores, Perspectivas, Procesos |
| H | **Datos externos** (tabla física) | `FactMercadoEdificaciones` | (independiente) |

---

## 4. Diccionario de dimensiones (área comercial)

### `vwDimFecha` — Calendario (grano mensual)
Grano = mes.
| Columna | Tipo | Descripción |
|---|---|---|
| `ano` | smallint | Año |
| `numeroMes` | smallint | Número de mes (1-12) — **llave para ordenar** |
| `mes` | char(10) | Nombre del mes |
| `AnoMes` | varchar(7) | `AAAA-MM` |

### `vwDimCliente` — Clientes  · PK = `tipo_cliente` + `sec_cliente`
| Columna | Tipo | Descripción |
|---|---|---|
| `tipo_cliente` | smallint | Tipo/segmento de cliente (parte 1 de la llave) |
| `sec_cliente` | int | Secuencia del cliente (parte 2 de la llave) |
| `nombre` | char(100) | Razón social |
| `num_rnc` | char(25) | RNC/Cédula |
| `direccion` | varchar(173) | Dirección |

### `vwDimVendedor` — Vendedores  · PK = `vendedor_id`
| Columna | Tipo | Descripción |
|---|---|---|
| `vendedor_id` | smallint | Código de vendedor (corresponde al nº de empleado) |
| `vendedor` | varchar(31) | Nombre y apellido |
| `equipo_id` | smallint | **FK → `vwDimEquipoVentas.equipo_id`** |

### `vwDimEquipoVentas` — Equipos de venta  · PK = `equipo_id`
| Columna | Tipo | Descripción |
|---|---|---|
| `equipo_id` | smallint | Código del equipo/departamento comercial |
| `equipoVentas` | nchar(200) | Nombre del equipo |

### `vwDimProducto` — Productos  · PK = `cod_n`+`cod_grupo`+`cod_tipo`+`cod_sec`
**Es la dimensión central de producto de todo el modelo.**
| Columna | Tipo | Descripción |
|---|---|---|
| `cod_n`, `cod_grupo`, `cod_tipo`, `cod_sec` | int | Llave compuesta del producto |
| `producto_id` | varchar(43) | Llave concatenada (`cod_n-cod_grupo-cod_tipo-cod_sec`) — **usar esta para relacionar en Power BI** |
| `descripcion_producto` | varchar(180) | Nombre del producto |
| `unidad_med` | char(4) | Unidad de medida |
| `clase` / `grupo` / `tipo` | char/nvarchar | Jerarquía de clasificación |
| `origen` | char(20) | Origen (nacional/importado/producción) |
| `categoria_titulo` | varchar(100) | Categoría comercial |
| `GerenteMarcas` | varchar(31) | Gerente de marca responsable |

### `vwDimCategoria` — Categorías comerciales  · PK = `cod_categoria`
| Columna | Tipo | Descripción |
|---|---|---|
| `cod_categoria` | smallint | Código de categoría |
| `categoria` | varchar(100) | Nombre de la categoría |

### `vwBridgeProductoCategoria` — Puente Producto ↔ Categoría
Resuelve que un producto (por `cod_n`+`cod_grupo`+`cod_tipo`) pertenece a una categoría.
| Columna | Tipo | Descripción |
|---|---|---|
| `cod_n`, `cod_grupo`, `cod_tipo` | smallint | Parte de la llave del producto |
| `cod_categoria` | smallint | **FK → `vwDimCategoria.cod_categoria`** |

### `vwDimProvincia` — Provincias  · PK = `cod_provincia`
| Columna | Tipo | Descripción |
|---|---|---|
| `cod_provincia` | smallint | Código de provincia |
| `nombre_provincia` | char(30) | Nombre |
| `pais` | nchar(20) | País |
| `idZona` | smallint | **FK → `vwDimZona.cod_zona`** |

### `vwDimZona` — Zonas geográficas  · PK = `cod_zona`
| Columna | Tipo | Descripción |
|---|---|---|
| `cod_zona` | smallint | Código de zona |
| `zonaGeografica` | char(30) | Nombre de la zona |

### `vwDimTipoVenta` — Tipo de venta / Moneda  · PK = `ventas`
Contiene la **tasa de cambio** usada para convertir a RD$.
| Columna | Tipo | Descripción |
|---|---|---|
| `ventas` | smallint | Código de tipo de venta |
| `descripcion` | nvarchar(80) | Descripción |
| `simbolo` | nvarchar(40) | Símbolo de moneda |
| `descripcion_moneda` | nchar(40) | Moneda |
| `tasa` | decimal | Tasa de cambio a RD$ |
| `tipo_operacion` | varchar(11) | `LOCAL_RD` / `LOCAL_USD` / `EXPORTACION` / `EURO` / `OTRO` |

### `vwDimDepartamentoProduccion` — Departamentos de producción  · PK = `codigodepto`
| Columna | Tipo | Descripción |
|---|---|---|
| `codigodepto` | smallint | Código de departamento |
| `nombre_depto` | char(30) | Nombre |
| `tipo_departamento` | nchar(40) | Tipo |
| `proceso_agrupado` | varchar(13) | Agrupación de proceso |

---

## 5. Diccionario de hechos (measures)

### `vwFactVentas` — Ventas facturadas  · grano: **línea de factura**
Una fila por cada línea de factura. Solo incluye documentos activos (no anulados).
| Columna | Tipo | Rol | Descripción |
|---|---|---|---|
| `factura`, `sucid` | int | Grano | Nº de factura + sucursal |
| `fecha`, `ano`, `mes` | date/int | → Fecha | Fecha de factura |
| `tipo_cliente`, `sec_cliente` | — | → Cliente | Llave del cliente |
| `vendedor` | smallint | → Vendedor | `sec_vend` (código del vendedor) |
| `ventas` | — | → TipoVenta | Código de moneda/tipo venta |
| `tipoVenta`, `simbolo`, `tasa` | — | Atributo | Descripción de moneda y tasa |
| `cod_provincia` | — | → Provincia | Provincia del cliente |
| `cotizacion_no` | int | → Cotización | Cotización que originó la venta |
| `cod_n`,`cod_grupo`,`cod_tipo`,`cod_sec` | — | → Producto | Llave del producto |
| `cantidad` | numeric | Medida | Cantidad vendida |
| `precio` | numeric | Medida | Precio unitario |
| `porc_desc` | numeric | Medida | % de descuento |
| `valor_bruto` | numeric | Medida | cantidad × precio |
| `valor_descuento` | numeric | Medida | Monto del descuento |
| `neto` | numeric | Medida | Neto en moneda original |
| **`neto_rd`** | numeric | Medida | **Neto convertido a RD$ (neto × tasa)** — usar para totales |

### `VWFACTCOTIZACIONES` — Cotizaciones  · grano: línea de cotización
Llaves: `cotizacion_no`, `tipo_cliente`+`sec_cliente`, `vendedor_id`, `cod_zona`, `cod_provincia`, `cod_n…cod_sec`.
Medidas: `cantidad`, `precio`, `porc_desc`, `neto_rd`, `monto_bruto`, `monto_descuento`, `estado`.

### `vwfactPipeline` — Embudo comercial (cotizado → vendido → despachado) · grano: cotización
Medidas: `cotizado_rd`, `vendido_rd`, `pendiente_venta_rd`, `conversion_pct`, `despachado_rd`, `pendiente_despacho_rd`.
Llaves: `cotizacion_no`, `tipo_cliente`+`sec_cliente`, `vendedor`, `cod_zona`, `cod_provincia`, `ventas`.

### `vwFactPresupuesto` — Presupuesto/meta de ventas
Llaves: `ano`,`mes`, `vendedor`, `ventas`, `cod_n…cod_sec`, `cod_categoria`.
Medidas: `cantidad`, `valor`, `valor_rd`.

### `vwFactCxC_Base` — Movimientos de Cuentas por Cobrar
Llaves: `tipo_cliente`+`sec_cliente`, `vendedor`, `num_doc`, `tipo_doc`, `ventas`.
Medidas: `monto`, `monto_rd`, `monto_signado`, `monto_signado_rd`, `dias_vencimiento`, `tipo_movimiento`.

### `vwFactCxC_Real` — Balance vigente de CxC por factura
Llaves: `tipo_cliente`+`sec_cliente`, `vendedor`, `factura`, `ventas`.
Medidas: `balance_rd`, `dias_vencimiento`.

### `vwProductoDisponible` — Disponibilidad de inventario (snapshot)
Disponibilidad calculada con la misma lógica del sistema operativo de inventario. Llave: `producto_id` / `cod_n…cod_sec`.
Medidas: `existencia`, `ordenes_abiertas`, `despachado`, `reservado`, `transito`, **`disponible`** (= existencia − (ordenes_abiertas − despachado) − reservado).

### `vwOrdenesPendientesDespacho` — Órdenes pendientes de despacho
Llaves: `cotizacion_no`, `tipo_cliente`+`sec_cliente`, `vendedor_id`, `cod_n…cod_sec`.
Medidas: `cantidadCotizada`, `cantidadDespachada`, `cantidadPendiente`, `valorCotizadoLinea`.

### `vwReqCotizaciones` — Requisiciones vs. cotizaciones
Medidas: `cantidadCotizada`, `cantidadDespachada`, `cantidadPendiente`, `valorRequisicion`, `valorPendienteDespachar`.

### `vwProduccion_pub` — Producción diaria  · grano: producto/día
Llaves: `codigodepto` → DepartamentoProducción, `cod_n…cod_sec` → Producto.
Medidas: `unidades`, `cantidad`, `existencia`, `cantidadVendida`.

### `vwFactContabilidad` — Movimientos contables
Llaves: `cuenta`, `codigodepartamento`, `ano`, `mes`, `tipo`, `banco`.
Medidas: `debito`, `credito`, `balance`, `presupuesto`. Incluye auditoría (`usuariocreador`, `fechacreacion`…).

---

## 6. Relaciones recomendadas en Power BI

> Como son vistas, **Power BI no detecta relaciones automáticamente**. Créalas a mano en la vista *Modelo*, con cardinalidad **Dimensión (1) → Hecho (\*)** y filtro en **dirección única**.

### 6.1 Área comercial (estrella)

| Dimensión (lado 1) | Columna | Hecho (lado \*) | Columna |
|---|---|---|---|
| `vwDimFecha` | `AnoMes` | `vwFactVentas` / cotizaciones / pipeline | `AnoMes` derivado de `ano`+`mes` |
| `vwDimCliente` | *clave compuesta* | `vwFactVentas`, `VWFACTCOTIZACIONES`, CxC | `tipo_cliente` + `sec_cliente` |
| `vwDimVendedor` | `vendedor_id` | `vwFactVentas` (`vendedor`), cotizaciones (`vendedor_id`) | vendedor |
| `vwDimEquipoVentas` | `equipo_id` | `vwDimVendedor` | `equipo_id` |
| `vwDimProducto` | `producto_id` | hechos con `cod_n…cod_sec` | *clave compuesta* |
| `vwDimCategoria` | `cod_categoria` | `vwBridgeProductoCategoria` | `cod_categoria` |
| `vwBridgeProductoCategoria` | `cod_n`+`cod_grupo`+`cod_tipo` | `vwDimProducto` | mismas columnas |
| `vwDimProvincia` | `cod_provincia` | `vwFactVentas`, cotizaciones, pipeline | `cod_provincia` |
| `vwDimZona` | `cod_zona` | `vwDimProvincia` | `idZona` |
| `vwDimTipoVenta` | `ventas` | hechos con `ventas` | `ventas` |

### 6.2 Claves compuestas — cómo resolverlas

Power BI **solo permite relaciones por UNA columna**. Para `Cliente` y `Producto` (llaves de 2 y 4 columnas) crea una **columna llave concatenada** con la misma fórmula en la dimensión y en el hecho:

```
// Cliente — en vwDimCliente y en cada hecho:
ClienteKey = FORMAT([tipo_cliente],"00") & "-" & FORMAT([sec_cliente],"0000000")

// Producto — usar el producto_id que ya trae vwDimProducto; en los hechos:
ProductoKey = FORMAT([cod_n],"0") & "-" & FORMAT([cod_grupo],"0") & "-" & FORMAT([cod_tipo],"0") & "-" & FORMAT([cod_sec],"0")
```
Luego relaciona por `ClienteKey` / `ProductoKey`.

### 6.3 Fechas
Los hechos traen `ano` + `mes`/`numeroMes` (grano mensual). Recomendado:
- Crear una **tabla de calendario** en Power BI (`CALENDAR`/`CALENDARAUTO`) y una columna `AnoMes` en cada hecho para relacionar; **o**
- Reutilizar `VW_DIM_CALENDARIO` (grano diario) como calendario compartido cuando se cruce con Indicadores.

### 6.4 Moneda
Los valores `*_rd` **ya vienen convertidos a RD$** usando la `tasa` de `vwDimTipoVenta`. Para totales monetarios usar siempre las columnas `neto_rd`, `monto_rd`, `valor_rd`, `balance_rd`.

---

## 7. Área de Indicadores / Balanced Scorecard (esquema `VW_*`)

Modelo estrella independiente para el tablero de gestión (indicadores, tiempos de caída, tickets de soporte).

**Dimensiones**
| Vista | PK | Descripción |
|---|---|---|
| `VW_DIM_CALENDARIO` | `Fecha` | Calendario diario (Año, Mes, Trimestre, Semana, EsFinDeSemana) |
| `VW_DIM_DEPARTAMENTOS` | `IdDepartamento` | Departamentos (Nombre, Tipo, Responsable, Activo) |
| `VW_DIM_INDICADORES` | `IdIndicador` | Indicadores (Meta, Peso, Frecuencia, UnidadMedida; FK `IdDepartamento`) |
| `VW_DIM_PERSPECTIVAS` | `IdPerspectiva` | Perspectivas del BSC (Financiera, Cliente, Procesos, Aprendizaje) |
| `VW_DIM_PROCESOS` | `IdProceso` | Procesos (Área, Criticidad, Tipo; FK `IdDepartamento`) |

**Hechos**
| Vista | Llaves | Medidas |
|---|---|---|
| `VW_HECHOS_INDICADORES` | `IdIndicador`, `Fecha`, `IdPerspectiva` | `ValorReal`, `ValorMeta`, `Cumplimiento`, `Score` |
| `VW_HECHOS_DOWNTIME` | `Fecha`, `IdDepartamento`, `IdProceso` | `HorasCaidas`, `ImpactoEstimado` |
| `VW_HECHOS_TICKETS` | `Fecha`, `IdProceso`, `IdDepartamento` | `HorasResolucion`, conteos por `status`/`priority`/`category` |
| `VW_SCORE_DEPARTAMENTO` | (derivada) | `ScorePromedio` por Departamento/Año/Mes |

**Relaciones**
- `VW_DIM_INDICADORES[IdIndicador]` → `VW_HECHOS_INDICADORES[IdIndicador]`
- `VW_DIM_PERSPECTIVAS[IdPerspectiva]` → `VW_HECHOS_INDICADORES[IdPerspectiva]`
- `VW_DIM_CALENDARIO[Fecha]` → `VW_HECHOS_INDICADORES / DOWNTIME / TICKETS[Fecha]`
- `VW_DIM_DEPARTAMENTOS[IdDepartamento]` → `VW_DIM_INDICADORES / VW_DIM_PROCESOS / hechos[IdDepartamento]`
- `VW_DIM_PROCESOS[IdProceso]` → `VW_HECHOS_DOWNTIME / VW_HECHOS_TICKETS[IdProceso]`

---

## 8. Tablas físicas (carga manual)

| Tabla | Contenido | Notas |
|---|---|---|
| `FactMercadoEdificaciones` | Datos de mercado de la construcción (municipio, barrio, tipo de destino, m² construidos, unidades, precio/m², situación del mercado, fuente) | Se carga con datos externos (ej. estadísticas de edificaciones) |

---

## 9. Vistas planas y personales (uso directo, fuera del modelo estrella)

Estas vistas **ya vienen denormalizadas** (traen las descripciones incorporadas): se conectan solas, sin relaciones.

| Vista | Uso |
|---|---|
| `ventas_facturas` | Vista completa de ventas con cliente, vendedor, producto, zona, moneda ya resueltos — ideal para una tabla dinámica rápida |
| `vwRotacionInventario_pub` / `vwRotacionInventarioPorBodega_pub` | Rotación de inventario (global / por bodega): cantidad vendida, valor ventas, `rotacion` |
| `item_conteo_ciclico` | Programación de conteo cíclico por clase ABC |
| `estadoResultado` | Estado de resultados por mes (`aplica_a`, `Balance`) |
| `vwProduccion_pub` | Producción diaria en formato plano |
| `analisisCotizaciones`, `analisisRequisiciones` | Análisis de cotizaciones y requisiciones (unidades/valores cotizados vs. despachados) |

**Copias personales (filtradas por vendedor/supervisor)** — *no usar para el modelo corporativo*:
`analisisCotizaciones_cdelacruz`, `_jefrancisco`, `_jisa`, `_mhurtado`, `_mpuig`, `_mvargas`;
`analisisRequisiciones_cdelacruz`, `_jefrancisco`, `_JISA`, `_mhurtado`, `_mpuig`;
`vwreportesfactura_cdelacruz`, `_jisa`, `_mpuig`;
`vwDimProductoMariaAna` (copia de `vwDimProducto`).

---

## 10. Buenas prácticas para el equipo de dashboards

1. **Un modelo por área** — no mezclar el esquema comercial con el de Indicadores en un mismo reporte salvo que se comparta el calendario.
2. **Usar siempre las columnas `*_rd`** para importes; la conversión de moneda ya está hecha.
3. **Dimensión en el lado 1, hecho en el lado \*** y filtro cruzado **unidireccional** (evita ambigüedad).
4. **Crear medidas DAX** (SUM, DISTINCTCOUNT…) en lugar de arrastrar columnas numéricas directamente.
5. **No apuntar a las vistas `_usuario`** para tableros compartidos; usar la vista base y filtrar con seguridad a nivel de fila (RLS) si se requiere segmentar por vendedor.
6. Ante dudas sobre el significado de una columna, consultar a Tecnología.