Saltar a contenido

12 conocimiento

Principio

El conocimiento necesario para operar, mantener y evolucionar SmallCountry no reside en la memoria del administrador, sino que se documenta de forma estructurada, se versiona junto al código en Forgejo y se publica en docs.sc mediante MkDocs.
Cada persona que utiliza el sistema puede realizar las tareas propias de su rol sin necesidad de recurrir a una figura administradora.

Los usuarios acceden a los servicios a través de un panel de inicio único, Homepage, que Authentik segmenta dinámicamente según los grupos a los que pertenece cada persona. Nadie ve servicios para los que no tiene permiso, y nadie necesita saber qué hay detrás de la interfaz para utilizarla.

El equipo de campo recibe recordatorios proactivos de las tareas que requieren intervención humana, con instrucciones y checklist, y los resultados se registran automáticamente en farmOS.
Si un flujo de trabajo habitual requiere la intervención del administrador, el diseño del sistema se considera defectuoso y debe corregirse.

Supervivencia del conocimiento

Este principio no es una cuestión de comodidad: es una cuestión de supervivencia. Si el arquitecto desaparece —por cualquier motivo—, el sistema debe poder ser comprendido, mantenido y evolucionado por otra persona sin formación previa en SmallCountry. La documentación es el testamento técnico del proyecto. Si no se entiende, el sistema muere con su creador. Por eso cada página está escrita para que cualquier persona —sin conocimientos previos— pueda entender todos los términos, acrónimos y referencias que contiene. El conocimiento no reside en la memoria del arquitecto: reside en estas páginas.

Cómo se garantiza el conocimiento compartido

Documentación como código

Elemento Herramienta Descripción
Redacción code-server Entorno de desarrollo desde el navegador donde se editan simultáneamente el código y la documentación.
Versionado Forgejo El repositorio docs.sc contiene toda la documentación en formato Markdown. Cada PR que modifica código debe incluir la actualización de la documentación correspondiente.
Publicación MkDocs Genera un sitio estático a partir del contenido del repositorio y lo sirve localmente en docs.sc.
Indexación para IA Qdrant La documentación se indexa en la base vectorial para que la IA de Ollama pueda responder preguntas contextuales sobre el sistema.

La documentación no es un añadido posterior. Forma parte del flujo descrito en el 1. Infraestructura y configuración como código: se escribe en el mismo momento en que se desarrolla el código, y viaja con él a través del pipeline de Forgejo Actions hasta producción.

Autoservicio sin administrador

Rol Herramientas y permisos
Familia Accede a Nextcloud, Immich, Jellyfin, Homepage y solicita contenido audiovisual desde Jellyseerr sin mediación.
Biólogo / equipo de campo Accede a Grafana (lectura de dashboards de finca), farmOS (registro completo de cultivos, cosechas y observaciones), Immich (álbum de biodiversidad), Forgejo (repositorio de ciencia abierta) y Qdrant (consultas a la colección de literatura científica). Recibe recordatorios proactivos de tareas (análisis de suelo, calicatas, revisión de NDVI) con checklist y registro automático.
Psicólogo Accede a Joplin Server (notas cifradas E2E (cifrado de extremo a extremo)), instrumentos clínicos locales y Qdrant (consulta de literatura científica). Cualquier dato sensible queda fuera del alcance del resto de usuarios.

Cada rol tiene un grupo en Authentik que determina qué servicios ve en Homepage. No existen paneles de administrador separados; la misma interfaz se adapta a cada persona.

Recordatorios proactivos y asistentes de campo

Los flujos de n8n programan recordatorios periódicos para las tareas agrícolas que requieren intervención humana. Cada recordatorio incluye:

  • Instrucciones paso a paso.
  • Checklist de comprobaciones.
  • Enlace al formulario de farmOS donde registrar el resultado.

Cuando el biólogo completa la tarea, el registro queda automáticamente vinculado a la parcela correspondiente, actualizando los dashboards de Grafana y el repositorio de ciencia abierta en Forgejo.

Herramienta CLI de autoservicio (sc-cli)

Para tareas de diagnóstico o recuperación que antes requerían acceso de administrador, existe una herramienta de línea de comandos, sc-cli, que pueden ejecutar usuarios con el rol buddy-admin:

  • sc-cli diagnose --service nextcloud: ejecuta una batería de comprobaciones sobre el servicio y sugiere acciones.
  • sc-cli restore --service immich --from-snapshot yesterday: restaura un snapshot ZFS (sistema de archivos con integridad de datos) del servicio, previa confirmación explícita.
  • sc-cli status --all: muestra un resumen del estado de todos los servicios en formato legible.

sc-cli ejecuta las acciones con privilegios controlados, sin dar acceso al shell del servidor ni a las herramientas de administración completas. Cualquier acción queda registrada en Victoria Metrics y notificada al administrador.

Stack necesario

  • code-server – Entorno de edición de documentación y código.
  • Forgejo – Repositorio docs.sc, CI/CD (integración y despliegue continuo).
  • MkDocs – Generador de documentación estática.
  • Homepage – Panel de inicio unificado con vistas segmentadas por rol.
  • Authentik – Proveedor de identidad, grupos y segmentación de acceso.
  • n8n – Recordatorios proactivos y flujos de asistencia al equipo de campo.
  • Joplin Server – Notas cifradas E2E para el psicólogo y el biólogo.
  • Qdrant – Indexación de la documentación y la literatura para consulta por parte de la IA.
  • sc-cli – Herramienta CLI de autoservicio para usuarios autorizados.
  • Victoria Metrics – Registro de auditoría de acciones ejecutadas desde sc-cli.

Relaciones con otros principios

Diagrama de conocimiento compartido y autonomía

graph TD
    subgraph Documentacion [Documentación como código]
        direction TB
        CodeServer[code-server]
        Forgejo[Forgejo docs.sc]
        MkDocs[MkDocs]
        CodeServer --> Forgejo
        Forgejo --> MkDocs
    end

    subgraph Autoservicio [Autoservicio de usuarios]
        direction TB
        Authentik[Authentik - grupos y roles]
        Homepage[Homepage segmentado]
        sccli[sc-cli - CLI de autoservicio]
        n8n[n8n - recordatorios]
        Authentik --> Homepage
        Authentik --> sccli
        n8n --> farmOS
    end

    subgraph Conocimiento [Conocimiento accesible]
        direction TB
        Qdrant[Qdrant]
        Joplin[Joplin Server - notas cifradas]
        Docs[MkDocs - docs.sc]
        Qdrant --> IA[Ollama - consultas]
        Docs --> Qdrant
    end

    Documentacion --> Conocimiento
    Autoservicio --> Conocimiento
    MkDocs --> Docs

    style Documentacion fill:#a5d6a7,stroke:#2e7d32,color:#000
    style Autoservicio fill:#90caf9,stroke:#1565c0,color:#000
    style Conocimiento fill:#ffe082,stroke:#f57f17,color:#000

← Principio 11: Contención de recursos   |   Protección de Datos (RGPD) →

Secciones relacionadas