Manual de Usuario — Sistema GIS Hacienda Morayma

Versión del manual: 1.6 · Fecha: 8 de agosto de 2026 Dirección: https://gis.haciendamorayma.com Este manual siempre está disponible actualizado dentro de la app: botón ❓ Ayuda → 📖 Manual completo. (El historial de cambios del sistema está en CHANGELOG.md)

1. Qué es este sistema

Es la plataforma de la finca para: ver y dibujar el mapa (parcelas, agua, construcciones, caminos, riego, árboles, sensores), registrar la producción (café, cacao, cabras, ovejas, gallinas, guadua, agua) y consultar resúmenes. Funciona en el navegador de la computadora y del celular, incluso sin señal en el campo.

2. Entrar al sistema

1. Abre https://gis.haciendamorayma.com — verás la pantalla de inicio con tres botones grandes: Mapa, Producción e Información. Toca el que necesites.
2. Escribe tu usuario y contraseña (los entrega el administrador).
3. En el celular, instálala como app: menú del navegador → "Agregar a pantalla de inicio". Queda con su ícono y abre a pantalla completa.

Tipos de usuario:

Protección de los datos (archivar en vez de borrar): nadie elimina información. El botón 🗄 archiva el registro pidiendo un motivo; deja de contar en los totales pero permanece guardado con el nombre de quién lo archivó y por qué. Para verlos, marca 🗄 Ver archivados en los filtros de Producción: aparecen tachados y en gris, con un botón ♻️ que los restaura de un clic. Los usuarios con rol Operador no ven ninguno de estos botones — solo pueden registrar.

Cambiar tu contraseña: en la página 📋 Producción → enlace 🔑 Contraseña (pide la actual y la nueva, mínimo 8 caracteres).

Cerrar sesión: botón 🚪 presente en todas las pantallas (en el mapa y el kiosco, en la barra superior; en las demás, en la cabecera). Importante: si tienes registros pendientes de enviar, el sistema te avisa — es mejor esperar a tener señal para que se sincronicen antes de salir. Al cerrar sesión también se borra el acceso sin señal de ese equipo.

3. El mapa

Moverse: arrastra para desplazarte; rueda del mouse o pellizco para zoom. La esquina inferior derecha muestra las coordenadas del cursor.

Panel de capas (derecha; en celular, botón 🗂):

• Base: OpenStreetMap o Satélite.
• Ortofotos: las fotos aéreas de dron. Se agregan solas cuando el administrador sube una nueva. La última que enciendas queda encima — útil para comparar vuelos de fechas distintas.
• Finca: las capas de trabajo, cada una con su color:

4. Consultar y editar datos de un objeto

En modo 🖐 Navegar, toca cualquier objeto → aparece su ficha con los datos y dos botones:

• Editar datos: cambia nombre, uso, tipo, etc. (no la forma).
• Eliminar: borra el objeto (pide confirmación; requiere señal).

Si dos objetos están encimados, apaga temporalmente la capa de arriba en el panel.

5. Dibujar objetos nuevos

1. Elige la capa en el selector de la barra superior.
2. Toca ✏️ Dibujar: clic por cada vértice; doble clic termina (los puntos son un solo clic). ESC cancela.
3. Llena el formulario y Guardar.

El dibujo se "pega" solo a los bordes existentes (snap) para no dejar huecos. Las áreas de parcelas se calculan solas en hectáreas.

Editar la forma: botón 🔧 Editar forma → toca el objeto → arrastra sus vértices. Arrastrar un borde crea un vértice; Alt+clic sobre un vértice lo elimina. Se guarda solo al soltar (requiere señal).

Medir: 📏 Distancia y ⬛ Área — solo consultan, no guardan nada.

6. Herramientas GPS (en el celular)

• 📍 GPS: muestra tu posición con un círculo azul de precisión. La primera vez el navegador pedirá permiso de ubicación — acéptalo. Bajo árboles la precisión baja (±10-25 m); a cielo abierto es de ±3-10 m.
• ⊕ Aquí: crea un punto de la capa seleccionada donde estás parado. Ejemplo: llegas al ojo de agua → capa "Puntos de agua" → ⊕ Aquí → formulario → listo. Si la precisión es mala (> ±15 m) te avisa antes.
• ▶ Ruta: graba tu caminata como línea (roja mientras grabas). Al tocar ⏹ Parar, le pones nombre y tipo y queda guardada en Recorridos.
• 📶 Señal: toma una muestra de la calidad de red cada 6 segundos mientras caminas. Enciende la capa "Señal WiFi (heatmap)" para ver el resultado: rojo = zona con mala señal (ahí falta antena). Las muestras tomadas sin conexión se guardan y suben solas.

