# INVENTARIO DE CONOCIMIENTO DEL PROYECTO — DASHBOARD TALENTO HUMANO
### Área de Innovación · Faranda Hotels & Resorts

> Respuesta al esquema de `prompt-inventario-conocimiento.md` (v1.0).
> Verificado contra código y base de datos el **2026-09-09**.
> Los campos sin evidencia se marcan `NO DOCUMENTADO`.

---

## 1. IDENTIDAD

- **Nombre del proyecto:** Dashboard Talento Humano (repo: `rrhh-report`)
- **Repositorio o ubicación del código:** Gitea del grupo — `https://git.faranda.online/faranda/rrhh-report.git`
  (ramas `main` = producción · `claude/angry-diffie-524755` = desarrollo). Copia de trabajo local en el equipo del responsable técnico.
- **Estado:** Producción
- **Responsable de este inventario:** Ricardo Martínez (BI / Apoyo Talento Humano) — único responsable técnico del proyecto.

---

## 2. APORTE A LA CAPA DATO (SQL)

### 2.1 Base de datos y motor

- **Nombre · motor · servidor:** `Base de Datos Historicos Talento Humano` · PostgreSQL · servidor central de Faranda en red interna (`172.19.0.160:5432`, categórico: mismo host que la API de nómina y la forja). Esquema `public`.
- **¿Fuente de verdad?** **Sí, para todo período mensual cerrado.** Todas las cifras de personal, ingresos/retiros, nómina y P&G de meses cerrados se consultan aquí. El **mes en curso NO está en esta base**: se consulta en vivo contra dos APIs externas — NominaApp (`api.innfinancial.cloud`) para personal y nómina, y AppsFaranda (`app.faranda.online`) para P&G. Esas dos APIs son las fuentes de verdad primarias; esta base es la consolidación histórica gobernada de lo que ellas entregaron en cada cierre.
- Existe además una base **local congelada** (`Base de Datos Talento Humano`, `localhost`) sin uso desde junio 2026 — no consultar.

### 2.2 Entidades consultables

| Tabla/vista | Qué contiene, en lenguaje de negocio | Granularidad | Filas aprox. | Rango de fechas |
|---|---|---|---|---|
| `historico_empleados` | Foto mensual de la plantilla activa: quién estaba contratado en cada propiedad, con su cargo, centro de costo, sueldo base, tipo de contrato, fecha de ingreso, fecha de nacimiento, sexo y si es socio u operación. | 1 fila = 1 persona en 1 propiedad en 1 mes | 43.957 | ene-2022 → ago-2026 (56 fotos mensuales) |
| `historico_ir` | Movimientos de entrada y salida de personal: ingresos, retiros y casos de ingreso-y-retiro en el mismo mes, con cargo, sueldo, causa de retiro y fechas. | 1 fila = 1 movimiento | 5.378 | grueso desde ene-2022; ~5 filas sueltas de 2005/2016/2017 (dato heredado, no representativo). Última: ago-2026 |
| `historico_nomina_pyg` | Caché estructurada de lo que devolvieron las APIs de nómina y P&G en cada cierre. Cuatro tipos de fila (`registro_tipo`): `respuesta` (JSON crudo completo por NIT), `resumen` (totales por hotel), `concepto` (agregado por concepto y hotel) y `empleado` (desglose completo por persona: conceptos, deducciones, provisiones, seguridad social). | Variable según `registro_tipo` | 56.317 | ene-2024 → ago-2026 |
| `historico_nomina_pyg_control` | Bitácora de las cargas de `historico_nomina_pyg`: qué NIT/período/estado (ok/error), cuántas filas, con qué error. | 1 fila = 1 intento de carga por NIT/período | 1.248 | ene-2024 → ago-2026 |
| `empresas` | Catálogo de razones sociales / NIT del grupo, con el `pyg_company_id` que las liga a la API de P&G. | 1 fila = 1 código de razón social | 28 | — |
| `hotel_unificacion` | Maestro de propiedades: liga cada razón social con su nombre en la API, su unidad de negocio (`bu_codigo`) y su nombre "de vitrina" (`nombre_personalizado`). Marca cuáles no se muestran. | 1 fila = 1 razón social / unidad de negocio | 29 | — |
| `cargo_unificacion` | Diccionario de normalización de cargos: nombre crudo del sistema fuente → nombre unificado. | 1 fila = 1 variante de cargo | 572 | — |
| `ceco_unificacion` | Diccionario de normalización de centros de costo: código/nombre crudo → nombre unificado. | 1 fila = 1 variante de centro de costo | 421 | — |
| `nomina_conceptos` | Diccionario de conceptos de nómina: código de la API → nombre legible, grupo, subgrupo y si se incluye o se ignora en los reportes del dashboard. | 1 fila = 1 concepto (con versiones `_v2`/`_v3` para un mismo código con distinto nombre) | 494 | — |
| `socios` | Cédulas de personas clasificadas como "Socio" (operación de multipropiedad), no "En Operación". Usado para el filtro de Operación. | 1 fila = 1 cédula | 20 activos | — |

