Documentación: Finalización de las 30 Reglas de Arquitectura - Versión Estable (58d2a666) | Commits | geo / gis-geoserver

Browse Code »

Commit 58d2a666dc493709e0d88d708ff511e484842b87

Authored by Administrator 2026-04-20 07:25:22 -0300

1 parent c75dbfb2

Documentación: Finalización de las 30 Reglas de Arquitectura - Versión Estable

Inline Side-by-side

Showing 2 changed files with 235 additions and 182 deletions

GIS-GEOSERVER-REGLAS.md

View file @58d2a66

1	-# Reglas del Proyecto: GIS-GEOSERVER (SNC + SIGEM)
2	-
3	-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.
4	-El ecosistema principal es Java 21 con Spring Boot y deberá usarse de forma preferencial todas las veces que se pueda.
5	-El frontend usa el framework corporativo AdminLTE/Bootstrap.
6	-
7	-Este proyecto GIS-GEOSERVER debe utilizar un patrón arquitectónico llamado Monolito Spring Boot con Recursos Embebidos (Server-Side Monolith).
8	-
9	-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).
10	-
11	-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/.
12	-
13	-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/).
14	-
15	-Regla 1. El ambiente de desarrollo y compilación se encuentra en el 192.168.1.123.
16	-El JENKINS a usar está en este servidor. Los comandos del jenkins se ejecutan en el servidor 192.168.1.123.
17	-El MAVEN a usar está en este servidor. Los comandos maven se ejecutan en el servidor 192.168.1.123.
18	-El DOCKER a usar está en el servidor 192.168.1.123. Los comandos docker se ejecutan en el servidor192.168.1.123.
19	-Todas las compilaciones se ejecutarán en el servidor 192.168.1.123.
20	-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:
21	-Usuario: sigem_user
22	-Contraseña: sigem_pass
23	-
24	-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
25	-
26	-Regla 3. El proxypass principal de redireccionamiento reside en el servidor 192.168.1.10
27	-El proxypass maestro de redireccionamiento reside en el servidor 192.168.1.20
28	-Estos proxypass no deben ser modificados por ningún motivo.
29	-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.
30	-
31	-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.
32	-Para el LOGIN, el usuario debe utilizar su usuario y contraseña del SIGEM del municipio.
33	-Para tus pruebas, por ahora tienes disponible las credenciales para acceder a esa BD.
34	-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.
35	-
36	-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.
37	-Los parámetros disponibles son:
38	-sigem_site,
39	-sigem_dbname,
40	-latlong,
41	-lng,
42	-lat,
43	-zoom,
44	-mapa_base,
45	-boundno,
46	-boundse,
47	-maxzoom,
48	-minzoom.
49	-
50	-Para obtener los datos de los municipios se debe utilizar la propia API de la aplicación.
51	-
52	-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.
53	-
54	-Regla 7. Credenciales 192.168.1.123: cbareiro/x25yvaga2023, root/x25yvaga2023.
55	-
56	-Regla 8. Credenciales 192.168.1.10: cbareiro/x25yvaga2020, root/x25yvaga2021.
57	-
58	-Regla 9. Credenciales 192.168.1.20: cbareiro/x25yvaga2020, root/x25yvaga2020.
59	-
60	-Regla 10. Credenciales 192.168.1.129: cbareiro/x25yvaga2025.
61	-
62	-Regla 11. Jenkins (.123): admin / x25yvaga2024.
63	-
64	-Regla 12. Jenkins SSH Credential ID: sigem-server-123 (root).
65	-
66	-Regla 13.
67	-Tomcat Manager: manager / x25yvaga2023.
68	-GeoServer Web UI: admin / geoserver.
69	-
70	-Regla 14.
71	-Endpoints Geoserver (.123:8080): /geoserver/wms, /geoserver/wfs, /geoserver/rest.
72	-
73	-User: admin
74	-Password: x25yvaga2023
75	-
76	-Regla 15.
77	-La aplicación se desplegará en el servidor 192.168.1.123
78	-La carpeta de trabajo es: /yvyape/proyectos/sigem-gis
79	-
80	-Regla 16. Conexión FDW y Sincronización de Vistas.
81	-Debe verificarse la existencia del FDW del municipio en cada LOGIN.
82	-Si no existe, crearlo.
83	-Refrescar obligatoriamente las vistas `vw_lotes_morosidad_X`.
84	-
85	-Regla 17. GIT
86	-El repositorio de Git se encuentra en git.yvaga.com.py en el servidor 192.168.1.100
87	-Credenciales de Git (.100): cbareiro@yvaga.com.py / carlos57. Repo: git@git.yvaga.com.py:geo/gis-geoserver.git.
88	-Si la carpeta a usar ya tiene archivos, el comando puede fallar, y debe limpiarse antes de clonar.
89	-
90	-Regla 18. SSH Local: Usar Bitvise con usuario cbareiro.
91	-
92	-Regla 19. Build:
93	-Terminar (Uso obligatorio) con ./mvnw clean package -DskipTests.
94	-
95	-Regla 20. Prefijo FrontEnd: /gis-geoserver/.
96	-
97	-Regla 21. ContextPath Backend: /gis-geoserver.
98	-
99	-Regla 22: Integridad de Comandos Remotos:
100	-Desde el ambiente de desarrollo (Windows 11) se utilizará SSH de Bitvise para los accesos a otros servidores, usando la Regla 9.
101	-Debe usarse -cmdQuoted para ejecutar comandos complejos.
102	-
103	-Queda prohibido el uso de comandos printf, echo o concatenaciones multilínea complejas para crear archivos. Usar sftpc para subir archivos íntegros.
104	-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.
105	-
106	-Por ejemplo:
107	-…\GIS-GEOSERVER > sexec cbareiro@192.168.1.123 -pw=x25yvaga2023 -cmd="cd /yvyape/proyectos/sigem-gis"
108	-…\GIS-GEOSERVER > sexec cbareiro@192.168.1.123 -pw=x25yvaga2023 -cmd="./mvnw clean package -DskipTests"
109	-…\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"
110	-…\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"
111	-
112	-Regla 23. Columnas de Unión (Joins). Standard SNC.
113	-Para toda vista de unión con el FDW, se debe utilizar la columna `snc_cuenta` (limpia) contra `REPLACE(liq.inm_ctacatastral, '-', '')`.
114	-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:
115	-```sql
116	-DROP VIEW IF EXISTS public.vw_lotes_morosidad_XXX CASCADE;
117	-CREATE OR REPLACE VIEW public.vw_lotes_morosidad_XXX AS
118	-SELECT
119	- lot.*,
120	- liq.inm_ficha,
121	- liq.inm_ctacatastral,
122	- liq.trb_tributo,
123	- liq.trb_total_deuda,
124	- liq.trb_total_pago,
125	- liq.ultimo_pago
126	-FROM public.eXXX_lotes_activos lot
127	-LEFT JOIN fdw_XXX.v_liq_entidad_totalxobjeto liq ON lot.snc_cuenta = REPLACE(liq.inm_ctacatastral, '-', '') ;
128	-
129	-Regla 24. Resiliencia del LOGIN y Servicios.
130	-Toda orquestación de servicios secundarios (GeoServer REST API, FDW, MVT) invocada durante el proceso de LOGIN debe ser no-bloqueante.
131	-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.
132	-
133	-Regla 25. Protocolo de Logros y Protocolo de Resguardo y Recuperación (Backup)
134	-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.
135	-1. Identificación del Hito:
136	-Registro en VERSION.txt con formato "Version SIG - AAAA.MM.DD.HH.MM.SS ID DOCKER: [ID] [Observación Técnica]".
137	-Sincronización de Código (Git): Ejecución de git add ., git commit y git push origin main hacia el servidor .100.
138	-Snapshot de Infraestructura (.123):
139	-Generación de volcado PostGIS: docker exec proyecto-postgres-1 pg_dump -U sigem_user sigem > sigem_postgres_dump.sql.
140	-Compresión de datos de GeoServer: tar -czvf geoserver-data_dir.tar.gz geoserver-data.
141	-Almacenamiento en carpeta cronológica dentro de /publico/.
142	-
143	-Solo bajo autorización del usuario.
144	-
145	-Regla 26. El motor de importación debe aplicar una limpieza universal al campo snc_cuenta para asegurar el match tributario.
146	-La identificación de la zona se realiza mediante la variable tipo_cuenta:
147	-1. Zona Urbana (tipo_cuenta = 1): snc_cuenta = Substring(ccatastral, 4) eliminando ceros a la izquierda y caracteres especiales.
148	-Algoritmo Java para Zona Urbana:
149	-substring(3) (4ª posición).
150	-replaceAll("[^a-zA-Z0-9]", "") (Eliminar guiones, puntos, etc.).
151	-replaceFirst("^0+", "") (Eliminar ceros a la izquierda resultantes).
152	-Algoritmo SQL para Zona Urbana:
153	-SUBSTRING(ccatastral FROM 4) (Substring desde la 4ª posición).
154	-REGEXP_REPLACE(..., '[^a-zA-Z0-9]', '', 'g') (Limpieza de caracteres especiales).
155	-LTRIM(..., '0') (Eliminación de ceros a la izquierda).
156	-
157	-2. Zona Rural (tipo_cuenta = 0): snc_cuenta = padron::text (sin modificaciones).
158	-Esta regla es mandatoria para toda municipalidad.
159	-Se debe aplicar ST_MakeValid(geom) en la inserción para prevenir errores de renderizado en GeoServer.
160	-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
161	-
162	-Regla 27. Optimización y Cache GeoWebCache (GWC):
163	-Para asegurar la fluidez nacional (>2M de registros), cada capa de municipio debe contar con índices espaciales GIST sincronizados.
164	-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.
165	-
166	-Regla 28. Importación de datos del SNC. Se utilizará el API: https://www.catastro.gov.py/geoserver/ows.
167	-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.
168	-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.
169	-La inserción en la base de datos se realizará mediante el uso directo de ST_GeomFromGeoJSON(?).
170	-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.
171	-Las columnas de las tablas eXXX_lotes_activos deberá tener todas las columnas del SNC.
172	-
173	-Regla 29.
174	-Para la construcción en la compilación, se usa JAVA21 del 192.168.1.123, en sincronía con la Regla 1.
175	-El uso de rutas relativas en Docker ya ha estado causando problemas desde antes. Debes usar rutas absolutas
176	-
177	-Regla 30. Arquitectura de Visualización en Dos Niveles.
178	-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).
179	-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.
180	-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.
181	-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".
182	-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.
183	\ No newline at end of file	1	\ No newline at end of file
		2	+# Reglas del Proyecto: GIS-GEOSERVER (SNC + SIGEM)
		3	+
		4	+Regla 0.
		5	+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 y MapLibre GL JS v4.0.0+ como motor de visualización vectorial.
		6	+
		7	+Este proyecto GIS-GEOSERVER debe utilizar un patrón arquitectónico llamado Monolito Spring Boot con Recursos Embebidos (Server-Side Monolith).
		8	+
		9	+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).
		10	+
		11	+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/.
		12	+
		13	+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 sistema de proxies enruta todo bajo el mismo dominio (usando los prefijos /gis-geoserver/ para la app y /geoserver/ para el motor de mapas) garantizando la ausencia de bloqueos de seguridad CORS.
		14	+
		15	+Regla 1.
		16	+Regla 1. El ambiente de desarrollo y compilación centralizado se encuentra en el servidor 192.168.1.123, específicamente en la ruta raíz del proyecto: /yvyape/proyectos/sigem-gis/.
		17	+
		18	+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. Se deberá utilizar preferentemente el Maven Wrapper (./mvnw) ubicado en la raíz del proyecto para asegurar la compatibilidad de versiones y evitar problemas de permisos globales. El DOCKER a usar está en el servidor 192.168.1.123. Los comandos docker se ejecutan en el servidor 192.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 (PostGIS) y reside en este mismo servidor. El superuser registrado en el motor de base de datos es: Usuario: sigem_user Contraseña: sigem_pass
		19	+
		20	+Regla 2.
		21	+La arquitectura es Multi-Municipio y se basa en la federación de Base de Datos municipales. Las bases de datos alfanuméricas de los municipios estarán ubicadas físicamente según las políticas de Yvaga en servidores registrados en la tabla ENTIDADES de la Base de Datos SIGEMWEB del servidor 192.168.1.254. Se vinculan dinámicamente con la base de datos georreferenciada PostGIS (servidor 192.168.1.123) mediante el uso de Foreign Data Wrappers (FDW) con su respectivo esquema fdw_[ID_ENTIDAD] generados automáticamente por este sistema.
		22	+
		23	+La tabla maestra de orquestación es ENTIDADES de la base de datos SIGEMWEB (.254). Para cada municipio, se deberá mantener un esquema FDW en PostGIS siguiendo la nomenclatura fdw_[ID_ENTIDAD] (ejemplo: fdw_505). El vínculo fundamental entre la base de datos georreferenciada (cartografía GIS) y la base de datos alfanumérica municipal para generar mapas temáticos se realiza exclusivamente a través del campo unificado snc_cuenta.
		24	+
		25	+Regla 3.
		26	+El proxypass principal de redireccionamiento reside en el servidor 192.168.1.10
		27	+El proxypass maestro de redireccionamiento reside en el servidor 192.168.1.20
		28	+Estos proxypass no deben ser modificados por ningún motivo.
		29	+Esta infraestructura unifica todo el ecosistema bajo un mismo dominio y punto de entrada:
		30	+Aplicación (Backend/Frontend): Enrutada bajo el prefijo /gis-geoserver/.
		31	+Motor de Mapas (GeoServer): Enrutado bajo el prefijo /geoserver/.
		32	+Se prohíbe terminantemente el uso de IPs directas o puertos específicos (ej: :8080, :8083) en el código JavaScript del frontend. Todas las peticiones (XHR, Fetch, Tile Requests) deben realizarse mediante rutas relativas o dinámicas (ej: ${window.location.origin}/geoserver/...).
		33	+El tráfico debe fluir siempre a través del proxy, eliminando de raíz los bloqueos de seguridad CORS y permitiendo el acceso transparente desde cualquier red.
		34	+
		35	+Regla 4.
		36	+El proceso de Autenticación (LOGIN) actúa como el selector de contexto Multi-Municipio del sistema.
		37	+Para el campo desplegable de las ENTIDADES (Municipios), los datos deben obtenerse exclusivamente de la tabla ENTIDADES del servidor 192.168.1.254 correspondientes a municipios activos. Un municipio se considera activo si su campo ESTADO = 'ACTIVO', y estado_mapa = '1' (Activo) o estado_mapa = '2' (En Implementación).
		38	+El usuario se autenticará utilizando sus credenciales oficiales del SIGEM municipal.
		39	+Tras un inicio de sesión exitoso, el sistema debe:
		40	+Emitir un Token JWT seguro para autorizar peticiones.
		41	+Persistir en el navegador (ej: localStorage) el Token, el nombre del usuario y, obligatoriamente, el ID de la Entidad.
		42	+Utilizar este ID de Entidad como único filtro en todas las consultas posteriores al Backend y al GeoServer, garantizando el aislamiento total de datos entre municipios.
		43	+En caso de error, el sistema debe proporcionar un mensaje simple, claro y descriptivo del motivo (ej: "Usuario no reconocido", "Servidor municipal fuera de línea") y permitir el reintento inmediato.
		44	+
		45	+Regla 5.
		46	+La configuración del Visor GIS es dinámica y se basa exclusivamente en los metadatos de la Entidad. El Frontend debe ser agnóstico y configurarse en tiempo de ejecución consumiendo los parámetros desde la API de la aplicación (ejemplo: /api/entidad/config/{id}).
		47	+Los parámetros críticos para el motor MapLibre son:
		48	+Encuadre Inicial: lat, lng y zoom para posicionar la cámara al cargar.
		49	+Restricción Territorial: boundno (Noroeste) y boundse (Sureste) para definir los límites máximos de navegación (maxBounds), impidiendo que el usuario se pierda fuera del municipio.
		50	+Profundidad: minzoom y maxzoom para controlar el nivel de detalle permitido.
		51	+Capa Soberana: El campo mapa_base definirá dinámicamente el nombre de la capa de lotes a cargar desde GeoServer (ejemplo: e505_lotes_activos).
		52	+Otros parámetros de orquestación disponibles: sigem_site, sigem_dbname, latlong.
		53	+
		54	+Regla 6.
		55	+El estándar de construcción y ejecución del proyecto es Java 21 (LTS). En total sincronía con la Regla 1, todas las compilaciones se realizan en el servidor 192.168.1.123.
		56	+
		57	+El proceso de construcción debe generar un único archivo binario .jar autoejecutable (Fat JAR). Este archivo debe contener tanto la lógica de negocio del Backend como la totalidad de los recursos estáticos del Frontend (HTML/JS/CSS), asegurando que el despliegue sea atómico y consistente en el contenedor Docker.
		58	+
		59	+Regla 7.
		60	+Credenciales de acceso SSH al servidor de desarrollo y producción (192.168.1.123):
		61	+Usuario: cbareiro / Contraseña: x25yvaga2023
		62	+Usuario: root / Contraseña: x25yvaga2023
		63	+
		64	+Regla 8.
		65	+Credenciales de acceso SSH al servidor Proxypass Principal 192.168.1.10:
		66	+Usuario: cbareiro / Contraseña: x25yvaga2020
		67	+Usuario: root / Contraseña: x25yvaga2021
		68	+
		69	+Regla 9.
		70	+Credenciales de acceso SSH al servidor Proxypass Maestro (192.168.1.20):
		71	+
		72	+Usuario: cbareiro / Contraseña: x25yvaga2020
		73	+Usuario: root / Contraseña: x25yvaga2020
		74	+
		75	+Regla 10.
		76	+Credenciales de acceso SSH al servidor KAFKA (192.168.1.129):
		77	+Usuario: cbareiro / Contraseña: x25yvaga2025
		78	+
		79	+Regla 11.
		80	+Credenciales de acceso a la Interfaz Web (Web UI) de Jenkins (servidor 192.168.1.123):
		81	+Usuario: admin / Contraseña: x25yvaga2024
		82	+
		83	+Regla 12.
		84	+Identificador de Credenciales (Credential ID) almacenado en Jenkins para la ejecución de despliegues automáticos (Pipelines) mediante SSH al servidor 192.168.1.123:
		85	+ID: sigem-server-123 (Vinculado al usuario root del servidor).
		86	+
		87	+Regla 13.
		88	+Credenciales de acceso a las interfaces administrativas de los servicios desplegados:
		89	+Tomcat Manager (Gestión del Backend): Usuario: manager / Contraseña: x25yvaga2023
		90	+GeoServer Web UI (Gestión de Capas y Estilos): Usuario: admin / Contraseña: geoserver
		91	+
		92	+Regla 14.
		93	+Puntos de enlace (Endpoints) y API de GeoServer para la comunicación interna (Backend-to-GeoServer):
		94	+Base URL Interna: http://192.168.1.123:8083/geoserver/ (Puerto real de servicio en el servidor .123).
		95	+Servicios disponibles: /wms, /wfs y la interfaz /rest para gestión automática de capas.
		96	+Credenciales de API REST:
		97	+Usuario: admin / Contraseña: x25yvaga2023 (Credencial técnica para procesos Java).
		98	+IMPORTANTE: Esta regla es de uso exclusivo para la lógica del servidor Java (Backend). El Frontend jamás debe utilizar estas rutas directas, debiendo ceñirse siempre a la Regla 3 (rutas relativas vía Proxy).
		99	+
		100	+Regla 15. Estructura de Despliegue y Persistencia.
		101	+El centro de operaciones del proyecto reside en el servidor 192.168.1.123, dentro de la carpeta de trabajo: /yvyape/proyectos/sigem-gis/.
		102	+Este directorio debe mantener la siguiente estructura crítica:
		103	+Orquestación: Contiene el archivo docker-compose.yml que gestiona los contenedores.
		104	+Persistencia de GeoServer: El subdirectorio geoserver-data/. Este volumen es vital y persistente; contiene todas las definiciones de capas, estilos y formatos (PBF/XYZ). Nunca debe ser eliminado ni sobreescrito por procesos de limpieza de Git.
		105	+Registro de Versiones: El archivo VERSION.txt para el seguimiento de hitos de éxito.
		106	+
		107	+Regla 16. Integridad de Datos y Sincronización Alfanumérica (FDW). Para garantizar que los mapas temáticos (Morosidad, Deuda, Pagos) reflejen la realidad municipal en tiempo real, el Backend debe realizar las siguientes acciones en cada proceso de LOGIN:
		108	+
		109	+Verificación de Enlace: Validar la existencia del esquema fdw_[ID_ENTIDAD] y sus tablas vinculadas (provenientes de la Regla 2). Si el enlace no existe o la conexión FDW ha fallado, el sistema debe reconfigurarlo automáticamente.
		110	+Sincronización de Capas: Ejecutar el refresco de las vistas de datos (ejemplo: vw_lotes_morosidad_[ID_ENTIDAD]) que sirven de fuente a GeoServer. Esto asegura que los atributos alfanuméricos estén perfectamente alineados con la geometría de los lotes.
		111	+Garantía de Vínculo: El proceso debe asegurar que el campo snc_cuenta mantenga la integridad referencial necesaria para el cruce de información espacial-alfanumérica.
		112	+
		113	+Regla 17. Sincronización y Control de Versiones (GIT).
		114	+El repositorio central del código reside en el servidor 192.168.1.100 (git.yvaga.com.py).
		115	+URL de Repositorio: git@git.yvaga.com.py:geo/gis-geoserver.git
		116	+Rama Principal: main (estándar obligatorio del proyecto).
		117	+Credenciales: cbareiro@yvaga.com.py / carlos57.
		118	+Gestión de Archivos en el Servidor 192.168.1.123:
		119	+Sincronización: Todo cambio validado en el servidor de desarrollo debe ser enviado (git push origin main) de inmediato para consolidar el hito.
		120	+Limpieza Segura: En caso de conflictos de archivos, se permite el uso de git clean -fd.
		121	+RESTRICCIÓN CRÍTICA: Queda prohibido el uso de comandos de limpieza o reset que afecten al directorio geoserver-data/. Este directorio debe estar excluido del rastreo de Git para evitar la pérdida de configuraciones cartográficas activas durante las actualizaciones de código.
		122	+
		123	+Regla 18. Herramientas de Acceso Remoto Local.
		124	+Desde el ambiente de desarrollo (Windows 11) se utilizará obligatoriamente Bitvise SSH Client como puente ÚNICO hacia los servidores Linux de la plataforma YVAGA.
		125	+Sesiones Interactivas: Uso del perfil de Bitvise con el usuario cbareiro.
		126	+Ejecución de Scripts: Uso de la utilidad sexec para la ejecución de comandos remotos automatizados (Maven, Docker, Git).
		127	+Gestión de Archivos: Uso de sftpc para la transferencia de archivos binarios y código fuente, garantizando la integridad de los datos transmitidos.
		128	+
		129	+Regla 19. Protocolo de Empaquetado y Despliegue (Build).
		130	+Todo ciclo de modificación de código Java o de recursos estáticos (HTML/JS/CSS) debe finalizar con el siguiente protocolo atómico en el servidor .123:
		131	+Empaquetado Obligatorio: Ejecutar sh ./mvnw clean package -DskipTests en la raíz del proyecto. El uso del prefijo sh es obligatorio para garantizar la ejecución sobre el Maven Wrapper independientemente de los permisos del sistema de archivos.
		132	+Sincronización de RAM: Tras obtener un BUILD SUCCESS, se debe reiniciar obligatoriamente el contenedor del backend para que la nueva versión del archivo .jar sea cargada en memoria: docker restart sigem-gis-backend
		133	+
		134	+Regla 20. Identidad de Ruta del FrontEnd.
		135	+Toda la interfaz de usuario y recursos del cliente residen bajo el prefijo obligatorio /gis-geoserver/.
		136	+Este prefijo es la "firma" que los proxies de la Regla 3 utilizan para identificar y dirigir el tráfico hacia el contenedor de Java. Por lo tanto:
		137	+Referencias en HTML: Todos los enlaces (<a>), scripts (<script src="...">) y hojas de estilo (<link href="...">) deben ser relativos al contexto o incluir explícitamente este prefijo (ejemplo: /gis-geoserver/mapas).
		138	+Redirecciones: Cualquier navegación interna activada por JavaScript debe respetar esta base de URL para no "romper" el enrutamiento del proxy.
		139	+
		140	+Regla 21. Configuración del Servidor de Aplicaciones (ContextPath).
		141	+El servidor Spring Boot debe estar configurado internamente con el ContextPath: /gis-geoserver.
		142	+Esta configuración (definida en el archivo application.properties mediante la propiedad server.servlet.context-path=/gis-geoserver) es la que permite que el motor de Java reconozca y procese las peticiones que le entrega el proxy. Cualquier cambio en este valor debe estar perfectamente sincronizado con las Reglas 3 y 20 para evitar errores 404 generalizados.
		143	+
		144	+Regla 22. Integridad de Comandos Remotos y Prevención de Escapes.
		145	+Para evitar la corrupción de archivos y errores de interpretación del shell de Windows hacia Linux, se establecen los siguientes estándares obligatorios:
		146	+Transferencia de Archivos: Queda prohibido el uso de comandos echo, printf o redirecciones multilínea para crear archivos en el servidor. Toda subida de código, SQL o configuración debe realizarse mediante sftpc (comando put), garantizando la integridad binaria del archivo.
		147	+Comandos Complejos: Debe utilizarse siempre el parámetro -cmdQuoted en sexec para asegurar que los argumentos (especialmente en comandos curl con JSON o XML) lleguen íntegros al servidor Linux.
		148	+Advertencia de PowerShell: Debido a que el ambiente local es Windows, caracteres como el signo de dólar ($), paréntesis () o comillas simples dentro de comandos Bash remotos deben ser escapados cuidadosamente para evitar que Windows intente procesarlos antes de enviarlos.
		149	+Ejemplos de Ejecución Correcta:
		150	+Construcción: sexec ... -cmd="sh ./mvnw clean package -DskipTests"
		151	+Subida de Estilos: sexec ... -cmdQuoted -cmd="curl -u admin:geoserver -X PUT -H 'Content-Type: application/vnd.ogc.sld+xml' -d @estilo.sld http://192.168.1.123:8083/geoserver/rest/styles/estilo_morosidad"
		152	+SQL Seguro: Subir el archivo .sql por SFTP y ejecutarlo remotamente con psql -f archivo.sql, nunca pegando el código SQL directamente en la consola.
		153	+
		154	+Regla 23. Estandarización de Cruce de Datos (FDW).
		155	+Para garantizar que la cartografía GIS pueda mostrar datos tributarios (deuda, pagos, morosidad), se establece un estándar obligatorio de unión entre la base geográfica y la alfanumérica:
		156	+Llave Primaria de Unión: El campo snc_cuenta (limpio) de la cartografía debe cruzarse con el campo de cuenta catastral municipal aplicando una limpieza de guiones: REPLACE(liq.inm_ctacatastral, '-', '').
		157	+Fuente para GeoServer: La vista resultante public.vw_lotes_morosidad_XXX (donde XXX es el ID de la Entidad) es la única fuente de datos que debe consumir el GeoServer para aplicar los estilos de visualización (SLD).
		158	+Plantilla SQL Estándar de Referencia:
		159	+DROP VIEW IF EXISTS public.vw_lotes_morosidad_XXX CASCADE;
		160	+CREATE OR REPLACE VIEW public.vw_lotes_morosidad_XXX AS
		161	+SELECT
		162	+ lot.*,
		163	+ liq.inm_ficha,
		164	+ liq.inm_ctacatastral,
		165	+ liq.trb_tributo,
		166	+ liq.trb_total_deuda,
		167	+ liq.trb_total_pago,
		168	+ liq.ultimo_pago
		169	+FROM public.eXXX_lotes_activos lot
		170	+LEFT JOIN fdw_XXX.v_liq_entidad_totalxobjeto liq ON lot.snc_cuenta = REPLACE(liq.inm_ctacatastral, '-', '') ;
		171	+
		172	+Regla 24. Resiliencia y Disponibilidad del Servicio (UX).
		173	+Para garantizar una experiencia de usuario fluida, el proceso de LOGIN debe ser resiliente a fallos o lentitud de servicios secundarios.
		174	+Orquestación No-Bloqueante: Toda tarea de sincronización (refresco de FDW, validación de capas en GeoServer o servicios MVT) debe ser tratada como secundaria. Si uno de estos servicios no responde, el usuario debe poder acceder al Dashboard de todos modos.
		175	+Límites de Tiempo (Timeouts): Es obligatorio configurar un timeout máximo de 2 segundos por cada conexión externa o secundaria durante el login.
		176	+Degradación Graciosa: El uso de bloques try-catch es mandatorio en el Backend. Si una sincronización falla, el sistema debe registrar el error internamente y permitir el acceso al Dashboard, informando al usuario de forma no intrusiva (ejemplo: "Cargando capas cartográficas...") en lugar de bloquear el inicio de sesión con un error genérico.
		177	+Alta Disponibilidad: Se busca evitar que un fallo en el servidor 192.168.1.254 o el del municipio, impida que los funcionarios entren a usar otras partes del sistema GIS.
		178	+Continuidad: Se busca que el sistema sea mucho más robusto ante micro-cortes de red o latencias en los servidores de mapas.
		179	+
		180	+Regla 25. Protocolo de Consolidación de Logros (Backup & Recovery).
		181	+Al alcanzar un Hito de Despliegue Exitoso (ejemplo: "Visualización de capas activa"), se ejecutará obligatoriamente el Tríptico de Seguridad bajo autorización expresa del usuario:
		182	+
		183	+1. Registro de Versión: Actualizar el archivo /yvyape/proyectos/sigem-gis/VERSION.txt con el formato: Version SIG - [Fecha.Hora] ID DOCKER: [ID_REAL] [Observación Técnica].
		184	+2. Resguardo de Código (Git): Sincronizar el repositorio local con el servidor central (.100) mediante el ciclo: git add ., git commit -m "Hito: [Descripción]", git push origin main.
		185	+3. Snapshot de Infraestructura (DRP):
		186	+ - Crear una carpeta cronológica en el servidor .123 bajo la ruta: /publico/backup-gis-[YYYYMMDDHHMM]/.
		187	+ - Volcado de Base de Datos: Realizar el dump de PostGIS: docker exec proyecto-postgres-1 pg_dump -U sigem_user sigem > dump.sql. (Se debe verificar que el archivo resultante tenga peso binario).
		188	+ - Persistencia de Mapas: Comprimir la totalidad del directorio geoserver-data/ para preservar capas, estilos SLD y configuraciones de grilla: tar -czvf mapas.tar.gz geoserver-data.
		189	+Nota crítica: Los respaldos físicos en la carpeta /publico/ se consideran la única fuente de recuperación absoluta ante corrupciones críticas del repositorio de código o fallos del motor Docker.
		190	+
		191	+Regla 26. Estándar de Normalización y Limpieza (ETL de Cartografía).
		192	+Esta regla solamente es válida al ejecutar una importación de datos del SNC.
		193	+Para asegurar el cruce exitoso entre la cartografía nacional (SNC) y los datos locales, el motor de importación debe aplicar una limpieza universal obligatoria al campo snc_cuenta:
		194	+Zona Urbana (tipo_cuenta = 1): El identificador se genera extrayendo desde la 4ª posición, eliminando caracteres especiales y quitando ceros a la izquierda.
		195	+Algoritmo SQL: LTRIM(REGEXP_REPLACE(SUBSTRING(ccatastral FROM 4), '[^a-zA-Z0-9]', '', 'g'), '0').
		196	+Algoritmo Java: ccatastral.substring(3).replaceAll("[^a-zA-Z0-9]", "").replaceFirst("^0+", "").
		197	+Zona Rural (tipo_cuenta = 0): Se utiliza el campo "padron" convertido a texto sin modificaciones adicionales.
		198	+Calidad Geométrica: Es mandatorio aplicar ST_MakeValid(geom) durante la inserción o actualización de lotes en PostGIS. Esto previene geometrías inválidas que bloquean el renderizado en GeoServer.
		199	+Catálogo del SNC:
		200	+La vinculación entre códigos SNC y códigos municipales debe resolverse mediante la tabla de orquestación public.snc_catalog_mapping.
		201	+
		202	+Regla 27. Optimización de Alto Rendimiento GEOSERVER(MVT & GWC).
		203	+Para asegurar la fluidez de navegación en un mapa de escala nacional (>2 millones de registros), se establecen los siguientes estándares de optimización:
		204	+Indexación: Toda tabla de lotes (eXXX_lotes_activos) y toda vista temática de morosidad debe contar obligatoriamente con un índice espacial GIST sincronizado sobre la columna geom.
		205	+Aceleración por Teselas: El sistema debe utilizar GeoWebCache (GWC) configurado con el Gridset XYZ-900913 y el formato MVT (PBF). Esta es la única forma de garantizar tiempos de respuesta menores a 200ms en el visor MapLibre.
		206	+Invalidación de Cache: Tras una actualización masiva de datos (ejemplo: proceso de morosidad), el Backend debe disparar automáticamente un truncado de la cache mediante la API REST de GWC (endpoint: /geoserver/gwc/rest/masstruncate). Esto asegura que el usuario visualice los cambios cromáticos (colores de morosidad) de forma inmediata.
		207	+
		208	+Regla 28. Protocolo de Importación Cartográfica del SNC.
		209	+El motor de importación debe garantizar la sincronización exacta con el Servicio Nacional de Catastro (SNC) bajo las siguientes directrices técnicas:
		210	+Fuente Oficial: Uso exclusivo de la API WFS: https://www.catastro.gov.py/geoserver/ows.
		211	+Soberanía del SRID 4326: Para garantizar la compatibilidad universal y la fluidez en dispositivos móviles, TODOS los datos deben almacenarse obligatoriamente en SRID 4326 (WGS 84).
		212	+Transformación en Origen: Es MANDATORIO solicitar la transformación de coordenadas directamente al servidor del SNC incluyendo el parámetro srsName=EPSG:4326 en la URL de la petición WFS. Esto delega la precisión cartográfica al ente emisor y evita errores de redondeo locales.
		213	+Procedimiento de Inserción:
		214	+Se debe implementar un TRUNCATE automático de la tabla eXXX_lotes_activos antes de iniciar la carga para asegurar un estado limpio.
		215	+La persistencia se realizará mediante el uso de ST_GeomFromGeoJSON(?) o ST_GeomFromText.
		216	+La tabla destino debe replicar la totalidad de las columnas entregadas por el SNC para asegurar la trazabilidad completa de cada lote.
		217	+
		218	+Regla 29. Integridad de Rutas y Persistencia (Docker).
		219	+Para garantizar la estabilidad del sistema y evitar fallos de montaje de servicios durante despliegues automáticos, se establece lo siguiente:
		220	+Prohibición de Rutas Relativas: Queda terminantemente prohibido el uso de rutas relativas (./, ../) en la configuración de docker-compose.yml o en scripts de despliegue.
		221	+Uso de Rutas Absolutas: Todas las referencias a volúmenes de datos, archivos de configuración y mapeos de archivos deben declararse mediante su ruta absoluta completa en el servidor (ejemplo: /yvyape/proyectos/sigem-gis/geoserver-data/ en lugar de ./geoserver-data/).
		222	+Consistencia de Binarios: El archivo .jar generado por Java 21 (servidor 192.168.1.123) debe ser referenciado también por su ruta absoluta, asegurando que el contenedor siempre encuentre la versión correcta independientemente del directorio desde donde se inicie el servicio.
		223	+
		224	+Regla 30. Arquitectura de Visualización en Dos Niveles.
		225	+Se usarán Capas Superpuestas. Para maximizar el rendimiento y garantizar que el mapa nunca presente "huecos" visuales, se establece la siguiente estrategia de renderizado:
		226	+Nivel 1: Capa Base (Esqueleto Físico):
		227	+Fuente: Tabla física soberana eXXX_lotes_activos.
		228	+Estilo: Neutro (Gris suave con bordes sutiles).
		229	+Propósito: Representar el 100% del territorio municipal de forma persistente. Actúa como la "red de seguridad" visual.
		230	+Nivel 2: Capa Temática (Inteligencia Tributaria):
		231	+Fuente: Vista lógica dinámica vw_lotes_morosidad_XXX.
		232	+Estilo: Dinámico (Semáforo cromático: Verde/Amarillo/Rojo).
		233	+Propósito: Superponer la información de morosidad solo sobre los lotes que tienen coincidencia en el SIGEM.
		234	+El Efecto "Cero Huecos": Si un lote tiene datos de deuda, la capa temática lo "pinta" de color. Si no tiene datos o el vínculo falla, el lote permanece gris (mostrando la capa base), garantizando una ciudad siempre completa y profesional.
		235	+
		236	+Seguridad de Red (Docker): El tráfico entre GeoServer y PostgreSQL debe fluir exclusivamente por la red interna privada de Docker. Se prohíbe el uso de IPs públicas para la comunicación entre contenedores, debiendo utilizarse los nombres de servicio (ejemplo: proyecto-postgres-1) para garantizar la estabilidad y el aislamiento del ecosistema.
184	\ No newline at end of file	237	\ No newline at end of file

VERSION.txt

View file @58d2a66

No preview for this file type