# Manual de Uso de GSD REOS

Guia para el equipo de GSD que va a operar el sistema: gerencia, asesores comerciales y area financiera. Lenguaje claro, sin tecnicismos. Le dice que puede usar hoy y que se activa en la siguiente fase.

Cada seccion marca con claridad dos estados:

- Disponible hoy: lo puede usar y mostrar funcionando ahora mismo.
- Se activa en la siguiente fase: ya esta construido y probado, pero esta apagado hasta cumplir un requisito (un numero telefonico, una clave, una base de datos o la firma del acuerdo comercial).

Regla de la casa que el sistema respeta en todo momento: los motores calculan, la IA solo narra, ningun numero se inventa. Si falta un dato, el sistema muestra "Pendiente". Nunca un cero fabricado.

---

## Indice

1. Que es GSD REOS, en una pagina
2. Como acceder al sistema
3. Centro Ejecutivo: el tablero de las 8 tarjetas
4. Los modulos de trabajo
   4.1 Caja y margen (tesoreria 30-60-90)
   4.2 Presupuesto (variance por partida)
   4.3 Captacion (valuacion y screening legal)
   4.4 Mercado (precio por metro cuadrado por zona)
5. El agente comercial es-PE por chat
6. El funnel de leads
7. El sistema de llamadas con IA
8. Buenas practicas y limites actuales
9. Soporte y proximos pasos

---

## 1. Que es GSD REOS, en una pagina

GSD REOS (Real Estate Operating System) es un sistema operativo digital que ayuda a correr un desarrollo inmobiliario de principio a fin: desde mirar la compra de un terreno hasta la venta de las unidades. Lo construye Bimbi Digital para GSD Tecnologia. El proyecto piloto real con el que esta cargado hoy es Urb. Alborada (Alameda del Rocio, Santiago de Surco, Lima).

El sistema tiene dos puertas que se apoyan sobre un mismo cerebro:

1. Un motor financiero tipo gerencia. Calcula factibilidad, precios, tesoreria, riesgo y rentabilidad (VAN, TIR, ROI). Le da a la gerencia respuestas de directorio con numeros que puede defender.
2. Un agente comercial en espanol peruano. Conversa por chat con los interesados que llegan por un QR o una landing, los capta, los califica y propone agendar una visita.

La idea central que hace confiable al sistema: la matematica la hacen motores que estan probados contra un estudio independiente, y la IA solo cuenta en palabras lo que esos motores ya calcularon. Si todavia no hay un dato (por ejemplo, la tasa de descuento para calcular el VAN), el sistema deja el campo en "Pendiente" en lugar de inventar un numero. Esto es a proposito.

Por que importa para GSD: GSD es una empresa de IT y nube privada. Por eso el sistema esta disenado para que los datos sean suyos. Puede correr sin depender de nube publica, sin credenciales externas, con la informacion guardada localmente. Usted decide cuando encender cada pieza.

---

## 2. Como acceder al sistema

### La demo en linea (Disponible hoy)

URL de la demo: gsd-bimbi-digital.vercel.app

Esta es la version de chat y tablero que puede abrir desde cualquier navegador. Es la cara publica para mostrar el producto. Importante: la demo en linea es solo texto y chat. El agente de voz por telefono no esta vivo en esta direccion (vea la seccion 7).

### Basic Auth en produccion (Disponible hoy)

En el entorno de produccion el sistema esta protegido con una clave de acceso (usuario y contrasena, lo que se llama Basic Auth). Si entra sin la clave, el sistema responde con un bloqueo y no muestra nada. Esto es intencional: es a prueba de fallos, si la clave no esta configurada, el sistema se cierra en lugar de abrirse.

Aclaracion honesta de alcance: esta clave es una sola credencial compartida para todo el equipo. Sirve como candado de la fase inicial. No es todavia un sistema de usuarios con roles separados (gerente, asesor, financiero, obra). Ese control de identidad por persona y por rol esta planeado para una fase posterior.

