docs: align all functional specifications with identity abstraction (ADR-0031)

Author: beyondnetPeru

src/ums-workspace/docs/en/01-requirements/conceptual-data-model.md

@@ -50,7 +50,7 @@ erDiagram
 - `organization_id` (UUID, FK): Owning tenant organization.
 - `email` (string, Unique): Corporate email address.
 - `password_hash` (string, **Nullable**): Populated **only** when the Internal Bcrypt Strategy adapter is active for the organization. `NULL` when authentication is delegated to an external IdP.
-- `employee_reference` (string): External unique ID linking to corporate HR/ERP records.
+- `identity_reference` (string): External unique ID linking to corporate HR/ERP records.
 - `status` (enum): `ACTIVE`, `SUSPENDED`, or `TERMINATED`.
 - `created_at` (timestamp): Record creation timestamp.
 

src/ums-workspace/docs/en/01-requirements/functional-stories/fs-01-user-authentication.md

@@ -39,8 +39,8 @@ sequenceDiagram
 2.  The web client redirects the user to the configured external Identity Provider (Keycloak/Azure AD) authorization endpoint using **OAuth 2.0 Auth Code Flow with PKCE**.
 3.  The user authenticates successfully using their corporate credentials on the IdP portal.
 4.  The IdP redirects the browser back to the SCM portal with an authorized single-use Authorization Code.
-5.  The SCM backend exchanges the Authorization Code with the IdP for a cryptographically signed Access Token (JWT) containing employee claims.
-6.  The backend verifies the token's RS256 signature and validates that the `employee_reference` matches an active employee record in the local SCM database.
+5.  The SCM backend exchanges the Authorization Code with the IdP for a cryptographically signed Access Token (JWT) containing identity claims.
+6.  The backend verifies the token's RS256 signature and validates that the `identity_reference` matches an active identity record in the local SCM database.
 7.  The system initializes the user session, injects the tenant context, and returns a secure, HTTP-Only, SameSite=Strict session cookie.
 
 ---
@@ -51,8 +51,8 @@ sequenceDiagram
 *   If the connection to Keycloak/Azure AD fails, the SCM Gateway intercepts the timeout error.
 *   The system displays a secure fallback credentials page allowing authorized IT Administrators to login using local ULPMS emergency credentials, while standard operators are prompted to retry.
 
-### Alternative Flow B: Unlinked Employee Reference
-*   If the authenticated IdP token succeeds but the `employee_reference` is not found or is suspended in the SCM database:
+### Alternative Flow B: Unlinked Organization Member Reference
+*   If the authenticated IdP token succeeds but the `identity_reference` is not found or is suspended in the SCM database:
     *   The backend aborts the login process.
     *   Saves a security warning inside the immutable access audit logs.
     *   Returns a `403 Forbidden` response explaining that the corporate account is not active on the SCM portal.

src/ums-workspace/docs/en/02-architecture/bounded-context-map.md

@@ -90,7 +90,7 @@ graph TD
 - IdP configuration data (owned by Config Context)
 
 **Integration Contracts (Published Language):**
-- `UserRegisteredEvent { userId, organizationId, branchId, employeeReference }`
+- `UserRegisteredEvent { userId, organizationId, branchId, identityReference }`
 - `UserSuspendedEvent { userId, tenantId }`
 - `OrganizationCreatedEvent { tenantId, idpStrategy }`
 

src/ums-workspace/docs/en/03-adrs/0031-abstract-identity-domain-subject.md

@@ -11,13 +11,13 @@
 Currently, the User Management System (UMS) and the extended SCM domain implicitly use the "Employee" concept as the fundamental unit that holds permissions, interacts with systems, and authenticates against the Identity Provider (IdP).
 
 This approach shows critical technical and functional coupling:
-*   **Database and APIs:** The use of the `employee_reference` property as mandatory backend validation after OAuth (JWT) token exchange.
-*   **Domain Events:** The `UserRegisteredEvent` directly carries the `employeeReference` field.
+*   **Database and APIs:** The use of the `identity_reference` property as mandatory backend validation after OAuth (JWT) token exchange.
+*   **Domain Events:** The `UserRegisteredEvent` directly carries the `identityReference` field.
 *   **Business Rules:** Validations that require the reference to match internal Human Resources systems exclusively.
 
 ### ⚠️ Identified Problem
 With the introduction of B2B business flows (such as **Use Case 12 / FS-10: External Access Approval Workflow**), the business now requires provisioning access to identities that **are not employees** of the host company (e.g., third-party drivers, forklift operators hired by suppliers, external auditors, B2B clients).
