📱 Cuaderno de Campo Apícola

Proyecto de App — Cliente de campo offline-first para apicultores

React Native + Expo. Transcripción local con Whisper. Tres capas de almacenamiento.
Funciona sola en el móvil. Se integra opcionalmente con SmallCountry.
Proyecto externo, independiente, que conecta con Corral del Viento y la comunidad apícola.

Versión 1.0 · Mayo 2026

• 1. Resumen Ejecutivo
• 2. Principios de diseño (no negociables)
• 3. Arquitectura de tres capas
• 4. Stack técnico
• 5. Pantallas principales
• 6. Integración con SmallCountry (Capa 2)
• 7. Servidor comunitario (Capa 3)
• 8. Integración con SmallCountry
• 9. Hoja de Ruta
• 10. Lo que NO debe hacer la app
• 11. Notas Finales

---

1. Resumen Ejecutivo

Un apicultor experto llega a una colmena con traje, guantes y ahumador. Tiene las manos ocupadas. Posiblemente sin cobertura. Necesita saber en tres segundos: ¿qué pasó aquí la última vez?, ¿qué tengo que hacer hoy?, y registrar lo que veo ahora mismo sin escribir ni navegar menús.

Las apps existentes fallan porque priorizan la captura de datos sobre la consulta rápida, requieren internet, tienen demasiados pasos para tareas simples, o están diseñadas para gestores de explotaciones grandes, no para apicultores de campo.

El Cuaderno de Campo Apícola es una app móvil para Android e iOS que resuelve esto. Voz como entrada principal, botones grandes, contexto de la colmena antes que el formulario. Tres capas de almacenamiento independientes y combinables: solo en el teléfono, sincronizada con farmOS de SmallCountry, o compartiendo datos voluntariamente con la comunidad apícola. Con incentivo: si compartes datos con la comunidad, la app te muestra información anonimizada de los apiarios cercanos directamente en la pantalla de colmena.

Visión: Que un apicultor pueda llegar a su colmena, saber en tres segundos su historial, y registrar lo que ve sin soltar el ahumador.

---

2. Principios de diseño (no negociables)

1. Offline-first absoluto. Sin internet, todo funciona igual. No hay funcionalidad degradada sin cobertura.
2. Una mano, con guantes. Todos los elementos interactivos son botones grandes. Nada requiere precisión táctil fina.
3. Voz como entrada principal. El texto es secundario. El teclado es el último recurso.
4. Contexto antes que captura. La primera pantalla de una colmena muestra su historial, no un formulario.
5. Tres segundos para lo esencial. El apicultor puede saber el estado de una colmena en tres segundos desde que abre la app.
6. Datos del usuario, siempre. Nada se envía a ningún sitio sin consentimiento explícito. El modo local es completo y permanente.
7. Agnosticismo y portabilidad. La app no depende de ningún proveedor, servicio externo ni tecnología concreta:
   • Backend libre: cualquier implementación del contrato BackendColmenas funciona. Provistas: SQLite, Git/Forgejo, farmOS, Odoo. Cualquiera puede escribir la suya.
   • IA opcional y sustituible: el parser por defecto es el diccionario apícola (ADR-013). El LLM es una capa opcional. Se puede cambiar de proveedor IA sin cambiar la app.
   • Datos exportables: JSON, CSV, SQLite accesible con cualquier herramienta SQL. Sin formatos propietarios.
   • Sin servidor necesario: la app funciona completa en modo standalone (Capa 1). Las Capas 2 y 3 son opt-in.
   • Módulos independientes: cada módulo se puede activar, desactivar o sustituir por otro sin afectar al resto.

---

3. Arquitectura de tres capas

El usuario configura en ajustes qué capas activa. Pueden combinarse libremente.

Capa 1 — Standalone (siempre activa)

• Todos los datos en SQLite local en el teléfono
• Funciona sin internet, sin cuenta, sin servidor
• Exportación local a JSON/CSV en cualquier momento
• Esta capa nunca se puede desactivar

Capa 2 — SmallCountry personal (opcional)