### 2.3 Preguntas de negocio que esta base YA puede responder con exactitud

1. ¿Cuántas personas activas tenía cada propiedad al cierre de un mes dado, y cuántas al inicio?
2. ¿Cuántos ingresos y cuántos retiros hubo en una propiedad en un mes, y por qué causa se fueron?
3. ¿Cuál fue el gasto total de personal (devengado, deducido, provisiones, aportes patronales, neto pagado) de una propiedad en un mes cerrado?
4. ¿Cuál es la trayectoria salarial y de cargos de una persona concreta a lo largo del tiempo dentro del grupo?
5. ¿Cómo se compone la nómina de una persona, concepto por concepto, para cualquier mes desde enero de 2024?

### 2.4 Campos que necesitan glosario

- `historico_empleados.fecha` → **no es una fecha de evento**, es la etiqueta del snapshot mensual (siempre el día 1 del mes). "Activos de julio" = filas con `fecha = '2026-07-01'`.
- `historico_empleados.fecha_ingreso` → **se reinicia con CUALQUIER cambio de cargo o de tipo de contrato**, incluso dentro de la misma empresa. No es la antigüedad real de la persona. Para antigüedad real usar el endpoint `ingreso-real-map`.
- **"Antigüedad" tiene TRES definiciones de negocio distintas y NO intercambiables:** (a) tabla/panel del dashboard — solo suma tiempo continuo en la MISMA razón social, corta con huecos > 62 días; (b) gráfica "Distribución por Antigüedad" — `MIN(fecha)` por cédula, ignora cambios de empresa y huecos; (c) panel "Historial por empresa" — suma todos los bloques cargo+empresa, incluye cambios de razón social. Comparar dos entre sí parece un bug y no lo es.
- `historico_empleados.codigo_empleado` → es la **cédula**, no un ID interno. Hasta sep-2024 hubo 298 personas con el valor literal `'NaN'` (string) por cédula vacía en la fuente; 1.271 filas se corrigieron, ~688 quedan irrecuperables. También se normalizó un sufijo `".0"` en 1.024 filas.
- `historico_nomina_pyg.empleado_codigo` → **columna vacía en toda la tabla**. Para identificar a la persona en filas `registro_tipo='empleado'` hay que leer `raw_data->>'identificacion'`.
- `historico_nomina_pyg.registro_tipo` → distingue JSON crudo (`respuesta`) de agregados (`resumen`, `concepto`) y del desglose por persona (`empleado`). Sumar sin filtrar por este campo mezcla granularidades y duplica.
- `historico_nomina_pyg.fuente` → `'nomina'` (proveedor de nómina) vs `'pyg'` (indicadores financieros). Dos orígenes distintos en la misma tabla.
- `operacion` (en `historico_empleados` y `historico_ir`) → solo dos valores reales: `"En Operación"` y `"Socio"`. "Socio" = personal de operación de multipropiedad/timeshare, no de hotel.
- `razon_social` → es el NIT empleador legal, **no la propiedad física donde trabaja la persona**. Servihoteles (`SERV`) agrupa personal de varias propiedades; se reclasifica por centro de costo. Varias razones sociales comparten NIT (ej. `CLUB` + `FEB` bajo NIT 900345450; `CCUC` + `CCAN` bajo 900361237).
- `historico_ir.origen` → `'api'` (dato del proveedor), `'snapshot'` (reconstruido comparando fotos mensuales, para propiedades que la API de ingresos/retiros dejó de entregar — CLUB/FEB desde jun-2026), `'ajuste'` (fila insertada a mano para cuadrar un traslado de centro de costo). `'snapshot'` no la borra un re-cierre; `'ajuste'` sí.
- `historico_nomina_pyg` respuesta con `num_empleados = 0` → la API respondió HTTP 200 pero **sin datos** (nómina del mes no cerrada por el proveedor). Se registró como carga "OK" pese a estar vacía.