-Forcing these individuals to have an "Employee Reference" forces "polluting" the HR database with external personnel, blocks agile provisioning, and creates semantic inconsistency in the domain.
+Forcing these individuals to have an "Organization Member Reference" forces "polluting" the HR database with external personnel, blocks agile provisioning, and creates semantic inconsistency in the domain.
 
 ---
 
@@ -29,7 +29,7 @@ The technical and functional implementation guidelines are:
 
 1.  **Semantic Abstraction:** The domain will no longer validate "Employees." Instead, it will validate a `Subject` that has a role and a contextual relationship with a `Tenant` through their `Organization`.
 2.  **Replacement of References:**
-    *   The `employee_reference` field in the database and API contracts will be renamed/migrated to `external_identity_reference` or simply `identity_reference`.
+    *   The `identity_reference` field in the database and API contracts will be renamed/migrated to `external_identity_reference` or simply `identity_reference`.
     *   The `identity_reference_type` field (`HR_ID`, `VENDOR_CODE`, `GOVERNMENT_ID`, `PARTNER_REF`) will be added to give semantic context to the external reference.
 3.  **Provisioning Responsibility by Organization:** The external user's organization becomes the entity responsible for their personnel's lifecycle, mediated by formal request flows approved by a corporate Sponsor (complying with the federated delegation principle).
 