• Sincronización con farmOS del usuario vía JSON:API
• Los datos van al servidor personal del apicultor
• Nadie más los ve
• Configuración: URL de farmOS + token OAuth2/OIDC vía Authentik
• Compatible con el módulo farm_bee extendido de Corral del Viento

Capa 3 — Comunidad (opcional, voluntaria, con incentivo)

• Servidor centralizado en la Zona Cero de SmallCountry
• El apicultor elige qué datos comparte (por defecto: nada)
• Los datos compartidos son anónimos (ubicación redondeada a ~5 km)
• API pública REST de lectura libre
• Datasets mensuales publicados con DOI en InvenioRDM
• Formato Darwin Core extendido para biodiversidad apícola
• El servidor comunitario alimenta a Corral del Viento con contexto regional
• Incentivo: si compartes, la app te muestra datos de los apiarios cercanos (anonimizados) directamente en la pantalla de colmena. Si no compartes, puedes acceder a los mismos datos desde la web de la Zona Cero: floraciones confirmadas en la zona, niveles de varroa regionales, patrones estacionales

App (React Native + Expo)
    │
    ├── SQLite local (siempre, offline-first)
    │
    ├── Capa 2: farmOS API (cuando hay cobertura)
    │   └── farm.corraldelviento.sc/api
    │
    └── Capa 3: Servidor comunitario (cuando hay WiFi)
        └── Zona Cero → API pública + InvenioRDM

---

4. Stack técnico

React Native + Expo SDK 51+
├── expo-av              → grabación de audio por nodo
├── react-native-whisper → transcripción local offline
│   └── Modelo: whisper-large-v3-turbo (809 MB)
│   └── Solo castellano (mejora precisión apícola)
│   └── Prompt inicial: contexto apícola
├── expo-sqlite          → base de datos local
├── expo-location        → GPS para geolocalizar inspección
├── expo-camera          → foto por nodo (opcional)
├── expo-notifications   → alertas locales de revisión
└── @tanstack/query      → sync con servidores en background

Nota: Los updates OTA se sirven desde Forgejo CI self-hosted en Horus. expo-updates apunta a URL local (updates.sc.duckdns.org). Sin Expo cloud, sin coste recurrente.

Por qué React Native + Expo: - Una codebase para Android e iOS - Expo maneja builds sin necesidad de Mac para iOS en desarrollo - react-native-whisper tiene soporte activo y compilación nativa de whisper.cpp - Ecosistema maduro para apps offline-first

Por qué whisper-large-v3-turbo: - 809 MB — razonable en móviles actuales - Solo castellano: el modelo puede especializarse en vocabulario apícola - Velocidad adecuada en gama media (~2-3 segundos por transcripción) - Calidad excelente para terminología técnica (varroa, oxálico, melojo)

El parser apícola (transcripción → campos)

Whisper transcribe. El parser convierte la transcripción en campos estructurados. No necesita LLM — un diccionario especializado es más rápido, más fiable y funciona 100% offline:

const DICCIONARIO_APICOLA = {
  reina: {
    vista:    ['reina presente', 'veo la reina', 'reina vista', 'localizada'],
    ausente:  ['sin reina', 'huérfana', 'no veo reina', 'falta la reina'],
    dudosa:   ['reina dudosa', 'no localizo la reina']
  },
  varroa: {
    ninguna:  ['sin varroa', 'no hay varroa', 'varroa cero', 'limpio'],
    baja:     ['poca varroa', 'varroa baja', 'varroa escasa'],
    media:    ['varroa media', 'bastante varroa', 'varroa moderada'],
    alta:     ['mucha varroa', 'varroa alta', 'varroa crítica']
  },
  tratamiento: {
    oxalico:  ['oxálico', 'ácido oxálico', 'sublimación'],
    formico:  ['fórmico', 'ácido fórmico', 'apilife'],
    timol:    ['timol', 'apiguard', 'thymovar']
  },
  celdas_reales: [
    'celdas reales', 'hay reales', 'veo reales', 'preparando enjambre'
  ]
}

El prompt inicial para Whisper que mejora la precisión:

