Reglas del Proyecto: GIS-GEOSERVER (SNC + SIGEM)

Regla 0. Eres un senior fullstack developer con experiencia reconocida en Base de Datos PostgreSQL, amplia experiencia en proyectos corporativos con geoserver con uso de plataformas basadas en Java, javascript, HTML, XML, git, jenkins, maven, springboot, swagger, proxy de apache y nginx. El ecosistema principal es Java 21 con Spring Boot y deberá usarse de forma preferencial todas las veces que se pueda. El frontend usa el framework corporativo AdminLTE/Bootstrap.

Este proyecto GIS-GEOSERVER debe utilizar un patrón arquitectónico llamado Monolito Spring Boot con Recursos Embebidos (Server-Side Monolith).

El Backend (El Cerebro): Está escrito en Java 21 con Spring Boot (ubicado en la carpeta src/main/java/). Se encarga de la lógica pesada: seguridad, conexión a la base de datos PostgreSQL/PostGIS, consultas FDW, y expone los servicios REST (ej. /api/gis/entidad/505).

El Frontend (La Cara): Utiliza tecnologías de navegador clásicas: HTML, Vanilla JavaScript, jQuery y AdminLTE/Bootstrap. Pero en lugar de vivir en un servidor web aparte (como un Nginx puro o un Node.js), todos estos archivos viven dentro de la carpeta del propio proyecto Java: en src/main/resources/static/ y src/main/resources/templates/.

No hay dos servidores distintos. Cuando Spring Boot arranca su servidor interno (Tomcat), hace el trabajo doble: Si el navegador le pide datos, el código Java responde con JSON (API REST). Si el navegador le pide /gis-geoserver/mapas, el mismo servidor Java va a su propia carpeta interna (static o templates), lee el archivo HTML, y se lo envía al navegador del usuario. Cuando se ejecute el comando de Maven (mvnw clean package) se empaquetará tanto el código Java como los archivos HTML dentro de un único archivo .jar. Todo se levanta en un solo contenedor Docker y el proxy de Apache enruta todo bajo el mismo prefijo (/gis-geoserver/).

Regla 1. El ambiente de desarrollo y compilación se encuentra en el 192.168.1.123. El JENKINS a usar está en este servidor. Los comandos del jenkins se ejecutan en el servidor 192.168.1.123. El MAVEN a usar está en este servidor. Los comandos maven se ejecutan en el servidor 192.168.1.123. El DOCKER a usar está en el servidor 192.168.1.123. Los comandos docker se ejecutan en el servidor192.168.1.123. Todas las compilaciones se ejecutarán en el servidor 192.168.1.123. La base de datos georreferenciada física es SIGEM del Postgis está en este servidor y el superuser es el usuario registrado en el motor de base de datos como: Usuario: sigem_user Contraseña: sigem_pass

Regla 2. Las bases de datos alfanuméricas de los municipios a usar vinculadas a la base de datos georreferenciada Postgis serán definidas dinámicamente usando la tabla ENTIDADES la Base de Datos SIGEMWEB en el servidor 192.168.1.254

Regla 3. El proxypass principal de redireccionamiento reside en el servidor 192.168.1.10 El proxypass maestro de redireccionamiento reside en el servidor 192.168.1.20 Estos proxypass no deben ser modificados por ningún motivo. El proxy de Nginx de la Regla 3 tiene GeoServer mapeado a la ruta /geoserver/. Las peticiones se deberán mantener en el mismo dominio para evitar bloqueos CORS y para que sean enrutadas correctamente al contenedor de GeoServer.

Regla 4. Para el LOGIN, para el campo desplegable de las ENTIDADES (Municipios) los datos deben ser obtenidos de la tabla ENTIDADES del SIGEMWEB del servidor 192.168.1.254. Para el LOGIN, el usuario debe utilizar su usuario y contraseña del SIGEM del municipio. Para tus pruebas, por ahora tienes disponible las credenciales para acceder a esa BD. En caso de error detectado al intentar iniciar sesión, la aplicación debe dar un mensaje de error simple y claro del motivo, y permitir al usuario que vuelva a intentar.

Regla 5. Los parámetros para la visualización y despliegue de mapas en el geoserver deberá usarse el registro correspondiente al municipio que se obtiene en la tabla ENTIDADES. Los parámetros disponibles son: sigem_site, sigem_dbname, latlong, lng, lat, zoom, mapa_base, boundno, boundse, maxzoom, minzoom.

Para obtener los datos de los municipios se debe utilizar la propia API de la aplicación.

Regla 6. Para la construcción en la compilación, se usa JAVA21 del 192.168.1.123, en sincronía con la Regla 1.

Regla 7. Credenciales 192.168.1.123: cbareiro/x25yvaga2023, root/x25yvaga2023.

Regla 8. Credenciales 192.168.1.10: cbareiro/x25yvaga2020, root/x25yvaga2021.

Regla 9. Credenciales 192.168.1.20: cbareiro/x25yvaga2020, root/x25yvaga2020.

Regla 10. Credenciales 192.168.1.129: cbareiro/x25yvaga2025.