### 2.5 Acceso de solo lectura

**No existe hoy una vía de consulta de solo lectura para consumo externo.** Verificado: en el servidor PostgreSQL existen los roles `fos_observer` y `str_dashboard_app`, pero **sin ningún permiso otorgado sobre las tablas de este esquema** — no son funcionales para esta base. El usuario que usa la aplicación (`rmartinez`) tiene permisos completos (SELECT/INSERT/UPDATE/DELETE/TRUNCATE). El servidor proxy (`servidor.py`) expone las rutas de lectura `/proxy/historico/*` **sin autenticación** (solo las rutas de escritura `/proxy/admin/*` piden clave). Está documentado como riesgo abierto pendiente de decisión.

### 2.6 Lo que NO debe consultarse nunca desde fuera del proyecto

- **Columnas de identificación y compensación individual de `historico_empleados`:** `codigo_empleado` (cédula), `nombre_completo`, `fecha_nacimiento`, `sexo`, `sueldo_base`. Datos personales bajo Ley de Habeas Data; su exposición cruzada (nombre + cédula + salario) es una fuga.
- **`historico_nomina_pyg` con `registro_tipo='empleado'`:** `raw_data` contiene el recibo de nómina completo por persona. Nunca debe indexarse ni exponerse a consulta libre.
- **`historico_ir`:** nombre, cargo, sueldo y causa de retiro por persona.
- **`socios`:** lista nominal de cédulas de socios.
- **`historico_nomina_pyg` con `registro_tipo` en (`resumen`, `respuesta`) y `fuente='pyg'`:** cifras financieras P&G por propiedad (ingresos, GOP, resultado neto) — dato financiero de la compañía.

---

## 3. APORTE A LA CAPA CONOCIMIENTO (RAG)

| Documento | Tipo | Qué responde que ninguna tabla responde | Ubicación | Formato | Vigencia | Autoridad |
|---|---|---|---|---|---|---|
| `README.md` | manual de usuario | Cómo se arranca, qué stack usa, qué variables de entorno necesita, en qué puerto corre. | Repo Gitea (`main`) | Markdown | vigente | descriptivo |
| `CHANGELOG.md` | bitácora | Qué cambió en cada versión y por qué; historial de decisiones de producto. | Repo Gitea (`main`) | Markdown | vigente | descriptivo |
| `docs/estado-dashboard.md` | bitácora | Estado vivo del proyecto: pendientes priorizados, hallazgos de auditoría, incidentes con el proveedor, decisiones operativas recientes. Copia versionada de la memoria de trabajo. | Repo Gitea (`main` y rama dev) | Markdown | vigente (snapshot con fecha de sincronización) | descriptivo |
| `ficha-relato-dashboard-talento-humano.md` | nota de evidencia | Relato para dirección: qué necesidad resolvía, qué se construyó, qué información antes no existía, dependencias y puntos de atención. | Carpeta del proyecto (local); `NO DOCUMENTADO` si está en la forja | Markdown | vigente | descriptivo |
| `P4_hr_dashboard_trabajo_realizado.md` | acta / nota de evidencia | Documentación exhaustiva del trabajo realizado como entregable del proyecto P4 (HR + Agentes IA). | Repo Gitea (`main`) | Markdown | histórico (última actualización may-2026) | descriptivo |
| `NOMINAAPP_API_ACCESS.  Cambios ir.md` | especificación / contrato | Contrato de la API de NominaApp: endpoints, scopes del token, rate-limit, historial de rotación de credenciales. Documento del proveedor, no de este proyecto. | Repo Gitea (`main`) | Markdown | vigente (v1.8, jul-2026) | normativo (para la integración) |
| `deploy/mac-mini/INSTALACION_MAC_MINI.md` + `README.md` | procedimiento operativo | Cómo se instala y opera el cierre mensual automático en el equipo dedicado. | Repo Gitea (`main`) | Markdown | vigente | normativo |
| `deploy/INSTALACION_JOB_SERVIDOR_API.md` + `deploy/README-cloud.md` | procedimiento operativo | Plan alternativo de despliegue del cierre en un servidor Linux con cron. | Repo Gitea (`main`) | Markdown | **superado** — documentado en julio, nunca se instaló; se optó por el Mac mini | exploratorio |
| Skills operativas (`/merge`, `/db`, `/dev`, `/endpoint`, `/changelog`) | procedimiento operativo | Cómo se fusiona dev→main, cómo se consulta la base, cómo se levanta el servidor. | `.claude/` — **excluido del repo** (`.gitignore`), vive solo local | Markdown | vigente | normativo (para el flujo de trabajo) |