"Inspección apícola en español. Vocabulario: colmena, reina, cría, varroa,
oxálico, fórmico, timol, enjambre, celda real, opérculo, alza, cuadro,
melojo, cantueso, retama, tomillo, Gredos, La Vera, Cáceres."

---

5. Pantallas principales

5.1 Inicio — Lista de colmenas

🐝 Mis colmenas                    [+ Nueva]
───────────────────────────────────────────
🟢 Solana 7                    hace 3d
   Reina vista · Cría buena
   ⚠️ Revisar pronto

🟡 Corcho grande               hace 8d
   Sin reina confirmada
   ⚠️ Requiere atención

🔴 Bajo el roble               hace 21d
   ⚠️ Sin inspección reciente

🟢 Kenya 1                     hace 5d
   Todo normal

El color refleja urgencia: verde (bien), amarillo (vigilar), rojo (atención requerida).

5.2 Colmena — El contexto

← Solana 7
Langstroth · Abeja Negra Ibérica
Reina 2024 · Marcada (verde)
───────────────────────────────────────────
ÚLTIMA INSPECCIÓN — hace 3 días

Reina vista ✓   Cría compacta ✓
Varroa: baja    Miel: suficiente

PENDIENTE
• Valorar alza si sigue creciendo
• Tratamiento oxálico en 2 sem

HISTORIAL
02/05 · Reina vista, cría buena
24/04 · Tratamiento oxálico

[  INICIAR INSPECCIÓN  ]  ← botón grande abajo

5.3 Inspección guiada — Árbol de decisión

Para principiantes o cuando se quiere ser exhaustivo. La app guía nodo a nodo con 7 secciones: Reina → Cría → Población → Reservas → Sanidad → Espacio → Acciones. Cada nodo tiene:

• Pregunta clara en texto grande
• Botón de micrófono (grabar observación sobre ese punto)
• 2-4 botones de respuesta rápida
• Ayuda contextual (desactivable)
• Botón "saltar" siempre visible

Inspección · Solana 7 · 1/7
─────────────────────────────────

    ¿Ves a la reina?

 ℹ️ Busca el abdomen más alargado.
   Suele estar rodeada de abejas.

 [  🎙️  Grabar nota  ]

 [   SÍ   ] [  NO  ] [ NO SÉ ]

             [Saltar →]

Campos de vigor de la colmena

Los nodos Población y Espacio recogen el vigor estructural de la colmena con métricas cuantitativas que permiten seguir su evolución en el tiempo:

Nodo Población — ¿Cuánta abeja hay?

Campo	Tipo	Descripción
Cuadros totales	Número	Cuadros que tiene la colmena en total (estándar Langstroth: 10)
Cuadros ocupados por abejas	Número	Cuadros donde hay abejas cubriendo ambas caras. Principal indicador de población
Láminas en la última visita	Número	Cuadros ocupados en la inspección anterior (arrastre automático del registro previo)
Tendencia	↑ = → ↓	Crecimiento, estabilidad o decrecimiento respecto a la visita anterior

Nodo Espacio — ¿Tiene sitio o está apretada?

Campo	Tipo	Descripción
Espacios sin cuadros	Número	Huecos libres en la cámara de cría — detecta si la colmena se está quedando sin espacio
Alzas con espacio	Número	Alzas melarias con panales sin ocupar completamente
Necesita alza	Sí / No / Pronto	Recomendación: añadir alza ahora, en la próxima visita, o no necesaria

Estos campos alimentan las alertas automáticas de la Capa 1 (offline): si los cuadros ocupados superan los cuadros totales menos 1 → alerta de enjambrazón inminente. Si los cuadros ocupados bajan más del 30% respecto a la visita anterior → alerta de posible pérdida de población.

5.4 Inspección rápida — Modo experto

Una sola pantalla con audio global:

Inspección rápida · Solana 7
─────────────────────────────────
 [  🎙️  HABLAR  ]

 Reina  [✓][?][✗]   Cría [✓][~][✗]
 Miel   [↑][=][↓]   Varroa [·][!][!!]
 Ánimo  [😊][😐][😠]

 Hecho hoy:
 [alza ✓] [alimentación] [tto]

 Próxima: [1s][2s][1m][+]

      [  GUARDAR  ]