Regla 11. Jenkins (.123): admin / x25yvaga2024.

Regla 12. Jenkins SSH Credential ID: sigem-server-123 (root).

Regla 13. Tomcat Manager: manager / x25yvaga2023. GeoServer Web UI: admin / geoserver.

Regla 14. Endpoints Geoserver (.123:8080): /geoserver/wms, /geoserver/wfs, /geoserver/rest.

User: admin Password: x25yvaga2023

Regla 15. La aplicación se desplegará en el servidor 192.168.1.123 La carpeta de trabajo es: /yvyape/proyectos/sigem-gis

Regla 16. Conexión FDW y Sincronización de Vistas. Debe verificarse la existencia del FDW del municipio en cada LOGIN. Si no existe, crearlo. Refrescar obligatoriamente las vistas vw_lotes_morosidad_X.

Regla 17. GIT El repositorio de Git se encuentra en git.yvaga.com.py en el servidor 192.168.1.100 Credenciales de Git (.100): cbareiro@yvaga.com.py / carlos57. Repo: git@git.yvaga.com.py:geo/gis-geoserver.git. Si la carpeta a usar ya tiene archivos, el comando puede fallar, y debe limpiarse antes de clonar.

Regla 18. SSH Local: Usar Bitvise con usuario cbareiro.

Regla 19. Build: Terminar (Uso obligatorio) con ./mvnw clean package -DskipTests.

Regla 20. Prefijo FrontEnd: /gis-geoserver/.

Regla 21. ContextPath Backend: /gis-geoserver.

Regla 22: Integridad de Comandos Remotos: Desde el ambiente de desarrollo (Windows 11) se utilizará SSH de Bitvise para los accesos a otros servidores, usando la Regla 9. Debe usarse -cmdQuoted para ejecutar comandos complejos.

Queda prohibido el uso de comandos printf, echo o concatenaciones multilínea complejas para crear archivos. Usar sftpc para subir archivos íntegros. Para los comandos SQL complejos debido a la interpretación del shell de Windows y para asegurar la integridad total (Regla 22), se deben subir los archivos de estructura y población por SFTPC ejecutándolos desde el respectivo servidor. El paso intermedio para no generar errores es preparar los archivos de comandos en el servidor local y luego copiar el archivo de comandos al interior del contenedor antes de su ejecución, usando sftpc para subir archivos íntegros.

Por ejemplo: …\GIS-GEOSERVER > sexec cbareiro@192.168.1.123 -pw=x25yvaga2023 -cmd="cd /yvyape/proyectos/sigem-gis" …\GIS-GEOSERVER > sexec cbareiro@192.168.1.123 -pw=x25yvaga2023 -cmd="./mvnw clean package -DskipTests" …\GIS-GEOSERVER > sftpc cbareiro@192.168.1.123 -pw=x25yvaga2023 -cmd="put -o docker-compose.yml.remote.tmp /yvyape/proyectos/sigem-gis/docker-compose.yml" …\GIS-GEOSERVER > sexec cbareiro@192.168.1.123 -pw=x25yvaga2023 -cmdQuoted -cmd="curl -s -u admin:geoserver -X PUT -H 'Content-Type: application/xml' -d @/yvyape/proyectos/sigem-gis/geoserver_config.xml http://proyecto-geoserver-1:8080/geoserver/rest/workspaces/sigem/datastores/sigem/featuretypes/vw_lotes_morosidad_505.xml"

Regla 23. Columnas de Unión (Joins). Standard SNC. Para toda vista de unión con el FDW, se debe utilizar la columna snc_cuenta (limpia) contra REPLACE(liq.inm_ctacatastral, '-', ''). La definición del SQL de JOIN entre los datos SNC (datos georreferenciados) y la base de datos del municipio (datos alfanuméricos) genera la vista public.vw_lotes_morosidad_XXX a usar para desplegar mapa georreferenciado coloreado y es la siguiente:

DROP VIEW IF EXISTS public.vw_lotes_morosidad_XXX CASCADE;
CREATE OR REPLACE VIEW public.vw_lotes_morosidad_XXX AS 
SELECT 
    lot.*, 
    liq.inm_ficha, 
    liq.inm_ctacatastral, 
    liq.trb_tributo, 
    liq.trb_total_deuda, 
    liq.trb_total_pago, 
    liq.ultimo_pago 
FROM public.eXXX_lotes_activos lot
LEFT JOIN fdw_XXX.v_liq_entidad_totalxobjeto liq ON lot.snc_cuenta = REPLACE(liq.inm_ctacatastral, '-', '') ;

Regla 24. Resiliencia del LOGIN y Servicios. 
Toda orquestación de servicios secundarios (GeoServer REST API, FDW, MVT) invocada durante el proceso de LOGIN debe ser no-bloqueante. 
Uso obligatorio de bloques try-catch y configuración de timeout máximo de 2 segundos por conexión para garantizar la fluidez del sistema.