@@ -43,10 +43,10 @@ classDiagram
     class User {
         +UUID id
         +String email
-        +String employee_reference
+        +String identity_reference
     }
     class HR_System {
-        +validateEmployee(employee_reference)
+        +validateEmployee(identity_reference)
     }
     User --> HR_System : Tight Coupling
 ```
@@ -95,9 +95,9 @@ To ensure operational continuity and not break backward compatibility:
 
 1.  **Coexistence Phase (Dual Read/Write):**
     *   Enrich the users table with the `identity_reference` and `reference_type` fields (temporarily nullable).
-    *   The .NET 8 API will read from `employee_reference` if present, but will save to both fields for existing records.
+    *   The .NET 8 API will read from `identity_reference` if present, but will save to both fields for existing records.
 2.  **API Deprecation Phase:**
-    *   Mark the `employee_reference` claim in the JWT payload as `[Obsolete]` or in the process of deprecation, but keeping it in the token for compatibility with legacy microservices.
+    *   Mark the `identity_reference` claim in the JWT payload as `[Obsolete]` or in the process of deprecation, but keeping it in the token for compatibility with legacy microservices.
     *   Inject the new unified claim `sub_ref` (Subject Reference).
 3.  **Purging Phase:**
-    *   Once 100% of the services consume `sub_ref`, execute a database script to remove the obsolete column `employee_reference`.
+    *   Once 100% of the services consume `sub_ref`, execute a database script to remove the obsolete column `identity_reference`.

src/ums-workspace/docs/en/04-artifacts/enterprise-iam-ums-specification.md

@@ -27,11 +27,11 @@ In this reference scenario, a **SCM Transportation Analyst** initiates a session
 ### Use Case: Contextual Authentication & Multi-Tenant Graph Synthesis
 *   **Primary Actor**: SCM Transportation Analyst.
 *   **Target System**: SCM Route Planner.
-*   **Preconditions**: User is registered in UMS and holds a valid employee reference; SCM Route Planner and Callao Terminal are registered in the UMS.
+*   **Preconditions**: User is registered in UMS and holds a valid identity reference; SCM Route Planner and Callao Terminal are registered in the UMS.
 *   **Postconditions**: Session established with dual cryptographically rotated tokens and a contextual, branch-restricted JSON authorization graph.
 
 ### Variations and Exception Paths
-*   **Variation A: Federated Identity Provider (Azure AD/Okta)**: Gateway delegates credential verification to the external corporate IdP via SAML2/OIDC. SCM local database is bypassed for credential verification, and user is mapped using `employee_reference` claims.
+*   **Variation A: Federated Identity Provider (Azure AD/Okta)**: Gateway delegates credential verification to the external corporate IdP via SAML2/OIDC. SCM local database is bypassed for credential verification, and user is mapped using `identity_reference` claims.
 *   **Variation B: Multi-Factor Authentication (MFA)**: If the tenant enforces adaptive MFA based on IP range, the analyst is prompted for WebAuthn (Passkeys) verification before the UMS authorization graph call is triggered.
 *   **Exception 1: Missing Tenant Context**: If the request lacks `tenant_id` or `branch_id`, the API returns a `400 Bad Request` with error code `ERR_MISSING_CONTEXT`, aborting graph resolution.
 *   **Exception 2: Authorization Graph Not Found**: If the user authenticates successfully but holds no active profile assignments for the Callao branch, the API returns a `403 Forbidden` with error code `ERR_ZERO_PERMISSIONS`.
@@ -124,7 +124,7 @@ Authorization: Bearer m2m_token_gateway_abc123
   "principal": {
     "user_id": "usr_analyst_callao_098",
     "email": "analyst@logisticscorp.com",
-    "employee_reference": "EMP-PERU-998"
+    "identity_reference": "EMP-PERU-998"
   },
   "context": {
     "tenant_id": "tenant_logistics_corp",

src/ums-workspace/docs/en/04-artifacts/enterprise-multitenant-governance-report.md

@@ -11,7 +11,7 @@
 After an exhaustive analysis of the UMS ecosystem, we have identified a **rigid structural coupling** in the original design that negatively impacts the platform's SaaS evolution.
 
 ### Key Architectural Findings
-1.  **Identity Coupling (Employee vs. Subject):** The dependence on `employee_reference` as a mandatory field assumes an internal employment relationship. This blocks B2B scenarios where the user is an external supplier, a third-party driver, or an integration bot (M2M) lacking a record in the corporate HR database.
+1.  **Identity Coupling (Employee vs. Subject):** The dependence on `identity_reference` as a mandatory field assumes an internal employment relationship. This blocks B2B scenarios where the user is an external supplier, a third-party driver, or an integration bot (M2M) lacking a record in the corporate HR database.
 2.  **Orphaned Software Assets:** Systems (SCM, WMS, ERP) and their components (Menus, APIs) currently operate in a "flat" global catalog. There is no explicit definition of who is the logical owner of the resource and under what conditions a third party (Tenant) can consume it.
 3.  **Ambiguous Security Boundaries:** The permission model focuses on the "What" (action) but not on "Who owns the object." This violates **Zero Trust** principles where the Organization should be the physical and logical frontier for every bit of information.
 
@@ -60,7 +60,7 @@ Systems and applications explicitly belong to an organization.
 ## 🚀 5. Incremental Transition Strategy
 
 1.  **Phase 01 (Foundation):** Implement the Organizations table as a boundary and associate 100% of current users with the "Root Organization."
-2.  **Phase 02 (Decoupling):** Migrate from `employee_reference` to `identity_reference` (Agnostic Subject). Inject `X-Org-Context` in the API Gateway.
+2.  **Phase 02 (Decoupling):** Migrate from `identity_reference` to `identity_reference` (Agnostic Subject). Inject `X-Org-Context` in the API Gateway.
 3.  **Phase 03 (Enforcement):** Activate RLS policies in PostgreSQL for all domain tables.
 4.  **Phase 04 (Federation):** Enable the B2B Access Request module so external organizations can autonomously request access to internal systems.
 

src/ums-workspace/docs/en/04-artifacts/ums-configuration-platform-spec.md

@@ -52,7 +52,7 @@ The UMS must allow per-tenant (and optionally per-system) configuration of one o
     "config_secret_ref": "vault://ums/secrets/logisticscorp/azure_client_secret",
     "scopes": ["openid", "profile", "email"],
     "user_claim_mapping": {
-      "employee_reference": "employeeId",
+      "identity_reference": "identityId",
       "email": "upn"
     }
   },

src/ums-workspace/docs/es/01-requirements/conceptual-data-model.md

@@ -52,7 +52,7 @@ erDiagram
 - `organization_id` (UUID, FK): Owning tenant organization.
 - `email` (string, Unique): Corporate email address.
 - `password_hash` (string, **Nullable**): Populated **only** when the Internal Bcrypt Strategy adapter is active for the organization. `NULL` when authentication is delegated to an external IdP.
-- `employee_reference` (string): External unique ID linking to corporate HR/ERP records.
+- `identity_reference` (string): External unique ID linking to corporate HR/ERP records.
 - `status` (enum): `ACTIVE`, `SUSPENDED`, or `TERMINATED`.
 - `created_at` (timestamp): Record creation timestamp.
 

src/ums-workspace/docs/es/01-requirements/functional-stories/fs-01-user-authentication.md

@@ -10,7 +10,7 @@ Este documento especifica el flujo de transacciones, los actores y las estrategi
 | :--- | :--- |
 | **Nombre** | Autenticación de Usuario vía IdP Externo |
 | **Actor Principal** | Usuario Corporativo SCM |
-| **Precondiciones** | El usuario está registrado en la base de datos de ULPMS y posee una referencia válida de empleado de RRHH. |
+| **Precondiciones** | El usuario está registrado en la base de datos de ULPMS y posee una referencia de identidad válida. |
 | **Postcondiciones** | La sesión se establece en la aplicación SCM y se devuelve una cookie segura HTTP-Only. |
 
 ---
@@ -30,7 +30,7 @@ sequenceDiagram
     User->>IdP: Ingresar Credenciales Corporativas
     IdP-->>Web: Redirigir con Auth Code
     Web->>API: Intercambiar Auth Code
-    Note over API: Verificar Token y Claim de Empleado
+    Note over API: Verificar Token y Claim de Identidad
     API-->>Web: Configurar Cookie de Sesión HTTP-Only
 ```
 