Whisper transcribe el audio y el parser rellena los botones automáticamente. El apicultor solo confirma o corrige.

5.5 Ajustes

ALMACENAMIENTO
  ✓ Local (siempre activo)
  ○ SmallCountry personal → URL farmOS, token
  ○ Comunidad apícola → qué datos comparto

MODO DE INSPECCIÓN
  ○ Guiado   ● Rápido
  Mostrar ayudas: ✓

DATOS
  [Exportar → JSON] [Exportar → CSV]

5.6 Arquitectura de módulos

La app se construye sobre un núcleo mínimo que funciona el día 1, y funcionalidades adicionales se activan como módulos opcionales desde Ajustes.

Núcleo (siempre activo):

• SQLite local offline-first
• Gestión de colmenas (CRUD básico)
• Inspección rápida (voz + botones)
• Lista de colmenas con estado visual
• Exportación básica (JSON/CSV)

Cada módulo, al activarse:

• Añade sus pantallas a la navegación
• Carga sus dependencias (SQLite, backend, APIs)
• Si requiere configuración (URL, token), aparece en Ajustes
• Se puede desactivar en cualquier momento sin perder datos

5.7 Catálogo de módulos

📦 Tipos de colmena — Plugin por tipo

Cada tipo de colmena es un plugin independiente. Al activarlo, se añade su dashboard visual y formulario de inspección específicos.

• Dadant (vertical, 12 cuadros, despiece completo)
• Layens (horizontal, 20-24 cuadros)
• Núcleos Dadant y Layens
• Langstroth, Corcho, Warré, Kenya Top Bar, National... y todos los del catálogo mundial
• Cada tipo: dashboard, formulario, estructura de piezas

📊 Dashboards

• Dashboard General (todos los apiarios)
• Dashboard por Apiario
• Dashboard por Colmena (historial cronológico)
• Dashboard por Tipo de Colmena
• Gráficos de tendencia (población, producción)

🏪 Almacén (Casa Paraíso)

Control de stock de materiales apícolas: cajas, alzas, cuadros, láminas, cera, excluidores, trampas, alimentadores (3 tipos), ácidos, jaulas reina, aislantes, etc.

• Descuento automático de materiales usados en cada visita
• Alertas configurables de stock mínimo

🌸 Floración

• Observaciones con foto geolocalizada + especie + fase BBCH
• Calendario de floración por especie y zona
• Feed comunitario de la zona (últimas observaciones)
• APIs externas: CAMS (polen atmosférico), Palinocam, Sentinel Hub NDVI

👥 Comunidad (Zona Cero)

• Compartir datos anónimos voluntariamente (opt-in granular)
• Ver datos agregados de la zona como incentivo
• GPS redondeado ~5km, datos mensuales, nunca individuales
• Servidor comunitario: FastAPI + PostGIS en Zona Cero
• Publicación de datasets con DOI en InvenioRDM (CC BY 4.0)
• API pública REST de consulta libre

☁️ Backends de sincronización

Se pueden activar uno, varios o ninguno:

Git/Forgejo (append-only + CI):

• Cada visita = commit a Forgejo
• Append-only, nunca se reescribe ni borra
• Forgejo CI valida schema y propaga a otros servicios

farmOS:

• Sincronización directa vía JSON:API
• Crea assets y logs de inspección/tratamiento/cosecha

Odoo (inventario + tienda):

• Sincronización de stock de materiales con Odoo Inventory
• En futuro: seguimiento de pedidos de la tienda online
• Catálogo de productos apícolas sincronizado

Git + farmOS + Odoo (Forgejo CI como puente):

• App escribe JSON → git push a Forgejo
• Forgejo CI valida → escribe en farmOS API + Odoo API simultáneamente
• Un solo punto de entrada, múltiples destinos

📈 Métricas y monitorización

• VictoriaMetrics (base de datos time-series)
• Grafana dashboards embebidos en la app vía WebView
• Grafana Alloy como recolector
• Sensores de colmena (peso, temperatura, humedad) vía PromQL

🤖 IA