### 3.1 Documento rector

`README.md` para entender qué es y cómo corre; `docs/estado-dashboard.md` para entender en qué estado está y qué está pendiente. Si solo se pudiera leer uno: **`docs/estado-dashboard.md`**, porque condensa arquitectura, decisiones, incidentes y trabajo pendiente en un solo lugar.

### 3.2 Conocimiento que HOY no está escrito y solo vive en la cabeza de alguien

- **Responsable funcional del lado de Talento Humano:** quién valida los datos, quién pide cambios, quién es el usuario real del tablero. `NO DOCUMENTADO`.
- **Criterio de clasificación de causas de retiro como "deseada" vs "indeseada":** está en el código como listas fijas, pero el porqué de cada asignación (y qué hacer con una causa nueva) no está escrito.
- **Mapeo de conceptos de nómina a líneas del P&G:** el criterio contable (qué concepto alimenta qué línea, casos como "DV38 no va a Auxilios", "Lavandería postea bajo Ama de Llaves") vive parcialmente en una memoria de reconciliación de mayo-2026 y parcialmente solo en la cabeza del responsable técnico y de quien maneja la contabilidad de cada hotel.
- **Maña operativa para huecos del proveedor:** cuándo un `num_empleados=0` es "esperar a que cierren" vs "reportar al proveedor"; cuándo re-correr el cierre sin la bandera `--empleados-activos-detalle`. Está en la bitácora como casos sueltos, no como procedimiento.
- **Qué credenciales están dónde y quién las rota:** el token de NominaApp lo rota el equipo del proveedor; el resto (`.env`, base de datos) `NO DOCUMENTADO` quién más los conoce además del responsable técnico.
- **Regla de reclasificación de Servihoteles por centro de costo:** qué propiedades se fusionan y cuáles no (GHS ≠ "The Club", Hotel Caribe no fusiona) — decisiones tomadas caso por caso, registradas en bitácora pero sin norma consolidada.

### 3.3 Regla de contradicción

`NO DOCUMENTADO`. No hay regla escrita. De facto: el código actual y el `CHANGELOG.md` mandan sobre cualquier ficha o memoria; entre documentos, el de fecha más reciente. Pero esto no está declarado en ningún lado.

---

## 4. APORTE A LA CAPA RELACIONES (grafo)

### 4.1 Entidades que este proyecto nombra

- **Sistemas:** NominaApp (proveedor externo de nómina, `api.innfinancial.cloud`), AppsFaranda / API P&G (`app.faranda.online`), PostgreSQL central de Faranda (`172.19.0.160`), Gitea del grupo (`git.faranda.online`), equipo dedicado de cierres (`macserverfos001s-Mac-mini`).
- **Propiedades / razones sociales:** 28 códigos — GHS, Casa Canabal (CCAN), FC Bogotá (CLUB), FC Cartagena (CCAR), FC Cúcuta (CCUC), FC Barranquilla (COLH), FC Medellín, FC Cali (HCAL), Belvedere (FEB), Casa Don Luis (CDON), Casa Bianca (BIAN), Hotel Caribe (MYS), Aloft Bogotá / DORA, Puerta del Sol (PSOL), Bantú (HBAN), Spiaggia (SPIA), Servihoteles (SERV) y variantes, entre otras.
- **Empresas / proveedores:** NominaApp (nómina), el equipo que administra la API P&G de AppsFaranda.
- **Roles:** responsable técnico BI (único), equipo NominaApp, contabilidad por hotel.
- **Conceptos de negocio:** activos inicio/fin de mes, ingresos, retiros, rotación deseada/indeseada, antigüedad (3 definiciones), centro de costo, concepto de nómina, provisión, seguridad social patronal, socio vs operación, P&G / GOP / gasto de personal.

### 4.2 Aristas

