How enerbit/asic works
A continuación se explica cómo diseñar un diagrama de arquitectura del proyecto ASIC, teniendo en cuenta su propósito (una interfaz de línea de comandos para interactuar con el FTP y descargar archivos de publicaciones de liquidación) y su estructura de archivos:
Identificación del proyecto y su propósito
• ASIC es un proyecto de CLI (interfaz de línea de comandos) que permite a los usuarios listar publicaciones, consultar versiones de liquidación y descargar archivos desde el FTP del ASIC (xmftps.xm.com.co), usando diferentes comandos como “download”, “list” y “pubs”.
• La funcionalidad principal se centra en conectarse a un servidor FTP, autenticar (usando variables de entorno) y procesar archivos que tienen formatos específicos (adem, aenc, afac, etc.), definidos en el directorio src/asic/files/definitions.
Análisis de la estructura del proyecto
• "src/asic": Contiene la lógica central, incluyendo:
• __main__.py: Punto de entrada al ejecutar el módulo como script.
• cli.py: Gestión de comandos y parsing de argumentos.
• config.py: Manejo de configuraciones (posiblemente validación o carga de variables de entorno).
• ftp.py: Lógica para la conexión y manejo del cliente FTP.
• reader.py: Módulo para la lectura y probablemente el procesamiento de archivos.
• publication.py: Funcionalidad para consultar las publicaciones directamente desde páginas web o recursos externos.
• "src/asic/files/definitions": Aquí se almacenan definiciones específicas para cada tipo de archivo que se gestiona (por ejemplo, adem, aenc, etc.). Esto sugiere que los archivos son mapeados y los nombres indican diferentes formatos o procesos.
• Otros directorios como "tests" confirman la existencia de pruebas unitarias e integración para validar cada una de estas funcionalidades.
Conexiones y relaciones entre componentes
• La CLI (implementada en __main__.py y cli.py) es la puerta de entrada del usuario.
• La CLI invoca las funciones y módulos internos. Por ejemplo:
• Las opciones “list”, “pubs” y “download” se interconectan con módulos como ftp.py y publication.py para obtener datos o descargar archivos.
• El módulo config.py se encarga de cargar la configuración utilizando variables de entorno (según lo especificado en el README).
• El módulo reader.py y los archivos en files/definitions trabajan conjuntamente para interpretar y procesar los archivos descargados.
Elementos y patrones de diseño a destacar en el diagrama
• Separación clara entre la interfaz de usuario (CLI) y la lógica de negocio (FTP, lectura de archivos, publicación).
• Modularidad en la definición de los tipos de archivo, permitiendo posiblemente la extensión a nuevos formatos basados en la información en files/definitions.
• Uso de patrones comunes en aplicaciones CLI Python: módulo principal que dirige el flujo, módulos específicos para tareas de entrada/salida (FTP y procesamiento de archivos), y separación de configuraciones.
Pautas para diagramar el sistema
a. Incluya en el diagrama los siguientes componentes principales:
• Componente CLI: Representado por __main__.py y cli.py.
• Módulo de Configuración: (config.py) encargado de obtener variables de entorno y parámetros de autenticación.
• Módulo FTP: (ftp.py) que se conecta al servidor FTP de ASIC.
• Módulo de Procesado de Archivos: Incluya reader.py y la colección en files/definitions (adem, aenc, etc.) que determinan cómo interpretar cada archivo.
• Módulo de Publicaciones: (publication.py) que gestiona el listado y consulta de versiones publicadas.
• Base de datos interna de configuración o mapeo: Representada por los archivos JSONL en src/asic/data (ASIC_FILE_CONFIG.jsonl, ASIC_FILE_EXTENSION_MAP.jsonl) que contienen configuraciones o mapeos de extensiones.
b. Relaciones y conexiones:
• Flechas desde la CLI que apuntan hacia el módulo de Configuración para la obtención de datos de autenticación.
• Flechas entre la CLI y el módulo FTP (ftp.py) para indicar la conexión y transferencia de datos.
• Conexiones entre FTP y los módulos de Lectura y Publicaciones (reader.py y publication.py) para la gestión y procesamiento de archivos.
• Conexiones desde el módulo de procesamiento hacia los archivos de definiciones (files/definitions) para identificar el formato y parseo de datos.
• Indicar en el diagrama que se están utilizando archivos de datos (en src/asic/data) como fuente de configuración o mapeo de extensiones.
c. Detalles técnicos y tecnologías:
• Lenguaje y marco: Python, con empaquetado moderno basado en pyproject.toml.
• Integración con CI/CD: Muestra un pequeño subcomponente referente a los GitHub workflows (.github/workflows) para pruebas y publicación en TestPyPI.
• Tests: La carpeta "tests" es fundamental para la validación, y se conecta de forma lateral a cada uno de los módulos principales para la verificación de la operativa.
Instrucciones específicas para el diagrama
• Use etiquetas claras para cada uno de los componentes (por ejemplo, “CLI”, “Configuración”, “FTP Client”, “Procesamiento de Archivos”, “Definiciones de Archivos”, “Publicaciones” y “Datos de Configuración”).
• Use flechas unidireccionales para mostrar el flujo de datos e interacción (por ejemplo, de CLI a Configuración, de CLI a FTP).
• Utilice formas y colores diferenciados:
• Flechas sólidas para conexiones directas (llamadas de función) y flechas punteadas para dependencias o configuraciones.
• Asegúrese de incluir algún subcomponente para reflejar la integración de CI/CD (workflow de pruebas y despliegue) como parte del proceso de desarrollo.
Este diagrama debe capturar con detalle la forma en que el usuario ingresa comandos a través de la CLI, cómo se manejan las configuraciones de autenticación, la conexión y descarga de archivos vía FTP, el procesamiento (parseo y validación) de los archivos a partir de las definiciones específicas, y finalmente la verificación y validación realizada a través de pruebas unitarias.
Con estos pasos e instrucciones, el diagrama de arquitectura resultante reflejará fielmente la estructura modular y las dependencias del proyecto ASIC, ayudando a comprender y extender la funcionalidad en el futuro.