• Chat IA: preguntas en lenguaje natural sobre los datos del usuario
• Usa RAG Hub local en Horus (Qdrant + modelo abierto)
• Solo responde sobre datos apícolas
• Streaming de respuestas
• Mejora opcional del parser de voz (LLM como alternativa al diccionario)
• Módulo desactivado por defecto

📅 Cría de reinas

• Calendario completo: fechas de traslarve, nacimiento, fecundación, inicio de puesta
• Seguimiento de linaje: madre, padre, apiario de origen
• Alertas de revisión programadas según el calendario

🔔 Alertas

• Schwarmalarm (detección de enjambrazón inminente)
• Stock mínimo en almacén
• Revisiones programadas (próxima visita recomendada)
• Condiciones meteorológicas adversas (conectado a Proyecto Clima)

📸 Fotos

• Galería de fotos por colmena
• Adjuntar fotos a inspecciones
• Reconocimiento de especies de flora (via API iNaturalist/PlantNet)

👪 Multiusuario

• Varios apicultores en la misma explotación
• Roles: admin, lector, colaborador
• Sincronización entre usuarios del mismo equipo

---

6. Integración con SmallCountry (Capa 2)

El pipeline completo

App escribe JSON visita (farmOS-ready)
       │
       ▼
Git push a Forgejo (append-only, cada visita = commit)
       │
       ▼
Forgejo CI:
  1. Valida schema JSON + IDs de colmena
  2. Escribe en farmOS API (logs: observation, treatment, activity)
  3. Escribe en Odoo API (inventario: descuenta materiales usados)
  4. Envía métricas a VictoriaMetrics (remote write Prometheus)
  5. Regenera dashboards si es necesario
       │
       ▼
Grafana Alloy recolecta y transforma
Grafana dashboards embebibles en app vía WebView

farmOS

Operación	Endpoint
Crear inspección	POST /api/log/observation
Registrar tratamiento	POST /api/log/input
Listar colmenas	GET /api/asset/animal

Odoo

Operación	Endpoint
Actualizar stock	POST /api/inventory/update
Registrar consumo material	POST /api/inventory/consumption
Consultar catálogo	GET /api/product/product

Forgejo CI como puente

La app nunca habla directamente con farmOS ni Odoo. Escribe a Forgejo, y el CI se encarga de propagar a ambos sistemas. Esto garantiza:

• Una sola fuente de verdad (git)
• Validación antes de cualquier escritura externa
• Auditoría completa (git log)
• Rollback si algo falla (git revert)

VictoriaMetrics + Grafana

Si hay sensores físicos (báscula, temperatura), la app consulta datos recientes vía PromQL:

query_range?query=colmena_peso_kg{colmena="X"}&start=-7d&step=1h

OTA updates

Forgejo CI compila updates de Expo y los publica en Horus. expo-updates apunta a URL local (updates.sc.duckdns.org). Sin Expo cloud, sin coste recurrente.

Chat IA (opcional, módulo)

RAG Hub local en Horus (Qdrant + modelo abierto). Solo datos apícolas del usuario. Streaming. Desactivado por defecto.

---

7. Servidor comunitario (Capa 3)

Qué es

Una API REST pública alojada en la Zona Cero de SmallCountry. Acepta datos de inspecciones anonimizadas de cualquier apicultor con la app. Publica datasets abiertos con DOI en InvenioRDM. Alimenta a Corral del Viento con contexto regional.

Endpoints públicos (lectura libre, sin auth)

Endpoint	Datos
GET /api/v1/floraciones?zona=gredos&radio=50km	Floraciones reportadas en la zona
GET /api/v1/varroa?zona=la_vera&mes=mayo	Niveles medios de varroa en la zona
GET /api/v1/calendario?lat=40.1&lon=-5.7	Calendario apícola basado en datos históricos
GET /api/v1/datasets	Datasets publicados con DOI

Lo que aporta a Corral del Viento

• «Esta semana, 3 apicultores de La Vera reportan varroa media-alta»
• «Floración de cantueso confirmada en radio 20 km desde el 3 de mayo»
• «Enjambrazón activa en la comarca — revisar colmenas con celdas reales»

