====== Ámbitos: quién ve qué ======

//La misma aplicación, la misma versión y la misma base de datos, pero cada
instalación —y si hace falta cada usuario— con sus formularios, su menú y sus
informes. Eso son los ámbitos.//

Lo que se configura por ámbito son hoy tres cosas, y las tres funcionan igual:

^ Qué se configura ^ Tabla ^ Quién elige la fila ^ Página ^
| El layout de una ficha de edición | ''PWA_FORMS'' | ''PWA_GET_FORM'' | [[pwa:doc:Documentación diseño de formularios en SmartPWA|Diseño de formularios]] |
| El menú de la aplicación | ''PWA_MENUS'' | ''PWA_GET_MENU'' | [[pwa:doc:Documentación diseño de menús en SmartPWA|Diseño del menú]] |
| El diseño de informe de una consulta | ''PWA_INFORMES'' | ''PWA_GET_INFORME'' | |

===== La clave: qué distingue una definición de otra =====

Las tres tablas llevan los mismos tres campos en su clave primaria, detrás de
lo que identifica el objeto (''COD_FORM'', ''COD_MENU'' o ''COD_PROC''):

^ Campo ^ Qué lleva ^
| ''TIPO_AMBITO'' | ''US'' un usuario, ''CI'' una clave de instalación o de grupo, ''G'' la definición general |
| ''COD_AMBITO'' | el código del usuario o la clave, según el tipo |
| ''CLAVE_INSTALACION'' | la instalación del usuario; solo se rellena en las de tipo ''US'' |

Los campos que no aplican **no se dejan en blanco: llevan el comodín ''*''**.
Forman parte de la clave primaria, y una clave con un hueco vacío no se puede
guardar. La aplicación los rellena sola cuando se crea la definición desde la
pantalla de listado.

<note>Solo hay tres tipos de ámbito para cinco niveles de precedencia, porque
dos pares comparten fila: una definición ''US'' vale para el usuario y para
quien herede de él, y una ''CI'' vale para la clave de instalación y para la
del grupo. Lo que cambia es contra qué valor casa ''COD_AMBITO'', no cómo se
guarda la fila.</note>

===== Las cinco precedencias =====

Cuando la aplicación necesita un layout, un menú o un informe, el procedimiento
''PWA_GET_*'' busca en este orden y **se queda con el primero que exista**:

^ # ^ Tipo ^ ''COD_AMBITO'' casa con ^ Para qué se usa ^
| 1 | ''US'' | el usuario conectado | el caso raro: una pantalla a medida de una persona |
| 2 | ''US'' | ''USUARIO.USUARIO_MENUS'' del conectado | un usuario hereda la configuración de otro, así no se repite |
| 3 | ''CI'' | ''EMPRESA.CLAVE_INSTALACION'' (tres caracteres) | lo normal: lo propio de un cliente |
| 4 | ''CI'' | ''EMPRESA.CLAVE_INSTALACION_GRUPO'' (cuatro caracteres) | lo común a un grupo de instalaciones |
| 5 | ''G'' | — | la definición general, la que vale para todos |

Las claves de instalación tienen **tres** caracteres y las de grupo **cuatro**,
así que nunca se confunden aunque compartan campo. El censo de instalaciones,
con sus claves, está en ''Z_LICENCIAS'', y la clave de la empresa en la que se
trabaja sale de ''EMPRESA''.

==== Por qué las de usuario llevan además la instalación ====

El mismo código de usuario existe en varias empresas —hay un ''JUANMA'' en cada
una— y los scripts de mantenimiento se aplican a todas. Sin la clave de
instalación, la definición del usuario de un cliente le caería encima al
usuario homónimo de otro. Por eso, en las filas ''US'', ''CLAVE_INSTALACION''
es obligatoria y la aplicación no deja crearlas sin ella.

===== La regla que hay que tener presente =====

<note important>Cada definición describe el objeto **entero**, no un parche
sobre el general.</note>

Una instalación con su propio layout de albarán tiene //todo// el layout del
albarán; una con su propio menú tiene //todo// el menú. La consecuencia:

  * **lo que se añade al general no llega a quien tiene lo suyo**. Una pestaña nueva en el formulario general de cliente no la verá la instalación que se hizo el suyo hace seis meses;
  * y por eso conviene tener pocos ámbitos propios, y crearlos **copiando el general** para partir de lo mismo.