Ademas, el sistema le dice a los buscadores de internet que no lo indexen, asi la demo no aparece en Google.

### Nota sobre el entorno local

Cuando el equipo de Bimbi corre el sistema en su propia computadora para desarrollo (entorno local, fuera de produccion), ese candado de Basic Auth se saltea a proposito para poder trabajar agil. El candado solo aplica en produccion. Tengalo presente: si alguien le muestra el sistema desde una laptop sin pedir clave, es porque esta en modo local, no porque el candado falle.

---

## 3. Centro Ejecutivo: el tablero de las 8 tarjetas

Ruta: /app/dashboard

Disponible hoy.

Es la primera pantalla para gerencia. Responde de un vistazo si el proyecto esta ganando, quemando caja o entrando en riesgo. Son 8 tarjetas de solo lectura, mas una narrativa de briefing (un resumen en palabras), un bloque de Alertas y un bloque de Decisiones recomendadas.

Cada tarjeta toma su cifra de un motor real. Ninguna cifra esta escrita a mano.

### Las 8 tarjetas

1. Caja libre a 90 dias. Cuanta caja queda disponible mirando los proximos 90 dias. Avisa si hay un quiebre de caja proximo.
2. Margen forecast vs plan. Como va el margen proyectado contra lo que se planeo.
3. Profit at Risk (utilidad en riesgo). Cuanta utilidad esta expuesta por desviaciones o por cobranza pendiente.
4. Proyecto mas critico. Cual proyecto necesita atencion primero (util cuando haya varios).
5. Partida mas desviada. Que partida de costos se salio mas de lo presupuestado.
6. Ventas comprometidas. Cuanto se ha comprometido en ventas, con separaciones activas.
7. Cobranza vencida. Cuanto dinero por cobrar ya paso su fecha.
8. Decision recomendada. La recomendacion que el sistema sugiere segun todo lo anterior.

### Como leer un "Pendiente" honesto

Esto es lo mas importante de entender. Cuando una tarjeta no tiene el dato necesario, muestra la palabra "Pendiente" con una linea que explica que falta. No muestra un cero.

Por que: un cero podria leerse como "todo bien, cero problema", cuando en realidad significa "no hay dato". Para no enganar a quien decide, el sistema separa esas dos cosas. "Pendiente" quiere decir: falta cargar este dato. Cero quiere decir: el motor calculo y el resultado es cero.

Cada tarjeta tambien muestra debajo de donde sale su numero (la fuente, es decir que motor lo calculo) y un detalle. Eso le da trazabilidad: puede saber por que un numero es lo que es.

### Drill (entrar al detalle)

Las tarjetas financieras son clickeables. Al hacer click, lo llevan al modulo correspondiente para ver el detalle (por ejemplo, una tarjeta de caja lo lleva al modulo de Caja y margen).

---

## 4. Los modulos de trabajo

Todos los modulos de esta seccion estan Disponibles hoy y corren sobre los datos semilla de Urb. Alborada.

### 4.1 Caja y margen (tesoreria 30-60-90)

Ruta: /app/cash-margin

Disponible hoy.

Muestra una proyeccion real de la tesoreria del proyecto. Que vera:

- La proyeccion de caja a 30, 60 y 90 dias (y horizontes mas largos).
- El primer quiebre de caja: la primera fecha en que la caja se pondria en rojo, si la hubiera.
- La brecha de financiamiento: cuanto dinero faltaria cubrir.

Para que sirve a financiero y gerencia: ver con anticipacion cuando el proyecto necesitaria mas caja, antes de que sea una urgencia.

### 4.2 Presupuesto (variance por partida)

Ruta: /app/budget

Disponible hoy.

Compara lo presupuestado contra lo real, partida por partida. Cada partida muestra su variacion con un semaforo de alerta:

- Amarillo: la partida se desvio mas de 5 por ciento.
- Rojo: la partida se desvio mas de 10 por ciento.

