feat(arch): enforce strict hierarchical ownership and enterprise audit standards (EN/ES)

Author: beyondnetPeru

architecture/adrs-es/0028-profile-centric-authorization-governance.md

@@ -1,36 +1,37 @@
-# ADR 0028: Modelo de Gobernanza y Autorización Centrado en el Perfil
+# ADR 0028: Modelo de Gobernanza y Autorización Centrado en el Perfil Enterprise
 
 ## Estatus
-Propuesto
+Refactorizado (Estándares Enterprise)
 
 ## Contexto
-El modelo de autorización anterior dependía de una asociación directa entre Usuarios, Roles y Permisos. Esto generaba inconsistencias conceptuales donde las anulaciones de permisos para un usuario específico requerían la creación de un nuevo rol o la gestión de asignaciones ad-hoc, complicando la gobernanza y la auditoría. Existe la necesidad de una entidad central que encapsule todo el contexto de una autorización (Usuario, Rol, Sistema, Sucursal e Inquilino) y sirva como contenedor para las "Autorizaciones Efectivas".
+Los modelos RBAC estándar fallan en entornos empresariales multi-inquilino y multi-sistema donde los permisos están contextualizados por la estructura organizacional (Sucursales) y los límites funcionales (Sistemas). La asignación directa usuario-rol crea brechas de gobernanza. Un modelo robusto debe aislar los roles dentro de los sistemas y consolidar la autoridad en un único pivote contextual: el **Perfil**.
 
 ## Decisión
-Haremos la transición a un **Modelo de Autorización Centrado en el Perfil**.
+Implementaremos un **Modelo de Autorización Centrado en el Perfil Enterprise** gobernado por las siguientes reglas estrictas:
 
-1.  **El Perfil como Eje de Gobernanza**:
-    *   Un **Perfil** es la unidad atómica de autorización.
-    *   Es una composición contextual de: `UserId` + `RoleId` + `SystemId` + `BranchId` + `TenantId`.
-    *   Un usuario puede tener múltiples perfiles (ej. "Gerente en Sucursal A" y "Auditor en Sucursal B").
+1.  **Propiedad Jerárquica Estricta**:
+    *   Un **Inquilino (Tenant)** posee sus **Usuarios**, **Sistemas (Suites)** y **Sucursales (Branches)**.
+    *   Un **Sistema** pertenece a un único Inquilino.
+    *   Un **Rol** pertenece a un único Sistema. Los roles globales están prohibidos.
+    *   Un **Permiso** pertenece al contexto funcional de un Sistema.
 
-2.  **Persistencia de Autorizaciones Efectivas**:
-    *   En lugar de resolver los permisos al vuelo desde los roles, el conjunto final de autorizaciones se persistirá a nivel de **Perfil** en una tabla `ProfilePermissions`.
-    *   Esto permite **Anulaciones (Overrides)** granulares (agregar o eliminar permisos) para un perfil específico sin afectar a otros usuarios que comparten el mismo Rol.
+2.  **El Perfil como Nexo Contextual**:
+    *   El **Perfil** es la intersección única de: `Tenant` + `Sistema` + `Sucursal` + `Usuario` + `Rol`.
+    *   Las autorizaciones se resuelven y persisten a nivel de **Perfil** como "Permisos Efectivos".
 
-3.  **Estándares de Trazabilidad y Auditoría**:
-    *   Todos los cambios de autorización deben rastrearse con un `TransactionId` o `AuditId`.
-    *   Cada entidad en el sistema seguirá el **Esquema de Auditoría Corporativa Estándar** (Created, Updated, Deleted, Version, Status).
+3.  **Estándares de Gobernanza y Auditoría**:
+    *   Cada entidad debe implementar el **Esquema de Auditoría Corporativa** (más de 10 columnas).
+    *   El soporte para **Soft Delete**, **Bloqueo Optimista** y **Pistas de Auditoría** es obligatorio para todas las operaciones de persistencia.
+    *   **Trazabilidad**: Las operaciones críticas de seguridad deben rastrear `CorrelationId`, `AuditId` y `TransactionId`.
 
-4.  **Desacoplamiento**:
-    *   **Rol**: Un esquema base de permisos.
-    *   **Perfil**: Una implementación contextual de un Rol para un Usuario y una Sucursal específicos.
+4.  **Motor de Autorización**:
+    *   El motor resuelve los permisos consultando la tabla de **Permisos Efectivos** para el `ProfileId` actual.
+    *   Admite **Anulaciones (Overrides)** (Conceder/Denegar) a nivel de Perfil para una granularidad máxima.
 
 ## Implementación Técnica