Inventario de árboles: capa "Árboles" → párate junto al árbol → ⊕ Aquí → el formulario recuerda la especie del anterior, así que una fila de aguacates se registra en segundos por árbol. Si un árbol muere, edítalo y cambia su estado (no lo borres — se conserva el historial).

7. Trabajar sin señal (modo offline)

La app funciona en el campo aunque no haya WiFi ni datos:

• Requisito único: haber entrado al sistema con conexión al menos una vez en ese teléfono.
• Sin señal verás el mapa de las zonas que ya habías visitado y todas las herramientas de captura funcionan.
• Todo lo que guardes aparece en el contador naranja "⏳ N sin enviar" (abajo a la izquierda).
• Al volver la señal, se envía solo (máximo 30 segundos) y el contador desaparece. No hagas nada.
• Lo que no funciona sin señal: editar formas, eliminar objetos y editar registros existentes — la app te lo dirá.

7b. 🖥 Modo Kiosco (registro rápido para operadores)

Pensado para la pantalla táctil de la finca o para quien solo necesita registrar. Desde la pantalla de inicio → Modo Kiosco:

1. ¿Qué vas a registrar? — toca la categoría (☕ café, 🐐 cabras, 🐔 gallinas...).
2. ¿Qué pasó? — toca el evento (cosecha, ordeño, recolección de huevos...).
3. ¿Cuánto? — teclea la cantidad en el teclado grande → Seguir → revisa el resumen → ✓ GUARDAR.

Flujos especiales del Kiosco (el sistema adapta las preguntas al evento):

• Ordeño: solo lista las hembras en lactancia, con "parió hace X días" bajo cada una. Se mide en litros.
• Monta: solo las hembras candidatas (pasado el descanso post-parto) y luego el macho. Devuelve la fecha probable de parto.
• Parto: eliges la madre y marcas una por una las crías (♀/♂) — al guardar se crean sus fichas con código, madre, padre (tomado de la monta registrada) y raza heredada. También existe "sin crías vivas".
• Compra: da de alta un animal nuevo preguntando solo el sexo; su raza y datos se completan después en 🐐 Animales.
• Muerte / venta: el animal sale del hato activo automáticamente (deja de aparecer en ordeño, montas y conteos) pero conserva todo su historial y su descendencia.
• Vacunación / desparasitación: el kiosco muestra los productos del catálogo — en verde los permitidos en orgánico, en rojo los convencionales con su retiro. Al elegir uno, el tratamiento queda en el historial sanitario del animal y el sistema calcula hasta qué fecha su leche o carne no son comercializables.
• Café, cacao y guadua: piden en qué parcela antes de la cantidad, para tener trazabilidad por lote.
• Secado, mantenimiento, incidencia: no piden cantidad, son hechos.

Estos flujos requieren señal porque crean o modifican fichas de animales; el ordeño y los registros simples sí funcionan offline.

La pantalla de confirmación evita errores, el registro queda con la fecha de hoy, y funciona sin señal igual que el resto (queda "⏳ sin enviar" y sube solo). El botón ← arriba a la izquierda regresa un paso, o al inicio.

8. Página 📋 Producción

Registra los eventos del día a día: cosechas, ventas, nacimientos, vacunaciones, recolección de huevos, cortes de guadua, lecturas de agua.

1. Nuevo registro: fecha (hoy por defecto), categoría → los eventos y la unidad se ajustan solos → cantidad, parcela (opcional) y notas.
2. Tabla: filtra por categoría, parcela y fechas. ✏️ edita, 🗑 elimina (solo el autor del registro o el administrador).
3. Resumen semanal: lo del día a día — totales de lunes a domingo por categoría y evento, con botones para moverte a semanas anteriores o volver a esta semana. Al lado muestra cuántos registros hubo, cuántos animales se tocaron y quiénes registraron, más los partos de la semana.
4. Resumen mensual: totales por categoría y evento, mes a mes, con selector de año.

También funciona offline: los registros nuevos quedan "sin enviar" y suben solos.

8b. 🐐 Animales (inventario individual con genealogía)

Cada animal del hato tiene su ficha con código único (el del arete/tag físico: CAP-001, OVI-014...). Se accede desde el enlace 🐐 Animales (inicio o Producción).