Tambien marca con una bandera "Observado" las partidas que requieren atencion. Asi el equipo de obra y financiero ve de inmediato donde se esta yendo el costo.

Nota de alcance: el control de costos cubre hoy 8 de las 10 partidas del proyecto piloto.

### 4.3 Captacion (valuacion y screening legal)

Ruta: /app/captacion

Disponible hoy.

Es la herramienta para evaluar terrenos o propiedades candidatas a compra. Para cada candidato muestra:

- Valuacion por comparables. Una estimacion de valor respaldada por propiedades comparables ponderadas. Si no hay comparables suficientes, en lugar de inventar muestra un "Sin valorizacion" honesto.
- Screening legal (semaforo legal). Una revision de hallazgos legales donde cada hallazgo queda citado a su documento de origen. Es decir, no le dice "hay un problema" sin decirle de que documento sale.
- Acciones humanas. Botones para registrar acciones reales del equipo: pedir perito, pedir abogado o publicar. Al usarlos, el sistema guarda la accion y recarga la vista.

Para que sirve a comercial y gerencia: decidir con criterio si un candidato vale la pena, con sustento de valor y de revision legal en una sola pantalla.

### 4.4 Mercado (precio por metro cuadrado por zona)

Ruta: /app/mercado

Disponible hoy.

Muestra el precio por metro cuadrado por zona, calculado a partir de comparables de ventas ya cerradas. Para cada zona vera:

- El precio por metro cuadrado.
- La mezcla de procedencia (de donde salen los datos).
- Un chip de confianza, que indica que tan solido es el dato segun cuantos cierres lo respaldan.
- El conteo real de cierres detras del numero.

Puede expandir una zona (por ejemplo Barranco, Miraflores, San Isidro o Santiago de Surco) para ver los comparables anonimizados y la tendencia mensual.

Limite importante: este modulo trabaja hoy sobre datos semilla (4 zonas, alrededor de 24 transacciones). Es un agregado genuino sobre esos datos, no un feed vivo conectado al mercado en tiempo real. La conexion a fuentes de precios y absorcion en vivo es de una fase posterior.

---

## 5. El agente comercial es-PE por chat

Disponible hoy (canal de chat y texto).

Es el vendedor virtual en espanol peruano. Conversa con el interesado, lo capta, lo califica y lo lleva hacia agendar una visita. Como funciona en la practica:

### Como conversa

La conversacion avanza por etapas ordenadas, sin saltarse pasos:

1. Saludo.
2. Consentimiento. Antes de capturar datos, pide permiso para tratar la informacion personal, en cumplimiento de la Ley 29733 de proteccion de datos.
3. Captura. Toma los datos del interesado.
4. Presentacion y calificacion. Presenta el proyecto y califica al prospecto con un puntaje calculado (no a ojo).
5. Agendado. Propone horarios de visita.
6. Cierre.

### El grounding guard (el control que evita que invente)

Esta es la pieza de confianza. Si el agente esta por afirmar un precio o una disponibilidad que no tiene respaldo de un motor, el grounding guard lo detecta y reescribe la respuesta para que no afirme algo que no puede sustentar. En la practica: si usted le pide un precio que el sistema no tiene confirmado, el agente se rehusa con elegancia y difiere, en lugar de inventar una cifra.

Esto protege la credibilidad de GSD frente al cliente final: el agente nunca promete un numero que no pueda cumplir.

### Calificacion y agendado

El puntaje de calificacion del lead es determinista (la misma entrada da el mismo puntaje, no depende del humor del modelo). Con base en eso, propone horarios de visita y cierra.

Nota tecnica para el area de sistemas: si alguien conectara un modelo de IA en la nube sin la autorizacion explicita del entorno, el sistema responde con un bloqueo (un error 503) en lugar de mandar datos afuera. Es otra capa de soberania de datos.

---

## 6. El funnel de leads

