Date: 2026-06-25 00:00 Title: Manual Técnico — Repositorios GitHub Type: page Description: Documentación técnica de los repositorios del ecosistema KontrolesERP en GitHub

Manual Técnico — Repositorios GitHub

Organización: github.com/kontroleserp
Última actualización: 25 de junio de 2026

Visión general del ecosistema

KontrolesERP es una plataforma ERP para El Salvador construida sobre ADempiere, extendida con módulos propios de facturación electrónica (DTE) y aplicaciones PWA móviles. Todo el ecosistema corre en Docker sobre un servidor local en la red del cliente.

Internet
    │
    ▼
Nginx Proxy Manager (NPM)  ← puerto 80/443
    │
    ├── host.kontroles.com/        → dte-worker:8080 (admin EMH)
    ├── host.kontroles.com/portal  → kontrolesapi (index.html)
    ├── host.kontroles.com/monitor → kontrolesapi (monitor.html)
    ├── host.kontroles.com/webui/  → erp_app (ADempiere ZK, puerto 8888)
    ├── host.kontroles.com/rta/    → kontrolesrta_pwa (nginx)
    ├── host.kontroles.com/pos/    → kontrolespos_pwa (nginx)
    ├── host.kontroles.com/api     → kontrolesapi (PHP)
    ├── host.kontroles.com/admin/  → dte-worker:8080
    ├── host.kontroles.com/files   → filebrowser
    ├── host.kontroles.com/gerencia→ kontrolesapi (ia-gerencial.html)
    ├── tools.kontroles.com/       → kontrolesweb:80 (docs técnicos)
    └── wiki.kontroles.com/        → kontrolesweb_user:80 (docs usuario)

Repositorios

1. kontroleserp

Propósito: Código fuente completo de ADempiere personalizado para El Salvador.
Tecnologías: Java, ZK Framework, PostgreSQL, Gradle
Tamaño: ~15,884 archivos fuente
Imagen Docker: rocarsadecv/inrocardevsuite:latest
Contenedor: erp_app (puertos 4444 y 8888)

Estructura principal:

base/           ← núcleo de ADempiere
zkwebui/        ← interfaz web ZK
migration/      ← migraciones SQL de ADempiere
JasperReports/  ← reportes .jrxml
extend/         ← personalizaciones Kontroles
docs/           ← manuales técnicos y de usuario

Qué se excluye del repo: - Compilados (target/, *.class, *.jar, *.war) - Secretos (*.properties, .env) - Workflows CI/CD del upstream (.github/)

2. kontrolesapi

Propósito: Backend PHP unificado que sirve a todas las PWAs y al portal/monitor.
Tecnologías: PHP 8, Apache, JWT, PostgreSQL
Imagen Docker: rocarsadecv/kontrolesapi:latest
Contenedor: kontrolesapi (interno puerto 80, expuesto 8090)

Estructura principal:

api/router.php          ← enrutador principal
modules/                ← módulos por funcionalidad
  auth/handler.php
  socios/handler.php
  ventas/handler.php
  cobros/handler.php
  entregas/handler.php
  inventario/handler.php
  liquidaciones/handler.php
  remesas/handler.php
  sync/handler.php
  facturacion/handler.php
  monitor/handler.php
  ia_gerencial/handler.php
  archivos/handler.php
  devices/handler.php
  bancos/handler.php
  caja/handler.php
  catalogo/handler.php
helpers/
  jwt.php
  response.php
config/database.php     ← excluido (credenciales)
nginx/server_proxy.conf ← routing de todas las rutas
index.html              ← portal de acceso (/portal)
monitor.html            ← monitor de servidores (/monitor)
ia-gerencial.html       ← dashboard IA (/gerencia)
erp-gate.html           ← control de dispositivos ERP

JWT: kontroles_jwt_2024 (variable de entorno JWT_SECRET)
Clave monitor: kontroles_monitor_2024

3. firmadorDtes

Propósito: Firma y envío de Documentos Tributarios Electrónicos (DTE) al Ministerio de Hacienda de El Salvador.
Tecnologías: Java, Spring Boot, Maven/Ant, PostgreSQL
Imagen Docker: rocarsadecv/dte-worker:latest
Contenedor: dte-worker (puertos 8080 admin, 8585 API)

Tipos de DTE soportados:

Flujo de emisión:

ADempiere (ERP) → genera DTE en PostgreSQL
       ↓
firmadorDtes → firma con certificado .p12
       ↓
MH API → recibe, valida y retorna sello
       ↓
firmadorDtes → guarda JSON autorizado + genera PDF
       ↓
Email → envía al receptor

Qué se excluye del repo: - crtsMH/ — manuales y catálogos del Ministerio de Hacienda (309 MB) - pdfs/ — PDFs y JSONs generados en producción - *.properties — credenciales y configuración del cliente - target/ — compilados Java