Contexto que ningún apicultor puede tener solo con sus propias colmenas.

Privacidad: opt-in con incentivo

El apicultor elige exactamente qué comparte. Por defecto: nada. Opciones: - Niveles de varroa (sin identificar colmena ni apicultor) - Floraciones observadas (ubicación redondeada a ~5 km) - Fechas de enjambrazón (solo sí/no, sin detalles)

Incentivo por compartir: si el apicultor activa la Capa 3 y comparte datos, la app le devuelve información de los apiarios más cercanos directamente en la pantalla de colmena, sin tener que salir a la web de la Zona Cero ni usar otra app:

┌─────────────────────────────────┐
│ 🌍 Tu zona — datos comunitarios │
│                                 │
│ Radio 20 km · 3 apicultores     │
│                                 │
│ Varroa: 🟡 media en la zona     │
│ Floración: 🌸 cantueso activo   │
│ Enjambrazón: ⚠️ activa          │
│                                 │
│ "Esta semana, 3 apicultores de  │
│  La Vera reportan varroa media. │
│  Cantueso en flor desde el 3/5" │
└─────────────────────────────────┘

Toda la información es anónima: no se muestra quién, qué colmena ni coordenadas exactas. Solo tendencias agregadas de la zona.

Si NO comparte datos: puede acceder a la misma información, pero a través de la web pública de la Zona Cero (datos.elsalto.sc) o conectando a la API desde otra herramienta. La app no se la muestra directamente. Esto incentiva la contribución sin obligar — el que aporta recibe contexto en el mismo lugar donde trabaja.

---

8. Integración con SmallCountry

8.1 Roles implicados

Rol	Función
Melissa — Colmenas y miel	Usuaria principal de la app en campo
Hefesto — Infraestructura	Despliegue del servidor comunitario en Zona Cero

8.2 Servicios de SmallCountry que usará

Recurso	Para qué
farmOS	Backend de registros apícolas (Capa 2)
Authentik	OAuth2/OIDC para autenticación de la app
Victoria Metrics	Datos de sensores de colmena (peso, temperatura)
n8n	Middleware de anonimización antes de InvenioRDM
InvenioRDM	Publicación de datasets comunitarios con DOI
ntfy	Notificaciones de alertas (Schwarmalarm, varroa)
Proyecto Clima	Datos meteorológicos para predicción de floración
Zona Cero	Alojamiento del servidor comunitario (público, sin auth)

Para el administrador

Servidor comunitario

LXC	Por asignar — Zona Cero
Dominio	api.elsalto.sc
Tier	C — Conveniente
Stack	FastAPI (Python) + PostgreSQL + PostGIS
ZFS dataset	rpool/datos/comunidad-apicola/
Backup	PBS diario + ZFS snapshot @15min

App móvil

• Repositorio: Forgejo (corral-del-viento/app-colmena)
• Builds: Expo EAS Build (Android + iOS)
• Distribución: APK directo + TestFlight (evita tasas de tiendas)
• Actualizaciones: OTA vía Expo Updates

Para el arquitecto

Esquema de integración

flowchart TB
    subgraph App["📱 App móvil"]
        SQLite[(SQLite local)]
        Whisper[Whisper.cpp<br/>transcripción]
        Parser[Parser apícola]
    end

    subgraph SmallCountry["⚙️ SmallCountry"]
        farmOS[farmOS<br/>JSON:API]
        Authentik[Authentik<br/>OAuth2/OIDC]
        VictoriaMetrics[Victoria Metrics<br/>sensores]
        n8n[n8n<br/>anonimización]
    end

    subgraph ZonaCero["🌐 Zona Cero"]
        API[API comunitaria<br/>FastAPI + PostGIS]
        InvenioRDM[InvenioRDM<br/>datasets DOI]
    end

    App -->|Capa 2| farmOS
    App -->|Capa 3| API
    Authentik -->|auth| farmOS
    Authentik -->|auth| API
    VictoriaMetrics -->|PromQL| App
    API --> n8n
    n8n --> InvenioRDM
    InvenioRDM -->|DOI público| ZonaCero