-*   La tabla `Users` ya no estará vinculada directamente a `Roles`.
-*   La tabla `Profiles` se convierte en el punto de unión central.
-*   El `Motor de Autorización` resolverá los permisos consultando el **ID del Perfil Activo** en el contexto de ejecución.
+*   **Cardinalidad**: `Tenant (1:N) Sistema (1:N) Rol (1:N) Perfil`.
+*   **Persistencia**: Los permisos efectivos se proyectan desde `Role -> ProfilePermission` al crear/sincronizar el perfil.
 
 ## Consecuencias
-*   **Positivo**: Granularidad perfecta para anulaciones, auditoría simplificada (un solo lugar para ver qué puede hacer un usuario en un contexto específico) y mejor alineación con estructuras organizacionales complejas.
-*   **Negativo**: Mayor número de filas en las tablas de permisos (`ProfilePermissions`) y necesidad de lógica para mantener los perfiles sincronizados con sus roles/plantillas de origen cuando sea necesario.
+*   **Positivo**: Aislamiento perfecto, resolución contextual simplificada, auditabilidad total y escalabilidad masiva para entornos multi-organización.
+*   **Negativo**: Mayor gestión de metadatos y requerimiento de una lógica de sincronización robusta entre Roles y Perfiles.

architecture/adrs/0028-profile-centric-authorization-governance.md

@@ -1,36 +1,37 @@
-# ADR 0028: Profile-Centric Authorization and Governance Model
+# ADR 0028: Enterprise Profile-Centric Authorization and Governance Model
 
 ## Status
-Proposed
+Refactored (Enterprise Standards)
 
 ## Context
-The previous authorization model relied on a direct association between Users, Roles, and Permissions. This led to conceptual inconsistencies where permission overrides for a specific user required creating a new role or managing ad-hoc assignments, complicating governance and audit. There is a need for a central entity that encapsulates the entire context of an authorization (User, Role, System, Branch, and Tenant) and serves as the container for "Effective Permissions".
+Standard RBAC models fail in multi-tenant, multi-suite enterprise environments where permissions are contextualized by organizational structure (Branches) and functional boundaries (Systems). Direct user-role assignment creates governance gaps. A robust model must isolate roles within systems and consolidate authority at a single contextual pivot: the **Profile**.
 
 ## Decision
-We will transition to a **Profile-Centric Authorization Model**.
+We will implement an **Enterprise Profile-Centric Authorization Model** governed by the following strict rules:
 
-1.  **Profile as the Governance Axis**:
-    *   A **Profile** is the atomic unit of authorization.
-    *   It is a contextual composition of: `UserId` + `RoleId` + `SystemId` + `BranchId` + `TenantId`.
-    *   A user can have multiple profiles (e.g., "Manager in Branch A" and "Auditor in Branch B").
+1.  **Strict Hierarchical Ownership**:
+    *   A **Tenant** owns its **Users**, **Systems (Suites)**, and **Branches**.
+    *   A **System** belongs to a single Tenant.
+    *   A **Role** belongs to a single System. Global roles are prohibited.
+    *   A **Permission** belongs to the functional context of a System.
 
-2.  **Effective Permission Persistence**:
-    *   Instead of resolving permissions on-the-fly from roles, the final set of authorizations will be persisted at the **Profile** level in a `ProfilePermissions` table.
-    *   This allows for granular **Overrides** (adding or removing permissions) for a specific profile without affecting other users sharing the same Role.
+2.  **Profile as the Contextual Nexus**:
+    *   The **Profile** is the unique intersection of: `Tenant` + `System` + `Branch` + `User` + `Role`.
+    *   Authorizations are resolved and persisted at the **Profile** level as "Effective Permissions".
 
-3.  **Traceability and Audit Standards**:
-    *   All authorization changes must be tracked with a `TransactionId` or `AuditId`.
-    *   Every entity in the system will follow the **Standard Corporate Audit Schema** (Created, Updated, Deleted, Version, Status).
+3.  **Governance & Audit Standards**:
+    *   Every entity must implement the **Corporate Audit Schema** (10+ columns).
+    *   Support for **Soft Delete**, **Optimistic Locking**, and **Audit Trails** is mandatory for all persistence operations.
+    *   **Traceability**: Critical security operations must track `CorrelationId`, `AuditId`, and `TransactionId`.
 
