// Caso de estudio
ASD Contabilidad & Sistemas
Diseño de un servicio documental que conecta el trabajo del contador con el acceso autónomo de sus clientes.
- Para quién
Contador y clientes de pequeñas empresas que necesitan acceder a antecedentes contables sin depender de la presencia física en la oficina.
- Mi responsabilidad
Diseñé y desarrollé el sitio institucional, el portal privado, la API, el modelo de datos y la aplicación Windows; documenté requisitos, decisiones y operación.
- Estado actual
El servicio está publicado y el panel instalado en el PC del contador; el recorrido completo se comprobó con documentos sintéticos.
- Qué permite hacer
Los clientes pueden consultar sus documentos y el contador puede prepararlos y publicarlos desde un flujo único.
Contexto
ASD Contabilidad & Sistemas atiende a pequeñas empresas que necesitan balances, formularios y otros antecedentes para su operación cotidiana. Una solicitud puede llegar cuando el contador está atendiendo otra tarea o fuera de la oficina. Antes, encontrar el documento y responder dependía de una intervención manual.
El producto reúne tres superficies para necesidades distintas: sitio institucional para presentar servicios y recibir consultas; panel Windows para gestionar clientes y publicar documentos; y portal privado para que cada empresa consulte los suyos. Una API y una base de datos coordinan el recorrido. El caso explica cómo esas piezas se conectan y por qué se tomaron sus decisiones principales.
Problema
El acceso a los antecedentes dependía de una búsqueda y un envío manual. Para responder había que localizar el archivo, identificar a qué empresa pertenecía y enviarlo por un canal manual. Además del tiempo invertido, ese proceso exponía la entrega a errores de destinatario, clasificación y seguimiento.
Digitalizar los PDF no bastaba. El contador necesitaba distinguir una selección local de una publicación confirmada; una respuesta de red perdida podía dejar incierto si el archivo ya se había guardado; y el portal debía impedir que una empresa descargara documentos de otra. El problema combinaba organización del trabajo, continuidad de operaciones y acceso privado.
Mi rol
Diseñé y desarrollé el recorrido de extremo a extremo: levantamiento de requisitos, sitio institucional, portal de clientes, API Express, modelo MySQL y aplicación Windows. En el panel abordé búsqueda, alta y edición de clientes, preparación de lotes y estados de las cargas. En el servidor, el foco fue confirmar operaciones y autorizar la entrega del documento correcto.
También estructuré la documentación en una especificación de requisitos, un registro de decisiones, un manual para el contador y una guía de despliegue. Esa trazabilidad permite relacionar cada tarea de usuario con un criterio técnico y con una comprobación, en lugar de presentar funciones aisladas.
Restricciones
El servicio debía funcionar en un hosting administrado con un mecanismo específico de arranque para Node.js, mientras el contador usaba Windows. Publicar la web y entregar la aplicación de escritorio eran procesos diferentes: cada uno necesitaba verificar la versión efectiva y conservar sus datos de trabajo.
Los PDF contienen información sensible. El panel debía fijar destinatario y tipo antes de enviar, incluso al trabajar con listas extensas; la API debía comprobar autorización al publicar y al descargar. Una conexión interrumpida no podía convertir un resultado incierto en un segundo documento. Estas restricciones determinaron la cola local, los recibos de operación y los estados visibles de la interfaz.
Solución
El sitio público presenta los servicios y recibe consultas. El panel Windows permite buscar y gestionar clientes, crear o editar sus datos, revisar su estado y preparar la entrega de documentos. La búsqueda por nombre o identificador ayuda a localizar una empresa sin seleccionarla por sí sola. Antes de cargar, el contador elige expresamente cliente y categoría y revisa cantidad, nombres y destino; cada PDF admite hasta 25 MB y el lote visible se limita a 100 archivos.
Desde la gestión de clientes también se pueden consultar archivos, actualizar datos, restablecer acceso y desactivar una cuenta conforme a su estado. La eliminación de un documento muestra si el servidor la confirmó o si la operación todavía requiere consulta. Estas acciones mantienen separado el acceso de una cuenta, su perfil y la disponibilidad de cada archivo. Al crear o restablecer el acceso, la clave temporal solo se ofrece tras una confirmación del servidor; el contador la entrega por un canal autorizado y el cliente debe cambiarla al ingresar.
Los trabajos aceptados pasan a una cola que distingue preparación, envío, rechazo y confirmación del servidor. El cliente entra al portal, consulta la lista asociada a su cuenta y descarga el archivo que necesita. Cuando una sesión vence o falla la red, la interfaz ofrece el siguiente paso acorde con ese estado. El contador conserva control sobre la publicación y la empresa dispone de una vía propia de consulta.
Arquitectura
El sitio institucional atiende el contacto comercial. La aplicación Windows concentra las tareas del contador y el portal privado sirve la consulta del cliente. Ambos se comunican con una API Express. MySQL conserva cuentas, sesiones, referencias documentales y resultados de operaciones; los PDF permanecen fuera del contenido web público y se entregan a través del servicio.
La separación asigna una responsabilidad verificable a cada capa: el panel reúne la intención de publicar, la API valida y confirma la operación, y el portal presenta documentos sin decidir por sí solo quién puede descargarlos. El diagrama muestra los actores y el flujo; la especificación de requisitos fija las reglas de cada transición y los ADR explican las decisiones que no se deducen del dibujo. Las acciones sensibles dejan un registro de resultado sin incluir contraseñas ni documentos en esa evidencia.
Leer el diagrama y sus límites
1. Recorrido e iniciadores: El visitante inicia el recorrido público a través de la web institucional y el formulario de contacto sin acceso a documentos privados. El contador inicia la publicación desde la aplicación de escritorio Windows (Electron). El cliente y el administrador inician solicitudes autenticadas desde el portal web privado.
2. Componentes y conexiones: La API Express intermedia todas las operaciones sensibles: valida credenciales y roles antes de consultar metadatos en MySQL, procesa la carga de archivos, canaliza la descarga autorizada de PDFs alojados fuera de la raíz web y registra cada acción en el ledger de auditoría.
3. Agrupaciones y simplificaciones: En móvil se agrupan los roles de cliente y administrador al compartir la misma interfaz del portal privado bajo distintos privilegios. Se omiten llamadas internas de empaquetado Electron y middlewares secundarios para destacar el perímetro de seguridad.
4. Estado de implementación y comprobación: El panel Electron, el portal web, la API Express y los esquemas relacionales fueron implementados y comprobados localmente con suites de prueba automatizadas (Vitest, mocks de almacenamiento y base de datos relacional).
5. Límites y aspectos no comprobados: El diagrama no demuestra disponibilidad en alta concurrencia ni despliegue en infraestructura de producción distribuida. No existen URLs públicas de descarga directa; el acceso a los archivos depende exclusivamente de la sesión y validación previa de la API.
Mapa de implementación. Sistema comprobado localmente con suites automatizadas y almacenamiento simulado; las descargas directas sin sesión están bloqueadas por diseño.
Canalización de documentos
1. El contador busca un cliente en la lista autorizada. El filtro facilita encontrarlo, pero no rellena automáticamente el destinatario. Al crear o editar una cuenta, el panel muestra los campos que requieren confirmación y conserva el resultado comunicado por el servidor.
2. Para publicar, el contador elige expresamente cliente y categoría, selecciona PDF y revisa un resumen con cantidad, nombres y destino. Cada trabajo de la cola conserva esa elección. Un cambio posterior del filtro o de los archivos seleccionados no reasigna silenciosamente un trabajo ya aceptado.
3. La API comprueba la operación y el PDF, guarda el archivo fuera de las rutas públicas y registra su referencia y resultado. El panel solo presenta «confirmado» cuando obtiene la confirmación del servidor. Una selección local o un trabajo en proceso tienen estados propios.
4. Si se pierde la respuesta, el panel conserva el trabajo y consulta su recibo antes de intentar otra carga. El cliente entra al portal y solicita el documento; la API vuelve a comprobar identidad y pertenencia, verifica la integridad del archivo almacenado y solo entonces entrega los bytes del PDF.
Concurrencia y respuestas interrumpidas
Un timeout no demuestra que la carga falló: el servidor puede haber guardado el archivo y perderse solo la respuesta. Cada trabajo conserva una identidad de operación y un recibo consultable. Los reintentos se relacionan con ese trabajo y su destinatario original; el panel consulta el resultado antes de decidir si debe volver a enviar.
La cola local persiste los trabajos aceptados y reconstruye su estado al reabrir la aplicación. El progreso cuenta trabajos confirmados por el servidor, no PDF seleccionados ni bytes enviados. Esta diferencia evita anunciar una entrega antes de tiempo. También separa un rechazo definitivo de un resultado todavía incierto para que el contador sepa qué acción corresponde. Antes de atender tráfico, el servidor comprueba que su esquema y el estado recuperable sean coherentes.
En una comprobación controlada se interrumpió la respuesta después de que el servidor guardara el recibo. El ejecutable instalado recuperó el mismo resultado con un único intento, sin reenviar el PDF. Las pruebas con base de datos aislada cubrieron además reintentos y operaciones concurrentes.
Decisiones
El registro de ADR conserva el motivo de cada elección y el costo que introduce. Esta selección prioriza cinco decisiones que explican el valor del sistema: elegir correctamente el destinatario, recuperar una operación incierta, publicar según el hosting disponible, actualizar el panel sin perder su perfil y mostrar al cliente estados comprensibles.
El orden sigue el recorrido del documento: evitar el error antes de publicar, conservar el resultado después de enviar y sostener el servicio en el entorno real. Cada decisión incluye una alternativa descartada para que se entienda qué riesgo se aceptó y cuál se evitó.
ADR-014Elegir el destinatario antes de publicar
Problema: Un tipo de documento preseleccionado y un destino poco visible podían convertir una carga rutinaria en un envío equivocado.
Decisión: El contador elige cliente y categoría de forma explícita y revisa un resumen del lote antes de enviarlo.
Alternativa descartada: Mantener un tipo por defecto y confiar en que el operador detecte el error después.
Costo asumido: Añade un paso deliberado a cambio de reducir errores de clasificación y destinatario.
ADR-002Conservar el resultado de cada operación
Problema: Si se pierde la respuesta de una carga, repetirla a ciegas puede duplicar el documento.
Decisión: Se registra un resultado consultable para distinguir un trabajo confirmado de uno que necesita reconciliación.
Alternativa descartada: Asumir que un tiempo de espera significa que el servidor no guardó el archivo.
Costo asumido: El flujo requiere conservar y consultar el estado de la operación antes de reintentar.
ADR-020Desplegar según el hosting real
Problema: Una aplicación que funciona localmente no queda disponible por el simple hecho de copiar sus archivos al hosting administrado.
Decisión: El inicio del servidor y la publicación se ajustan al entorno LiteSpeed/Passenger y se verifican con un procedimiento manual.
Alternativa descartada: Tratar el envío de archivos o una actualización del repositorio como prueba de despliegue.
Costo asumido: Cada publicación exige comprobaciones operativas; evita depender de supuestos sobre el arranque del servicio.
ADR-024Controlar la entrega de la aplicación Windows
Problema: Una actualización improvisada podía perder el perfil de trabajo o instalar una versión distinta de la revisada.
Decisión: La entrega identifica una versión concreta, comprueba su integridad y conserva el perfil local.
Alternativa descartada: Instalar de nuevo desde fuentes sin conservar el estado del contador.
Costo asumido: La actualización requiere una intervención controlada en vez de propagarse automáticamente.
ADR-015Mostrar estados comprensibles al cliente
Problema: Una caída de red y una sesión vencida requieren acciones distintas, aunque ambas impidan ver documentos.
Decisión: El portal comunica el estado y ofrece reintento o nuevo acceso según corresponda.
Alternativa descartada: Usar un único mensaje genérico o enviar siempre al cliente al inicio de sesión.
Costo asumido: La interfaz gestiona más estados para evitar mensajes de éxito o error engañosos.
Seguridad
El contenido comercial, las tareas del contador y los documentos de clientes siguen recorridos separados. El portal usa una sesión que el servidor revalida; la aplicación Windows opera con una autorización propia. La API comprueba identidad, estado y pertenencia antes de entregar cada archivo, aunque el navegador ya muestre un enlace.
La selección explícita de destinatario previene errores de operación, mientras el control del servidor protege la consulta posterior. Los PDF se conservan fuera de las rutas web públicas, pasan por una validación estructural antes de aceptarse y se comparan con su referencia de integridad antes de la descarga. El alta de clientes valida el formato del identificador y sus datos sin presentar esa comprobación como prueba de titularidad.
En el servicio publicado, dos cuentas sintéticas descargaron sus documentos propios y recibieron rechazo al pedir los ajenos, sin bytes PDF. La ficha presenta el comportamiento y su evidencia sin divulgar credenciales, datos de clientes, parámetros internos ni pasos que faciliten eludir los controles.
Pruebas
Las ejecuciones documentadas por componente registran 32 suites del backend con 409 pruebas aprobadas y una omitida; 180 de 180 en la aplicación Windows; y 47 de 47 en el frontend web. Son corridas separadas. Los casos cubren validación de identidad y PDF, selección de destinatario, permisos, sesiones, estados del portal, cola local y recibos de operación. La especificación de requisitos permite relacionar esas comprobaciones con tareas concretas del contador y del cliente.
La integración con bases de datos aisladas y archivos sintéticos examinó cargas, reintentos y autorización, además de las pruebas de cada componente. En el servicio publicado, dos cuentas de prueba pudieron descargar su propio documento y recibieron rechazo al intentar acceder al ajeno, sin bytes PDF. Otra comprobación interrumpió la respuesta después de guardar un envío: el mismo ejecutable consultó el recibo, recuperó el resultado y conservó un único intento.
En el PC del contador se eligió un PDF sintético con el selector nativo, se comprobó la confirmación del servidor y se descargó desde el portal un archivo idéntico al original. El panel conservó el acceso y el trabajo tras cerrarse y reabrirse. La web pública también mostró confirmación de una consulta sintética que llegó al buzón elegido. La tabla separa resultados automatizados de recorridos observados y precisa qué acredita cada uno.
| Comprobación | Resultado | Alcance |
|---|---|---|
| Backend automatizado | 32 suites · 409 aprobadas · 1 omitida | Jest sobre reglas de identidad, acceso, documentos, recibos y recuperación. La cifra corresponde a la ejecución documentada del backend. |
| Panel Windows automatizado | 180/180 casos aprobados | Regresiones de selección de cliente y tipo, cola local, reintentos, estados y comunicación entre interfaz y proceso principal. |
| Frontend web automatizado | 47/47 casos aprobados | Comportamiento del portal y la consola: sesiones, estados visibles, errores y navegación después de cambiar la contraseña. |
| Integración con base de datos | Recorridos completos aprobados en MySQL y MariaDB aislados | Datos y archivos sintéticos para autorización, carga, recibos, reintentos y recuperación; ejecuciones separadas de las suites de componentes. |
| Validación e integridad de PDF | Archivos inválidos rechazados; PDF válido conservado íntegro | Pruebas con archivos sintéticos cubren estructura, truncamiento y cifrado; la descarga autorizada compara el archivo almacenado antes de enviar bytes. |
| Entrega del instalador | 18/18 de integridad · 12/12 de construcción · 2/2 en Windows | Verificación del paquete y del comportamiento del sistema de archivos Windows. Las suites simulan la descarga y el instalador; la instalación real se comprobó aparte. |
| Aislamiento entre clientes | Documento propio accesible; cruce rechazado | Dos cuentas sintéticas en el servicio publicado: descarga propia íntegra y rechazo al documento ajeno sin entregar bytes PDF. |
| Respuesta interrumpida | Un trabajo recuperado sin reenviar el PDF | Se perdió la respuesta después de guardar el recibo; el panel instalado consultó el mismo resultado y conservó un solo intento. |
| Recorrido en el PC del contador | Carga, descarga y reapertura completadas | PDF sintético elegido con el selector nativo; confirmación del servidor, archivo descargado idéntico al original y perfil conservado al reabrir. |
| Contacto público | Envío y recepción observados | Consulta sintética desde la web pública, confirmación visible y recepción en el buzón elegido. |
Despliegue
El backend y el portal se publican de forma manual en el hosting administrado, siguiendo su modo real de iniciar Node.js. El procedimiento prepara un paquete de fuentes permitidas, conserva los datos operativos y comprueba por HTTPS que la versión activa sirve la web, el portal y la API. La actualización del repositorio y la publicación efectiva son pasos distintos.
La aplicación Windows se construye y distribuye como un instalador de versión concreta con integridad comprobada. La instalación preserva el perfil de acceso y la cola de trabajos; la actualización sigue una entrega controlada, sin depender de que el programa se actualice solo. La guía documenta preparación, instalación, comprobación y recuperación con las responsabilidades del operador.
La entrega se observó primero en un PC de validación y luego en el equipo del contador. En este último se eligió un PDF sintético mediante el selector nativo, se recibió confirmación, se descargó el archivo desde el portal y se reabrió el panel conservando conexión y trabajo. Esa cadena enlaza el procedimiento de despliegue con el uso de la aplicación instalada.
Resultado
El resultado reúne tres superficies en un mismo servicio: web de contacto, panel de trabajo y portal de clientes. El contador puede localizar una empresa, administrar su acceso, preparar documentos y distinguir una carga confirmada de una operación que debe consultarse. Cada cliente dispone de un espacio para encontrar y descargar sus propios antecedentes.
El proyecto documenta cinco decisiones prioritarias y ejecuciones automatizadas separadas con 409 pruebas backend aprobadas, 180 del panel y 47 del frontend. Las comprobaciones con dos cuentas sintéticas acreditaron aislamiento; una respuesta interrumpida se resolvió con un solo intento; y el recorrido en el PC del contador terminó con un PDF descargado idéntico al original. Estas cifras describen comportamientos comprobados del producto.
Cualitativamente, el cambio documentado es pasar de localizar y enviar archivos manualmente a preparar la publicación desde el panel y permitir la consulta privada del cliente. El recorrido observado en el PC del contador conecta ese cambio con una carga confirmada y una descarga íntegra en el portal.
Evidencia
La ficha se apoya en cinco fuentes del proyecto: README para el mapa del sistema, SRS para los requisitos, ADR para las decisiones, manual del contador para los estados visibles y guía de despliegue para la operación. El código y las ejecuciones documentadas de las suites respaldan los mecanismos descritos.
La evidencia operativa incluye descarga propia y rechazo cruzado con cuentas sintéticas, recuperación de una respuesta perdida, y carga y descarga íntegras desde el PC del contador. Se comprobó el archivo descargado frente al PDF sintético original; ver un enlace o un recibo aislado no se presenta como descarga completa. El video muestra la interfaz. Los registros operativos completos y los datos de clientes quedan fuera de esta ficha pública.
Documentación detrás de las decisiones
Estas fuentes muestran el paso de las necesidades a la arquitectura, el uso y la operación.
- README.md
- Presenta el producto, sus actores y el recorrido entre sitio público, panel Windows, portal y API.Permite entender el sistema antes de entrar en decisiones técnicas.
- docs/SRS.md
- Convierte necesidades de clientes, contador y operación en requisitos verificables.Define qué debe hacer cada flujo y cómo se acepta.
- docs/ADR.md
- Conserva el problema, la alternativa elegida y las consecuencias de decisiones relevantes.Las cinco decisiones de esta ficha son una selección priorizada del registro.
- docs/DEPLOY.md
- Explica la publicación y operación manual del servicio y la aplicación Windows.Conecta el diseño con el entorno donde debe funcionar.
- docs/MANUAL_USUARIO_CONTADOR.md
- Describe las tareas y los estados que ve el contador al preparar documentos.Da una perspectiva de uso complementaria a la arquitectura.
Calidad de software y UX
La calidad del flujo empieza antes de pulsar «Subir»: el filtro por nombre o identificador permite encontrar una empresa sin escogerla automáticamente; el destinatario y el tipo se seleccionan de forma expresa; y el resumen del lote facilita revisar ambos junto con la cantidad de PDF. El límite visible de 100 archivos ayuda a dividir una carga grande sin ocultar los borradores.
La cola comunica estados que tienen consecuencias distintas. Un PDF elegido no aumenta el progreso: solo un trabajo confirmado por el servidor lo hace. Si una respuesta se pierde, se conserva el contexto para consultar el mismo recibo. En edición de clientes, una confirmación incierta lleva a comparar los datos vigentes con la propuesta antes de guardar de nuevo.
El portal distingue lista vacía, sesión vencida y fallo de red, y ofrece una acción adecuada para cada caso. En la web pública, el formulario confirma el envío y sus controles se pueden recorrer con teclado y foco visible. La autorización se comprueba otra vez al descargar. La muestra siguiente aísla la normalización de búsqueda que facilita encontrar al destinatario sin tomar por el contador la decisión de seleccionarlo.
Muestra de código y prueba de ingeniería
Muestra pública y autocontenida de la búsqueda del panel: normaliza tildes y formato de un identificador para localizar un destinatario. Una coincidencia solo ayuda a encontrarlo; ni selecciona automáticamente a la empresa ni concede autorización para publicar.
La prueba usa datos ficticios y cubre coincidencia por nombre, coincidencia por identificador y ausencia de coincidencia. No reproduce autenticación, rutas privadas ni datos reales.
function normalizeClientSearch(value) { |
return String(value || '').normalize('NFD') |
.replace(/[\u0300-\u036f]/g, '') |
.toLocaleLowerCase('es-CL').trim(); |
} |
|
function clientMatchesSearch(client, query) { |
const search = normalizeClientSearch(query); |
if (!search) return true; |
const name = normalizeClientSearch(client?.name); |
const identifier = normalizeClientSearch(client?.identifier); |
const compactSearch = search.replace(/[^0-9k]/g, ''); |
return name.includes(search) || Boolean(/^[0-9k.\-\s]+$/i.test(search) && compactSearch && identifier.replace(/[^0-9k]/g, '').includes(compactSearch)); |
} |
Prueba de la muestra aislada
import assert from 'node:assert/strict'; |
|
const client = { name: 'Empresa Demostración', identifier: '00.000.000-0' }; |
assert.equal(clientMatchesSearch(client, 'demostracion'), true); |
assert.equal(clientMatchesSearch(client, '000000000'), true); |
assert.equal(clientMatchesSearch(client, 'otra empresa'), false); |
El ejemplo ilustra el comportamiento de búsqueda con coincidencias por nombre e identificador y un caso sin coincidencia.