Orquestación

Componente	Path / Nombre
App móvil	corral-del-viento/app-colmena/ (Forgejo)
Servidor comunitario	roles/comunidad-apicola/
Playbook	deploy-comunidad-apicola.yml
Forgejo Actions	.forgejo/workflows/comunidad-apicola.yml

---

9. Hoja de Ruta

Fase 1 — MVP de campo

• [ ] Lista de colmenas con estado visual
• [ ] Pantalla de colmena con historial y pendientes
• [ ] Inspección rápida con audio global
• [ ] Transcripción local con Whisper large-v3-turbo (castellano)
• [ ] Parser apícola básico (reina, varroa, cría, miel)
• [ ] SQLite local
• [ ] Sin servidor, sin cuenta, sin internet
• [ ] Arquitectura modular: núcleo + sistema de plugins
• [ ] Tipos de colmena: Dadant, Layens, Núcleos como plugins
• [ ] Dashboard General + por tipo de colmena
• [ ] Módulo Almacén básico
• [ ] Forgejo CI: build + OTA update automático
• [ ] Módulo Chat IA (desactivado por defecto)
• [ ] Exportación JSON/CSV

Fase 2 — Modo guiado + backends

• [ ] Árbol de decisión completo (7 nodos: reina, cría, población, reservas, sanidad, espacio, acciones)
• [ ] Audio por nodo individual
• [ ] Ayudas contextuales para principiantes
• [ ] Registro de floraciones
• [ ] Calendario de cría de reinas: planificación de fechas de traslarve, nacimiento, fecundación e inicio de puesta. Seguimiento del linaje de cada reina (madre, padre, apiario de origen). Alertas de revisión programadas según el calendario de cría
• [ ] Más tipos de colmena del catálogo mundial
• [ ] Módulo Git/Forgejo: sincronización + CI pipeline
• [ ] Módulo farmOS: logs vía CI
• [ ] Módulo Odoo: inventario vía CI
• [ ] Dashboards Grafana embebidos
• [ ] Integración VictoriaMetrics + Alloy

Fase 3 — Comunidad

• [ ] Módulo Floración completo (fotos geolocalizadas + APIs)
• [ ] Módulo Comunidad: servidor Zona Cero (FastAPI + PostGIS)
• [ ] Publicación de datasets con DOI en InvenioRDM
• [ ] Módulo IA: chat RAG Hub activable
• [ ] Alertas (Schwarmalarm, stock mínimo)
• [ ] Módulo Fotos

Fase 4 — Escalado

• [ ] Módulo Multiusuario
• [ ] Tienda online (pedidos desde Odoo)
• [ ] Módulo Alertas meteorológicas (Proyecto Clima)
• [ ] API pública comunitaria v1.0

9.1 Contrato de datos (Interface BackendColmenas)

Todo backend de colmenas implementa esta interfaz:

get_colmena(id) → Colmena
list_colmenas(apiario, tipo) → Colmena[]
save_visita(visita) → id
get_historial(id) → Visita[]
get_estado_actual(id) → Colmena
get_almacen() → Material[]
update_stock(material, cantidad) → void
save_observacion_flor(obs) → id
list_floraciones(zona, fecha) → ObservacionFlor[]

Implementaciones actuales: SQLite (standalone), Git/Forgejo, farmOS, Odoo.

---

10. Lo que NO debe hacer la app

• ❌ No requerir registro ni cuenta para funcionar
• ❌ No enviar datos a ningún servidor sin consentimiento explícito
• ❌ No tener menús de más de dos niveles de profundidad
• ❌ No usar teclado como entrada principal
• ❌ No fallar si no hay internet
• ❌ No perder datos nunca (SQLite es la fuente de verdad siempre)
• ❌ No intentar ser un ERP de gestión de explotación
• ❌ No competir con farmOS — la app es el cliente de campo, farmOS es el servidor
• ❌ No depender de LLM para funcionar (parser diccionario es el camino principal)
• ❌ No requerir servidor de IA (chat IA es módulo desactivado por defecto)
• ❌ No tener vendor lock-in: cualquier backend que implemente el contrato funciona
• ❌ No depender de servicios cloud externos (todo self-hosteable)
• ❌ No acoplar módulos entre sí (cada módulo debe poder funcionar independientemente)