- Dashboard Talento Humano → **consume de** → API NominaApp (personal y nómina del mes en curso)
- Dashboard Talento Humano → **consume de** → API P&G AppsFaranda (indicadores financieros por hotel)
- Dashboard Talento Humano → **alimenta a** → `Base de Datos Historicos Talento Humano` (vía cierre mensual)
- Cierre mensual (`cierre_mes.py`, `cargar_historico_nomina_pyg.py`) → **depende de** → API NominaApp + API P&G
- Cierre mensual → **depende de** → equipo dedicado `macserverfos001s-Mac-mini`
- Dashboard Talento Humano → **comparte infraestructura con** → cargas MLX de Faranda (`com.faranda.mlx-glmocr`, `com.faranda.mlx-qwen35-9b`) en el mismo Mac mini
- Dashboard Talento Humano → **consume de** → catálogos internos de unificación (hoteles, cargos, centros de costo) mantenidos vía Excel
- Dashboard Talento Humano → **se entrelaza con** → proyecto Inntime (`NO DOCUMENTADO` la naturaleza exacta del enlace)
- Dashboard Talento Humano → **habilita a** → cualquier proyecto futuro que necesite histórico de personal/nómina gobernado sin depender de la API en vivo
- Proyecto P4 (HR + Agentes IA) → **contiene a** → Dashboard Talento Humano (es su entregable de visualización)

### 4.3 Definiciones compartidas

- **Este proyecto es dueño de:** el maestro de unificación de propiedades (`hotel_unificacion`), el diccionario de cargos unificados (`cargo_unificacion`), el diccionario de centros de costo unificados (`ceco_unificacion`) y el diccionario de conceptos de nómina (`nomina_conceptos`). Cualquier otro proyecto del área que hable de "propiedades Faranda con nómina", "cargos" o "centros de costo" debería consumir estas tablas en vez de reconstruir su propio mapeo.
- **Este proyecto consume (no es dueño de):** el catálogo de NIT / `pyg_company_id` (lo define la operación contable y la API P&G), la nomenclatura de conceptos cruda de NominaApp, y los scopes/rotación del token de la API de nómina (los define el equipo del proveedor).

---

## 5. GOBIERNO DEL DOCUMENTO

### 5.1 ¿Dónde vive la documentación hoy?

- **Repositorio versionado — Gitea del grupo (`git.faranda.online/faranda/rrhh-report`):** `README.md`, `CHANGELOG.md`, `docs/estado-dashboard.md`, `P4_hr_dashboard_trabajo_realizado.md`, `NOMINAAPP_API_ACCESS.  Cambios ir.md`, todo `deploy/`.
- **Carpeta del proyecto en el equipo local, no versionada:** `ficha-relato-dashboard-talento-humano.md`, `ficha-relato-proyecto-innovacion.md`, este mismo archivo de inventario.
- **Espacio local privado, excluido del repo por `.gitignore` (`.claude/`):** memoria de trabajo del proyecto (`PENDIENTES.md` y otras notas), definiciones de comandos operativos. Es la fuente de `docs/estado-dashboard.md`, pero el original no se versiona.
- **Dentro de herramientas:** los catálogos de unificación se editan como archivos Excel (`Unificacion_Hoteles.xlsx`, `Unificacion_Cargos.xlsx`, `Unificacion_CECOs.xlsx`, `Conceptos_Nomina_Mapeo.xlsx`) que sí están en el repo, y se sincronizan a PostgreSQL con un botón del dashboard.
- **Equipo dedicado (Mac mini):** copia del repo en `~/rrhh-report` y logs de cierre en `~/rrhh-report/logs/cloud/` (los logs no se versionan).

### 5.2 Estado respecto de la forja única

| Ubicación | Estado |
|---|---|
| Repo `rrhh-report` en Gitea | **Ya está en el Gitea del grupo.** |
| `ficha-relato-*.md` + este inventario (local) | **Sin control de versiones / migrable.** Falta `git add` + commit. Riesgo mientras tanto: pérdida si falla el disco del equipo local; son el único relato para dirección. |
| Memoria de trabajo `.claude/` (local) | **No migrable tal cual** — es espacio privado del asistente, excluido a propósito. Su contenido relevante ya se replica manualmente a `docs/estado-dashboard.md` en la forja; esa réplica es manual y puede quedar desfasada. |
| Logs de cierre (Mac mini) | **Sin control de versiones**, por diseño (son operativos, rotan). No requieren migración. |
| Excel de unificación | **Ya están en el Gitea del grupo** (en el repo). |