-4.  **Decoupling**:
-    *   **Role**: A blueprint of permissions.
-    *   **Profile**: A contextual implementation of a Role for a specific User and Branch.
+4.  **Authorization Engine**:
+    *   The engine resolves permissions by querying the **Effective Permissions** table for the current `ProfileId`.
+    *   Supports **Overrides** (Grant/Deny) at the Profile level for maximum granularity.
 
 ## Technical Implementation
-*   The `Users` table will no longer be directly linked to `Roles`.
-*   The `Profiles` table becomes the central junction point.
-*   The `Authorization Engine` will resolve permissions by querying the **Active Profile ID** in the execution context.
+*   **Cardinality**: `Tenant (1:N) System (1:N) Role (1:N) Profile`.
+*   **Persistence**: Effective permissions are projected from `Role -> ProfilePermission` upon profile creation/sync.
 
 ## Consequences
-*   **Positive**: Perfect granularity for overrides, simplified audit (one place to see what a user can do in a specific context), and better alignment with complex organizational structures.
-*   **Negative**: Higher number of rows in the permission tables (`ProfilePermissions`) and the need for logic to keep profiles in sync with their source roles/templates when required.
+*   **Positive**: Perfect isolation, simplified contextual resolution, full auditability, and massive scalability for multi-org environments.
+*   **Negative**: Increased metadata management and the requirement for a robust synchronization logic between Roles and Profiles.

architecture/blueprints-es/architecture-spec.md

@@ -402,18 +402,23 @@ Para ver el diseño detallado, tipos de datos específicos de SQL Server y polí
 
 ## 🏗️ 14. Flujo de Plantillas de Autorización y Herencia
 
-El UMS implementa un sistema desacoplado de gestión de autorizaciones donde los permisos se agrupan en **Suites** y se estandarizan mediante **Plantillas de Permisos**.
-
-### 14.1 Ciclo de Vida y Gobernanza
-*   **Definición**: Las plantillas se definen a nivel de Sistema (Global) o de Inquilino (Local).
-*   **Herencia**: Los roles se crean seleccionando una versión de Plantilla. El sistema admite la **Inicialización Estática** (copia al crear) y la **Sincronización Vinculada** (actualizaciones dinámicas).
-*   **Versionado**: Las plantillas utilizan el versionado semántico (v1.0.0). Los roles pueden actualizarse a versiones más nuevas de las plantillas mediante un flujo de migración controlado.
-
-### 14.2 Modelo de Desacoplamiento
-1.  **Sistema/Suite**: El límite funcional (ej. ERP, CRM).
-2.  **Plantilla de Permisos**: El esquema reutilizable.
-3.  **Rol/Perfil**: La implementación específica del inquilino.
-4.  **Autorización Efectiva**: El conjunto final de permisos resultante de la herencia de la plantilla más las anulaciones específicas del inquilino.
+El UMS implementa un sistema de gestión de autorizaciones desacoplado y jerárquico donde la autoridad se resuelve a nivel de **Perfil** dentro de una estructura multi-inquilino estrictamente aislada.
+
+### 14.1 Propiedad Jerárquica
+*   **Núcleo del Tenant**: El Tenant es el ancla raíz; posee los **Sistemas (Suites)** y las **Sucursales (Branches)**.
+*   **Alcance del Sistema**: Un **Sistema** posee sus **Roles** y **Permisos** específicos. No existen roles globales; cada rol está contenido dentro de un límite de Sistema.
+*   **Nexo del Perfil**: Un **Perfil** es la tupla contextual única: `(Tenant + Sistema + Sucursal + Usuario + Rol)`.
+
+### 14.2 Ciclo de Vida y Gobernanza
+*   **Herencia**: Los roles se crean a partir de Plantillas específicas del Sistema. Los perfiles se crean a partir de Roles.
+*   **Persistencia Efectiva**: Las autorizaciones finales se persisten a nivel de **Perfil** para permitir **Anulaciones (Overrides)** granulares (Conceder/Denegar) sin afectar al Rol base.
+*   **Versionado**: Todas las plantillas y perfiles efectivos admiten el versionado semántico y flujos de migración controlados.
+
+### 14.3 Modelo de Desacoplamiento
+1.  **Sistema/Suite**: El límite funcional (ej. ERP, CRM) propiedad de un Inquilino.
+2.  **Rol**: El esquema base de permisos dentro de un Sistema.
+3.  **Perfil**: La implementación contextual para un Usuario y Sucursal específicos.
+4.  **Autorización Efectiva**: El conjunto final de permisos persistido y auditado para un Perfil.