---

11. Notas Finales

El Cuaderno de Campo Apícola no compite con Tierras Apícolas, Hiveeyes ni con farmOS. Es la capa de campo que conecta al apicultor con su colmena y, opcionalmente, con su infraestructura SmallCountry y con la comunidad.

La decisión de diseño más importante ya está tomada: la app funciona sola. SmallCountry la enriquece pero no la condiciona. Un apicultor puede usar la app para siempre en modo standalone; otro puede sincronizarla con su farmOS; un tercero puede además compartir datos con la comunidad. Las tres opciones son válidas y no excluyentes.

---

Próximo paso: Construir el MVP con React Native + Expo: lista de colmenas, inspección rápida con audio, transcripción local, SQLite.

---

Secciones relacionadas

• Proyecto: 🐝 Corral del Viento
• Proyecto: 🌦️ Proyecto Clima
• Proyecto: 🔬 Ciencia Abierta
• Legal: RGPD — Comunidad Apícola
• Ficha: farmOS
• Ficha: Hermes Agent
• Ficha: InvenioRDM
• Ficha: Authentik
• Rol: Melissa — Colmenas y miel

---

Apéndice A: Catálogo completo de datos

Colmena: id, apiario, tipo, subtipo, estado_vida (activa/muerta/crítica), ubicación

Reina: color (blue/white/yellow/red/green/unmarked/unseen), vista, marcada, origen (portuguesa/propia), tipo (fecundada/virgen), fecha_introducción, celdas_reales

Población: nivel (very_weak→very_strong), marcos_cubiertos, marcos_cría, huevos, polen_entrando

Estructura por tipo:

• Dadant: tapa → sobre_entretapa+alimentador(3 tipos) → entretapa → rejilla_propóleo → alzas[](cada una 9 cuadros partidos, 2 caras) → excluidor → cámara_cría(9 cuadros) → suelo(sanitario/tradicional) → piquera(cazapolen, reductor)
• Layens: caja única 20-24 cuadros partidos + separador + piquera (2 posibles)
• Núcleo: 5-6 cuadros + alimentador + reina jaulita (sin alzas, sin excluidor)

Valores cara cuadro partido (cada cara = array, múltiples valores simultáneos): cria_huevos, cria_rosquilla, cria_operculada, cria_operculada_tostada, zanqano_huevos, zanqano_rosquilla, zanqano_operculado, realera, miel, polen, lámina, estirando, néctar, vacío

Miel: estado (nada/entrando/produciendo/lista), honey_stores, pollen_incoming

Salud: varroa, nivel_varroa, loque, cría_zángano_excesiva, problemas, tratamientos[](tipo+fecha), comportamiento(agresiva/nerviosa/dócil)

Visita: ts ISO8601, trace(visita-YYYYMMDD-apiario), event(census/inspection/installation/mortality/general_note), observer, notes, actions[], pending[], materials_used[]

Acciones: create_nucleus, introduce_queen(Portuguesa/Propia), add_propolis_trap, feed, transfer_nucleus_to_hive, transport_nuclei, add_foundation, add_frames, transfer_super, assign_numbers

Pendientes: add_super, add_new_frames, add_feeder, feed, move_to_box, repair_floor, replace_excluder, mark_queen, observe, extreme_caution, verificar_aceptacion_reina, revision_puesta, check_laying_and_mark, possible_split

Almacén (~20 materiales): cajas Dadant US, cajas nuevas, corchos, núcleos, alzas, cuadros con cera, láminas cera, cera estampada(kg), cera opérculo(kg), excluidores, trampas polen, mallas propóleo, alimentadores(3 tipos), rotuladores, jarabe, candy, ác.oxálico(kg), ác.fórmico(uds), jaulas reina, aislantes/ponchos

Floración: especie, fase BBCH(55-69), fecha, coordenadas(redondeadas~5km comunidad), foto(opcional), fuente(usuario/API)