Código

NAHPU es más que una simple aplicación de catálogo digital para el trabajo de campo en historia natural. Es un sistema de software para apoyar la digitalización de especímenes justo en el momento de la recolección. Esta página se centra en explicar cómo contribuir a la aplicación principal de NAHPU, que es el catálogo digital en sí. Consulte la sección de herramientas de desarrollo para obtener más detalles sobre cómo contribuir al software de soporte del proyecto.

Inicio rápido

Prerrequisitos

Antes de poder contribuir al proyecto NAHPU, asegúrese de tener instalado lo siguiente en su máquina:

Para preparar su máquina para el desarrollo de NAHPU:

Instale el SDK de Flutter
Siga la guía del equipo de Flutter. También deberá instalar Android Studio.
Instale el toolchain de Rust
Instale Flutter rust bridge

Contribución de código

Haga un fork del repositorio de NAHPU en GitHub.
Clone el repositorio forkeado en su máquina local.
Ventana de terminal
```
git clone https://github.com/hhandika/nahpu.git
```
Si está utilizando GitHub CLI.
Ventana de terminal
```
gh repo clone hhandika/nahpu
```
Cambie al directorio del repositorio NAHPU.
Ventana de terminal
```
cd nahpu/
```
Cree una nueva rama para sus cambios.
Ventana de terminal
```
git checkout -b nombre-de-su-rama
```
Realice sus cambios y confírmelos (commit).
Ventana de terminal
```
git add .
git commit -m "Su mensaje de commit"
```
Suba (push) sus cambios a su repositorio forkeado.
Cree un pull request al repositorio principal de NAHPU.
Si está trabajando en cambios en la interfaz de usuario, asegúrese de incluir capturas de pantalla o un video de demostración para ilustrar sus cambios. Se pueden encontrar buenos ejemplos de cambios en la interfaz de usuario en los issues de GitHub de NAHPU.

Cambios en el esquema de base de datos

NAHPU utiliza Drift para la administración de la base de datos SQLite. Puede encontrar las definiciones de esquemas de bases de datos en el directorio db_schemas/.

Proponga primero el cambio de esquema en un issue de GitHub.
Una vez que el cambio sea aprobado, agregue la definición de nuevo esquema en el archivo /lib/services/database/table.drift.
Actualice la versión de la base de datos en el archivo /lib/services/database/database.dart.
Por ejemplo, para pasar de la versión 6 a la 7, actualice la constante kSchemaVersion:
```
const int kSchemaVersion = 7;
```

Escriba una nueva función de migración en el mismo archivo para manejar el cambio en el esquema. Por ejemplo:

Future<void> _migrateFromVersion7(Migrator m) async {
  await m.addColumn(specimens, specimens.newColumn);
  // Agregue cualquier paso de migración adicional aquí
}

Después de actualizar el esquema, ejecute el generador de código para actualizar el código Dart generado:
Ventana de terminal
```
flutter pub run build_runner build --delete-conflicting-outputs
```
Genere (dump) el esquema final a un archivo nuevo en db_schemas/ con la próxima versión numerada.
Utilice el comando integrado drift_dev para producir el "dump" del esquema:
Ventana de terminal
```
dart run drift_dev schema dump lib/services/database/database.dart db_schemas/drift_schema_v7.json
```
Ejecute el test (las pruebas).
Ventana de terminal
```
flutter test
```
Realice un commit con sus cambios y abra un pull request con una descripción clara abordando el cambio, la razón del mismo y efectos potenciales sobre los datos existentes.

Solución de problemas

Aquí hay algunos problemas comunes y sus soluciones:

`flutter_rust_bridge_codegen` no encontrado

Causa: flutter_rust_bridge_codegen no está en su PATH.
Solución: Asegúrese de haberlo instalado con cargo install flutter_rust_bridge_codegen y que el directorio bin de cargo esté en su PATH.

Error en macOS: `flutter_rust_bridge_codegen` falla con "Please supply one or more path/to/llvm..."

Causa: El generador de código no puede encontrar su instalación de LLVM.
Solución: Instale LLVM con Homebrew (brew install llvm).

Error en Windows: falla con "nudget" o errores de enlazador (linker)

Causa: Las herramientas de compilación de MSVC o el SDK de Windows faltan o no están configurados correctamente, lo que provoca que el toolchain de Rust falle durante el enlazado.
Solución: Instale las Herramientas de compilación de Visual Studio y asegúrese de que la carga de trabajo Desarrollo para el escritorio con C++ esté seleccionada. Luego, configure el toolchain de Rust a MSVC:
Ventana de terminal
```
rustup default stable-x86_64-pc-windows-msvc
```

Profundización

Arquitectura del código