Registrar un animal: elige la especie (el código se sugiere solo), sexo, nombre, raza (lista con las razas conocidas de esa especie — primero las adaptadas al trópico; si falta alguna, "➕ otra raza..." la agrega al catálogo), fecha de nacimiento y el origen: nacimiento (nació en la finca), compra (adquirido), o carga inicial (los animales que ya tenías al arrancar el sistema).

La genealogía: al registrar un nacimiento, selecciona la madre y el padre de las listas (solo aparecen animales de la misma especie y del sexo correcto). Con eso el sistema arma solo el árbol familiar: el botón 👪 de cada animal muestra sus abuelos, padres e hijos — la base para decidir cruces y evitar consanguinidad.

Cartilla del animal (dashboard): en 🐐 Animales, toca cualquier fila de la tabla (o el botón 📊 Cartilla) para abrir la ficha completa: indicadores arriba (edad, peso actual, ganancia diaria de peso, condición corporal, partos, crías por parto, intervalo entre partos), gráficas de evolución de peso, condición corporal y producción (curva de lactancia), historial sanitario, genealogía, composición racial y estado reproductivo. Desde la tabla de Producción, hacer clic en el código del animal abre directamente su cartilla.

Botones al pie de la cartilla para registrar en el momento: ➕ Peso, ➕ Condición (escala 1-5) y ➕ Tratamiento. En tratamientos se piden los días de retiro en leche y carne — si hay un retiro vigente, la cartilla lo muestra en rojo con la fecha desde la cual el producto vuelve a ser comercializable (requisito de la certificación orgánica).

Qué conviene registrar de cada animal: peso (mensual en crecimiento, trimestral en adultos), condición corporal (al parto, al secado y en revisiones), producción por ordeño, tratamientos sanitarios con su retiro, y los eventos reproductivos. Con eso el sistema calcula solo el resto.

Ciclo reproductivo (el estado se calcula solo): no hay que marcar a mano quién está preñada o en ordeño. El operador registra hechos desde el Kiosco — monta (con qué macho), parto, secado — y el sistema deriva todo lo demás:

• Fecha probable de parto = monta + gestación de la especie (cabras 150 días, ovejas 147, vacas 283, cerdas 114, yeguas 340).
• En ordeño: las hembras que parieron y aún no se han secado. Al ordeñar, el Kiosco solo muestra esas — no hay que buscar entre todo el hato.
• Listas para monta: las que pasaron el descanso post-parto (60 días por defecto), las secas y las vacías con edad suficiente.
• Avisos: cuándo toca confirmar preñez, cuándo conviene secar antes del parto, y qué hembras pasaron su fecha probable sin registrar el parto.

Todo esto se ve de un vistazo en el panel 🐣 Reproducción — qué toca ahora de la página Animales, y en la ficha 👪 de cada hembra con su historial completo. Los parámetros por especie (días de gestación, lactancia, descanso) se pueden ajustar en la base si tu manejo es distinto.

Composición racial automática: la ficha 👪 calcula el porcentaje de cada raza del animal a partir de su genealogía (cada padre aporta 50%, hacia atrás por generaciones) y lo muestra en una barra de colores. Si la mezcla coincide con una raza compuesta reconocida, lo indica: por ejemplo, 50% Brahman + 25% Hereford + 25% Shorthorn se identifica como Beefmaster. Las razas compuestas se expanden solas a sus componentes, así que un cruce de dos Brangus sigue calculando bien. El porcentaje "sin determinar" señala dónde faltan datos: registrar la raza de los animales base mejora el cálculo de todos sus descendientes.

Carga masiva del hato (importar desde Excel): en 🐐 Animales, sección 📥 Importar hato:

1. ⬇️ Descargar plantilla Excel — trae tres hojas: Hato (donde llenas, con listas desplegables para especie, sexo, origen y estado), Instrucciones y Razas (las 117 del catálogo, para copiar el nombre exacto).
2. Llena una fila por animal. Obligatorios: código, especie, sexo y origen. Borra la fila de ejemplo. Pon primero los adultos y después las crías, así puedes escribir el código de la madre y del padre de cada cría.
3. Sube el archivo y toca Revisar archivo: el sistema muestra cuántas filas están listas, cuáles tienen errores (con número de fila y motivo) y avisos —por ejemplo si una raza no existe (se agrega sola) o si no encuentra a la madre indicada (importa el animal sin ese vínculo).
4. Nada se guarda hasta que confirmes. Al confirmar, crea los animales y luego resuelve los vínculos de madre y padre.