La pantalla de menús trae para esto la opción **Comparar con el general**, que
dice qué opciones tiene el general y a este ámbito le faltan. Es lo primero que
hay que mirar cuando alguien dice «a mí no me sale eso que habéis puesto».

===== Cómo se crea una definición para un ámbito =====

Desde la aplicación, en el listado correspondiente —**Formularios**, **Menús**
o **Diseños de informe**— con el botón de nuevo registro. Se piden solo el
código del objeto y el ámbito; los comodines los pone la aplicación:

  - **COD_FORM / COD_MENU / COD_PROC**: qué pantalla, qué menú o qué consulta.
  - **TIPO_AMBITO**: ''US'', ''CI'' o ''G''.
  - **COD_AMBITO**: el usuario o la clave. En la general se deja vacío: se guarda el comodín.
  - **CLAVE_INSTALACION**: solo si el tipo es ''US''.

La aplicación comprueba lo que no puede salir bien y lo dice con estas mismas
palabras:

  * //«El tipo de ámbito debe ser US, CI o G.»//
  * //«Los ámbitos distintos del general necesitan el usuario o la clave de instalación.»//
  * //«Las definiciones de usuario necesitan la clave de instalación: el mismo código de usuario existe en varias empresas.»//

Recién creada, la definición está **vacía**: hay que pegarle el texto del
general (o el de otra instalación parecida) y quitarle lo que no aplique. En
los menús ese paso es una sola opción: **Copiar a otro ámbito**, desde la
definición que sirve de origen.

==== Saber cuál se está aplicando ====

La barra de título de las pantallas de edición lo dice: //«Formulario
albaran-venta-edit · Usuario JUANMA (026)»//, //«· Clave de instalación 026»// o
//«· General»//. Es la manera rápida de comprobar que se está tocando la
definición que se cree.

===== Llevar un ámbito a otra base de datos =====

Los ámbitos viven en la base de datos de cada cliente, así que un cambio hecho
aquí no viaja solo. Las pantallas de formularios y de menús traen:

  * **Copiar script de actualización**: deja en el portapapeles el ''UPDATE OR INSERT'' de esta definición.
  * **Descargar script (.sql)**: lo mismo en un archivo.

Ese script es idempotente —se puede ejecutar las veces que haga falta— y es lo
que se incorpora a la base del cliente por la vía de siempre. Las definiciones
**generales** están además versionadas en el repositorio
(''db/pwa_forms_layouts.sql'', ''db/pwa_menus_datos.sql''), que es de donde
salen para todos los clientes; las de instalación o de usuario, al ser de uno
solo, no se versionan ahí.

===== Consejos =====

  * **Empezar siempre por el general.** Si algo tiene que verlo todo el mundo, va al general; un ámbito propio es la excepción, no el punto de partida.
  * **Preferir ''CI'' a ''US''.** Lo que necesita un usuario suele necesitarlo su puesto, no su persona; y un ámbito de usuario es uno que nadie recuerda que existe cuando algo no sale.
  * **Usar el grupo** cuando varias instalaciones del mismo cliente comparten manera de trabajar: una fila en vez de cinco.
  * **No dejar definiciones vacías.** Una fila creada y sin texto es una definición que gana al general y no enseña nada; si se crea por error, se borra.
  * **Al añadir algo al general, repasar quién tiene lo suyo**, con la comparación de menús o mirando las filas de esa pantalla en ''PWA_FORMS''.

===== Cómo se mantiene esta página =====

^ Qué ^ Dónde ^
| Tipos de ámbito, comodín y descripciones | ''projects/smart-core/src/lib/utilidades/pwa-forms.ts'' |
| Lectura del layout por ámbito | ''projects/smart-core/src/lib/servicios/form-layout.service.ts'' |
| Lectura del menú por ámbito | ''projects/smart-core/src/lib/servicios/menu.service.ts'' |
| Alta de definiciones con sus comprobaciones | ''projects/smart-core/paginas/src/lib/tabla-list-wrap/'' |
| Copiar a otro ámbito y comparar con el general | ''projects/smart-core/paginas/src/lib/pwa-menu-edit/'' |
| Procedimientos ''PWA_GET_FORM'', ''PWA_GET_MENU'', ''PWA_GET_INFORME'' | ''db/pwa_forms_procs.sql'', ''db/pwa_menus_procs.sql'', ''db/pwa_informes_procs.sql'' |