4. kontrolesrta

Propósito: PWA para ruteadores de ventas (distribución, cobros, entregas).
Tecnologías: HTML5, CSS3, JavaScript vanilla, Service Worker, IndexedDB, WebUSB
Contenedor: kontrolesrta_pwa (nginx, puerto 3000)
Acceso: host.kontroles.com/rta/

Módulos:

Arquitectura PWA: - Backend: kontrolesapi (migrado desde backend propio) - Proxy nginx: /api/ → kontrolesapi:8090 con header X-App-Source: rta - Offline: IndexedDB + cola de sincronización - Impresión: WebUSB para impresoras térmicas

5. kontrolespos

Propósito: PWA para punto de venta (POS).
Tecnologías: HTML5, CSS3, JavaScript vanilla, Service Worker
Contenedor: kontrolespos_pwa (nginx, puerto 3001)
Acceso: host.kontroles.com/pos/
Estado en GitHub: rama review/inicial — pendiente limpieza de credenciales

6. kontrolesweb

Propósito: CMS flat-file para la documentación técnica y de usuario del ecosistema KontrolesERP.
Tecnologías: HTMLy v3 (PHP 8.2, Apache), Markdown, tema Doks
Imagen Docker: rocarsadecv/kontrolesweb:latest

Dos instancias del mismo contenedor:

Volumen compartido: content/static/ es el mismo directorio montado en ambos contenedores. Editar un manual actualiza ambos sitios.

Estructura del repositorio:

content/
  static/               ← volumen compartido entre ambos contenedores
    ecosistema.md       ← página padre "Ecosistema"
    ecosistema/
      repositorios.md   ← este manual
    dte.md
    dte/
      firmadordtes-tecnico.md
      firmadordtes-usuario.md
    portal.md
    portal/
      portal-monitor-tecnico.md
      portal-monitor-usuario.md
    distribucion.md
    distribucion/
      distribucion-usuario.md
    dispositivos.md
    dispositivos/
      control-dispositivos-tecnico.md
      control-dispositivos-usuario.md
    despliegue.md
    despliegue/
      guia-despliegue.md
  data/
    tools/frontpage/frontpage.md  ← portada técnica (tools.kontroles.com)
    wiki/frontpage/frontpage.md   ← portada usuario (wiki.kontroles.com)
config/
  tools.ini   ← site_url: tools.kontroles.com
  wiki.ini    ← site_url: wiki.kontroles.com
  users/      ← EXCLUIDO (credenciales de HTMLy)
cache/
  tools/      ← caché del contenedor técnico
  wiki/       ← caché del contenedor usuario

Restricción en wiki.kontroles.com (nginx bloquea con 403): - /ecosistema/ — arquitectura y repositorios - /despliegue/ — guía de instalación - /dte/firmadordtes-tecnico — detalles técnicos del firmador - /dispositivos/control-dispositivos-tecnico — API de dispositivos - /portal/portal-monitor-tecnico — configuración del monitor

Qué se excluye del repo: config/users/, cache/**

7. despliegue_cliente

Propósito: Scripts, SQL y docker-compose para desplegar el ecosistema en servidores de clientes.
Contenido:

docker-compose.yml          ← orquestación completa del cliente
kontrolesrta/               ← frontend + nginx.conf del cliente
kontrolespos/               ← frontend + nginx.conf del cliente
kontrolesweb/               ← contenido y config del cliente
reports/                    ← reportes .jrxml por cliente
sql/                        ← migraciones SQL por cliente
scripts/                    ← build y deploy scripts
update_dte.sh               ← actualiza firmadorDtes en producción

Qué se excluye: - *.properties, .env — credenciales del cliente - *.p12, *.pfx — certificados digitales - *.dmp, *.dump — dumps de base de datos - *.jar, *.war, *.tar.gz — binarios

Infraestructura del servidor

Host: 192.168.1.99
OS: Linux (Docker Engine)
Red Docker principal: postgresql_default
Red proxy: erp-docker_erp_proxy_net

Contenedores en producción

Configuración de dominios (NPM)

Criterio de versionado en GitHub

Se incluye en git: - Código fuente (.java, .php, .js, .css, .html) - Recursos necesarios para compilar (.png, .jpg, .svg usados en UI) - Configuraciones de despliegue (Dockerfile, docker-compose.yml, .conf, .ini) - Manuales técnicos y de usuario (.md)

Se excluye de git: - Compilados (target/, *.class, *.jar, *.war, dist/) - Archivos generados en runtime (PDFs de DTE, JSONs autorizados, logs) - Credenciales (*.properties, .env, config/users/, *.p12) - Dependencias (vendor/, node_modules/) - Documentación externa descargada (crtsMH/)