Se puede importar en varias tandas; los códigos ya existentes se rechazan, así que no se duplican animales.

Producción por animal: al registrar en 📋 Producción una categoría de animales (cabras, ovejas, gallinas), aparece el selector Animal — eliges la cabra ordeñada, o dejas (todo el lote) si el dato es del grupo. En el Kiosco es un paso más de botones: categoría → evento → ¿cuál animal? → cantidad. Después, la ficha 👪 de cada animal muestra su producción acumulada, promedio y últimos eventos — así ves qué cabra rinde más y decides con datos.

Reglas de buen uso: el código nunca se cambia después de asignado (es la identidad del animal); si un animal muere o se vende, edítalo y cambia su estado — no se borra nunca, así la genealogía de sus crías queda intacta. Para la carga inicial del hato, registra primero los animales viejos (los posibles padres/madres) y después los jóvenes, para poder vincularlos.

8c. 🐐 Hato caprino (consola de gestión)

Página /hato.html (enlace "🐐 Hato caprino" en la portada). Reúne los módulos de manejo del hato en pestañas grandes, pensadas también para la tableta del corral.

🏠 Corrales: da de alta cada corral con su tipo (ordeño, secas, preñadas, levante, sementales, maternidad, enfermería), capacidad y ubicación. La tabla muestra cuántos animales tiene cada corral frente a su capacidad, con una barra y aviso de "sobrepoblado" cuando se pasa. El corral de cada animal se actualiza solo cuando registras un traslado.

👤 Empleados: la lista de personas que hacen registros (encargado, ordeñador, ayudantes, veterinario). Se usan para el campo "Responsable" de las demás pantallas — se elige el nombre de una lista, sin contraseña. Es trazabilidad de captura, distinta del usuario con el que entras al sistema.

🔀 Movimientos: registra traslados entre corrales, ventas, compras y salidas, con peso, valor, contraparte y número de guía. Un traslado mueve al animal de corral; una venta o descarte lo saca del hato activo (sin borrar su historial).

🍼 Parto detallado: registra el parto cría por cría. A cada cría le pones su sexo y si nació viva o muerta — el sistema no te deja guardar si falta alguno de esos dos datos (así no se pierden las crías macho ni las que nacen muertas, como pasaba en el cuaderno). Las crías vivas entran al inventario con su madre, padre y corral; de las muertas queda constancia para la mortalidad.

⚰️ Defunciones: registra una muerte con su causa, la sospecha de enfermedad contagiosa (CAE, Clostridium…) y si se hizo necropsia. Al guardar, da de baja al animal y actualiza el reporte de mortalidad — muertes por causa, por categoría (cría/adulto), por mes y cuántas fueron neonatales. Es el reporte que faltaba para ver un brote a tiempo.

9. Página 📊 Información

Resumen automático de toda la finca, siempre al día: hectáreas tituladas por lote (con verificación contra el plano legal), uso del suelo con distribución, puntos de agua con capacidad, construcciones con área, vías y riego en metros, sensores y actividad de producción.

10. Problemas comunes

11. Para administradores (referencia rápida)

• Usuario solo-kiosco: crear el rol ROLE_OPERADOR y el grupo operadores en GeoServer, asignar el usuario a ese grupo. Al entrar irá directo al Kiosco, sin acceso a editar ni anular (bloqueado en el servidor, no solo en pantalla). Dale también lectura del workspace si necesita ver el mapa.
• Registros archivados: se ven y restauran desde la propia app (filtro "🗄 Ver archivados" → botón ♻️). No hace falta SQL.
• Usuarios: GeoServer → Security → Users, Groups, Roles. Crear usuario → asignarlo a grupo (lectores, editores, mapeadores, operadores). Las reglas de acceso están en el workspace finca → Security y en Security → Data.
• Ortofotos nuevas: subir el COG a s3://finca-gis-backups-.../rasters/ → se publica y aparece solo (~10 min). Nombrar con fecha: zona_2026jul_cog.tif.
• Tablas/capas nuevas: requieren publicarse en GeoServer (Layers → Add → store PostGIS).
• Respaldos: automáticos a las 3 AM hacia S3. Restaurar: scripts/restore.sh <archivo>.
• Linderos legales: se cargan por SQL desde las coordenadas del plano, nunca a mano (ver sql/fincas-schema.sql).
• Servidor: /opt/gis en la instancia EC2; docker compose ps para estado; guía completa en GUIA-DESPLIEGUE.md.