Regla 25. Protocolo de Logros y Protocolo de Resguardo y Recuperación (Backup)
El sistema debe garantizar la preservación de la integridad del proyecto mediante un tríptico de acciones atómicas ejecutadas obligatoriamente bajo pedido del usuario al alcanzar un hito.
1. Identificación del Hito:
Registro en VERSION.txt con formato "Version SIG - AAAA.MM.DD.HH.MM.SS ID DOCKER: [ID] [Observación Técnica]".
Sincronización de Código (Git): Ejecución de git add ., git commit y git push origin main hacia el servidor .100.
Snapshot de Infraestructura (.123):
Generación de volcado PostGIS: docker exec proyecto-postgres-1 pg_dump -U sigem_user sigem > sigem_postgres_dump.sql.
Compresión de datos de GeoServer: tar -czvf geoserver-data_dir.tar.gz geoserver-data.
Almacenamiento en carpeta cronológica dentro de /publico/.

Solo bajo autorización del usuario.

Regla 26. El motor de importación debe aplicar una limpieza universal al campo snc_cuenta para asegurar el match tributario.
La identificación de la zona se realiza mediante la variable tipo_cuenta:
1. Zona Urbana (tipo_cuenta = 1): snc_cuenta = Substring(ccatastral, 4) eliminando ceros a la izquierda y caracteres especiales.
Algoritmo Java para Zona Urbana:
substring(3) (4ª posición).
replaceAll("[^a-zA-Z0-9]", "") (Eliminar guiones, puntos, etc.).
replaceFirst("^0+", "") (Eliminar ceros a la izquierda resultantes).
Algoritmo SQL para Zona Urbana:
SUBSTRING(ccatastral FROM 4) (Substring desde la 4ª posición).
REGEXP_REPLACE(..., '[^a-zA-Z0-9]', '', 'g') (Limpieza de caracteres especiales).
LTRIM(..., '0') (Eliminación de ceros a la izquierda).

2. Zona Rural (tipo_cuenta = 0): snc_cuenta = padron::text (sin modificaciones).
Esta regla es mandatoria para toda municipalidad.
Se debe aplicar ST_MakeValid(geom) en la inserción para prevenir errores de renderizado en GeoServer.
Para la relación entre código SNC y código de municipio se debe utilizar la tabla ENTIDADES que se registra en public.snc_catalog_mapping

Regla 27. Optimización y Cache GeoWebCache (GWC):
Para asegurar la fluidez nacional (>2M de registros), cada capa de municipio debe contar con índices espaciales GIST sincronizados. 
El sistema debe intentar disparar el truncado de cache en GeoWebCache (GWC) cada vez que se detecte un cambio masivo en la tabla de morosidad remota del municipio.

Regla 28. Importación de datos del SNC. Se utilizará el API: https://www.catastro.gov.py/geoserver/ows. 
Para garantizar la compatibilidad universal en el visor web, TODOS los datos deben almacenarse en SRID 4326 (Coordenadas Geográficas) en las tablas eXXX_lotes_activos. 
Es MANDATORIO solicitar la transformación de coordenadas directamente al SNC incluyendo el parámetro srsName=EPSG:4326 en la URL de la petición WFS. 
La inserción en la base de datos se realizará mediante el uso directo de ST_GeomFromGeoJSON(?).
Implementar un TRUNCATE automático al inicio del proceso de importación. Si al importar los números son UTM, se deben transformar a 4326 antes de guardarlos.
Las columnas de las tablas eXXX_lotes_activos deberá tener todas las columnas del SNC.

Regla 29. 
Para la construcción en la compilación, se usa JAVA21 del 192.168.1.123, en sincronía con la Regla 1. 
El uso de rutas relativas en Docker ya ha estado causando problemas desde antes. Debes usar rutas absolutas

Regla 30. Arquitectura de Visualización en Dos Niveles.
El visor GIS utiliza una estrategia de superposición para optimizar el rendimiento y la claridad visual. Utiliza dos tipos de capas para mostrar los lotes: Una Capa Base (Lotes Grises) y múltiples Capas Temáticas (Lotes Coloreados).
1. Capa Base (Esqueleto): Utiliza la tabla física soberana `eXXX_lotes_activos`. Se publica en GeoServer con un estilo neutro (gris/transparente). Representa la totalidad del territorio y siempre es local y persistente.
2. Capa Temática (Inteligencia): Utiliza la vista lógica `vw_lotes_morosidad_XXX`. Es la capa dinámica que aplica el JOIN con el FDW municipal.
El Efecto Visual: La capa temática se superpone a la base. Aquellos lotes con coincidencia tributaria se "pintan" con el estilo de morosidad (semáforo), mientras que los lotes sin vínculo o sin deuda permanecen en gris (dejando ver la capa base), garantizando que la ciudad nunca se vea "incompleta".
El contenedor de GeoServer (sigem-gis-geoserver-1) y el de PostgreSQL (proyecto-postgres-1) tienen sus propias redes internas de Docker y no tienen acceso directo a otras redes Docker por seguridad y estabilidad. Por lo tanto, debe configurarse y ejecutarse dentro de la red privada interna de Docker.