@@ -39,8 +39,8 @@ sequenceDiagram
 2.  El cliente web redirige al usuario al endpoint de autorización del Proveedor de Identidad externo configurado (Keycloak/Azure AD) utilizando el **Flujo de Código de Autorización OAuth 2.0 con PKCE**.
 3.  El usuario se autentica exitosamente utilizando sus credenciales corporativas en el portal del IdP.
 4.  El IdP redirige el navegador de vuelta al portal SCM con un Código de Autorización de un solo uso autorizado.
-5.  El backend SCM intercambia el Código de Autorización con el IdP por un Token de Acceso firmado criptográficamente (JWT) que contiene los claims del empleado.
-6.  El backend verifica la firma RS256 del token y valida que la `employee_reference` coincida con un registro de empleado activo en la base de datos local de SCM.
+5.  El backend SCM intercambia el Código de Autorización con el IdP por un Token de Acceso firmado criptográficamente (JWT) que contiene los claims de identidad.
+6.  El backend verifica la firma RS256 del token y valida que la `identity_reference` coincida con un registro de identidad activa en la base de datos local de SCM.
 7.  El sistema inicializa la sesión del usuario, inyecta el contexto del tenant y devuelve una cookie de sesión segura, HTTP-Only y SameSite=Strict.
 
 ---
@@ -51,8 +51,8 @@ sequenceDiagram
 *   Si falla la conexión a Keycloak/Azure AD, el Gateway SCM intercepta el error de tiempo de espera (timeout).
 *   El sistema muestra una página de credenciales de respaldo segura que permite a los Administradores de TI autorizados iniciar sesión utilizando credenciales locales de emergencia de ULPMS, mientras que a los operadores estándar se les solicita reintentar.
 
-### Flujo Alternativo B: Referencia de Empleado no Vinculada
-*   Si el token del IdP autenticado es exitoso pero no se encuentra la `employee_reference` o está suspendida en la base de datos SCM:
+### Flujo Alternativo B: Referencia de Miembro de Organización no Vinculada
+*   Si el token del IdP autenticado es exitoso pero no se encuentra la `identity_reference` o está suspendida en la base de datos SCM:
     *   El backend aborta el proceso de inicio de sesión.
     *   Guarda una advertencia de seguridad dentro de los registros de auditoría de acceso inmutables.
     *   Devuelve una respuesta `403 Forbidden` explicando que la cuenta corporativa no está activa en el portal SCM.

src/ums-workspace/docs/es/02-architecture/bounded-context-map.md

@@ -1,4 +1,4 @@
-> ?? **Nota de Arquitectura:** Este documento se encuentra actualmente en su versión original (Inglés) y está programado para traducción oficial en la hoja de ruta.
+> ?? **Nota de Arquitectura:** Este documento se encuentra actualmente en su versin original (Ingls) y est programado para traduccin oficial en la hoja de ruta.
 
 # 🗺️ Bounded Context Map — User Management System (UMS)
 
@@ -92,7 +92,7 @@ graph TD
 - IdP configuration data (owned by Config Context)
 
 **Integration Contracts (Published Language):**
-- `UserRegisteredEvent { userId, organizationId, branchId, employeeReference }`
+- `UserRegisteredEvent { userId, organizationId, branchId, identityReference }`
 - `UserSuspendedEvent { userId, tenantId }`
 - `OrganizationCreatedEvent { tenantId, idpStrategy }`