Es el recorrido de un interesado desde que llega hasta que se convierte en una operacion. Aqui conviven partes que ya estan vivas hoy y partes que se activan en la siguiente fase. Las separamos con claridad.

### Intake con atribucion de ads (Disponible hoy)

Cuando un interesado llena un formulario, el sistema crea un lead y guarda de donde vino: la fuente del anuncio, el medio, la campana, el identificador del anuncio y los parametros utm. Esto le permite a comercial saber que campana paga esta trayendo a cada interesado. Funciona incluso sin base de datos conectada.

### Estados de disposicion (Disponible hoy, logica pura)

Cada lead tiene un estado de seguimiento que avanza por un arbol definido: nuevo, llamar, mensaje, llamar de nuevo, y finalmente congeladora si no responde. El sistema lleva la cuenta de los intentos y reconoce cuando un lead llego a un estado terminal. Esta logica esta completa y probada.

### Deal al convertir (Disponible hoy, en memoria)

Cuando un lead se convierte (por ejemplo, separa una unidad), el sistema registra la conversion, marca la unidad y abre un Deal con el monto pactado, la moneda y el estado "separado".

Limite que hay que tener claro: hoy esa apertura de deal ocurre en memoria. La persistencia durable de deals y de citas (que queden guardados de forma permanente) se activa cuando se conecte la base de datos Postgres. Hasta entonces, son registros de la sesion.

### Aviso de lead al vendedor (Disponible hoy solo el texto)

El sistema sabe armar el mensaje de aviso al vendedor cuando entra un lead nuevo, en espanol peruano y con los datos personales enmascarados por privacidad. El texto se genera correctamente. Lo que todavia no ocurre es el envio real por un canal (vea la seccion 8).

### Lo que se activa en la siguiente fase

- Que el funnel corra solo de punta a punta, procesando leads vencidos de forma automatica. Hoy la pieza que procesa leads arranca vacia y no se alimenta sola del listado real de leads. Es un puente conocido y pendiente.
- Que el estado del funnel viva en la base de datos Postgres. Hoy vive en memoria.

---

## 7. El sistema de llamadas con IA

Estado real: construido y probado fuera de linea, se activa en la siguiente fase. El camino de llamada en vivo todavia no se ha probado contra una llamada real.

Que hace (cuando este encendido): atiende o realiza una llamada telefonica de verdad y la conecta en vivo con el cerebro de GSD. El interesado habla por telefono, su voz se transcribe a texto, ese texto va al cerebro, el cerebro responde, la respuesta se convierte en voz y se le devuelve al interesado. Incluye corte por interrupcion (si la persona habla encima, el agente se calla y escucha). Igual que en el chat, el agente de voz solo dice numeros que los motores le entregan: no inventa.

Que esta listo hoy: todo el motor de voz esta escrito y probado fuera de linea, en la computadora local, sin conectarse a la red telefonica. Funciona en pruebas controladas.

Que falta para encenderlo (siguiente fase):

- Un numero telefonico peruano (+51) y la linea para conectarlo.
- Las claves de los servicios de voz (transcripcion y sintesis de voz).
- La firma del acuerdo comercial.

El servicio que corre las llamadas esta desplegado en modo apagado a proposito (en cero instancias activas). Encenderlo es un solo paso deliberado de la siguiente fase, no un olvido.

Que NO afirmar hoy, para evitar malentendidos con clientes:

- Hoy no se puede tomar ni hacer una llamada real. No hay numero, ni linea, ni claves conectadas.
- El canal de voz no esta vivo en la demo en linea. La demo en linea es solo chat.

El canal comercial vivo hoy es el chat (seccion 5). La voz llega despues.

---

## 8. Buenas practicas y limites actuales

### Buenas practicas