### 5.3 ¿Cómo se sabe que un documento está desactualizado?

- `CHANGELOG.md`: versión y fecha por entrada.
- `docs/estado-dashboard.md`: línea de "última sincronización" con fecha; frontmatter interno con `updated:`.
- `P4_hr_dashboard_trabajo_realizado.md`: frontmatter con `version` y `ultima_actualizacion`.
- `README.md`: **sin fecha ni versión** — se sabe que está al día solo comparándolo con el código.
- Fichas de relato: sin sello de vigencia — se sabe preguntando.
- **No hay un mecanismo uniforme.** Depende del documento.

### 5.4 ¿Quién aprueba un cambio en la documentación normativa?

`NO DOCUMENTADO`. En la práctica lo aprueba y ejecuta el único responsable técnico. No hay revisor ni segunda firma definida.

### 5.5 Frecuencia de cambio

- Código y `CHANGELOG.md` / `docs/estado-dashboard.md`: **por hito** (varias veces por semana en períodos activos, luego semanas sin cambios).
- `README.md`, fichas de relato, docs de `deploy/`: **casi nunca** (solo ante un cambio estructural).
- Datos (no documentación): la base se actualiza **mensual** (cierre) con reintentos los días 5 y 7.

---

## 6. SENSIBILIDAD — QUÉ NO PUEDE INDEXARSE

| Contenido | Qué es | Dónde está | ¿Convive con documentación indexable? |
|---|---|---|---|
| **Datos personales de empleados** | Nombre completo, cédula, fecha de nacimiento, sexo de ~1.000 personas activas y decenas de miles de registros históricos. | Tablas `historico_empleados`, `historico_ir`, `socios` (PostgreSQL). | No en documentos — solo en la base. Pero la base no tiene barrera de solo lectura. |
| **Salarios y nómina individual** | Sueldo base por persona; recibo de nómina completo (conceptos, deducciones, provisiones, seguridad social) por persona y mes desde ene-2024. | `historico_empleados.sueldo_base`; `historico_nomina_pyg` (`registro_tipo='empleado'`, campo `raw_data`). | Solo en la base. |
| **Nombres + cédulas dentro de documentación de texto** | Casos de integridad de datos citan personas reales por nombre completo y cédula (hallazgos de "cargo duplicado", "antigüedad", "filas duplicadas", ajuste manual de IR). | `docs/estado-dashboard.md` (versionado en Gitea) y su original en la memoria local `.claude/`. | **Sí — este archivo mezcla bitácora técnica indexable con nombres y cédulas reales. Es el punto de riesgo principal para RAG.** |
| **Credenciales / tokens / cadenas de conexión** | Clave de la API de nómina, clave de la API P&G, usuario/contraseña de PostgreSQL, `ADMIN_API_KEY` del canal administrativo. | Archivo `.env` local y en el Mac mini — **no versionado** (`.gitignore`). No hay tokens crudos en archivos del repo (verificado). | No conviven con documentación indexable. |
| **Metadatos de credenciales** | Prefijo del token (`ri_60415`), ID interno, owner, scopes, historial de rotación, rate-limit, host del proveedor. | `NOMINAAPP_API_ACCESS.  Cambios ir.md` (versionado en Gitea). | **Sí — documento técnico útil que además revela la estructura y el ciclo de vida de la credencial.** |
| **IP interna del servidor central** | `172.19.0.160:5432` (host de PostgreSQL y de la API de nómina). | `CHANGELOG.md`, `PENDIENTES.md`, `docs/estado-dashboard.md`, `deploy/*.md`, `P4_hr_dashboard_trabajo_realizado.md` — todos versionados. | **Sí — aparece repetida en casi toda la documentación operativa.** |
| **Cifras financieras de la compañía** | Ingresos, GOP, resultado neto, gasto de personal por propiedad y mes (P&G). Cifras reales de Hotel Caribe usadas como ejemplo en la memoria de P&G. | `historico_nomina_pyg` (`fuente='pyg'`); memoria `project_pyg_excel` (local, no versionada). | La memoria de P&G local mezcla metodología (indexable) con cifras reales de un hotel. |
| **Condiciones comerciales con proveedores** | Rate-limit, TTL de caché, scopes contratados con NominaApp. | `NOMINAAPP_API_ACCESS.  Cambios ir.md`. | Sí, dentro del mismo documento técnico. |