NAHPU es una aplicación multiplataforma construida con Flutter, un framework de alto rendimiento para crear aplicaciones compiladas nativamente. Flutter utiliza el lenguaje de programación Dart, que está optimizado para construir interfaces de usuario rápidas y atractivas. Este enfoque simplifica el proceso de desarrollo y es nuestra receta para asegurar que NAHPU sea eficiente y admita sistemas operativos móviles y de escritorio.

Almacenamiento de datos: En el backend, NAHPU depende en gran medida de SQLite para el almacenamiento local, priorizando el funcionamiento sin conexión (offline-first). Debido a que el trabajo de campo a menudo ocurre en áreas remotas sin acceso a Internet, la gestión robusta de datos locales es crítica.

La integración con Rust: Desde principios de 2024, hemos estado migrando las operaciones de cómputo intensivo a Rust. Rust es un lenguaje de programación de sistemas que se centra en el rendimiento, la confiabilidad y la seguridad de la memoria. Al integrar Rust con Flutter a través de flutter_rust_bridge, logramos lo mejor de ambos mundos:

Flutter/Dart maneja la gestión de estado, el enrutamiento y la renderización de la interfaz de usuario de manera fluida a 60-120 fps. Rust se encarga del trabajo pesado: análisis de grandes conjuntos de datos, transformaciones de datos complejas, E/S de archivos y algoritmos especializados que de otro modo saturarían el isolate de Dart.

Interfaz de usuario y diseño

NAHPU utiliza el sistema Material Design 3 como base para su identidad visual.

Consistencia: Material Design está profundamente integrado con Flutter. Siempre que es posible, utilizamos widgets estándar de Material para asegurar una experiencia de usuario consistente, accesible e intuitiva en todos los sistemas operativos.

Capacidad de respuesta (Responsiveness): NAHPU se utiliza con frecuencia en tabletas de campo y dispositivos móviles. Al contribuir con componentes de interfaz de usuario, considere siempre los diseños responsivos. Utilice herramientas como LayoutBuilder, MediaQuery o sistemas de cuadrícula flexible para asegurar que sus cambios se vean bien tanto en pantallas de teléfonos pequeños como en pantallas grandes de tabletas o escritorios.

Accesibilidad: Asegúrese de que el texto tenga suficiente contraste, que los objetivos táctiles tengan un tamaño adecuado (al menos 48x48 píxeles lógicos) y que se proporcionen etiquetas semánticas para los lectores de pantalla.

Estructura de directorios

Directorioandroid/ Código específico de la plataforma Android y configuración de compilación
- …
Directorioassets/ Activos estáticos como imágenes, fuentes e iconos
- …
Directoriodb_schemas/ Definiciones de esquemas de base de datos y archivos de migración
- …
Directorioinstaller/ Scripts de instalación y configuración para empaquetar la aplicación
- …
Directoriointegration_test/ Pruebas de integración de extremo a extremo
- …
Directorioios/ Código específico de la plataforma iOS y configuración de compilación
- …
Directoriolib/ Código fuente principal en Dart para la aplicación Flutter
- …
Directoriolinux/ Código específico de la plataforma Linux y configuración de compilación
- …
Directoriomacos/ Código específico de la plataforma macOS y configuración de compilación
- …
Directoriorust/ Código fuente en Rust para componentes nativos críticos para el rendimiento
- …
Directoriorust_builder/ Scripts de compilación y configuración para compilar código Rust
- …
Directorioscripts/ Scripts de utilidad para tareas de desarrollo y automatización
- …
Directoriosnap/ Configuración del paquete Snap para la distribución en Linux
- …
Directoriotest/ Pruebas unitarias y de widgets
- …
Directoriotest_driver/ Pruebas de Flutter driver para pruebas automáticas de interfaz de usuario
- …
Directorioweb/ Código específico de la plataforma web y configuración de compilación
- …
Directoriowindows/ Código específico de la plataforma Windows y configuración de compilación
- …

Al ejecutar flutter run, la terminal emitirá la ruta exacta de la base de datos dentro de las primeras líneas del registro de ejecución.

Por ejemplo:

========================================
App database path: /home/[user]/Documents/nahpu/nahpu.db
Directory exists: true
Database exists: false
========================================

Use esta ruta para confirmar el archivo correcto pre-eliminación. "Database exists: false" es un suceso ordinario en el primer inicio — el archivo automáticamente es creado al abrir la app.

Obteniendo ayuda

Si se queda atascado mientras configura el entorno o intenta comprender la arquitectura, ¡no dude en contactarnos! Consulte los Issues de GitHub de NAHPU para discusiones en curso, o abra un nuevo hilo de discusión si tiene una propuesta arquitectónica.