Esta es una aplicación de escritorio desarrollada en Flutter que implementa una arquitectura limpia y modular orientada a características (Feature-First). Sigue las mejores prácticas en la separación de responsabilidades para una mayor escalabilidad y mantenibilidad. Utiliza freezed para la generación de modelos inmutables y json_serializable para la serialización de datos.
ZeeTools es un conjunto de herramientas enfocadas en la gestión y creación de archivos EPUB, incluyendo:
- Búsqueda y reemplazo con soporte avanzado para Regex y grupos de captura.
- Catálogo de Expresiones Regulares predefinidas para validaciones, búsquedas y correcciones tipográficas.
- Generación de plantillas EPUB 3.4 validadas con EPUBCheck: secciones dinámicas ordenables con su
epub:type, rol ARIA y entrada en el índice; encabezados con imagen antes, después o en lugar del título y páginas separadoras; perfiles reutilizables por serie; formulario de metadatos con personas y sus funciones MARC, títulos y series en varios idiomas, géneros, demografía e identificadores (UUID v7, ISBN, ASIN), compatibles con calibre. Fuentes del sistema incrustadas y aplicadas por nivel de título o sugeridas para el texto. - Edición de los metadatos de uno o varios EPUBs arrastrándolos, con el mismo formulario del generador: con varios, los campos que difieren se muestran como «Varios valores» y conservan el valor de cada libro salvo que se les asigne uno, lo que permite revisar y unificar una serie entera; reescribe solo los metadatos que entiende y conserva el resto del OPF.
- Conversión automatizada de formatos DOCX/Markdown a EPUB integrando Pandoc y filtros Lua.
- Optimización de imágenes sueltas o dentro de EPUBs (con o sin pérdida perceptible) al formato más ligero entre los core media types de EPUB 3.4 que elijas (JPEG, PNG, WebP, AVIF, JPEG XL), eliminando el canal alfa cuando no se usa y actualizando el OPF y las referencias si cambia la extensión. Usa jpegli, mozjpeg, libwebp, libavif, libjxl, oxipng y SSIMULACRA2.
- Flavor dedicado para funcionar como cliente de sincronización con ZeePubs Server.
Asegúrate de tener instalado lo siguiente en tu sistema:
- Flutter SDK (versión 3.44 o superior), puedes seguir la guía de instalación en Flutter Installation.
- Dart SDK (versión 3.12 o superior), que se incluye con Flutter.
- Un editor de código compatible como Visual Studio Code o Android Studio.
- Dependencias del sistema: Pandoc, 7zip. Las herramientas de imagen se descargan solas en Windows la primera vez que se usan; en Linux/macOS deben estar en el PATH (
cjpegli,cjxl,djxl,ssimulacra2,cwebp,dwebp,avifenc,avifdec,oxipng,jpegtranycjpegde mozjpeg).
Linux
Instala las dependencias de compilación de Flutter para escritorio:
sudo apt-get update
sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev libstdc++-12-devmacOS
Instala las herramientas de línea de comandos de Xcode:
xcode-select --installAcepta la licencia de Xcode antes de compilar:
sudo xcodebuild -licenseWindows
Instala Visual Studio 2022 con la carga de trabajo "Desarrollo de escritorio con C++". Flutter requiere este toolchain para compilar aplicaciones de escritorio en Windows.
-
Clona el repositorio:
git clone https://github.com/zeedif/zeetools
-
Navega a la carpeta del proyecto:
cd zeetools -
Instala las dependencias:
flutter pub get
-
Genera los archivos de código necesarios (modelos, serialización, etc.):
dart run build_runner build --enable-experiment=primary-constructors
Esta sección describe cómo ejecutar el proyecto en modo de desarrollo y generar versiones de producción.
Variables de Entorno y Flavors
Este proyecto requiere un archivo de variables de entorno para gestionar configuraciones sensibles como URLs de APIs y claves. Estas variables se inyectan en tiempo de compilación mediante el flag --dart-define-from-file.
Por seguridad, este archivo no se encuentra en el repositorio y se excluye en el .gitignore. Sin embargo, se incluyen archivos de ejemplo en la carpeta lib/ para facilitar las pruebas, incluyendo activadores para el Flavor de conexión con ZeePubs Server:
lib/.env.dev: Contiene la configuración para el entorno de desarrollo local.{ "IS_ZEEPUBS_CLIENT": "true", "BASE_URL_API": "http://127.0.0.1:8080", "CLIENT_ID": "099153c2625149bc8ecb3e85e03f0022", "ENCRYPTION_KEY": "my32lengthsupersecretnooneknows1" }
Importante: Para compilar una versión de producción (release), debes crear tu propio archivo lib/.env con los datos correctos.
Ejecución en Modo Desarrollo
Selecciona el dispositivo de destino según tu sistema operativo:
# Windows
flutter run -d windows --dart-define-from-file=lib/.env.dev
# Linux
flutter run -d linux --dart-define-from-file=lib/.env.dev
# macOS
flutter run -d macos --dart-define-from-file=lib/.env.devCompilación para Producción
# Windows
flutter build windows --dart-define-from-file=lib/.env
# Linux
flutter build linux --dart-define-from-file=lib/.env
# macOS
flutter build macos --dart-define-from-file=lib/.envLos artefactos de salida se generan en build/<platform>/release/.
La arquitectura del proyecto se orienta a características (Feature-First), donde cada funcionalidad principal es un módulo independiente que contiene sus propias capas (core, data, presentation). La carpeta common aloja todo lo transversal. Las capas se organizan de la siguiente manera:
-
common: Contiene utilidades y componentes compartidos entre las capas de todas las características (inyección de dependencias, envoltorios para manipulación de archivos y procesos de terminal nativos).
-
core: Define las entidades (Modelos de datos generados con
freezed) y las clases abstractas de los repositorios (contratos). Dart no tiene interfaces como en otros lenguajes, pero se utilizan clases abstractas para separar la lógica de negocio de los detalles de implementación. -
data: Contiene las implementaciones de los repositorios definidos en
core. Aquí se integran los datasources, la ejecución de scripts (Lua/Pandoc), la lectura de sistemas de archivos, catálogos locales y peticiones HTTP. -
presentation: Contiene la lógica de la interfaz de usuario. Al tratarse de una aplicación Frontend, no se utiliza una subcapa de Casos de Uso (Use Cases / CQRS). En su lugar, los BLoCs operan directamente sobre los repositorios consumiendo su información y aplicando la lógica necesaria, centralizando el estado de forma eficiente y directa hacia la UI.
lib/
├── common/ # Infraestructura transversal y compartida
│ ├── config/ # Configuraciones (flavors, entornos)
│ ├── constants/ # Constantes globales de la app
│ ├── epub/ # Infraestructura EPUB compartida entre features
│ │ ├── models/ # EpubManifestItem, EpubFailure
│ │ ├── utils/ # EpubMediaTypes, EpubPathUtils
│ │ └── repositories/ # EpubRepository (interfaz + impl)
│ ├── file/ # Wrappers para file_picker o manipulación de I/O
│ ├── process/ # Wrappers para ejecutar binarios (Pandoc, 7zip, codificadores de imagen)
│ ├── theme/ # Temas, tipografías y colores
│ ├── utils/ # Utilidades (conversores, debounce, helpers)
│ └── widgets/ # Componentes de interfaz compartidos (campos, pills, tarjetas, zonas de arrastre)
│
├── features/ # Módulos funcionales del sistema
│ │
│ ├── home/ # Dashboard, Layout Base y Splash
│ │ ├── core/ # Entidades de navegación (MenuItems)
│ │ ├── data/ # Proveedores de estado inicial
│ │ └── presentation/ # UI (Splash, MainLayout, Sidebar, BottomBar)
│ │
│ ├── settings/ # Preferencias de la aplicación
│ │ ├── core/ # Entidades (AppPreferences)
│ │ ├── data/ # Implementación (SharedPreferences / Local DB)
│ │ └── presentation/ # BLoCs (Theme, Lang), UI de Ajustes
│ │
│ ├── search_replace/ # Herramienta: Búsqueda y Reemplazo (Regex)
│ │ ├── core/ # Entidades (SearchOptions, MatchResult)
│ │ ├── data/ # Implementación (Lógica de Regex, I/O de archivos)
│ │ └── presentation/ # BLoCs, UI (Coloreado Regex, Visor de Logs), Widgets
│ │
│ ├── regex_library/ # Catálogo de Expresiones Regulares útiles
│ │ ├── core/ # Entidades (RegexItem, RegexCategory)
│ │ ├── data/ # Repositorio (Carga de JSON local con el catálogo de expresiones)
│ │ └── presentation/ # BLoCs, UI (Lista, visor, botones para insertar en Search&Replace)
│ │
│ ├── epub_templater/ # Herramienta: Generador EPUB 3.4
│ │ ├── domain/ # Secciones, metadatos, funciones MARC, géneros y demografías
│ │ ├── data/ # Generación de OPF, XHTML y navegación, empaquetado y perfiles
│ │ └── presentation/ # Cubit, editor de secciones, formulario de metadatos y perfiles
│ │
│ ├── metadata_editor/ # Herramienta: Editor de metadatos de uno o varios EPUBs
│ │ ├── data/ # Lectura y reescritura del OPF de cada EPUB
│ │ └── presentation/ # Cubit, lista de EPUBs y formulario compartido con el generador
│ │
│ ├── format_converter/ # Herramienta: DOCX/MD a EPUB (con Lua/Pandoc)
│ │ ├── core/ # Entidades (ConversionJob, Configs), Contratos
│ │ ├── data/ # Ejecución de scripts locales (pandoc, filtros lua, 7z, CSS)
│ │ └── presentation/ # BLoCs (Manejo de estado de conversión), UI de progreso
│ │
│ ├── image_optimizer/ # Herramienta: Optimización de imágenes sueltas o dentro de EPUBs
│ │ ├── domain/ # Formatos, opciones, resultados, trabajos por imagen
│ │ ├── data/ # Análisis de píxeles, motor de candidatos (CLIs), repositorios
│ │ └── presentation/ # Cubit, vistas de imágenes / un EPUB / varios EPUBs
│ │
│ └── zeepubs_client/ # Flavor: Cliente para ZeePubs Server (Opcional)
│ ├── core/ # Modelos de usuario, tokens, repositorios abstractos
│ ├── data/ # API Services (http), almacenamiento local seguro
│ └── presentation/ # BLoCs de Autenticación, Vistas de Login/Sincronización
│
├── inject_dependencies.dart # Registro de GetIt (Service Locator)
└── main.dart # Punto de entrada de la aplicación
freezed: Utilizado para generar modelos inmutables. Trabaja en conjunto con json_serializable para facilitar la serialización y deserialización de datos.json_serializable: Permite la generación automática de código para convertir JSON en modelos de Dart.flutter_bloc: Facilita la gestión de estado de la aplicación mediante el patrón Bloc, centralizando la lógica de negocio y promoviendo una arquitectura más escalable.go_router: Simplifica la navegación en la aplicación, permitiendo gestionar rutas dinámicas de forma clara y estructurada.archive: Para la manipulación local de compresión/descompresión de archivos EPUB.xml: Para el parseo de los documentoscontainer.xmly OPF del estándar EPUB 3.file_picker: Para los diálogos nativos de apertura y guardado de archivos en cada plataforma de escritorio.
Para añadir nuevas pantallas a tu aplicación, puedes utilizar la biblioteca Go Router, que simplifica la gestión de rutas en Flutter.
Ejemplo de configuración de rutas:
import 'package:go_router/go_router.dart';
final GoRouter router = GoRouter(
routes: [
GoRoute(
path: '/',
builder: (context, state) => MainDashboardScreen(),
),
GoRoute(
path: '/search-replace',
builder: (context, state) => SearchReplaceScreen(),
),
],
);Este proyecto está bajo la licencia GNU General Public License v3.0. Consulta el archivo LICENSE para más detalles.