- Use el Centro Ejecutivo como punto de partida cada manana: las 8 tarjetas y el briefing le dan el estado del proyecto en un minuto.
- Confie en los "Pendiente". Son honestos. Si una tarjeta dice "Pendiente", el camino correcto es cargar el dato que falta, no asumir que es cero.
- Para decisiones de directorio, apoyese en que cada numero tiene su fuente trazada. Puede mostrar de donde sale.
- Para el cliente final, deje que el agente maneje precios y disponibilidad. El grounding guard esta ahi justamente para que nadie prometa de mas.

### Limites actuales (sea honesto al presentar)

- Datos semilla. Todo corre hoy sobre los datos del piloto Urb. Alborada. Los modulos son reales, los datos son de ejemplo cargados a mano. Cuando GSD entregue datos propios, el sistema los usa.
- Todavia no envia email. La secuencia de nutricion por correo arma el contenido, pero el envio real no esta conectado (falta el servidor de correo). Hoy no sale ningun email.
- Todavia no llama por telefono. Vea la seccion 7. El motor esta listo, la linea no.
- Todavia no avisa por Telegram ni otro canal. El texto del aviso se genera, pero ningun canal lo entrega aun.
- Persistencia apagada por defecto. Deals, citas y el estado del funnel viven en memoria hasta conectar la base de datos. Reiniciar pierde lo que estaba en memoria.
- Ingestion de documentos limitada. Hoy el sistema lee presupuestos en formato CSV y parametros municipales. Leer PDF y Excel todavia no esta habilitado.
- Vista 360 del proyecto. La pantalla de detalle completo por proyecto todavia no esta construida (muestra un marcador de "en construccion").
- Sin usuarios por rol todavia. El acceso es por una clave compartida. Los roles por persona (gerente, asesor, financiero, obra) son de una fase posterior.
- Los importes son estimaciones. Cualquier monto de costo o precio que vea es estimacion de planeacion para validar, no una cotizacion firme.

### Resumen rapido: que esta vivo y que no

Disponible hoy:

- Centro Ejecutivo con las 8 tarjetas y briefing.
- Caja y margen (tesoreria 30-60-90).
- Presupuesto (variance con semaforo amarillo y rojo).
- Captacion (valuacion por comparables y screening legal citado).
- Mercado (precio por metro cuadrado por zona, sobre datos semilla).
- Agente comercial por chat con grounding guard.
- Intake de leads con atribucion de ads y estados de disposicion.

Se activa en la siguiente fase:

- Llamadas con IA por telefono (+51, claves, acuerdo firmado).
- Envio real de email, avisos por Telegram u otros canales.
- Persistencia permanente en base de datos (deals, citas, funnel).
- Feeds de mercado en vivo.
- Usuarios y roles por persona.
- Lectura de PDF y Excel.
- Vista 360 del proyecto.

---

## 9. Soporte y proximos pasos

### Soporte

El sistema lo construye y mantiene Bimbi Digital para GSD Tecnologia. Para reportar un problema, pedir un dato cargado o solicitar una activacion de fase, escriba al contacto de Bimbi asignado al proyecto.

Cuando reporte algo, ayuda incluir: la ruta donde paso (por ejemplo /app/budget), que esperaba ver y que vio, y si fue en la demo en linea o en otro entorno.

### Proximos pasos sugeridos

1. Validar los datos del piloto Urb. Alborada y entregar a Bimbi los datos reales que reemplacen las semillas.
2. Definir y entregar la tasa de descuento para que el VAN deje de estar en "Pendiente".
3. Decidir la fecha para activar la persistencia en base de datos (deja todo guardado de forma permanente).
4. Iniciar el procuramiento del numero +51 y las claves de voz, que es el item de mayor tiempo de espera, para habilitar las llamadas con IA.
5. Cerrar el acuerdo comercial, que es lo que destraba la activacion de la infraestructura y de la voz.

Nota sobre costos: cualquier cifra de inversion o tarifa que se converse es una estimacion de planeacion para validar, no una cotizacion comprometida. Las cifras finales se definen al firmar.