---

## 7. PREGUNTAS QUE HOY NADIE PUEDE RESPONDER

1. "¿Quién en Talento Humano es el dueño funcional de este tablero — quién valida que los números están bien y quién pide los cambios?" `[CONOCIMIENTO]`
2. "¿Desde qué fecha exacta está en producción y quién lo usa de verdad — cuántas personas lo abren, con qué frecuencia?" `[CONOCIMIENTO]` (la parte de uso sería `[DATO]` si se instrumentara)
3. "Si aparece una causa de retiro nueva que no está en las listas, ¿va a rotación deseada o indeseada, y quién decide?" `[CONOCIMIENTO]`
4. "¿Qué concepto de nómina alimenta cada línea del P&G, y por qué algunos no cuadran (asientos manuales de contabilidad)?" `[CONOCIMIENTO]`
5. "Cuando el proveedor devuelve una propiedad vacía o con error, ¿cómo sé si toca esperar o toca escalar, y a quién escalo?" `[CONOCIMIENTO]`
6. "Si el responsable técnico no está disponible, ¿quién puede levantar el servidor, correr un cierre manual o rotar una credencial?" `[CONOCIMIENTO]` + `[RELACIÓN]`
7. "¿Qué otros proyectos del área leen esta base de datos o dependen de estos catálogos de hoteles/cargos, y se romperían si cambio un nombre?" `[RELACIÓN]`
8. "¿En qué consiste exactamente el enlace con Inntime — quién alimenta a quién?" `[RELACIÓN]`
9. "¿Cuántos meses-hotel tienen la nómina completa cargada y cuántos tienen huecos, hoy?" `[DATO]` (calculable ya, pero nadie lo tiene como indicador)
10. "¿Qué se hace si el equipo dedicado del Mac mini se cae el día 1 del mes — hay un plan B y quién lo ejecuta?" `[CONOCIMIENTO]`

---

## 8. RIESGOS DE INDEXACIÓN

- **`docs/estado-dashboard.md` mezcla bitácora técnica con datos personales reales.** Si se indexa tal cual, una pregunta sobre "el bug de antigüedad" puede devolver el nombre completo y la cédula de un empleado concreto. Requiere anonimizar antes de indexar, o excluirlo.
- **`NOMINAAPP_API_ACCESS.  Cambios ir.md` y los `deploy/*.md` exponen IP interna, estructura del token y su historial de rotación.** Útiles para operar, peligrosos indexados: dan a cualquier consultante del RAG el mapa de la infraestructura y del ciclo de vida de la credencial.
- **`deploy/INSTALACION_JOB_SERVIDOR_API.md` describe un despliegue que nunca ocurrió**, redactado en presente y con el mismo tono normativo que el de Mac mini (que sí es real). Un lector — o el RAG — puede tomarlo como la instalación vigente. Debería marcarse explícitamente como "superado / no implementado".
- **`ficha-relato-*.md` y `P4_hr_dashboard_trabajo_realizado.md` describen el estado a una fecha pasada** sin sello visible de vigencia; afirmaciones como "próximo hito: certificar el cierre de septiembre" ya quedaron obsoletas y siguen escritas como futuras.
- **Cifras de ejemplo que parecen reales:** la memoria de P&G contiene cifras financieras reales de Hotel Caribe presentadas como "resultado de ejemplo del script". Indexadas, se leen como dato de negocio consultable.
- **Decisiones revertidas escritas como vigentes:** la reclasificación de Servihoteles se aplicó, se revirtió parcialmente (GHS, Hotel Caribe) y se volvió a ajustar varias veces; la bitácora conserva las versiones intermedias. Un RAG puede devolver la regla equivocada por similitud.
- **Contradicción sobre la base de datos:** varios documentos aún mencionan la base local `Base de Datos Talento Humano` como si fuera la de producción; la real es la remota `Base de Datos Historicos Talento Humano`. Sin la regla de contradicción escrita (3.3), el RAG no tiene forma de saber cuál gana.
- **El `.env` está bien excluido, pero el patrón de exclusión depende de `.gitignore`.** Un `git add -f` o un clon mal configurado del Mac mini rompería la única barrera que hoy protege las credenciales.

---

*Área de Innovación · Faranda Hotels & Resorts · Inventario generado 2026-09-09*