+ © BeyondNet S.A.C. · RUC 20100412447 · Operador Logístico Aduanero desde 1978 +
diff --git a/docs/architecture/ep-06-approvals-detailed-design.es.md b/docs/architecture/ep-06-approvals-detailed-design.es.md new file mode 100644 index 00000000..8d7bbb6d --- /dev/null +++ b/docs/architecture/ep-06-approvals-detailed-design.es.md @@ -0,0 +1,1074 @@ +# EP-06: Diseño Detallado — Seguridad, Acceso Externo y Delegación **Versión:** 1.0 **Fecha:** 2026-05-14 **Épica:** EP-06 (Post-MVP) + +**Historias:** US-017 a US-022 **Functional Stories:** FS-09, FS-10, FS-14 + +--- + +## PARTE 1: FS-09 — Adaptive MFA & Passwordless Authentication + +### 1.1 Definición **FS-09** implementa autenticación adaptativa donde + +* **MFA**: Multi-Factor Authentication (requisito condicional basado en riesgo) +* **Passwordless**: Métodos sin contraseña (FIDO2, magic links, biometría) + +El sistema calcula un **Risk Score**en tiempo real y decide automáticamente si MFA es requerido. + +### 1.2 Risk Scoring Model + +#### 1.2.1 Factores de Riesgo + +| Factor | Rango | Peso | Ejemplo | +| -------- | ------- | ------ | --------- | +| **Login Frequency Anomaly** | 0-30 | 0.20 | User nunca ha hecho login a esta hora | +| **Geographic Anomaly** | 0-30 | 0.25 | User está en país diferente al usual | +| **Device Reputation** | 0-20 | 0.15 | Device nuevo o no reconocido | +| **Network Anomaly** | 0-10 | 0.10 | IP sospechosa, VPN, proxy | +| **Failed Attempts** | 0-10 | 0.10 | N intentos fallidos recientes | +| **Tenant Risk Level** | 0-30 | 0.20 | Tenant categorizado como "high-risk" | + +**Risk Score = Σ(Factor × Weight)** Rango: 0 (bajo riesgo) a 100 (alto riesgo) + +#### 1.2.2 Thresholds de Decisión + +```csharp +public class MFADecisionEngine +{ + // Risk Score → MFA Requirement + public MFARequirement CalculateMFARequirement(decimal riskScore, User user, Tenant tenant) + { + return (riskScore, user.Category, tenant.RiskLevel) switch + { + // Bajo riesgo: Sin MFA requerido + (< 20, _, _) => MFARequirement.NotRequired, + + // Riesgo medio: MFA recomendado (opcional) + (20 to 40, UserCategory.INTERNAL, _) => MFARequirement.Recommended, + (20 to 40, _, _) => MFARequirement.Required, + + // Riesgo alto: MFA obligatorio + (40 to 70, _, _) => MFARequirement.Required, + + // Riesgo crítico: MFA + intervención de admin + (> 70, _, _) => MFARequirement.RequiredWithSecurityReview, + + _ => MFARequirement.Required + }; + } +} + +public enum MFARequirement +{ + NotRequired, // User puede skipear MFA + Recommended, // Mostrar prompt pero permitir skip + Required, // MFA obligatorio + RequiredWithSecurityReview // MFA + manual admin review +} +``` + +#### 1.2.3 Cálculo de Riesgos por Factor + +```csharp +public class RiskScoringEngine +{ + // Factor 1: Login Frequency Anomaly (0-30 puntos) + public int CalculateFrequencyAnomaly(User user, DateTime loginAttemptTime) + { + var userLoginHistory = _auditRepository.GetLoginsByUser(user.Id, lastDays: 30); + var usualLoginHours = userLoginHistory + .GroupBy(l => l.Timestamp.Hour) + .Select(g => (hour: g.Key, frequency: g.Count())) + .OrderByDescending(g => g.frequency) + .Take(5) // Top 5 horas + .Select(g => g.hour) + .ToList(); + + if (!usualLoginHours.Contains(loginAttemptTime.Hour)) + return 30; // Anomalía total + + return 0; // Patrón conocido + } + + // Factor 2: Geographic Anomaly (0-30 puntos) + public int CalculateGeographicAnomaly(User user, string ipAddress) + { + var userLocation = _geoIpService.GetLocation(ipAddress); + var usualCountries = _auditRepository.GetLoginsByUser(user.Id, lastDays: 90) + .Select(l => _geoIpService.GetLocation(l.IpAddress).Country) + .Distinct() + .ToList(); + + if (!usualCountries.Contains(userLocation.Country)) + { + // Check si geográficamente POSIBLE viajar en el tiempo + var lastLoginLocation = _auditRepository.GetLastLogin(user.Id); + var travelTime = CalculateTravelTime(lastLoginLocation, userLocation); + + if (travelTime.TotalMinutes < 120) // Imposible viajar en 2h + return 30; // Muy sospechoso + + return 20; // Viaje posible pero raro + } + + return 0; + } + + // Factor 3: Device Reputation (0-20 puntos) + public int CalculateDeviceReputation(User user, string deviceFingerprint) + { + var knownDevices = _deviceRepository.GetDevicesByUser(user.Id) + .Where(d => d.Status == DeviceStatus.TRUSTED) + .Select(d => d.Fingerprint) + .ToList(); + + if (!knownDevices.Contains(deviceFingerprint)) + return 20; // Device desconocido + + return 0; + } + + // Factor 4: Network Anomaly (0-10 puntos) + public int CalculateNetworkAnomaly(string ipAddress) + { + var threatIntel = _threatIntelService.CheckIP(ipAddress); + + return threatIntel switch + { + { IsMalicious: true } => 10, + { IsVPN: true } => 5, // VPN = algo sospechoso + { IsProxy: true } => 5, + { IsTor: true } => 10, + _ => 0 + }; + } + + // Factor 5: Failed Attempts (0-10 puntos) + public int CalculateFailedAttempts(User user, string ipAddress) + { + var recentFailures = _auditRepository + .GetFailedLoginAttempts(user.Id, ipAddress, lastMinutes: 60) + .Count; + + return recentFailures switch + { + 0 => 0, + 1 to 3 => 3, + 4 to 6 => 7, +>= 7 => 10 + }; + } + + // Factor 6: Tenant Risk Level (0-30 puntos) + public int CalculateTenantRiskLevel(Tenant tenant) + { + return tenant.RiskLevel switch + { + TenantRiskLevel.LOW => 0, + TenantRiskLevel.MEDIUM => 10, + TenantRiskLevel.HIGH => 25, + TenantRiskLevel.CRITICAL => 30, + _ => 10 + }; + } +} +``` + +--- + +### 1.3 Acceptance Criteria (FS-09) + +#### US-017: Adaptive MFA**Como:** Administrador de Seguridad **Quiero:** Reglas de MFA adaptativo para exigir verificación en accesos de riesgo **Para que:** La postura de seguridad mejore sin fricción uniforme **Criteria:** + +```gherkin +Feature: Adaptive MFA Requirements + + Scenario: Low-risk login (interno, dispositivo conocido, hora usual) + Given User "alice@corp.com" (INTERNAL) intenta login a las 9am + And desde su dispositivo conocido + And desde su país usual + When Risk Score calculado = 15 + Then MFA no es requerido + And login completa sin MFA + + Scenario: Medium-risk login (hora inusual) + Given User "bob@corp.com" intenta login a las 3am + And Risk Score calculado = 35 + When User category = INTERNAL + Then MFA es "Recommended" (optional) + And se muestra prompt "Verificación adicional?" con skip button + + Scenario: High-risk login (país diferente) + Given User "charlie@corp.com" (EXTERNAL) intenta login desde Brasil + And su último login fue desde USA hace 1 hora (viaje imposible) + When Risk Score calculado = 75 + Then MFA es "Required" + And login BLOQUEADO hasta completar MFA + + Scenario: Critical risk login (múltiples factores) + Given User intenta login con Risk Score = 85 + And factores: país desconocido + 5 intentos fallidos + IP maliciosa + When Risk Score > 70 + Then MFA es "RequiredWithSecurityReview" + And login bloqueado + security team notificado + And auditoría registra intent malicioso + + Scenario: Tenant High-Risk Category + Given Tenant "HighRiskCorp" categorizado como HIGH_RISK + And User es de ese tenant + When cualquier login + Then Risk Score recibe +25 puntos automáticamente + And MFA es más probable (threshold más bajo) +``` + +--- + +### 1.4 Métodos Passwordless Soportados + +#### FS-09 Scope: Métodos Disponibles + +| Método | Descripción | Seguridad | UX | Requisitos | +| -------- | ------------- | ----------- | ----- | ------------ | +| **FIDO2 / WebAuthn** | Biometría o security key | (Alta) | (Excelente) | Device con soporte FIDO2 | +| **Magic Link** | Link por email con token temporal | (Media) | (Excelente) | Email access | +| **App Notification** | Push a app móvil (similar a Microsoft/Google Authenticator) | (Alta) | (Excelente) | Authenticator app instalada | +| **SMS OTP** | Código temporal por SMS | (Baja) | (Buena) | Número teléfono verificado | +| **TOTP** | Time-based OTP (Google Authenticator, Authy) | (Media) | (Buena) | Authenticator app | + +**MVP FS-09 Scope:** FIDO2 + Magic Link + App Notification + +```csharp +public interface IPasswordlessMethod +{ + string MethodName { get; } // "fido2", "magic_link", "app_notification" + TaskCrear session
Hash token + API->>Email: Enviar magic link + Email-->>API: Email sent + API-->>Browser: 202 Accepted { sessionId, expiresAt } + Note over Browser: Usuario click magic link + Browser->>API: GET /auth/passwordless/verify?token=XXX&session=YYY + Note over API: Recuperar session
Validar token
Crear JWT + API-->>Browser: 302 Redirect + Set-Cookie session_jwt + Note over Browser: Usuario autenticado +``` + +--- + +### 1.5 Configuration (FS-09) + +Dónde y cómo se configuran las reglas MFA: + +```sql +-- Nueva tabla en Configuration Context +CREATE TABLE configuration.mfa_policies (id uuid PRIMARY KEY, + root_tenant_id uuid NOT NULL, + code varchar(64), -- "default", "high-risk-users", etc. + name varchar(255), + enabled boolean, + scope_type varchar(32), -- 'GLOBAL', 'TENANT', 'ORGANIZATION' + applies_to_user_category varchar(32), -- 'INTERNAL', 'EXTERNAL', 'B2B' + +-- Risk-based thresholds + risk_score_required_threshold integer, -- Ej: 40 + risk_score_review_threshold integer, -- Ej: 70 + +-- Enabled methods + allow_fido2 boolean, + allow_magic_link boolean, + allow_app_notification boolean, + allow_sms_otp boolean, + allow_totp boolean, + +-- Passwordless-only mode (no password auth) + passwordless_only boolean, + + created_at timestamptz, + modified_at timestamptz, + root_tenant_id uuid); + +-- Tabla de Risk Scoring customization por tenant +CREATE TABLE configuration.risk_scoring_weights (id uuid PRIMARY KEY, + root_tenant_id uuid NOT NULL, + frequency_anomaly_weight DECIMAL(3,2), -- Default: 0.20 + geographic_anomaly_weight DECIMAL(3,2), -- Default: 0.25 + device_reputation_weight DECIMAL(3,2), -- Default: 0.15 + network_anomaly_weight DECIMAL(3,2), -- Default: 0.10 + failed_attempts_weight DECIMAL(3,2), -- Default: 0.10 + tenant_risk_weight DECIMAL(3,2) -- Default: 0.20); +``` + +--- + +## PARTE 2: FS-14 — Delegated Administration & Scopes + +### 2.1 Definición **FS-14** permite que administradores deleguen autoridad de gestión a otros con límites controlados + +* **Delegating Admin** (A) → **Delegated Admin** (B): "Puedes gestionar usuarios en mi división" +* **Scope Limiting**: "Solo en ORGANIZATION X", "Solo acciones CREATE_USER y ASSIGN_PROFILE" +* **Temporal Constraints**: "Válido hasta 2026-12-31" +* **Approval Required**: Crear delegación puede requerir aprobación (si es sensitive) + +### 2.2 State Machine (Delegación) + +#### Ciclo de Vida de la Delegacion + +```mermaid +stateDiagram-v2 + [*] --> DRAFT: Admin completa configuracion + DRAFT --> PENDING_APPROVAL: Si requiere approval + DRAFT --> ACTIVE: Si no requiere approval + PENDING_APPROVAL --> ACTIVE: Approver aprueba + PENDING_APPROVAL --> REJECTED: Approver rechaza + ACTIVE --> REVOKED: Revocado + ACTIVE --> EXPIRED: Expirado + ACTIVE --> COMPLETED: Finaliza + REVOKED --> ARCHIVED + EXPIRED --> ARCHIVED + COMPLETED --> ARCHIVED + REJECTED --> ARCHIVED + ARCHIVED --> [*] +``` + +#### 2.2.1 Estados Detallados + +| Estado | Descripción | Transiciones Válidas | Eventos | +| -------- | ------------- | --------------------- | -------- | +| **DRAFT** | Delegación en creación, no visible | → PENDING_APPROVAL, → ACTIVE | Created | +| **PENDING_APPROVAL** | Esperando aprobación (si config lo requiere) | → ACTIVE (approved), → REJECTED | SubmittedForApproval | +| **ACTIVE** | Delegación operativa | → REVOKED, → EXPIRED | Activated | +| **REVOKED** | Revocado manualmente por admin | → ARCHIVED | Revoked | +| **EXPIRED** | Expiró por fecha (valid_until) | → ARCHIVED | Expired | +| **COMPLETED** | Finalizado naturalmente (fin de período) | → ARCHIVED | Completed | +| **REJECTED** | Rechazado en aprobación | → ARCHIVED | Rejected | +| **ARCHIVED** | Histórico (no visible en operaciones) | (ninguna) | Archived | + +#### 2.2.2 Transiciones Bloqueadas + +```csharp +public class DelegationStateValidator +{ + public bool IsValidTransition(DelegationStatus from, DelegationStatus to) + { + var validTransitions = new Dictionary
Generates events] + AC -->|APPROVAL_REQUEST_CREATED
APPROVAL_SUBMITTED
APPROVAL_APPROVED
APPROVAL_REJECTED
APPROVAL_ESCALATED| AU + AU[AUDIT CONTEXT
audit_log receives events
stores immutable trail] +``` + +Cada decision de aprobacion se registra en `audit_log` con: approver, timestamp, decision, reason. + +### 4.3 Approvals ↔ Configuration Context + +```mermaid +flowchart TD + CC[CONFIGURATION CONTEXT
approval_workflows configurable
approval_rules configurable
mfa_policies configurable
risk_scoring_weights tunable] + CC -->|Defines approval behavior| AC + AC[APPROVALS CONTEXT
Uses workflows from config
Applies rules from config
Evaluates risk scores per config] +``` + +--- + +## Summary EP-06 Deliverables + +### Completed in This Document + +1. **FS-09 Adaptive MFA** + + * Risk Scoring Model (6 factors, weighted) + * Decision Engine (thresholds) + * Passwordless Methods (FIDO2, Magic Link, App Notification) + * Configuration Model + * Acceptance Criteria (5 scenarios) + +2. **FS-14 Delegated Admin** + + * State Machine (8 states) + * Scope Model (5 scope types, allowed actions) + * Principle of Least Privilege Validation + * Temporal Constraints & Auto-Expiration + * Acceptance Criteria (6 scenarios) + +3. **ER Model (Complete)** + + * approval_workflows + * approval_rules + * approval_requests + * approval_approvers + * approval_attachments + * user_management_delegations + * Indices for performance + +4. **Integration Map** + + * Approvals ↔ Authorization + * Approvals ↔ Audit + * Approvals ↔ Configuration + +--- + +### Próximo: EP-07 Compliance (Documento separado) + +--- + +**Aprobado por:** Arquitecto Principal **Fecha:** 2026-05-14 diff --git a/docs/architecture/ep-07-compliance-detailed-design.es.md b/docs/architecture/ep-07-compliance-detailed-design.es.md new file mode 100644 index 00000000..28ef9ed7 --- /dev/null +++ b/docs/architecture/ep-07-compliance-detailed-design.es.md @@ -0,0 +1,959 @@ +# EP-07: Diseño Detallado — Ciclo de Vida de Cumplimiento + +**Versión:** 1.0 +**Fecha:** 2026-05-14 +**Épica:** EP-07 (Post-MVP) +**Historias:** US-023 a US-028 +**Functional Stories:** FS-11, FS-15 (NEW), FS-16 (NEW) + +--- + +## PARTE 1: FS-11 — Upload & Validate User Document + +### 1.1 Definición + +**FS-11** permite que usuarios y administradores carguen documentos (identidad, certificados, acuerdos) para cumplimiento. + +Workflow: + +1. **Upload**: Usuario carga documento → storage seguro +2. **Validation**: Validador revisa → APPROVED / REJECTED +3. **Lifecycle**: Documento válido hasta fecha de revalidación +4. **Enforcement**: Si vence, acceso puede ser afectado (integración con FS-16) + +### 1.2 Document Type Taxonomy + +```csharp +public enum DocumentType +{ + // Identity Verification + IDENTITY_PROOF, // Passport, DNI, Driver License + ADDRESS_VERIFICATION, // Utility bill, bank statement + CORPORATE_REGISTRATION, // Articles of incorporation + + // Authorization + SERVICE_AGREEMENT, // B2B contract + DATA_PROCESSING_AGREEMENT, // DPA + NON_DISCLOSURE_AGREEMENT, // NDA + + // Compliance + BACKGROUND_CHECK, // Criminal record clearance + INSURANCE_CERTIFICATE, // Liability, D&O + SECURITY_CLEARANCE, // Government clearance + + // Role-specific + CERTIFICATION, // Professional cert (CPA, CISSP) + TRAINING_COMPLETION, // Mandatory training proof + MEDICAL_CLEARANCE, // For certain roles + + // Custom (tenant-specific) + CUSTOM_DOCUMENT // Tenant-defined +} + +public record DocumentTypeConfiguration +{ + public DocumentType Type { get; init; } + public string Name { get; init; } + public string Description { get; init; } + public TimeSpan ValidityPeriod { get; init; } // Cuánto tiempo válido + public bool RequiresValidation { get; init; } // Quién aprueba + public List
+ © BeyondNet S.A.C. · RUC 20100412447 · Operador Logístico Aduanero desde 1978 +
diff --git a/docs/architecture/session-context-architecture-review.es.md b/docs/architecture/session-context-architecture-review.es.md new file mode 100644 index 00000000..9b71e9be --- /dev/null +++ b/docs/architecture/session-context-architecture-review.es.md @@ -0,0 +1,605 @@ +# Informe de Evaluación de Arquitectura — UMS: Autenticación, Grafo de Autorización y Contexto de Sistema + +**Repositorio:** `ums` (rama `develop`) · **Fecha:** 2026-08-01 · **Autor:** Software Architect Enterprise +**Alcance:** backend `.NET 10` (`src/apps/ums.api`), SDK (`src/libs/sdk`), frontend (`src/apps/ums.web-app`), infraestructura (`src/infra`) +**Método:** análisis estático con verificación adversarial de todas las afirmaciones de alto impacto. Las afirmaciones refutadas o corregidas durante la verificación **no** aparecen como hechos en este informe. + +--- + +## 1. Resumen ejecutivo + +UMS **ya tiene** un motor de contexto de sesión. No hay que construirlo: `AuthorizationGraph` + `AuthorizationGraphBuilderService` + `AuthGraphPayload` son exactamente el "contexto de sistema" que pide el escenario objetivo, construido en 11 pasos y compartido por `/auth/login` y `/api/v1/client/authenticate` (`AuthorizationGraph.cs:83-112`, `AuthorizationGraphBuilderService.cs:84-237`, `AuthGraphPayload.cs:40-67`). Los patrones enterprise necesarios están presentes y bien usados: CQRS tipado sobre MediatR, Result pattern, agregados DDD, repositorios con UnitOfWork, outbox transaccional, factory de serializadores y dos capas AOP de autorización. **La brecha no es de patrones: es de cardinalidad, de composición del contrato y de coste por login.** + +Cuatro conclusiones, en orden de gravedad: + +1. **El contrato es mono-perfil y mono-sistema por construcción.** El builder elige UN perfil con `FirstOrDefault` sobre un orden por `RoleId` (un GUID) y descarta el resto sin registrarlo — no hay logger inyectado en el servicio (`AuthorizationGraphBuilderService.cs:121-123`, `PostgreSqlProfileRepository.cs:70`). `GraphContext` lleva un `SystemSuite?`, un `Role?` y un `Profile?` escalares (`GraphContext.cs:9-15`). El escenario multi-perfil es alcanzable en producción: el índice `(TenantId, UserId, RoleId, BranchId)` no es único (`ProfileRecordConfiguration.cs:21`) y el flujo IGA crea perfiles adicionales cuando difieren rol o sucursal (`ApproveRequestCommandHandler.cs:187-191`). Los puntos 3 y 4 del escenario objetivo **no tienen hoy ninguna representación en el contrato**. + +2. **El aplanamiento del árbol de navegación pierde datos en silencio.** `MenuNode` es un árbol recursivo de profundidad arbitraria aceptado por ADR-0090, pero `BuildMenuAccess` recorre exactamente tres niveles literales Menu→SubMenu→Option (`AuthorizationGraphBuilderService.cs:307,311,315`). Cualquier opción fuera de ese patrón —creable hoy desde la API (`AddNodeCommand.cs:37-51` no valida forma) y desde el UI de administración (`SuiteNode.tsx:90,358-360`)— desaparece del grafo sin error ni traza. El efecto es _fail-closed_ (el usuario pierde acceso, no lo gana), pero el diagnóstico es caro porque la data semilla nunca lo reproduce (`AuthorizationDevDataSeeder.cs:346-355`) y el read path administrativo **sí** muestra el nodo (`SystemSuiteDto.cs:73`, recursivo). + +3. **El coste por login es alto y una parte es desperdicio puro y demostrable.** El grafo emite 16 sentencias SQL estrictamente secuenciales (verificado sumando las implementaciones: Tenant 1 + Profile 2 + Role 1 + SystemSuite 7 + Templates 2 + FeatureFlags 3); el login completo suma ~24 con el handler. De esas, **2 son 100 % desperdicio**: la carga de todas las plantillas del inquilino con sus ítems cuyo resultado se descarta con `#pragma warning disable S1481` (`AuthorizationGraphBuilderService.cs:148-155`, `PostgreSqlPermissionTemplateRepository.cs:52-63`). Se paga en login, en ambos refresh y en el preview. Ninguna lectura del grafo usa `AsNoTracking` — hay exactamente una ocurrencia en todo `Infrastructure/Persistence` (`RefreshTokenStore.cs:53`). + +4. **El bloqueador operativo más urgente no es el grafo: es que UMS no puede escalar a más de una réplica.** `backend-deployment.yaml:8` fija `replicas: 1` literal, sin `resources`, sin HPA ni PDB. Y aunque se cambiara, se rompería funcionalidad: el código selecciona Redis con `configuration["Redis:Connection"]` (`DependencyInjection.cs:151`) mientras el chart inyecta `REDIS_CONNECTION` (`backend-deployment.yaml:53-54`) — la clave no enlaza, así que en Kubernetes corren `InMemoryTokenRevocationStore` e `InMemoryConfigurationCache`. Sumado a la ausencia total de Data Protection persistido (0 ocurrencias de `PersistKeysTo`/`SetApplicationName`, `AuthenticationExtensions.cs:49-70`), escalar hoy produce cookies indescifrables entre pods y tokens revocados que siguen valiendo. + +**Recomendación global:** no rediseñar. Hay una secuencia de siete cambios acotados —cinco de ellos de riesgo bajo y efecto medible— que resuelven el 80 % del problema antes de tocar el contrato. El contrato solo debe cambiar una vez, y con ADR. + +--- + +## 2. Evaluación de la arquitectura actual + +### 2.1 Lo que está bien hecho (y no hay que tocar) + +| Área | Evidencia | Valoración | +|---|---|---| +| CQRS tipado | `ICommand.cs:6`, `IQueryHandler.cs:6`, MediatR 12.4.1 (`Ums.Application.csproj:19`) | Separación de contrato, no solo de nombres. Correcto. | +| Result pattern | `Result.cs:7-45` | Alta adopción. Único reparo: el error es `string` y el código HTTP se extrae por parsing (`ClientAuthEndpoints.cs:160-164`). Deuda menor, no bloqueante. | +| Agregados DDD | `Profile.cs:10`, `SystemSuite.cs:14` sobre `AggregateRootesquema por módulo")] + BUS["Bus de eventos
+ Transactional Outbox"] + end + + WEB --> API --> ID + API --> AUTHZ + API --> CFG + API --> APR + API --> IGA + ID -->|IDs| AUTHZ + APR -->|IDs| IGA + ID & AUTHZ & CFG & APR & IGA -->|eventos| BUS + BUS --> AUD + ID & AUTHZ & CFG & APR & IGA & AUD --> DB + + style Contexts fill:#e3f2fd,stroke:#1565c0,color:#000 + style AUD fill:#e8f5e9,stroke:#2e7d32,color:#000 +``` + +Los contextos coinciden con los del PRD: **Identity**, **Authorization**, +**Configuration**, **Approvals**, **IGA** y **Audit** (suscriptor _downstream_ de +todos). El código materializa esta división en `src/apps/ums.api`. + +## 3. Estructura por Capas + +Cada contexto respeta la misma estratificación (proyectos `Ums.*`): + +| Capa | Proyecto | Responsabilidad | Dependencias | +| :--- | :--- | :--- | :--- | +| Domain | `Ums.Domain` | Agregados, invariantes, eventos de dominio | Solo `System.*` | +| Application | `Ums.Application` | CQRS (comandos/queries), handlers, validación | MediatR, FluentValidation | +| Infrastructure | `Ums.Infrastructure` | Persistencia, outbox, adaptadores, AOP | EF Core, Npgsql, MassTransit | +| Presentation | `Ums.Presentation` | API, endpoints, middleware | ASP.NET Core | +| ReadModels | `Ums.ReadModels` | Proyecciones de lectura (CQRS) | EF Core | +| Globalization | `Ums.Globalization` | Localización | — | + +La regla de dependencia apunta siempre hacia adentro: Presentation → Application → +Domain; Infrastructure implementa los puertos que Application declara. + +## 4. Contratos e Integraciones + +* **API REST unificada (ADR-UMS-055/059, revisado — [D-007](../../DECISIONS.md)):** un único + transporte REST para queries (GET, con proyecciones planas de lectura) y comandos + (POST/PUT/PATCH/DELETE). GraphQL fue retirado; el CQRS permanece en la capa de + aplicación. Nivel único tras el gateway/BFF. +* **Grafo de Autorización (ADR-UMS-088/0080/0081):** contrato de salida hacia los + sistemas cliente. Snapshot inmutable y autocontenido, _Code-First / ID-Optional_, + serializable (JSON/XML/YAML/CSV), entregado en el login y validado localmente por + el cliente. +* **SDK multi-runtime (ADR-UMS-073):** `Ums.Sdk.*` (.NET) y `@ums/ums-*` + (TypeScript / NestJS) para que los consumidores integren autorización sin acoplarse + a la API interna. +* **Proveedores de identidad externos:** OIDC / SAML 2.0 / WS-Federation, resueltos + dinámicamente desde configuración (ADR-UMS-072), no desde código. +* **Mensajería (ADR-UMS-051):** eventos de integración por bus como puerto inyectable, + con _Transactional Outbox_. El contrato de entrada de MMS + (`Ums.Contracts.MasterData:TenantEvent`) está fijado y su integración + diferida (D-006, [G-011](../../GAPS.md)). +* **Auditoría:** suscriptor _downstream_ que recibe eventos de todos los contextos + y persiste una traza inmutable (ADR-UMS-052). + +## 5. Transversales (Cross-Cutting) + +* **Shells corporativos:** `BeyondNetCode.Shell.*` (DDD, AOP, Factory, Bootstrapper), + ruteados desde el framework de origen (D-005). Ver [DECISIONS.md](../../DECISIONS.md). +* **AOP (ADR-UMS-060):** _concerns_ transversales (logging, auditoría, transacción, + validación de tenant, idempotencia) vía DispatchProxy sobre el pipeline, no + esparcidos en los handlers. +* **Contexto de ejecución (ADR-UMS-061):** propagación de correlación/traza; hoy con un + shim local de observabilidad ([G-015](../../GAPS.md)) pendiente de migrar a + `ActivitySource` nativo. +* **Observabilidad (ADR-UMS-053):** OpenTelemetry (trazas/métricas) y logging seguro de + PII (ADR-UMS-062). +* **Idempotencia (ADR-UMS-063):** middleware de `Idempotency-Key` ante reintentos. + +## 6. Persistencia y Datos + +* **PostgreSQL autoritativo (ADR-UMS-089)**, con **esquema por módulo** (ADR-UMS-087/0070) + para aislar los contextos también a nivel físico. +* **Aislamiento por inquilino** en la capa de aplicación mediante _global query filters_ + de EF Core sobre `OrganizationId` (mecanismo primario y suficiente). El _failsafe_ de + Row-Level Security a nivel de base de datos no está activo con PostgreSQL + ([G-020](../../GAPS.md)). +* **CQRS:** los `ReadModels` mantienen proyecciones planas para la vía de lectura; + la escritura pasa por los agregados y el outbox. +* **Fechas en UTC** (ADR-UMS-076); zona horaria e idioma se resuelven en el cliente. + +## 7. Topología de Despliegue + +UMS opera como **pasarela de identidad y autorización**, _standalone_ o integrada +con IdPs externos, tras un **API Gateway / BFF** (YARP, ADR-UMS-058) que aplica +límites de complejidad, timeouts y rate limiting. La infraestructura de referencia +(Terraform, Helm, Docker Compose con stack de observabilidad) se importó bajo +`src/infra/`; su promoción a un pipeline de despliegue gobernado es +[G-010](../../GAPS.md). + +## 8. Trazabilidad a ADRs + +Las decisiones estructurales residen en el corpus importado (ADR-0050 a ADR-0083). +Ancla por área: API híbrida (ADR-UMS-055/059), gateway (ADR-UMS-058), grafo de +autorización (ADR-UMS-088/0080/0081), resolución de auth (ADR-UMS-072), AOP (ADR-UMS-060), +contexto de ejecución (ADR-UMS-061), persistencia (ADR-UMS-087/0070/0082), auditoría +(ADR-UMS-052), SDK (ADR-UMS-073), guardas de dependencia (ADR-UMS-079). + +Estos ADRs son de origen importado; su **retrazado a ADRs aceptados de +`evolith-core`** (S-06) está registrado como [G-012](../../GAPS.md). + +## Historial de Cambios + +| Versión | Fecha | Autor | Descripción | +| :--- | :--- | :--- | :--- | +| 1.0.0 | 2026-07-13 | BeyondNet S.A.C. | Arquitectura de solución inicial: topología, capas, contratos y trazabilidad. Cierra G-007 | + +--- + +
+ © BeyondNet S.A.C. · RUC 20100412447 · Operador Logístico Aduanero desde 1978 +
diff --git a/docs/architecture/system-selection-at-login-design.es.md b/docs/architecture/system-selection-at-login-design.es.md new file mode 100644 index 00000000..a2b37120 --- /dev/null +++ b/docs/architecture/system-selection-at-login-design.es.md @@ -0,0 +1,465 @@ +# Diseño — El cliente declara su sistema al autenticar (`systemCode`) y el multi-perfil por el carril de satélite + +> **Estado:** Propuesta · **Fase SDLC:** 2 · Diseño · **Fecha:** 2026-08-02 +> **Norma que realiza:** `ADR-0156` de `evolith-core` (`reference/architecture/adrs/core/0156-autenticacion-tablero-ums-sistema-solicitado-grafo-por-api.es.md`), §2.5, §2.6 y §2.10. Supersede a `ADR-0155`. +> **Amplía a:** [Cambio de perfil y lista de perfiles](./diseno-cambio-de-perfil.md) — implementa su §4.2, que quedó como propuesta y **nunca se construyó**, y renombra su campo `system` a `systemCode` (§3.1). +> **Consumidor de referencia:** [Análisis de integración E2E — UMS ↔ Tablero SDLC](./analisis-integracion-e2e-ums-tablero-sdlc.md) +> **Gaps relacionados:** [G-177](../../GAPS.md), [G-184](../../GAPS.md), [G-201](../../GAPS.md), [G-202](../../GAPS.md) +> **Alcance:** especificación de contrato y de cambios. **No contiene código de producto**; contiene la precisión suficiente para implementarlo sin volver a decidir. + +--- + +## 1. El defecto, en una frase + +Ni [`ClientAuthRequest`](../../src/apps/ums.api/Ums.Presentation/Endpoints/Identity/Auth/ClientAuthEndpoints.cs) ni [`AuthenticateUserCommand`](../../src/apps/ums.api/Ums.Application/Identity/Auth/Commands/AuthenticateUserCommand.cs) aceptan **qué sistema pide el llamante**, de modo que +[`AuthorizationGraphBuilderService`](../../src/apps/ums.api/Ums.Application/Authorization/Graph/AuthorizationGraphBuilderService.cs) resuelve el perfil por desempate (`:160-167`) y construye el grafo del sistema que ese desempate elija. + +El desempate no está mal: **responde a una pregunta que nadie le hizo**, porque el contrato no permite hacerla. Es la causa de [G-184](../../GAPS.md) y la causa de que el Tablero SDLC reciba el grafo de `SIL`. + +**Verificado el 2026-08-02** contra `http://localhost:5080` con `admin@beyondnet.com.pe` / `BEYONDNET`: `context.systemSuite.code` = `SIL`, `profiles` con un solo elemento, también de `SIL`. En esta instancia **ningún usuario tiene más de un perfil** (13 perfiles / 13 usuarios distintos, consultado en `GET /api/v1/profiles`), así que **el escenario multi-perfil no es reproducible con la siembra actual**: exige sembrar un usuario con dos perfiles antes de poder probarse (§9). + +## 2. Modelo, tal como el cliente lo precisó + +* Un **perfil** ata **inquilino + sistema + usuario**. El **rol** es la dimensión que varía: el mismo usuario, en el mismo inquilino y el mismo sistema, puede tener más de un perfil por rol. La sucursal lo acota opcionalmente. El modelo ya lo permite: el índice `(TenantId, UserId, RoleId, BranchId)` no es único. +* El **inquilino es `BEYONDNET` siempre**, salvo indicación contraria. Lo resuelve el servidor del cliente por configuración; **no se pide al usuario**. +* El **login pide usuario y contraseña**. Ni rol, ni inquilino, ni sistema. +* El **sistema lo declara el cliente**, no el usuario, y es **opcional en el contrato**: sin él, UMS devuelve los perfiles del usuario en ese inquilino **de todos los sistemas** (caso multiproducto); con él, los acota a ese sistema. +* Si el resultado trae **más de un perfil**, el cliente ofrece **cambio de perfil**, reutilizando lo que UMS ya publica. +* El cliente **no calcula permisos**: usa exclusivamente el grafo. + +--- + +## 3. Contrato de petición + +### 3.1 Dónde entra `systemCode` + +Cuatro puntos, en este orden. Los tres primeros son obligatorios; el cuarto cierra un hueco preexistente. + +| # | Capa | Artefacto | Cambio | +| :--- | :--- | :--- | :--- | +| 1 | Presentation | `ClientAuthRequest` (`ClientAuthEndpoints.cs:320-325`) | Nuevo parámetro `string? SystemCode = null`, **posicionado al final** para no alterar el orden de los existentes | +| 2 | Application | `AuthenticateUserCommand` (`AuthenticateUserCommand.cs:16-23`) | Nuevo parámetro `string? SystemCode = null`, al final | +| 3 | Domain (puerto) | `IAuthorizationGraphBuilder.BuildAsync` (`IAuthorizationGraphBuilder.cs:21-25`) | Nuevo parámetro `string? systemCode`, **entre `authMethod` y `cancellationToken`** | +| 4 | Presentation | `LoginRequest` (`AuthEndpoints.cs:861-865`) | Nuevo parámetro `string? SystemCode = null`, al final. Segunda ola (§10) | + +**Nombre: `systemCode`, no `system`.** [`diseno-cambio-de-perfil.md`](./diseno-cambio-de-perfil.md) §4.2 propuso `system`; nunca se implementó, así que no hay compatibilidad que romper. Se elige `systemCode` por simetría con `tenantCode`, que ya está en el mismo cuerpo, y porque el valor es un **código de negocio**, no un objeto. Esta decisión **anula** el nombre de aquella propuesta. + +**Normalización, en el endpoint y en un solo sitio:** `SystemCode?.Trim().ToUpperInvariant()`, y **cadena vacía o solo espacios equivale a ausente** (`null`). Sin esta regla, `"systemCode": ""` significaría «un sistema cuyo código es la cadena vacía» y devolvería cero perfiles: un cliente mal configurado obtendría «sin acceso» en vez del comportamiento multiproducto, y el diagnóstico sería caro. + +**El `systemCode` no es un campo de formulario.** Es configuración solo-servidor del cliente, igual que la URL de UMS. UMS no lo impone —no puede—, pero el contrato lo documenta: `ADR-0156` §2.5. + +### 3.2 Petición resultante + +```jsonc +POST /api/v1/client/authenticate?format=json +Content-Type: application/json + +{ + "tenantCode": "BEYONDNET", + "username": "pmo.sdlc@beyondnet.com.pe", + "password": "…", + "systemCode": "SDLC", // NUEVO · opcional · el Tablero lo envía siempre + "format": "JSON" // ya existía +} +``` + +### 3.3 Lo que NO se toca + +* **`RequestedScopes`** (`ClientAuthRequest`) sigue sin uso. No se aprovecha para esto: es un filtro de *scopes*, no de sistema, y darle una segunda semántica lo dejaría inservible para la primera. +* **`AuthenticateUserCommand.SystemSuiteId`** (`Guid?`) **no se reutiliza como entrada**. Es el contexto de resolución de IdP de FR-042 / `ADR-UMS-097` §2.2, viaja como identificador y hoy siempre llega `null`. Mezclar ambas semánticas en un campo ata el enrutado de IdP al filtro de perfiles, que son problemas distintos. + **Sí se puebla como salida derivada** (§4.4): cuando el código resuelva a una suite, el manejador rellena `SystemSuiteId` para que el enrutado por suite tenga por fin una fuente. Es una mejora colateral, **best-effort y silenciosa**: si no resuelve, se queda `null` y la autenticación sigue exactamente igual. + +--- + +## 4. Cómo filtra + +### 4.1 La regla que hace el filtro anti-enumeración por construcción + +> **El filtro se aplica sobre los sistemas de los perfiles que el usuario ya tiene. Este camino NO consulta el catálogo de sistemas por código. Nunca.** + +Es decir: **está prohibido** llamar a `ISystemSuiteRepository.GetByCodeAsync` en el flujo de autenticación para validar el `systemCode` recibido. + +La consecuencia es la propiedad de seguridad que pide `ADR-0156` §6: un código de sistema **inexistente** y un código **existente en el que el usuario no tiene perfil** producen exactamente el mismo estado interno —lista de candidatos vacía— y por tanto exactamente la misma respuesta. No hay dos ramas que puedan divergir en un mensaje, un status o un tiempo de respuesta, porque **no hay dos ramas**. Validar el código contra el catálogo y luego «devolver el mismo error» es la variante frágil: sobrevive hasta el primer refactor que añada un `log.Warn("suite {code} no existe")`. + +### 4.2 Punto exacto del cambio + +En `AuthorizationGraphBuilderService.ConstruirAsync`, entre `:129` y `:140`: + +1. Se cargan los perfiles activos (`GetActiveByUserAndTenantAsync`, `:129-130`) — sin cambio. +2. Se cargan sus roles por lote (`GetByIdsAsync`, `:134-137`) — sin cambio. +3. **Se adelanta** la resolución de resúmenes de suite (`_suiteRepo.GetSummariesByIdsAsync`) que hoy vive dentro de `ConstruirPerfilesAsync` (`:362-363`), y el diccionario resultante se pasa a esa función en vez de que lo calcule. **No añade consultas: mueve una.** +4. Se calcula la lista de candidatos: + +```text +perfilesCandidatos = + systemCode == null + ? perfilesDelUsuario + : perfilesDelUsuario donde suiteDelRol(perfil).Code ==(OrdinalIgnoreCase) systemCode +``` + +5. El desempate de `:160-167` opera sobre `perfilesCandidatos`, no sobre `perfilesDelUsuario`. +6. `ConstruirPerfilesAsync` proyecta `perfilesCandidatos`, **no** la lista completa. + +**El punto 6 es una regla de seguridad, no de estética.** Si el bloque `profiles` viajara completo mientras el grafo está acotado, un satélite que pide `SDLC` recibiría el inventario de los sistemas en los que ese usuario trabaja. Eso es información del inquilino filtrándose a un sistema que no la necesita, y contradice `ADR-0156` §2.5. + +### 4.3 Un perfil cuyo rol o suite no resuelva se descarta, y se registra + +`ConstruirPerfilesAsync` ya descarta en silencio el perfil cuyo rol o cuya suite no encuentra (`:369-370`). Con el filtro activo ese descarte **cambia de significado**: deja de ser una fila que no se pinta y pasa a poder ser la diferencia entre «tienes acceso» y «no tienes acceso». Debe **registrarse en el log a nivel `Warning`** con el identificador del perfil y el del rol. El servicio no tiene logger hoy —es la causa raíz que [G-177](../../GAPS.md) documentó— y hay que inyectárselo. + +### 4.4 Poblado derivado de `SystemSuiteId` + +Cuando `systemCode != null` y **coincide con la suite de algún perfil del usuario**, el manejador rellena `AuthenticateUserCommand.SystemSuiteId` con el id de esa suite antes de llamar a `_methodResolver.ResolveAsync` (`AuthenticateUserCommandHandler.cs:88-93`). + +**Orden y honestidad del dato:** hoy la resolución de método ocurre **antes** de conocer al usuario (paso 2 del manejador) y el filtro de perfiles **después** (paso 5). Resolver la suite antes exigiría o consultar el catálogo —prohibido por §4.1— o cargar los perfiles antes de validar credenciales —inaceptable—. Por tanto: + +> **En esta ola, `SystemSuiteId` se sigue enviando `null` al resolver de IdP.** El poblado derivado queda **fuera de alcance** y se registra como hallazgo. Prometerlo aquí y no poder cumplirlo sería exactamente el tipo de afirmación sin evidencia que `SD-05` prohíbe. + +--- + +## 5. Respuesta: 0, 1 y N perfiles + +### 5.1 Discriminador nuevo en el grafo: `accessState` + +`onboardingPending` no basta. Hoy significa «el usuario no tiene ningún perfil» (grafo lobby, G-043). Con el filtro aparece un estado que **no es ese**: el usuario tiene perfiles, pero ninguno en el sistema que se pidió. Devolver `onboardingPending: true` ahí sería mentir, y el cliente mostraría un flujo de alta a alguien que ya está de alta. + +Se añade un campo de primer nivel, **enumeración cerrada**: + +| `accessState` | Significado | `onboardingPending` | +| :--- | :--- | ---: | +| `Granted` | Hay perfil vigente y el grafo lleva su navegación y sus permisos | `false` | +| `NoProfileInSystem` | El usuario **tiene** perfiles, pero **ninguno** en el sistema pedido — o el sistema pedido no existe, que es indistinguible por §4.1 | `false` | +| `OnboardingPending` | El usuario **no tiene ningún** perfil activo en el inquilino | `true` | + +`onboardingPending` **se conserva** y se emite como `accessState == "OnboardingPending"`. No se retira en esta versión: un consumidor de 2.0–2.3 sigue funcionando sin tocarlo. Su retirada, si se decide, sigue el ciclo de deprecación de `SCHEMA_VERSIONING.md`. + +### 5.2 Eco del sistema pedido: `context.requestedSystem` + +```jsonc +"context": { + "requestedSystem": { "code": "SDLC" } // o null si no se pidió ninguno +} +``` + +Es el **eco literal de la entrada**, ya normalizada. No es una lectura del catálogo y por tanto no filtra nada que el llamante no supiera. Sirve para dos cosas: que el cliente pueda decir «no tiene acceso a *SDLC*» sin llevar su propia configuración al navegador, y que un grafo capturado como evidencia sea autodescriptivo —hoy, ante un grafo de `SIL`, no hay forma de saber si alguien pidió otra cosa—. + +### 5.3 `profiles[].id` pasa a emitirse siempre + +Hoy `AuthGraphPayload.Profile` (`AuthGraphPayload.cs:133`) emite el `id` a través de `WithId(meta, …)`, es decir **solo** cuando el inquilino activa `AUTH_GRAPH_INCLUDE_TECHNICAL_METADATA`, que por defecto está en `false`. **Verificado en vivo:** las claves de `profiles[0]` son `system`, `role`, `branch`, `scope`, `isCurrent`. **No hay `id`.** + +Consecuencia medida: **el cliente recibe una lista de perfiles y no tiene nada que enviar para cambiar a ninguno**, porque `POST /api/v1/auth/switch-profile` exige `{ "profileId": "+ © BeyondNet S.A.C. · RUC 20100412447 · Operador Logístico Aduanero desde 1978 +
+ diff --git a/docs/architecture/technical-debt.md b/docs/architecture/technical-debt.md index d7b177d7..7b3cf26c 100644 --- a/docs/architecture/technical-debt.md +++ b/docs/architecture/technical-debt.md @@ -27,17 +27,14 @@ ## [TD-002] GraphQL Queries Return Empty Data for AppConfigurations -- **Status**: Acknowledged +- **Status**: Acknowledged — **workaround withdrawn, needs re-measuring** - **Severity**: Medium - **Component**: `Ums.Presentation/GraphQL/Configuration/AppConfigurationQueries.cs`, `Ums.Application/Configuration/AppConfiguration/Queries/GetAllAppConfigurationsQueryHandler.cs` -- **Description**: GraphQL endpoint for AppConfigurations (`appConfigurations` query) returns empty items array with `totalItems: 0` despite REST endpoint returning correct data (7 items). The handler executes successfully (~25ms) without errors, but the result is empty. Other GraphQL queries (e.g., `tenants`) work correctly. -- **Rationale**: Investigation did not reveal root cause. Same handler logic works for REST, same repository returns data for REST but not for GraphQL. Possible HotChocolate DataLoader or resolver scope issue. -- **Impact**: - - Frontend falls back to REST due to `FRONTEND_CONFIG_TRANSPORT = "rest"` flag. - - GraphQL remains non-functional for AppConfiguration bounded context. - - Reduced flexibility for frontend data fetching choices. -- **Workaround**: Use `FRONTEND_CONFIG_TRANSPORT = "rest"` flag in BD (current default). -- **Target Resolution**: Investigate HotChocolate resolver execution context, DataLoader caching, or any middleware that could affect GraphQL resolution differently from REST. +- **Description**: The `appConfigurations` GraphQL query returned an empty `items` array with `totalItems: 0` while the REST endpoint returned the same data correctly. The handler completed in ~25 ms without error; the result was simply empty. Other GraphQL queries (e.g. `tenants`) behaved normally. +- **Rationale**: The investigation never found a root cause. Same handler, same repository — data for REST, nothing for GraphQL. Suspected a HotChocolate DataLoader or resolver-scope issue. +- **What changed (2026-08-09 resync)**: the escape hatch this entry relied on **no longer exists**. The `FRONTEND_CONFIG_TRANSPORT` parameter and the `query-transport.service` that read it were withdrawn along with the web app's REST/GraphQL switch; the imported data-access layer calls REST directly and `branding.service` is the only consumer left on the GraphQL client. So there is no flag to set, and no fallback to fall back *from* — but also no live symptom, because nothing routes AppConfiguration reads through GraphQL any more. +- **Impact today**: latent, not observed. The GraphQL query still exists and is still registered in the schema; if a client starts using it, the original defect — whatever it is — is presumably still there. +- **Next step is measurement, not investigation**: query `appConfigurations` directly against a seeded environment and see whether it still returns empty. If it does, the entry stands and the DataLoader/resolver-scope hypothesis is the place to start. If it does not, close it — something along the way fixed it, and carrying a phantom is worse than carrying nothing. - **Related Files**: - `src/apps/ums.api/Ums.Presentation/GraphQL/Configuration/AppConfigurationQueries.cs` - `src/apps/ums.api/Ums.Application/Configuration/AppConfiguration/Queries/GetAllAppConfigurationsQueryHandler.cs` @@ -65,3 +62,74 @@ - **Related Documents**: - [Parameterization System Specification](../governance/construction/ddd-design/parameterization-system-spec.md) - [TODO-003](../governance/project/TODO.md#todo-003-implement-parameterization-system-with-loader-and-provider) + +--- + +## [TD-004] The Web App Typecheck Has Never Actually Run + +- **Status**: Confirmed +- **Severity**: High +- **Component**: `src/apps/ums.web-app/tsconfig.app.json`, `src/apps/ums.web-app/tsconfig.node.json` +- **Description**: Both configs declare `tsBuildInfoFile` without `incremental` or `composite`. That combination is a **configuration error**, not a warning: `tsc` reports `TS5111` and exits *before* type-checking anything. Running `tsc --noEmit -p tsconfig.app.json` on a file containing a deliberately undefined identifier reports nothing and exits 0. The project believes it has a typecheck and does not have one. +- **How it surfaced**: During the 2026-08-09 resync a `useCallback` import was omitted from three components. The "typecheck" passed; **vitest** caught it at render time with `ReferenceError: useCallback is not defined`. A second, worse case slipped even further: a helper extracted into the wrong scope (`renderValue` declared inside an `if (!config)` guard while the consumer lived outside it) passed both the typecheck and the build, and would have been a runtime `ReferenceError` on opening the panel. No test covers that panel. +- **Inherited, not introduced**: `unimar-ums` carries the identical `tsconfig`, so its type errors are hidden the same way. This is not a regression of the resync. +- **Impact**: + - `vite build` uses esbuild and does **not** type-check, so nothing in the local loop catches type errors. + - CI never runs `tsc` either: the `build` script is `vite build`. + - Enabling `"incremental": true` surfaces **545 pre-existing type errors**, several of them substantive — e.g. `Property 'menus' does not exist` on the authorization-graph node type, which suggests the graph schema (`nodes`) and its consumers (`menus`) have drifted apart. +- **Why it is not fixed here**: Landing 545 errors inside the resync PR without a triage plan would bury them. The fix is one line; the work is the backlog behind it. +- **Suggested resolution**: + 1. Add `"incremental": true` to both configs and capture the full error list as a baseline. + 2. Triage it — the `menus` vs `nodes` drift in the authorization graph is the first thing to look at, since it is the code path that decides what a user can see. + 3. Add a `typecheck` script and wire it into CI so the gate stops being decorative. + 4. Report the same defect upstream: the source platform has it too. +- **Related**: the three-component `useCallback` omission and the `renderValue` scope bug are both fixed in the resync branch. + +--- + +## [TD-005] Notification Bodies Are Logged in Cleartext, Unconditionally + +- **Status**: Confirmed +- **Severity**: High +- **Component**: `Ums.Infrastructure/Services/Notifications/SimulatedNotificationAdapter.cs`, `Ums.Infrastructure/DependencyInjection.cs:88` +- **Description**: `SimulatedNotificationAdapter` is the **only** implementation of `INotificationService`, and it is registered with `services.AddScoped(solo auth local)"] + end + subgraph Datos["Zona de datos (aislada por inquilino)"] + DB["PostgreSQL
(global query filters)"] + AUD["Auditoría (append-only)"] + SEC["Secretos / llaves"] + end + + U --> GW --> API + CLI --> GW + IDP -.credenciales federadas.-> API + API --> DB + API --> AUD + API -.referencia.-> SEC + ADMIN["Admin interno
cross-tenant"] --> PORTAL --> API + + style Publico fill:#fdecea,stroke:#c0392b,color:#000 + style Datos fill:#e8f5e9,stroke:#2e7d32,color:#000 + style SEC fill:#fff3e0,stroke:#e65100,color:#000 +``` + +**Fronteras de confianza principales:** + +* **Internet → Gateway:** todo tráfico externo pasa por el gateway (límites de + complejidad, timeouts, rate limiting). +* **API externa vs Portal de gestión:** el portal interno usa _siempre_ + autenticación local (nunca IdP), aunque el inquilino tenga federación + (`AuthAccessScope.PortalManagement`). +* **Aislamiento por inquilino:** frontera lógica dentro de la zona de datos; + ningún actor lee u opera datos de otro inquilino salvo `INTERNAL_ADMIN`, y + siempre auditado. +* **Frontera con el IdP externo:** UMS delega la verificación de credenciales pero + no confía ciegamente en los claims. + +## 3. Activos y Clasificación + +| Activo | Sensibilidad | Control base | +| :--- | :--- | :--- | +| Contraseñas (hash BCrypt) | Crítica | Hash en API, columna cifrada, nunca en logs/grafo (FR-010) | +| Tokens de sesión / Grafo de Autorización | Crítica | Vigencia acotada, sin secretos en el grafo (FR-034) | +| PII de usuario | Alta | Redacción en logs, anonimización en borrado (FR-004) | +| Traza de auditoría | Alta | Append-only, no repudio, sin UPDATE/DELETE (FR-070) | +| Secretos de IdP / llaves de cifrado | Crítica | Indirección por `SecretRef`; ver §5 | +| Configuración por inquilino | Media | Cifrado opcional (`IsEncrypted`), scope controlado | + +## 4. Análisis STRIDE + +### 4.1 Spoofing (suplantación de identidad) + +* **Amenazas:** robo de credenciales, replay de tokens, suplantación de IdP, + falsificación del claim `is_internal_admin`. +* **Controles existentes:** BCrypt para contraseñas locales; MFA multi-método + (FR-014); resolución dinámica del método de auth (FR-013); validación del claim + interno en `switch-tenant`. +* **Brechas / mitigación:** definir política de rotación y bloqueo por intentos + fallidos; validar `issuer`/`audience`/firma de los tokens del IdP; considerar + binding de sesión. → acciones de seguimiento en [G-001](../../GAPS.md). + +### 4.2 Tampering (manipulación) + +* **Amenazas:** alteración de permisos en tránsito, manipulación del Grafo de + Autorización, corrupción de configuración o de la traza. +* **Controles existentes:** grafo inmutable y autocontenido (FR-034); guardas de + dependencia; Result Pattern; validación de integridad de documentos por checksum + (FR-052); auditoría append-only. +* **Brechas / mitigación:** firmar el Grafo de Autorización entregado al cliente + para detección de manipulación; integridad de mensajes en el bus. + +### 4.3 Repudiation (repudio) + +* **Amenazas:** un actor niega una acción sensible (cambio de rol, aprobación). +* **Controles existentes:** traza inmutable no repudiable con actor, instante y + resultado (FR-070); `UPDATE/DELETE` de auditoría denegado en cadenas estándar; + control anti-colusión en aprobaciones (FR-050); SoD en IGA (FR-062). +* **Brechas / mitigación:** proteger la llave de emergencia que sí puede mutar + auditoría; considerar sellado criptográfico de la cadena de auditoría. + +### 4.4 Information Disclosure (divulgación) + +* **Amenazas:** fuga de PII, hashes o secretos por logs, proyecciones, el grafo o + lecturas cross-tenant. +* **Controles existentes:** PII redactada en logs (Serilog seguro); `PasswordHash` + nunca en logs/proyecciones/grafo; sin GUIDs crudos en la UI; aislamiento por + inquilino mediante _global query filters_ de EF Core sobre `OrganizationId` + (primario y suficiente; el _failsafe_ RLS a nivel de BD no está activo con + PostgreSQL, [G-020](../../GAPS.md)) (FR-022, NFR-Multitenancy); desinfección de + metadatos de auditoría (FR-072). +* **Brechas / mitigación:** revisión sistemática de los DTO de salida para PII; + cifrado en tránsito (TLS) exigido por política; pruebas automatizadas de + aislamiento cross-tenant. + +### 4.5 Denial of Service (denegación de servicio) + +* **Amenazas:** saturación del gateway, consultas REST de lectura costosas, tormenta + de eventos, agotamiento de conexiones. +* **Controles existentes:** límites de complejidad, timeouts y rate limiting en el + gateway (NFR-Rendimiento); pipeline interno de baja latencia para el grafo; + idempotencia ante reintentos (NFR-Confiabilidad). +* **Brechas / mitigación:** cuotas por inquilino; circuit breakers hacia el IdP; + backpressure en el consumidor de eventos. + +### 4.6 Elevation of Privilege (elevación de privilegios) + +* **Amenazas:** un usuario obtiene permisos que no le corresponden; un admin de + inquilino opera cross-tenant; promoción de rol sin control. +* **Controles existentes:** precedencia de permisos `Deny > Allow` con denegación + implícita (FR-035); cross-tenant restringido a `INTERNAL_ADMIN` y auditado + (FR-022); máquina de estados de promoción con revisión de seguridad y análisis + de riesgo tóxico (FR-060, FR-061); SoD (FR-062); feature flags _fail-closed_ + (FR-041). +* **Brechas / mitigación:** revisión periódica de accesos (certificaciones IGA); + principio de menor privilegio en los roles semilla; pruebas de autorización + negativas en el CI. + +## 5. Gestión de Secretos + +**Estado actual:** + +* Los secretos de IdP se referencian por indirección (`SecretRef`), no se + almacenan inline en la configuración. +* Los valores de configuración sensibles se cifran en reposo + (`IsEncrypted` + servicio de cifrado AES). +* Las contraseñas se guardan como hash BCrypt; nunca se exponen. +* Las credenciales de infraestructura (cadena de conexión, Redis) y los secretos + de CI se inyectan por entorno/secretos, nunca al repositorio (`.env` en + `.gitignore`; el CI usa el secreto `STANDARD_TOKEN`). + +**Objetivo (mitigación pendiente):** + +* Centralizar los secretos y las **llaves de cifrado** en un gestor dedicado + (vault / KMS), con rotación y auditoría de acceso, en vez de depender solo de + variables de entorno. +* Gestión del ciclo de vida de la llave AES que protege la configuración cifrada. +* Trazar la decisión de gestión de secretos a un ADR aceptado de `evolith-core`. + +## 6. Trazabilidad de Controles + +| Categoría | Controles (FR/NFR) | ADRs de referencia | +| :--- | :--- | :--- | +| Spoofing | FR-010, FR-013, FR-014 | ADR-UMS-072 | +| Tampering | FR-034, FR-052 | ADR-UMS-088, ADR-UMS-079 | +| Repudiation | FR-070, FR-050, FR-062 | ADR-UMS-052 | +| Info. Disclosure | FR-004, FR-022, FR-072 | ADR-UMS-062, ADR-UMS-065 | +| Denial of Service | NFR-Rendimiento, NFR-Confiabilidad | ADR-UMS-063, ADR-UMS-080 | +| Elevation | FR-035, FR-060, FR-061 | ADR-UMS-088, ADR-UMS-075, ADR-UMS-077 | + +## 7. Riesgos Residuales y Acciones + +Este modelo consolida los controles existentes y nombra las mitigaciones +pendientes. Las de mayor alcance se gestionan como gaps: la gestión centralizada +de secretos y las pruebas automatizadas de aislamiento/autorización se abordan +junto con la estabilización de pruebas ([G-014](../../GAPS.md)) y la observabilidad +de seguridad ([G-004](../../GAPS.md)). El modelo se revisa cuando cambie un actor, +una frontera de confianza o un activo crítico. + +## Historial de Cambios + +| Versión | Fecha | Autor | Descripción | +| :--- | :--- | :--- | :--- | +| 1.0.1 | 2026-07-14 | BeyondNet S.A.C. | Alineación a API REST-only + PostgreSQL-only (D-007, D-008): DoS sin GraphQL, aislamiento por global query filters con RLS no activo (G-020) | +| 1.0.0 | 2026-07-13 | BeyondNet S.A.C. | Modelo de amenazas STRIDE inicial y política de gestión de secretos. Cierra G-001 | + +--- + +
+ © BeyondNet S.A.C. · RUC 20100412447 · Operador Logístico Aduanero desde 1978 +
diff --git a/docs/architecture/web-frontend/material-design3-uiux-standard.es.md b/docs/architecture/web-frontend/material-design3-uiux-standard.es.md index 1602b26e..b24b8dbe 100644 --- a/docs/architecture/web-frontend/material-design3-uiux-standard.es.md +++ b/docs/architecture/web-frontend/material-design3-uiux-standard.es.md @@ -122,6 +122,8 @@ Todas las pantallas React de frontend deben pasar esta lista de verificacion aut > [!IMPORTANT] > **Estrategia de transporte REST vs GraphQL:** > El frontend usa un modelo de transporte mixto. Algunos contextos delimitados son intencionalmente solo REST, mientras que otros siguen usando GraphQL para lecturas donde esa sigue siendo la implementación activa. -> - Las lecturas de configuración que hoy son solo REST se manejan mediante `httpClient`. +> - Las lecturas de configuración se manejan mediante `httpClient` (REST). Es el arreglo +> definitivo, no uno transitorio: el conmutador REST/GraphQL (`FRONTEND_CONFIG_TRANSPORT` y +> `query-transport.service`) se retiró en la resincronización de 2026-08-09. > - Los contextos delimitados que siguen respaldados por GraphQL permanecen activos en áreas como autorización e identidad. > - Cualquier migración futura de regreso a GraphQL debe evaluarse por contexto delimitado, no como una regla global para todo el frontend. diff --git a/docs/architecture/web-frontend/material-design3-uiux-standard.md b/docs/architecture/web-frontend/material-design3-uiux-standard.md index 30e4f625..d181fceb 100644 --- a/docs/architecture/web-frontend/material-design3-uiux-standard.md +++ b/docs/architecture/web-frontend/material-design3-uiux-standard.md @@ -122,6 +122,6 @@ All frontend React screens must pass this automated and manual checklist prior t > [!IMPORTANT] > **REST vs GraphQL Transport Strategy:** > The frontend uses a mixed transport model. Some bounded contexts are intentionally REST-only, while others still use GraphQL for reads where that remains the active implementation. -> - Configuration reads that are currently REST-only are handled through `httpClient`. +> - Configuration reads go through `httpClient` (REST). This is the settled arrangement, not a transitional one: the REST/GraphQL switch was withdrawn in the 2026-08-09 resync. > - GraphQL-backed bounded contexts remain in place for areas such as authorization and identity. > - Any future migration back to GraphQL should be evaluated per bounded context, not as a blanket frontend-wide rule. diff --git a/docs/architecture/web-frontend/ums-react-applied-reference.es.md b/docs/architecture/web-frontend/ums-react-applied-reference.es.md index 4badb3dd..5b442a10 100644 --- a/docs/architecture/web-frontend/ums-react-applied-reference.es.md +++ b/docs/architecture/web-frontend/ums-react-applied-reference.es.md @@ -46,6 +46,9 @@ Perfil de implementacion observado: | Puente Tailwind de tokens | `src/apps/ums.web-app/tailwind.config.js` expone colores semanticos `m3.*` mediante `hsl(var(--token))`. | Candidato boilerplate | | Frontera HTTP | `src/apps/ums.web-app/src/infrastructure/http/httpClient.ts` centraliza configuracion Axios, headers, CSRF y errores normalizados. | Patron de frontera reutilizable; headers son locales | | Request context | `src/apps/ums.web-app/src/infrastructure/http/request-context.ts` centraliza contexto de usuario e idioma y base URL por entorno. | Patron reutilizable; placeholder de tenant es deuda tecnica local | +| Forma del error en la frontera | `httpClient.ts` exporta `NormalisedApiError` y `asApiError(unknown)`. **No** valida: un error que viene de la red puede ser cualquier cosa, así que da acceso tipado a los sitios donde tiene sentido mirar (`normalised`, `response.data`, `message`) sin dejar que `any` se filtre al catch. | Patrón de frontera reutilizable | +| Estado visual de campo | `src/apps/ums.web-app/src/presentation/shared/components/field-state.ts` concentra la matriz foco/error de los campos: el foco manda en el grosor del borde, el error manda en el color. Lo comparten `M3TextField`, `M3Select`, `M3FieldsetWrapper`, `SearchableSelect` y `TenantSelect`. | Reutilizable; los nombres de token son locales | +| Búsqueda en el grafo de autorización | `src/apps/ums.web-app/src/application/authorization/utils/graph-lookup.ts` recorre el árbol de navegación **recursivo** (`menuAccess[].nodes[]`, ADR-0090) para resolver un nodo o una acción. La ausencia significa «no concedido», no «error». | Reutilizable; el contrato lo gobierna `@ums/sdk-contracts` | | Perfil de pruebas | `src/apps/ums.web-app/package.json` declara Vitest, Testing Library, MSW y Playwright. | Perfil candidato de quality gates | ## 4. Items que deben permanecer locales en UMS diff --git a/docs/architecture/web-frontend/ums-react-applied-reference.md b/docs/architecture/web-frontend/ums-react-applied-reference.md index 27bbdf8f..2f0f5aa6 100644 --- a/docs/architecture/web-frontend/ums-react-applied-reference.md +++ b/docs/architecture/web-frontend/ums-react-applied-reference.md @@ -46,6 +46,9 @@ Observed implementation profile: | Tailwind token bridge | `src/apps/ums.web-app/tailwind.config.js` exposes `m3.*` semantic colors through `hsl(var(--token))`. | Boilerplate candidate | | HTTP boundary | `src/apps/ums.web-app/src/infrastructure/http/httpClient.ts` centralizes Axios setup, request headers, CSRF, and normalized errors. | Reusable boundary pattern; headers are local | | Request context | `src/apps/ums.web-app/src/infrastructure/http/request-context.ts` centralizes user and language request context and environment-based API base URL. | Reusable pattern; tenant placeholder is local technical debt | +| Error shape at the boundary | `httpClient.ts` exports `NormalisedApiError` and `asApiError(unknown)`. It does **not** validate: an error off the network can be anything, so it gives typed access to the places worth looking (`normalised`, `response.data`, `message`) without letting `any` leak into the catch. | Reusable boundary pattern | +| Field visual state | `src/apps/ums.web-app/src/presentation/shared/components/field-state.ts` holds the focus/error matrix for form fields: focus decides border weight, error decides colour. Shared by `M3TextField`, `M3Select`, `M3FieldsetWrapper`, `SearchableSelect` and `TenantSelect`. | Reusable; token names are local | +| Authorization graph lookup | `src/apps/ums.web-app/src/application/authorization/utils/graph-lookup.ts` walks the **recursive** navigation tree (`menuAccess[].nodes[]`, ADR-0090) to resolve a node or an action. Absence means "not granted", not "error". | Reusable; contract is governed by `@ums/sdk-contracts` | | Testing profile | `src/apps/ums.web-app/package.json` declares Vitest, Testing Library, MSW, and Playwright. | Candidate quality gate profile | ## 4. Items that should remain UMS-local diff --git a/docs/domain-es/approvals/access-enforcement-policy.md b/docs/domain-es/approvals/access-enforcement-policy.md index 0e0e8613..172131e4 100644 --- a/docs/domain-es/approvals/access-enforcement-policy.md +++ b/docs/domain-es/approvals/access-enforcement-policy.md @@ -10,25 +10,30 @@ ## 1. Vista General del Agregado ### Propósito + El agregado raíz `AccessEnforcementPolicy` establece reglas generales de restricción de acceso a nivel de inquilino (tenant). Determina qué privilegios de acceso (como un perfil o mapeo de rol) se bloquean, degradan o restringen cuando un usuario entra en estado de incumplimiento (por ejemplo, falta de credenciales válidas obligatorias o documentos críticos vencidos). ### Responsabilidad de Negocio -- Definir bloqueos de acceso específicos asignados a componentes de autorización (perfiles o roles). -- Administrar la segregación multi-inquilino de las reglas de política específicas de cada inquilino. -- Mantener el control del ciclo de vida (activo frente a inactivo) sobre las ejecuciones de políticas. -- Forzar una validación estricta al cambiar los comportamientos de aplicación. + +* Definir bloqueos de acceso específicos asignados a componentes de autorización (perfiles o roles). +* Administrar la segregación multi-inquilino de las reglas de política específicas de cada inquilino. +* Mantener el control del ciclo de vida (activo frente a inactivo) sobre las ejecuciones de políticas. +* Forzar una validación estricta al cambiar los comportamientos de aplicación. ### Raíz del Agregado + `AccessEnforcementPolicy` actúa como una raíz de agregado independiente de `DocumentType` para separar las definiciones de credenciales de las reglas de reacción de seguridad. ### Invariantes y Reglas de Consistencia + 1. **INV-AEP1 (Restricción del Alcance de la Política):** Una política debe apuntar a un `ProfileId` o a un `RoleId` (o a ambos). Está prohibido crear una política sin especificar al menos un objetivo (`DomainErrors.Approvals.PolicyRequiresProfileOrRole`). 2. **INV-AEP2 (Desactivación del Ciclo de Vida):** Una política no se puede desactivar si ya está inactiva (`DomainErrors.Approvals.PolicyAlreadyInactive`). 3. **INV-AEP3 (Integridad del Inquilino):** Las políticas deben asignarse explícitamente a un `TenantId` para garantizar la seguridad de la partición de inquilinos. ### Entidades Relacionadas / Objetos de Valor + | Entidad / VO | Tipo | Descripción | -|---|---|---| +| --- | --- | --- | | `AccessEnforcementPolicyId` | Objeto de Valor | Identificador único del agregado | | `TenantId` | Objeto de Valor | Identificador del inquilino propietario | | `ProfileId` | Objeto de Valor | Perfil de autorización de destino (opcional) | @@ -41,7 +46,8 @@ El agregado raíz `AccessEnforcementPolicy` establece reglas generales de restri ## 2. Modelo de Dominio ### Clases / Entidades / Objetos de Valor -``` + +```text AccessEnforcementPolicy (Aggregate Root) └── Props: AccessEnforcementPolicyProps ├── Id: AccessEnforcementPolicyId @@ -100,7 +106,7 @@ sequenceDiagram participant App as Servicio de Aplicación participant Policy as AccessEnforcementPolicy [Agregado] participant Repo as AccessEnforcementPolicyRepository - participant DB as SQL Server + participant DB as PostgreSQL Admin->>Portal: Configura nueva regla de aplicación Portal->>App: CreateAccessEnforcementPolicyCommand(ProfileId, Action) @@ -135,7 +141,8 @@ erDiagram ``` ### Reglas de Aislamiento de Inquilinos (Tenancy) -- Las políticas se particionan estrictamente por `TenantId`. Los filtros de inquilino deben aplicarse a todas las lecturas y escrituras para garantizar las fronteras operativas. + +* Las políticas se particionan estrictamente por `TenantId`. Los filtros de inquilino deben aplicarse a todas las lecturas y escrituras para garantizar las fronteras operativas. --- @@ -166,16 +173,18 @@ flowchart TD ## 7. Capa de Aplicación ### Comandos y Consultas -- **CreateAccessEnforcementPolicyCommand:** Configura una nueva política de cumplimiento bajo el contexto del inquilino activo. -- **DeactivateAccessEnforcementPolicyCommand:** Deshabilita una política activa, liberando las restricciones de acceso para los actores objetivo. -- **GetAccessEnforcementPolicyByIdQuery:** Recupera detalles de la política. -- **GetAllAccessEnforcementPoliciesQuery:** Enumera las políticas activas bajo el inquilino del administrador. + +* **CreateAccessEnforcementPolicyCommand:** Configura una nueva política de cumplimiento bajo el contexto del inquilino activo. +* **DeactivateAccessEnforcementPolicyCommand:** Deshabilita una política activa, liberando las restricciones de acceso para los actores objetivo. +* **GetAccessEnforcementPolicyByIdQuery:** Recupera detalles de la política. +* **GetAllAccessEnforcementPoliciesQuery:** Enumera las políticas activas bajo el inquilino del administrador. --- ## 8. Infraestructura/Persistencia ### Configuración del Mapeo de EF Core + ```csharp public class AccessEnforcementPolicyConfiguration : IEntityTypeConfigurationcross-tenant"] -->|opera| API + API -->|delega si federado| IDP["IdP externo
OIDC/SAML/WS-Fed"] + API -->|emite| AG["Grafo de
Autorizacion"] + AG -->|decide acceso| CLI["Sistema cliente"] + API -->|publica eventos| BUS["Bus de eventos"] + BUS -->|suscribe| AUD["Auditoria
inmutable"] + APR["Solicitante"] -->|solicita| API + API -->|bandeja| APB["Aprobador"] + + style U fill:#e3f2fd,stroke:#1565c0,color:#000 + style AG fill:#fff3e0,stroke:#e65100,color:#000 + style AUD fill:#e8f5e9,stroke:#2e7d32,color:#000 +``` + +## 3. Contexto y Requisitos Técnicos + +### Bounded Context + +UMS se organiza en contextos acotados con integración **solo por identificadores +centrales** (nunca referencias directas entre contextos): + +* **Identity:** inquilinos, ramas, cuentas de usuario, credenciales, + MFA, proveedores de identidad y onboarding. +* **Authorization:** system suites, módulos, acciones, recursos de dominio, roles, + plantillas de permisos, perfiles y grafo de autorización. +* **Configuration:** parámetros jerárquicos, feature flags y configuración de IdP. +* **Approvals:** flujos de aprobación, tipos de documento, documentos de usuario, + reglas de notificación y enforcement de acceso. +* **IGA:** promociones de rol, análisis de impacto/riesgo y madurez de rol. +* **Audit:** traza inmutable transversal (suscriptor de todos los contextos). + +### Dependencias + +* **Runtime:** .NET 10 LTS (backend) y Node.js 24 LTS + React 18/Vite (frontend). +* **Persistencia:** PostgreSQL vía EF Core + Npgsql, con esquema por módulo. +* **Mensajería:** bus de eventos con _Transactional Outbox_ (consistencia eventual + sin 2PC). +* **Librerías transversales:** shells corporativos `BeyondNetCode.Shell.*` (DDD, AOP, + Factory, Bootstrapper), ver [DECISIONS.md](../../DECISIONS.md). +* **Integración externa:** proveedores de identidad (OIDC/SAML/WS-Fed) y la + proyección de inquilinos del sistema MMS (contrato de mensajería, ver + [G-011](../../GAPS.md)). + +### Restricciones + +* **Idioma único español** en documentación (SD-08). +* **Dominio 100 % POCO** sin dependencias NuGet en la capa Domain. +* **Result Pattern** (sin excepciones para control de flujo) y _Broken Rules + Registry_ para invariantes. +* **Guardas de dependencia:** no se desactiva, archiva ni elimina un agregado con + dependencias activas. +* **Fechas en UTC**; zona horaria e idioma se resuelven en el cliente. +* **Decisiones técnicas trazables** a ADRs aceptados (S-06); el retrazado del + corpus importado (ADR-0050…0083) a `evolith-core` es deuda ([G-012](../../GAPS.md)). + +## 4. Requisitos Funcionales + +Los requisitos se agrupan por capacidad; cada uno tiene un identificador estable +`FR-NNN` y anota su **estado de implementación** ([Implementado]/[Parcial]/ +[Planificado]) **verificado contra el código** (símbolos entre paréntesis). El +detalle de invariantes vive en [docs/02-diseno/dominio/](../02-diseno/dominio/), pero prevalece el +código donde discrepen. + +### 4.1 Identidad y cuentas + +* **FR-001** [Implementado] — El sistema debe registrar cuentas de usuario + asociadas a un inquilino (y opcionalmente a una rama), con email único por + inquilino. _(`UserAccount.Create`.)_ +* **FR-002** [Implementado] — El sistema debe gestionar el ciclo de vida de la + cuenta e impedir autenticar cuentas no activas. Estados reales + (`UserStatus`): `Pending`, `Active`, `Blocked`, `Deleted`, **`Denied`**. + Transiciones: `Pending → Active` (`Activate`), **`Pending → Denied`** (`Deny`, + el admin de inquilino rechaza el alta — terminal, omitido en versiones previas + de este PRD), `→ Blocked` (`Block`, desde cualquier estado no bloqueado), + `Blocked → Active` (`Restore`) y `→ Deleted` (`Delete`, borrado lógico terminal, + bloqueado si hay perfiles activos). El **bloqueo temporal por intentos fallidos** + (FR-017) es un mecanismo aparte del `Blocked` administrativo. +* **FR-003** [Implementado] — El sistema debe permitir el alta pública (signup) + creando cuentas en `Pending` y activarlas al aprobar; una cuenta `Active` sin + perfil se representa como "lobby de onboarding". _(`SignupUserCommand`, + `TenantSignupRequest`.)_ +* **FR-004** [Implementado] — El sistema debe borrar lógicamente cuentas + anonimizando PII y anulando el hash de credenciales (GDPR). _(`UserAccount.Delete` + → `UserStatus.Deleted` + `SoftDeleteAsync` anonimiza en persistencia.)_ + +### 4.2 Autenticación + +* **FR-010** [Implementado] — El sistema debe almacenar la contraseña como hash + BCrypt generado en la API (el cliente nunca envía el hash), con una sola + credencial activa por usuario e historial inmutable de las anteriores. + _(`PasswordCredential`; `UserAccount.AddPassword` desactiva las previas.)_ +* **FR-011** [Parcial] — El sistema debe registrar proveedores de identidad + externos por inquilino, con estrategia inmutable, y delegar la autenticación + federada al adaptador correspondiente. **Estado real:** el contrato + `IIdpAuthAdapter`, la resolución por estrategia y el **adaptador OIDC real** + (Authorization Code + PKCE, validación estricta del `id_token` vía JWKS) están + **implementados y cableados en producción** (`IdpAuthAdapterFactorySetup`) para + la familia OIDC — Keycloak, GenericOidc, Azure AD, Okta, Zitadel, Auth0, Google + ([ADR-UMS-094](../../reference/architecture/adrs/UMS-094-idp-federado-adaptador-real-y-arnes-keycloak.es.md), + slice 1; [G-049](../../GAPS.md)). **Residual:** **SAML 2.0** y **LDAP** son + estrategias registradas **sin adaptador** (retornan `AUTH_012`); **WS-Federation + no existe** en el código. En entornos no-producción se usa `StubIdpAuthAdapter` + (credenciales `MOCK-*`). +* **FR-012** [Implementado] — El sistema debe impedir que un usuario federado + tenga una contraseña local activa, desactivándola al vincular la identidad + externa. _(`UserAccount.AddPassword` rechaza si `IdentityReference` está fijado.)_ +* **FR-013** [Implementado] — El sistema debe resolver dinámicamente, en tiempo de + login y desde configuración (`AUTH_USE_EXTERNAL_IDP`), si el inquilino usa + autenticación local o federada, forzando siempre local para el portal de gestión + interna. _(La resolución **por motor de reglas** con prioridad/fallback por suite + es FR-042, hoy [Implementado] — ver §4.5.)_ +* **FR-014** [Implementado] — El sistema debe enrolar múltiples métodos MFA por + usuario (TOTP, WebAuthn, SMS-OTP, Email-OTP) con ciclo `NotEnrolled → Enrolled → + Verified` y respetar la exigencia de MFA del inquilino (`MfaRequiredForAdmin`). + _(`MfaMethod`: `Totp`/`WebAuthn`/`SmsOtp`/`EmailOtp`; `UserAccount.EnrollMfa` / + `VerifyMfaChallenge`.)_ +* **FR-015** [Parcial] — El sistema debe, **cuando el inquilino lo active por + configuración** + (`AUTH_REFRESH_TOKEN_ENABLED`, jerarquía Global>Suite>Tenant>Module; fail-closed: + apagado ⇒ solo expiración), emitir un **refresh token** parametrizable por tenant + (vida, rotación en cada uso, detección de reuso, tope de renovaciones) y, al vencer + el grafo (`validUntil`), **regenerar el Grafo de Autorización COMPLETO** desde el + estado actual (permisos, roles, plantillas, overrides, feature flags, config + efectiva) al presentar un refresh válido. Ante reuso de un refresh consumido debe + invalidar toda la familia y forzar re-login. El refresh nunca aparece en logs, + proyecciones ni en el grafo; se guarda hasheado/cifrado. Revisa el límite «sin + refresh» de FR-034 y de **ADR-UMS-088**; cumple + **[ADR-UMS-091](../../reference/architecture/adrs/UMS-091-refresh-token-configurable-revocacion.es.md)** + (Aceptado, [G-034](../../GAPS.md)). Verificable con la historia + [fs-36](../02-diseno/historias-funcionales/fs-36-refresh-token-configurable.md). + **Estado real ([D-019](../../DECISIONS.md)):** coexisten **dos mecanismos**. (a) El + **refresh de sesión por cookie deslizante** (`POST /auth/refresh`, + `RefreshSessionCommand`) **está implementado y en uso**: regenera el Grafo de + Autorización completo en espejo del login y emite un graph JWT con los permisos + vigentes, con corte en caliente si el inquilino/usuario deja de estar activo. (b) + El **refresh token opaco** (`POST /auth/refresh-token`, grant de ADR-UMS-091, + regeneración completa + rotación + detección de reuso) **está implementado pero + apagado por defecto** (`AuthRefreshTokenEnabled=false`, `RefreshTokenPolicyProvider` + fail-closed): su **activación es opt-in por inquilino** — de ahí el [Parcial]. +* **FR-016** [Implementado] — El sistema debe permitir **revocar** refresh tokens + (logout real / invalidación de sesión, por usuario, por cuenta bloqueada o + suspendida y por cambio crítico de permisos): un refresh revocado no puede + regenerar grafo y la siguiente renovación falla exigiendo re-autenticación + completa. **Alcance explícito:** la revocación actúa sobre la capacidad de + **renovar**; un grafo ya emitido sigue válido hasta su `validUntil` salvo que el + cliente valide sesión por operación. Todo evento de revocación se audita + (append-only, acotado por inquilino). _(`/auth/logout` → + `IRefreshTokenStore.RevokeAllForUserAsync`.)_ Verificable con + [fs-37](../02-diseno/historias-funcionales/fs-37-revocacion-refresh-token.md). +* **FR-017** [Implementado] — El sistema debe **bloquear temporalmente** una cuenta + tras alcanzar el máximo de intentos de autenticación fallidos, de forma + **auto-expirable** (sin intervención administrativa) y **distinta** del bloqueo + permanente (`Blocked`). El dominio (`UserAccount.RecordAuthenticationAttempt` / + `IsLockedOut`) lleva `FailedLoginAttempts` y `LockedUntil`; los parámetros + (`MAX_LOGIN_ATTEMPTS`, `ACCOUNT_LOCKOUT_DURATION_MINUTES`) salen de la config + efectiva. Enforcement: en `/auth/login` una cuenta bloqueada devuelve + **HTTP 423 (`AUTH_017`)** con mensaje accionable; en el **endpoint de cliente** + (público y anónimo) colapsa a **401 genérico** e indistinguible de credenciales + inválidas (anti-enumeración, [G-053](../../GAPS.md)). Cumple + **[ADR-UMS-095](../../reference/architecture/adrs/UMS-095-bloqueo-cuenta-intentos-fallidos.es.md)**. + +### 4.3 Multi-tenancy + +* **FR-020** [Implementado] — El sistema debe registrar inquilinos con `Code` + globalmente único, gestionar su ciclo de vida y bloquear la autenticación de los + usuarios de un inquilino suspendido. Estados reales (`TenantStatus`): `Active`, + `Suspended`, `Archived`. Transiciones: `Active ↔ Suspended` (`Suspend` / + `Activate`) y `Archived` como estado **terminal** (no se puede suspender ni + reactivar). _(El PRD previo decía «Inactive»; el estado real es `Archived`.)_ +* **FR-021** [Implementado] — El sistema debe gestionar ramas por inquilino con + código único y geocercado válido. _(`Tenant.AddBranch` con `geofencingMetadata`.)_ +* **FR-022** [Implementado] — El sistema debe aislar todos los datos por inquilino + mediante _global query filters_ de EF Core sobre `OrganizationId` en la capa de + aplicación (mecanismo primario y suficiente); el _failsafe_ RLS a nivel de base de + datos no está activo con PostgreSQL ([G-020](../../GAPS.md)). Toda operación + cross-tenant se audita y se permite solo a `INTERNAL_ADMIN`. + +### 4.4 Autorización + +* **FR-030** [Parcial] — El sistema debe modelar la topología funcional por suite + (`SystemSuite → Module → MenuNode`, árbol recursivo de profundidad variable, ADR-0090) y exponer acciones granulares + (`Action`: READ, WRITE, EXPORT…). **Residual:** el rediseño a un **árbol de nodos + recursivo** (`MenuNode` auto-referente, profundidad variable, N:M + funcionalidad↔opción) está en curso ([D-009](../../DECISIONS.md), cumple ADR-0090; + [G-029](../../GAPS.md)). +* **FR-031** [Implementado] — El sistema debe mantener un catálogo de roles por + inquilino y suite, con jerarquía opcional acíclica. +* **FR-032** [Implementado] — El sistema debe definir plantillas de permisos + reutilizables (globales o por inquilino) que mapean acciones a objetivos, + publicables solo con al menos un ítem. +* **FR-033** [Implementado] — El sistema debe materializar perfiles (usuario + rol + * rama) que derivan permisos efectivos desde plantillas publicadas, con overrides + controlados (allow/deny/neutral) sin mutar la plantilla fuente. _(`Profile`, + `PermissionEffect` Allow/Deny/Neutral; modelo de perfiles fijado en + [D-011](../../DECISIONS.md).)_ +* **FR-034** [Implementado] — El sistema debe construir, tras autenticar, un + **Grafo de Autorización** inmutable y autocontenido (contexto, acciones, accesos + de menú, permisos de dominio, feature flags, configuración efectiva y scopes) con + vigencia `validUntil = generatedAt + sessionTimeoutMinutes`. Cada instancia del + grafo es inmutable; **FR-015** revisa el modelo de vigencia para permitir + **regenerar** un grafo nuevo por refresh (no extender el previo) en vez de exigir + re-autenticación completa al expirar. +* **FR-035** [Parcial] — El sistema debe resolver la autorización por precedencia + (`Deny > Allow`, `Override > Template`, ausencia = no concedido) y traducir los + permisos a scopes OAuth2 para validación rápida en el cliente. **Residual:** la + resolución multi-fuente (perfil + plantilla + regla) con _deny-wins_ y ciclos del + grafo efectivo está solo **parcialmente probada** ([G-085](../../GAPS.md)). + +### 4.5 Configuración + +* **FR-040** [Implementado] — El sistema debe persistir configuración jerárquica + (`code/value/description`) con alcance derivado, ciclo `Draft → Published → + Archived`, versionado y banderas de herencia y cifrado. Alcances reales + (`ConfigurationScope`): `Global`, `Suite`, `Tenant`, `Module` y también `User`; + la cascada de resolución usa `Global > Suite > Tenant > Module`. +* **FR-041** [Implementado] — El sistema debe gestionar feature flags acotados a + una suite (nunca globales), con criterios dinámicos evaluados con lógica `OR` + intra-tipo y `AND` entre tipos, postura _fail-closed_ y registro de cada + evaluación. +* **FR-042** [Implementado] — El sistema debe registrar reglas de resolución de IdP por + inquilino y suite, con prioridad y fallback encadenado. **Estado real (2026-07-21, + épica [G-096]/[ADR-UMS-097](../../reference/architecture/adrs/UMS-097-resolucion-idp-prioridad-suite-fallback.es.md)):** + el login consume el motor de reglas (`IdpConfigurationSelector`) por **prioridad, + suite y dominio**, unificado con el endpoint OIDC; el **fallback encadenado** recorre + `FallbackToId` **solo ante indisponibilidad de infra**, nunca ante fallo de + credenciales (fail-closed, anti credential-spraying), con detección de ciclos, tope y + auditoría por intento (cadena agotada → 503). Probado a fondo en unit (selector, + clasificador, cadena). **Residuales (gaps propios):** la **fuente de la suite + pre-autenticación** aún no existe → el scoping por suite está cableado pero no + alimentado ([G-110](../../GAPS.md)); el **arnés Keycloak real** (validar el adapter OIDC + contra un IdP real, deuda de ADR-UMS-094) está diferido ([G-109](../../GAPS.md)); y la + clasificación 4xx/5xx del token endpoint ([G-108](../../GAPS.md)). + +### 4.6 Aprobaciones y cumplimiento + +> **Nota de cobertura (§4.6):** el backend (dominio + handlers) de Aprobaciones y +> cumplimiento está implementado; **carece de esquemas/pantallas en el frontend** +> (no hay contexto `approvals` en `ums.web-app`), de **pruebas de contrato** +> ([G-082](../../GAPS.md)) y de **E2E de UI** para los flujos irreversibles +> ([G-084](../../GAPS.md)). El estado [Implementado] es a nivel de capacidad de dominio. + +* **FR-050** [Implementado] — El sistema debe permitir definir flujos de aprobación + por inquilino con su checklist de documentos obligatorios, e instanciar + solicitudes (`Pending → Approved/Rejected`, irreversibles) que no puede aprobar el + propio solicitante. _(`ApprovalWorkflow`, `ApprovalRequest`.)_ +* **FR-051** [Implementado] — El sistema debe clasificar documentos por criticidad + y exigir, para los críticos, exactamente una política de enforcement activa + (bloqueo/degradación ante vencimiento) con período de gracia. _(`DocumentType`, + `DocumentCriticity`, `AccessEnforcementPolicy`.)_ +* **FR-052** [Implementado] — El sistema debe gestionar la carga y verificación de + documentos de usuario (`PendingReview → Valid/Rejected → Expired → ReUpload`) con + integridad por checksum, y notificar por umbrales configurables + (Email/SMS/portal/push). _(`UserDocument`, `DocumentStatus`, `NotificationRule`.)_ +* **FR-053** [Implementado] — El sistema debe aplicar políticas de enforcement que + bloqueen, degraden o restrinjan el acceso ante incumplimiento (documento crítico + vencido). _(`AccessEnforcementPolicy`, `AccessEnforcementAction`.)_ + +### 4.7 Gobernanza de accesos (IGA) + +> **Nota de cobertura (§4.7):** IGA está implementado en el backend (dominio + +> handlers + un E2E de integración del efecto); **carece de frontend y de pruebas +> de contrato** ([G-087](../../GAPS.md)). El estado [Implementado] es a nivel de +> capacidad de dominio/aplicación. + +* **FR-060** [Implementado] — El sistema debe gestionar promociones de rol mediante + una máquina de estados auditada y **aplicar el cambio de rol** al ejecutarse. + Máquina real (`RolePromotionStatus`): `Draft → PendingEligibilityCheck → + PendingManagerApproval → (PendingSecurityReview si RiskScore ≥ umbral) → Approved + → Executed → Verified`, con cortes terminales `Rejected` y `Cancelled`. La + **elegibilidad es fail-closed** (`PendingEligibilityCheck`: no elegible ⇒ + `Rejected`, nunca avanza — omitido en versiones previas de este PRD). El **efecto** + de `Execute` (reasignar `Profile.RoleId` del objetivo) — que antes **no existía** + ([G-093](../../GAPS.md)) — hoy **se aplica con entrega garantizada por Transactional + Outbox**: `ExecuteRolePromotionCommandHandler` publica el evento de integración + antes de `SaveEntitiesAsync` y `RolePromotionRoleAssignmentConsumer` lo + materializa con reintentos/dead-letter, nunca en descarte silencioso + ([ADR-UMS-096](../../reference/architecture/adrs/UMS-096-iga-sod-ejecutor-y-efecto-promocion.es.md), + [D-020](../../DECISIONS.md), [G-094](../../GAPS.md)). +* **FR-061** [Implementado] — El sistema debe calcular un análisis de impacto/riesgo + tóxico (`RiskScore` 0–100, permisos nuevos/removidos, conflictos) inmutable por + solicitud. _(`RiskScore` se congela en `Submit` — INV-RPR2.)_ +* **FR-062** [Implementado] — El sistema debe evaluar la elegibilidad de promoción + (sin incidencias de cumplimiento, desempeño ≥ 3.0, tiempo mínimo en el nivel — + 6/12/18/24 meses por salto, nivel `Principal` no promocionable) y **garantizar + segregación de funciones (SoD)**. SoD real endurecida (INV-RPR3, + [ADR-UMS-096](../../reference/architecture/adrs/UMS-096-iga-sod-ejecutor-y-efecto-promocion.es.md)): + `solicitante ≠ objetivo`; `aprobador ≠ objetivo ≠ solicitante`; `revisor ≠ objetivo + ≠ aprobador`; **`ejecutor ≠ objetivo ≠ aprobador ≠ revisor`**; `verificador ≠ + ejecutor ≠ objetivo` (más estricta que el «aprobador ≠ objetivo ≠ auditor» de + versiones previas; [G-091](../../GAPS.md)). _(`RoleMaturityStatus.EvaluateEligibility`, + `RolePromotionRequest` invariantes.)_ + +### 4.8 Auditoría + +* **FR-070** [Implementado] — El sistema debe registrar una traza cronológica, + inmutable (append-only) y no repudiable de todo evento crítico, capturando actor, + instante, cambio, resultado, entidad e inquilino afectados. _(`AuditRecord` + append-only; endurecimiento de no-repudio/aislamiento en [G-040](../../GAPS.md).)_ +* **FR-071** [Implementado] — El sistema debe recibir los eventos de auditoría vía + Transactional Outbox desde todos los contextos, permitir su consulta acotada por + inquilino e impedir la lectura cruzada. _(`AuditTrailOutboxSink` → + `AuditTrailPersistenceConsumer`, entrega post-commit por el outbox EF; + [G-040](../../GAPS.md)/[G-066](../../GAPS.md).)_ +* **FR-072** [Implementado] — El sistema debe desinfectar los metadatos serializados + eliminando datos sensibles (hashes, PIN, llaves) antes de persistir. + _(`RecordAuditCommandValidator`.)_ + +## 5. Requisitos No Funcionales + +* **NFR-Seguridad:** contraseñas y secretos nunca en logs, proyecciones ni grafo; + columnas sensibles cifradas en reposo; PII redactada en logs; sin GUIDs crudos en + la UI; UPDATE/DELETE de auditoría denegado en cadenas estándar (no repudio). + El modelo de amenazas formal y la gestión de secretos son [G-001](../../GAPS.md). +* **NFR-Multitenancy:** aislamiento en capa de aplicación por _global query filters_ + de EF Core sobre `OrganizationId` (primario y suficiente); el _failsafe_ RLS a + nivel de base de datos no está activo con PostgreSQL ([G-020](../../GAPS.md)); toda + lectura cross-tenant bloqueada y auditada. +* **NFR-Rendimiento:** CQRS en la capa de aplicación con API REST-only (lectura por + `GET`, escritura por `POST/PUT/PATCH/DELETE`); emisión y validación del grafo por + pipeline interno de baja latencia; el gateway aplica límites de complejidad, + timeouts y rate limiting. +* **NFR-Confiabilidad:** consistencia eventual por Outbox sin 2PC; idempotencia ante + reintentos mediante middleware de `Idempotency-Key`. +* **NFR-Observabilidad:** trazas y métricas con OpenTelemetry; propagación de + contexto de correlación; errores accionables con id de diagnóstico. +* **NFR-Cumplimiento:** bitácora inmutable de transiciones críticas; fechas en UTC. +* **NFR-Mensajería:** eventos de integración por bus como puerto inyectable; + auditoría como suscriptor downstream. + +**Contra-métrica:** ninguna optimización de rendimiento puede introducir una ruta +que lea u opere datos fuera del inquilino del solicitante. + +## 6. Trazabilidad y Decisiones + +Las decisiones técnicas de UMS residen en su corpus de ADRs importado +([reference/architecture/](../../reference/architecture/index.md), ADR-0050 a +ADR-0083). Ejemplos con impacto directo en este PRD: motor del Grafo de +Autorización (ADR-UMS-088), resolución dinámica del método de autenticación +(ADR-UMS-072), alcance de feature flags (ADR-UMS-068), audit trail inmutable (ADR-UMS-052), +guardas de dependencia (ADR-UMS-079) y persistencia PostgreSQL (ADR-UMS-089). + +Capacidades reconciliadas en esta versión y su ADR/decisión de respaldo: +**bloqueo temporal de cuenta** ([ADR-UMS-095](../../reference/architecture/adrs/UMS-095-bloqueo-cuenta-intentos-fallidos.es.md), +FR-017); **refresh token configurable + revocación** ([ADR-UMS-091](../../reference/architecture/adrs/UMS-091-refresh-token-configurable-revocacion.es.md), +[D-012](../../DECISIONS.md)/[D-019](../../DECISIONS.md), FR-015/016); **autoridad de +escritura del operador** ([ADR-UMS-092](../../reference/architecture/adrs/UMS-092-autoridad-escritura-operador-inquilinos-gestionados.es.md), +[D-013](../../DECISIONS.md)); **máquina de estados IGA** ([ADR-UMS-093](../../reference/architecture/adrs/UMS-093-iga-maquina-estados-promocion-rol.es.md), +[D-014](../../DECISIONS.md), FR-060/061/062); **adaptador OIDC real** +([ADR-UMS-094](../../reference/architecture/adrs/UMS-094-idp-federado-adaptador-real-y-arnes-keycloak.es.md), +[D-015](../../DECISIONS.md), FR-011); **SoD endurecida + efecto de promoción** +([ADR-UMS-096](../../reference/architecture/adrs/UMS-096-iga-sod-ejecutor-y-efecto-promocion.es.md), +[D-020](../../DECISIONS.md), FR-060/062). + +Estos ADRs son de origen importado; su **retrazado a ADRs aceptados de +`evolith-core`** (S-06) está registrado como [G-012](../../GAPS.md). Los criterios de +aceptación verificables por FR se elaborarán en las historias (épicas e +historias), registrado como [G-009](../../GAPS.md). + +Dos decisiones locales fijan el estado actual del transporte y la persistencia: la +API es **REST-only** ([D-007](../../DECISIONS.md); la lectura por `GET` y la escritura +por `POST/PUT/PATCH/DELETE`, con el CQRS confinado a la capa de aplicación) y la +persistencia es **PostgreSQL únicamente** ([D-008](../../DECISIONS.md), que hace +cumplir ADR-UMS-089; `InMemory` solo en tests). + +## Historial de Cambios + +| Versión | Fecha | Autor | Descripción | +| :--- | :--- | :--- | :--- | +| 0.2.0 | 2026-07-21 | BeyondNet S.A.C. | **Reconciliación producto-completo contra el código fuente** (fuente de verdad, SD-05), cerrando la parte PRD de [G-075]. Reencuadre de MVP/piloto a **producto completo**: se conservan todas las capacidades (FR-001…FR-072) y cada FR anota su estado real ([Implementado]/[Parcial]/[Planificado]) con evidencia en código. Nuevo/corregido: **FR-017** bloqueo temporal por intentos fallidos (ADR-UMS-095, AUTH_017→423 en `/login`, 401 genérico en cliente); **FR-011** [Parcial] — adaptador OIDC real cableado en producción (ADR-UMS-094/G-049), SAML2/LDAP como estrategias sin adaptador, **WS-Federation retirada** (sin respaldo en código); **FR-015/016** dos mecanismos de refresh (cookie deslizante `/refresh` que regenera el grafo, D-019; token opaco `/refresh-token` opt-in, apagado por defecto, ADR-UMS-091); **FR-002** estado `Denied` desde `Pending`; **FR-020** ciclo de inquilino `Active↔Suspended`/`Archived` (antes «Inactive»); **FR-060** máquina IGA con `PendingEligibilityCheck` (fail-closed) y `Cancelled`; **FR-062** SoD endurecida (`ejecutor ≠ objetivo ≠ aprobador ≠ revisor`) y efecto de promoción por Transactional Outbox (ADR-UMS-096/D-020, G-091/G-093/G-094); **FR-030/035/042** marcados [Parcial]. El documento ahora **se reconcilia contra el código**, no deriva de la doc de dominio | +| 0.1.2 | 2026-07-21 | BeyondNet S.A.C. | Reconciliación con la fuente ([G-075]): las capacidades MVP (US-001…US-012: identidad/tenant, autenticación local, topología, plantillas, perfiles, configuración) están **verificadas y gateadas en CI** — E2E de caminos MVP + subconjunto de integración (ver [TE-09](../../reference/architecture/blueprints/technical-enablers/te-09-definition-of-release-piloto.md), Definition of Release del piloto). Ajuste FR-013 confirmado en vivo: login local del portal de gestión (BEYONDNET) operativo | +| 0.1.1 | 2026-07-14 | BeyondNet S.A.C. | Alineación a API REST-only + PostgreSQL-only (D-007, D-008): NFR-Rendimiento sin GraphQL, FR-022/NFR-Multitenancy por global query filters con RLS no activo (G-020) | +| 0.1.0 | 2026-07-13 | BeyondNet S.A.C. | Borrador inicial del PRD brownfield, derivado de la documentación de dominio importada. Cierra la ausencia registrada en G-006 | + +--- + +
+ © BeyondNet S.A.C. · RUC 20100412447 · Operador Logístico Aduanero desde 1978 +
diff --git a/docs/governance/project-es/api-aggregate-implementation-tracker.md b/docs/governance/project-es/api-aggregate-implementation-tracker.md index b50e1d2c..a8803328 100644 --- a/docs/governance/project-es/api-aggregate-implementation-tracker.md +++ b/docs/governance/project-es/api-aggregate-implementation-tracker.md @@ -90,7 +90,7 @@ Este documento registra el estado actual de implementacion de la API UMS por agr - Capacidades API faltantes: - ciclo de vida de modules - ciclo de vida de menus - - ciclo de vida de submenus + - ciclo de vida de nodos (`MenuNode` recursivo, ADR-0090) - ciclo de vida de options - ciclo de vida de actions - ciclo de vida de app settings diff --git a/docs/governance/project-es/functional-story-gap-tracker.md b/docs/governance/project-es/functional-story-gap-tracker.md index 9fd60982..f9dadb8a 100644 --- a/docs/governance/project-es/functional-story-gap-tracker.md +++ b/docs/governance/project-es/functional-story-gap-tracker.md @@ -20,7 +20,7 @@ Este documento mantiene una vista dinamica de lo que ya esta implementado, lo qu | Estado | Cantidad | IDs de historia | |---|---:|---| -| Implementado / utilizable | 25 | [FS-01](../requirements-es/functional-stories/fs-01-user-authentication.md), [FS-02](../requirements-es/functional-stories/fs-02-create-authorization-template.md), [FS-03](../requirements-es/functional-stories/fs-03-register-organization.md), [FS-04](../requirements-es/functional-stories/fs-04-register-system-topology.md), [FS-05](../requirements-es/functional-stories/fs-05-create-profile-manual-template.md), [FS-06](../requirements-es/functional-stories/fs-06-auto-assign-template.md), [FS-07](../requirements-es/functional-stories/fs-07-visual-graph-resolver.md), [FS-08](../requirements-es/functional-stories/fs-08-hosted-login-redirection.md), [FS-09](../requirements-es/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md), [FS-10](../requirements-es/functional-stories/fs-10-external-b2b-access-request-approval.md), [FS-11](../requirements-es/functional-stories/fs-11-user-document-upload.md), [FS-13](../requirements-es/functional-stories/fs-13-hierarchical-config.md), [FS-14](../requirements-es/functional-stories/fs-14-delegated-management.md), [FS-15](../requirements-es/functional-stories/fs-15-notification-rules.md), [FS-16](../requirements-es/functional-stories/fs-16-access-enforcement-policy.md), [FS-17](../requirements-es/functional-stories/fs-17-maintain-system-roles.md), [FS-18](../requirements-es/functional-stories/fs-18-manage-local-user-password.md), [FS-19](../requirements-es/functional-stories/fs-19-admin-password-reset-validity-management.md), [FS-20](../requirements-es/functional-stories/fs-20-system-parameter-management.md), [FS-21](../requirements-es/functional-stories/fs-21-tenant-signup-request-approval.md), [FS-22](../requirements-es/functional-stories/fs-22-user-signup-request-approval.md), [FS-24](../requirements-es/functional-stories/fs-24-profile-request-approval.es.md), [FS-25](../requirements/functional-stories/fs-25-ddd-domain-resource-hierarchy.es.md), [FS-26](../requirements/functional-stories/fs-26-auth-graph-preview-from-profile.es.md), [FS-27](../requirements/functional-stories/fs-27-state-change-consistency-broken-rules.es.md)] | +| Implementado / utilizable | 25 | [FS-01](../requirements-es/functional-stories/fs-01-user-authentication.md), [FS-02](../requirements-es/functional-stories/fs-02-create-authorization-template.md), [FS-03](../requirements-es/functional-stories/fs-03-register-organization.md), [FS-04](../requirements-es/functional-stories/fs-04-register-system-topology.md), [FS-05](../requirements-es/functional-stories/fs-05-create-profile-manual-template.md), [FS-06](../requirements-es/functional-stories/fs-06-auto-assign-template.md), [FS-07](../requirements-es/functional-stories/fs-07-visual-graph-resolver.md), [FS-08](../requirements-es/functional-stories/fs-08-hosted-login-redirection.md), [FS-09](../requirements-es/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md), [FS-10](../requirements-es/functional-stories/fs-10-external-b2b-access-request-approval.md), [FS-11](../requirements-es/functional-stories/fs-11-user-document-upload.md), [FS-13](../requirements-es/functional-stories/fs-13-hierarchical-config.md), [FS-14](../requirements-es/functional-stories/fs-14-delegated-management.md), [FS-15](../requirements-es/functional-stories/fs-15-notification-rules.md), [FS-16](../requirements-es/functional-stories/fs-16-access-enforcement-policy.md), [FS-17](../requirements-es/functional-stories/fs-17-maintain-system-roles.md), [FS-18](../requirements-es/functional-stories/fs-18-manage-local-user-password.md), [FS-19](../requirements-es/functional-stories/fs-19-admin-password-reset-validity-management.md), [FS-20](../requirements-es/functional-stories/fs-20-system-parameter-management.md), [FS-21](../requirements-es/functional-stories/fs-21-tenant-signup-request-approval.md), [FS-22](../requirements-es/functional-stories/fs-22-user-signup-request-approval.md), [FS-24](../requirements-es/functional-stories/fs-24-profile-request-approval.es.md), [FS-38](../requirements/functional-stories/fs-38-ddd-domain-resource-hierarchy.es.md), [FS-39](../requirements/functional-stories/fs-39-auth-graph-preview-from-profile.es.md), [FS-40](../requirements/functional-stories/fs-40-state-change-consistency-broken-rules.es.md)] | | Parcial | 0 | — | | Diferido | 9 | [FS-12](../requirements-es/functional-stories/fs-12-role-promotion-process.md), [FS-28](../requirements-es/functional-stories/fs-28-access-review-campaigns.md), [FS-29](../requirements-es/functional-stories/fs-29-entitlement-packages.md), [FS-30](../requirements-es/functional-stories/fs-30-provisioning-deprovisioning-connectors.md), [FS-31](../requirements-es/functional-stories/fs-31-privileged-access-time-bound-elevation.md), [FS-32](../requirements-es/functional-stories/fs-32-operational-reliability-guardrails.md), [FS-33](../requirements-es/functional-stories/fs-33-authorization-graph-explorer.md), [FS-34](../requirements-es/functional-stories/fs-34-business-semantic-access-packages.md), [FS-35](../requirements-es/functional-stories/fs-35-continuous-access-health.md) | diff --git a/docs/governance/project/api-aggregate-implementation-tracker.md b/docs/governance/project/api-aggregate-implementation-tracker.md index 3ccf9b3d..5cd87381 100644 --- a/docs/governance/project/api-aggregate-implementation-tracker.md +++ b/docs/governance/project/api-aggregate-implementation-tracker.md @@ -90,7 +90,7 @@ This document captures the current implementation status of the UMS API by aggre - Missing API capabilities: - module lifecycle - menu lifecycle - - submenu lifecycle + - node lifecycle (recursive `MenuNode`, ADR-0090) - option lifecycle - action lifecycle - app setting lifecycle diff --git a/docs/governance/project/functional-story-gap-tracker.md b/docs/governance/project/functional-story-gap-tracker.md index 944b7e64..d8979d99 100644 --- a/docs/governance/project/functional-story-gap-tracker.md +++ b/docs/governance/project/functional-story-gap-tracker.md @@ -20,7 +20,7 @@ This document keeps a dynamic view of what is already implemented, what is parti | Status | Count | Story IDs | |---|---:|---| -| Implemented / usable | 25 | [FS-01](../requirements/functional-stories/fs-01-user-authentication.md), [FS-02](../requirements/functional-stories/fs-02-create-authorization-template.md), [FS-03](../requirements/functional-stories/fs-03-register-organization.md), [FS-04](../requirements/functional-stories/fs-04-register-system-topology.md), [FS-05](../requirements/functional-stories/fs-05-create-profile-manual-template.md), [FS-06](../requirements/functional-stories/fs-06-auto-assign-template.md), [FS-07](../requirements/functional-stories/fs-07-visual-graph-resolver.md), [FS-08](../requirements/functional-stories/fs-08-hosted-login-redirection.md), [FS-09](../requirements/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md), [FS-10](../requirements/functional-stories/fs-10-external-b2b-access-request-approval.md), [FS-11](../requirements/functional-stories/fs-11-user-document-upload.md), [FS-13](../requirements/functional-stories/fs-13-hierarchical-config.md), [FS-14](../requirements/functional-stories/fs-14-delegated-management.md), [FS-15](../requirements/functional-stories/fs-15-notification-rules.md), [FS-16](../requirements/functional-stories/fs-16-access-enforcement-policy.md), [FS-17](../requirements/functional-stories/fs-17-maintain-system-roles.md), [FS-18](../requirements/functional-stories/fs-18-manage-local-user-password.md), [FS-19](../requirements/functional-stories/fs-19-admin-password-reset-validity-management.md), [FS-20](../requirements/functional-stories/fs-20-system-parameter-management.md), [FS-21](../requirements/functional-stories/fs-21-tenant-signup-request-approval.md), [FS-22](../requirements/functional-stories/fs-22-user-signup-request-approval.md), [FS-24](../requirements/functional-stories/fs-24-profile-request-approval.md), [FS-25](../requirements/functional-stories/fs-25-ddd-domain-resource-hierarchy.md), [FS-26](../requirements/functional-stories/fs-26-auth-graph-preview-from-profile.md), [FS-27](../requirements/functional-stories/fs-27-state-change-consistency-broken-rules.md) | +| Implemented / usable | 25 | [FS-01](../requirements/functional-stories/fs-01-user-authentication.md), [FS-02](../requirements/functional-stories/fs-02-create-authorization-template.md), [FS-03](../requirements/functional-stories/fs-03-register-organization.md), [FS-04](../requirements/functional-stories/fs-04-register-system-topology.md), [FS-05](../requirements/functional-stories/fs-05-create-profile-manual-template.md), [FS-06](../requirements/functional-stories/fs-06-auto-assign-template.md), [FS-07](../requirements/functional-stories/fs-07-visual-graph-resolver.md), [FS-08](../requirements/functional-stories/fs-08-hosted-login-redirection.md), [FS-09](../requirements/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md), [FS-10](../requirements/functional-stories/fs-10-external-b2b-access-request-approval.md), [FS-11](../requirements/functional-stories/fs-11-user-document-upload.md), [FS-13](../requirements/functional-stories/fs-13-hierarchical-config.md), [FS-14](../requirements/functional-stories/fs-14-delegated-management.md), [FS-15](../requirements/functional-stories/fs-15-notification-rules.md), [FS-16](../requirements/functional-stories/fs-16-access-enforcement-policy.md), [FS-17](../requirements/functional-stories/fs-17-maintain-system-roles.md), [FS-18](../requirements/functional-stories/fs-18-manage-local-user-password.md), [FS-19](../requirements/functional-stories/fs-19-admin-password-reset-validity-management.md), [FS-20](../requirements/functional-stories/fs-20-system-parameter-management.md), [FS-21](../requirements/functional-stories/fs-21-tenant-signup-request-approval.md), [FS-22](../requirements/functional-stories/fs-22-user-signup-request-approval.md), [FS-24](../requirements/functional-stories/fs-24-profile-request-approval.md), [FS-38](../requirements/functional-stories/fs-38-ddd-domain-resource-hierarchy.md), [FS-39](../requirements/functional-stories/fs-39-auth-graph-preview-from-profile.md), [FS-40](../requirements/functional-stories/fs-40-state-change-consistency-broken-rules.md) | | Partial | 0 | — | | Deferred | 9 | [FS-12](../requirements/functional-stories/fs-12-role-promotion-process.md), [FS-28](../requirements/functional-stories/fs-28-access-review-campaigns.md), [FS-29](../requirements/functional-stories/fs-29-entitlement-packages.md), [FS-30](../requirements/functional-stories/fs-30-provisioning-deprovisioning-connectors.md), [FS-31](../requirements/functional-stories/fs-31-privileged-access-time-bound-elevation.md), [FS-32](../requirements/functional-stories/fs-32-operational-reliability-guardrails.md), [FS-33](../requirements/functional-stories/fs-33-authorization-graph-explorer.md), [FS-34](../requirements/functional-stories/fs-34-business-semantic-access-packages.md), [FS-35](../requirements/functional-stories/fs-35-continuous-access-health.md) | diff --git a/docs/governance/requirements-es/functional-stories/fs-01-user-authentication.md b/docs/governance/requirements-es/functional-stories/fs-01-user-authentication.md index 9183b9a7..def732dd 100644 --- a/docs/governance/requirements-es/functional-stories/fs-01-user-authentication.md +++ b/docs/governance/requirements-es/functional-stories/fs-01-user-authentication.md @@ -1,4 +1,4 @@ -# Functional Story 1: Autenticación Corporativa vía IdP Externo +# Historia Funcional 1: Autenticación Corporativa vía IdP Externo ## 1. Propósito de Negocio @@ -13,12 +13,13 @@ Los usuarios corporativos necesitan acceder a los sistemas cliente usando el pro | **Usuario Corporativo** | Intenta iniciar sesión en un sistema cliente. | | **Proveedor de Identidad Externo** | Confirma la identidad corporativa del usuario. | | **UMS** | Valida la identidad contra registros activos y establece la sesión de aplicación. | -| **Administrador TI** | Puede usar acceso de emergencia cuando el proveedor externo no estáá disponible. +| **Administrador TI** | Puede usar acceso de emergencia cuando el proveedor externo no estáá disponible. | + ## 3. Precondiciones de Negocio -- El usuario existe en UMS y estáá vinculado a una referencia de identidad corporativa válida. -- La cuenta del usuario estáá activa. -- La organización tiene configurado un proveedor de identidad. +* El usuario existe en UMS y estáá vinculado a una referencia de identidad corporativa válida. +* La cuenta del usuario estáá activa. +* La organización tiene configurado un proveedor de identidad. --- @@ -71,17 +72,17 @@ Si el usuario existe pero estáá suspendido o terminado, el sistema bloquea el ## 8. Requisitos Técnicos -- Soportar OAuth 2.0 Authorization Code con PKCE para autenticación externa. -- Validar tokens firmados y claims obligatorios de identidad. -- Vincular el claim de identidad externa con la referencia de identidad en UMS. -- Establecer una sesión segura mediante cookies HTTP-only, SameSite o el mecanismo aprobado. -- Retornar fallo de autorización cuando la identidad no estáá vinculada o activa. -- Emitir eventos inmutables de auditoría para fallos y advertencias. +* Soportar OAuth 2.0 Authorization Code con PKCE para autenticación externa. +* Validar tokens firmados y claims obligatorios de identidad. +* Vincular el claim de identidad externa con la referencia de identidad en UMS. +* Establecer una sesión segura mediante cookies HTTP-only, SameSite o el mecanismo aprobado. +* Retornar fallo de autorización cuando la identidad no estáá vinculada o activa. +* Emitir eventos inmutables de auditoría para fallos y advertencias. --- ## 9. Trazabilidad -- Entidades: `USER_ACCOUNT`, `IDP_CONFIGURATION`, `PROFILE` -- ADRs: ADR-0020, ADR-0022, ADR-0026 -- Historias relacionadas: FS-08, FS-09 +* Entidades: `USER_ACCOUNT`, `IDP_CONFIGURATION`, `PROFILE` +* ADRs: ADR-0020, ADR-0022, ADR-0026 +* Historias relacionadas: FS-08, FS-09 diff --git a/docs/governance/requirements-es/functional-stories/fs-02-create-authorization-template.md b/docs/governance/requirements-es/functional-stories/fs-02-create-authorization-template.md index 18dce377..da149f54 100644 --- a/docs/governance/requirements-es/functional-stories/fs-02-create-authorization-template.md +++ b/docs/governance/requirements-es/functional-stories/fs-02-create-authorization-template.md @@ -1,4 +1,4 @@ -# Functional Story 2: Crear e Instanciar Plantilla de Autorización +# Historia Funcional 2: Crear e Instanciar Plantilla de Autorización ## 1. Propósito de Negocio @@ -9,11 +9,13 @@ Los administradores necesitan plantillas de autorización reutilizables para gob | Actor | Responsabilidad | | :--- | :--- | | **Administrador Global de TI** | Crea y mantiene plantillas reutilizables de autorización. | -| **Administrador de Tenant/Sistema** | Asigna plantillas aprobadas a perfiles cuando estáá permitido. | ## 3. Precondiciones de Negocio +| **Administrador de Tenant/Sistema** | Asigna plantillas aprobadas a perfiles cuando estáá permitido. | -- La topología del sistema destino estáá registrada. -- Las acciones disponibles estáán definidas. -- El administrador tiene permiso para gestionar plantillas. +## 3. Precondiciones de Negocio + +* La topología del sistema destino estáá registrada. +* Las acciones disponibles estáán definidas. +* El administrador tiene permiso para gestionar plantillas. ## 4. Flujo Funcional Principal @@ -51,14 +53,14 @@ Si una nueva versión de plantilla entra en conflicto con sobrescrituras locales ## 8. Requisitos Técnicos -- Persistir plantillas y permisos usando `PERMISSION_TEMPLATE`, `PROFILE` y `PROFILE_PERMISSION`. -- Validar integridad de jerarquía de recursos antes de publicar. -- Invalidar caché del grafo de autorización compilado para usuarios afectados tras asignación o actualización. -- Emitir eventos de auditoría por creación, publicación, asignación y cambio de versión. -- Preservar linaje de versionado semántico. +* Persistir plantillas y permisos usando `PERMISSION_TEMPLATE`, `PROFILE` y `PROFILE_PERMISSION`. +* Validar integridad de jerarquía de recursos antes de publicar. +* Invalidar caché del grafo de autorización compilado para usuarios afectados tras asignación o actualización. +* Emitir eventos de auditoría por creación, publicación, asignación y cambio de versión. +* Preservar linaje de versionado semántico. ## 9. Trazabilidad -- Entidades: `PERMISSION_TEMPLATE`, `PROFILE`, `PROFILE_PERMISSION`, `ACTION` -- ADRs: ADR-0039, ADR-0042, ADR-0021 -- Technical Enabler: TE-01 +* Entidades: `PERMISSION_TEMPLATE`, `PROFILE`, `PROFILE_PERMISSION`, `ACTION` +* ADRs: ADR-0039, ADR-0042, ADR-0021 +* Technical Enabler: TE-01 diff --git a/docs/governance/requirements-es/functional-stories/fs-03-register-organization.md b/docs/governance/requirements-es/functional-stories/fs-03-register-organization.md index ac779a53..ac092023 100644 --- a/docs/governance/requirements-es/functional-stories/fs-03-register-organization.md +++ b/docs/governance/requirements-es/functional-stories/fs-03-register-organization.md @@ -1,4 +1,4 @@ -# Functional Story 3: Registrar Organización y Configurar Estrategia de IdP +# Historia Funcional 3: Registrar Organización y Configurar Estrategia de IdP ## 1. Propósito de Negocio @@ -13,10 +13,10 @@ UMS debe permitir que administradores de seguridad incorporen una nueva organiza ## 3. Precondiciones de Negocio -- El actor estáá autenticado como administrador global. -- La organización estáá aprobada para onboarding. -- La información empresarial requerida estáá disponible. -- El tenant se crea o se marca con `IsManagementOwner=true` cuando debe administrar su propio scope interno de UMS. +* El actor estáá autenticado como administrador global. +* La organización estáá aprobada para onboarding. +* La información empresarial requerida estáá disponible. +* El tenant se crea o se marca con `IsManagementOwner=true` cuando debe administrar su propio scope interno de UMS. ## 4. Flujo Funcional Principal @@ -56,15 +56,15 @@ Si la referencia empresarial ya existe, el sistema evita crear una organización ## 8. Requisitos Técnicos -- Persistir datos del tenant en el Agregado Root `Tenant`. -- Persistir configuración de proveedor de identidad en la Entidad hija `IdentityProvider`. -- Persistir el flag de responsable de gestión en `Tenant` e inicializarlo para tenants que administrarán su propio scope de UMS. -- Aplicar unicidad para referencias externas de compañía. -- Emitir `TenantCreatedEvent`. -- Validar configuración IdP según el tipo de proveedor seleccionado. +* Persistir datos del tenant en el Agregado Root `Tenant`. +* Persistir configuración de proveedor de identidad en la Entidad hija `IdentityProvider`. +* Persistir el flag de responsable de gestión en `Tenant` e inicializarlo para tenants que administrarán su propio scope de UMS. +* Aplicar unicidad para referencias externas de compañía. +* Emitir `TenantCreatedEvent`. +* Validar configuración IdP según el tipo de proveedor seleccionado. ## 9. Trazabilidad -- Entidades: `Tenant` (AR), `Branch` (Entidad Hija), `IdentityProvider` (Entidad Hija), `UserAccount` (AR) -- ADRs: ADR-0031, ADR-0032, ADR-0034, ADR-0010 -- Technical Enabler: TE-03 +* Entidades: `Tenant` (AR), `Branch` (Entidad Hija), `IdentityProvider` (Entidad Hija), `UserAccount` (AR) +* ADRs: ADR-0031, ADR-0032, ADR-0034, ADR-0010 +* Technical Enabler: TE-03 diff --git a/docs/governance/requirements-es/functional-stories/fs-04-register-system-topology.md b/docs/governance/requirements-es/functional-stories/fs-04-register-system-topology.md index 5364c466..bce6d491 100644 --- a/docs/governance/requirements-es/functional-stories/fs-04-register-system-topology.md +++ b/docs/governance/requirements-es/functional-stories/fs-04-register-system-topology.md @@ -1,4 +1,4 @@ -# Functional Story 4: Registrar Sistema y Definir Topología de Menú +# Historia Funcional 4: Registrar Sistema y Definir Topología de Menú ## 1. Propósito de Negocio @@ -9,10 +9,12 @@ UMS debe permitir que los administradores registren sistemas cliente y describan | Actor | Responsabilidad | | :--- | :--- | | **Administrador de Seguridad Global** | Registra sistemas cliente y define su topología de menú. | -| **Dueño del Sistema Cliente** | Proporciona la estructura del sistema y sus acciones de acceso. | ## 3. Precondiciones de Negocio +| **Dueño del Sistema Cliente** | Proporciona la estructura del sistema y sus acciones de acceso. | -- El administrador esta autorizado para registrar sistemas. -- El dueño del sistema ha proporcionado módulos, menús, opciones y acciones esperadas. +## 3. Precondiciones de Negocio + +* El administrador esta autorizado para registrar sistemas. +* El dueño del sistema ha proporcionado módulos, menús, opciones y acciones esperadas. ## 4. Flujo Funcional Principal @@ -53,12 +55,18 @@ Si un nodo de topologia esta incompleto, UMS puede guardarlo como borrador pero > **ESTADO DE IMPLEMENTACION: ACTIVO** > `SystemSuite` y su topologia de menus estan implementados en el dominio de Autorizacion. El mantenimiento del catalogo de roles asociado a la suite seleccionada esta cubierto por FS-17. -- Asegurar la persistencia del identificador y metadatos del sistema. -- Asegurar la unicidad de los códigos de sistema. -- Emitir eventos de dominio cuando se registran metadatos de sistema. + + +> [!NOTE] +> **REVISION (ADR-0090, Aceptado 2026-07-15):** la topologia deja de ser una jerarquia rigida de 4 niveles (Menu→SubMenu→Opcion, submenu obligatorio) y pasa a un **arbol de nodos recursivo** (`MenuNode` auto-referente, `NodeKind`, **profundidad variable**, **submenu opcional**), con **funcionalidad↔opcion N:M** y **metadatos SDLC por nodo** (responsable, criticidad, producto impactado, componente tecnico, dependencias, evidencias, trazabilidad). Un modulo puede tener opciones directas o jerarquias mas profundas. Implementacion en curso: satelite `ums` (D-009 / G-029). + +* Asegurar la persistencia del identificador y metadatos del sistema. +* Asegurar la unicidad de los códigos de sistema (por ámbito del padre: `(ParentId, Code)` dentro del módulo). +* Emitir eventos de dominio cuando se registran metadatos de sistema. +* Soportar profundidad variable y submenús opcionales; una funcionalidad puede relacionarse con una o varias opciones. ## 9. Trazabilidad -- Entidades: `SystemSuite`, `Module`, `Menu`, `SubMenu`, `Option`, `Action` -- ADRs: ADR-0032, ADR-0034, ADR-0047 -- Historias relacionadas: FS-02, FS-07, FS-17 +* Entidades: `SystemSuite`, `Module`, `MenuNode` (recursivo; reemplaza `Menu`/`SubMenu`/`Option`), `Action`, `NodeAction` (puente N:M) +* ADRs: **ADR-0090** (forma de la topología: árbol recursivo flexible), ADR-0032, ADR-0034, ADR-0047 +* Historias relacionadas: FS-02, FS-07, FS-17 diff --git a/docs/governance/requirements-es/functional-stories/fs-05-create-profile-manual-template.md b/docs/governance/requirements-es/functional-stories/fs-05-create-profile-manual-template.md index fd33d555..de5c50ab 100644 --- a/docs/governance/requirements-es/functional-stories/fs-05-create-profile-manual-template.md +++ b/docs/governance/requirements-es/functional-stories/fs-05-create-profile-manual-template.md @@ -1,4 +1,4 @@ -# Functional Story 5: Crear Perfil y Asignar Manualmente Plantilla de Autorización +# Historia Funcional 5: Crear Perfil y Asignar Manualmente Plantilla de Autorización ## 1. Propósito de Negocio @@ -9,11 +9,13 @@ Los administradores necesitan crear perfiles que representen responsabilidades r | Actor | Responsabilidad | | :--- | :--- | | **Administrador de Seguridad** | Crea perfiles y asigna plantillas. | -| **Gestáor de Operaciones de Tenant** | Administra perfiles locales dentro de su alcance delegado. | ## 3. Precondiciones de Negocio +| **Gestáor de Operaciones de Tenant** | Administra perfiles locales dentro de su alcance delegado. | -- La organización destino existe. -- La sede destino existe cuando se requiere alcance por sede. -- Existe al menos una plantilla de autorización disponible. +## 3. Precondiciones de Negocio + +* La organización destino existe. +* La sede destino existe cuando se requiere alcance por sede. +* Existe al menos una plantilla de autorización disponible. ## 4. Flujo Funcional Principal @@ -50,14 +52,14 @@ Si el perfil ya tiene una plantilla activa, el administrador debe confirmar si l ## 8. Requisitos Técnicos -- Persistir perfiles en `PROFILE`. -- Vincular plantillas mediante `PROFILE_PERMISSION` / relación de asignación de plantilla. -- Invalidar caché del grafo de autorización para usuarios afectados. -- Emitir `ProfileCreatedEvent` y `TemplateAssignedEvent`. -- Preservar metadata de asignación, incluyendo si fue manual. +* Persistir perfiles en `PROFILE`. +* Vincular plantillas mediante `PROFILE_PERMISSION` / relación de asignación de plantilla. +* Invalidar caché del grafo de autorización para usuarios afectados. +* Emitir `ProfileCreatedEvent` y `TemplateAssignedEvent`. +* Preservar metadata de asignación, incluyendo si fue manual. ## 9. Trazabilidad -- Entidades: `PROFILE`, `PERMISSION_TEMPLATE`, `PROFILE_PERMISSION` -- ADRs: ADR-0039, ADR-0042, ADR-0043, ADR-0035 -- Technical Enabler: TE-01 +* Entidades: `PROFILE`, `PERMISSION_TEMPLATE`, `PROFILE_PERMISSION` +* ADRs: ADR-0039, ADR-0042, ADR-0043, ADR-0035 +* Technical Enabler: TE-01 diff --git a/docs/governance/requirements-es/functional-stories/fs-06-auto-assign-template.md b/docs/governance/requirements-es/functional-stories/fs-06-auto-assign-template.md index cac46755..d7551b68 100644 --- a/docs/governance/requirements-es/functional-stories/fs-06-auto-assign-template.md +++ b/docs/governance/requirements-es/functional-stories/fs-06-auto-assign-template.md @@ -1,4 +1,4 @@ -# Functional Story 6: Auto-Asignar Plantilla de Autorización al Crear Perfil +# Historia Funcional 6: Auto-Asignar Plantilla de Autorización al Crear Perfil ## 1. Propósito de Negocio @@ -9,11 +9,13 @@ UMS debe reducir administración manual asignando la plantilla correcta cuando u | Actor | Responsabilidad | | :--- | :--- | | **Administrador de Seguridad** | Configura reglas de asignación. | -| **Motor de Reglas UMS** | Aplica reglas coincidentes durante la creación del perfil. | ## 3. Precondiciones de Negocio +| **Motor de Reglas UMS** | Aplica reglas coincidentes durante la creación del perfil. | -- Existe al menos una regla de asignación activa. -- El perfil creado contiene atributos evaluables. -- Existe una plantilla coincidente activa. +## 3. Precondiciones de Negocio + +* Existe al menos una regla de asignación activa. +* El perfil creado contiene atributos evaluables. +* Existe una plantilla coincidente activa. ## 4. Flujo Funcional Principal @@ -54,12 +56,12 @@ Si más de una regla coincide, UMS aplica la regla de mayor prioridad y registra > **ESTADO DE IMPLEMENTACIÓN: Verde — Completado (2026-06-03)** > El agregado `TemplateAssignmentRule` está implementado. `CreateProfileCommandHandler` asigna automáticamente la plantilla coincidente de mayor prioridad al crear el perfil. Los endpoints REST para gestión de reglas están expuestos en `/template-assignment-rules`. -- Persistir el estado de asignación en la relación perfil/plantilla. Hecho (entradas `ProfilePermission` creadas mediante `Profile.AssignTemplate`) -- Invalidar la caché del grafo de autorización para usuarios afectados. (invalidación de caché gestionada por el observador existente de `TemplateLinkedToProfileEvent`) -- Emitir eventos de dominio y auditoría para las asignaciones de plantillas. Hecho (`TemplateAutoAssignedEvent` emitido) +* Persistir el estado de asignación en la relación perfil/plantilla. Hecho (entradas `ProfilePermission` creadas mediante `Profile.AssignTemplate`) +* Invalidar la caché del grafo de autorización para usuarios afectados. (invalidación de caché gestionada por el observador existente de `TemplateLinkedToProfileEvent`) +* Emitir eventos de dominio y auditoría para las asignaciones de plantillas. Hecho (`TemplateAutoAssignedEvent` emitido) ## 9. Trazabilidad -- Entidades: `Profile` (AR), `PermissionTemplate` (AR), `TemplateAssignmentRule` (Implementado) -- ADRs: ADR-0042, ADR-0043, ADR-0035 -- Technical Enabler: TE-01 +* Entidades: `Profile` (AR), `PermissionTemplate` (AR), `TemplateAssignmentRule` (Implementado) +* ADRs: ADR-0042, ADR-0043, ADR-0035 +* Technical Enabler: TE-01 diff --git a/docs/governance/requirements-es/functional-stories/fs-07-visual-graph-resolver.md b/docs/governance/requirements-es/functional-stories/fs-07-visual-graph-resolver.md index b835512b..2590c865 100644 --- a/docs/governance/requirements-es/functional-stories/fs-07-visual-graph-resolver.md +++ b/docs/governance/requirements-es/functional-stories/fs-07-visual-graph-resolver.md @@ -1,4 +1,4 @@ -# Functional Story 7: Diagnosticar Permisos vía Visualizador de Grafos +# Historia Funcional 7: Diagnosticar Permisos vía Visualizador de Grafos ## 1. Propósito de Negocio @@ -9,11 +9,13 @@ Los equipos de soporte y seguridad necesitan entender por qué un usuario puede | Actor | Responsabilidad | | :--- | :--- | | **SRE / Ingeniero de Soporte** | Investiga problemas de permisos. | -| **Administrador de Seguridad** | Revisa configuración y decisiones de autorización. | ## 3. Precondiciones de Negocio +| **Administrador de Seguridad** | Revisa configuración y decisiones de autorización. | -- El actor tiene permisos de diagnóstico. -- El usuario objetivo existe. -- El usuario objetivo tiene al menos un perfil. +## 3. Precondiciones de Negocio + +* El actor tiene permisos de diagnóstico. +* El usuario objetivo existe. +* El usuario objetivo tiene al menos un perfil. ## 4. Flujo Funcional Principal @@ -50,13 +52,13 @@ Si aplican reglas de permitir y denegar, el sistema explica que la denegación e ## 8. Requisitos Técnicos -- Resolver el grafo diagnóstico de autorización sin mutar permisos. -- Incluir reglas fuente y razones de decisión en la respuestá diagnóstica. -- Omitir o refrescar caché cuando la precisión diagnóstica requiera datos fuente actuales. -- Emitir eventos de auditoría por acceso diagnóstico. +* Resolver el grafo diagnóstico de autorización sin mutar permisos. +* Incluir reglas fuente y razones de decisión en la respuestá diagnóstica. +* Omitir o refrescar caché cuando la precisión diagnóstica requiera datos fuente actuales. +* Emitir eventos de auditoría por acceso diagnóstico. ## 9. Trazabilidad -- Entidades: `PROFILE`, `PROFILE_PERMISSION`, `PERMISSION_TEMPLATE`, `ACTION` -- ADRs: ADR-0021, ADR-0039 -- Technical Enabler: TE-01 +* Entidades: `PROFILE`, `PROFILE_PERMISSION`, `PERMISSION_TEMPLATE`, `ACTION` +* ADRs: ADR-0021, ADR-0039 +* Technical Enabler: TE-01 diff --git a/docs/governance/requirements-es/functional-stories/fs-08-hosted-login-redirection.md b/docs/governance/requirements-es/functional-stories/fs-08-hosted-login-redirection.md index 3e68cbf7..970d9ff4 100644 --- a/docs/governance/requirements-es/functional-stories/fs-08-hosted-login-redirection.md +++ b/docs/governance/requirements-es/functional-stories/fs-08-hosted-login-redirection.md @@ -1,8 +1,8 @@ -# Functional Story 8: Autenticar vía Página de Inicio Personalizable +# Historia Funcional 8: Autenticar vía Página de Inicio Hospedada ## 1. Propósito de Negocio -Los sistemas cliente necesitan una experiencia centralizada de inicio de sesión que pueda reflejar la marca de cada tenant o sistema, manteniendo la autenticación gobernada por UMS. +Los sistemas cliente necesitan una experiencia centralizada de inicio de sesión, coherente con el contexto de cada tenant o sistema, manteniendo la autenticación gobernada por UMS. ## 2. Actores @@ -10,26 +10,28 @@ Los sistemas cliente necesitan una experiencia centralizada de inicio de sesión | :--- | :--- | | **Usuario Final** | Inicia sesión desde un sistema cliente. | | **Sistema Cliente** | Redirige usuarios al login hospedado y recibe el resultado. | -| **Administrador de Tenant/Sistema** | Configura branding y comportamiento de login. | ## 3. Precondiciones de Negocio +| **Administrador de Tenant/Sistema** | Configura el comportamiento de login. | -- El sistema cliente estáá registrado en UMS. -- Las ubicaciones de retorno estáán configuradas para el sistema cliente. -- Existen configuraciones de branding/login o se usan valores por defecto. +## 3. Precondiciones de Negocio + +* El sistema cliente estáá registrado en UMS. +* Las ubicaciones de retorno estáán configuradas para el sistema cliente. +* Existen configuraciones de login o se usan valores por defecto. ## 4. Flujo Funcional Principal 1. El usuario inicia login desde un sistema cliente. 2. El usuario es enviado a la página hospedada de UMS. -3. UMS muestra el branding y opciones de inicio de sesión correspondientes. +3. UMS muestra las opciones de inicio de sesión correspondientes. 4. El usuario completa autenticación mediante el método configurado. 5. UMS devuelve al usuario al sistema cliente. 6. El sistema cliente recibe el contexto autenticado y continúa la experiencia del usuario. ## 5. Flujos Alternativos y Excepciones -### A. Branding No Configurado +### A. Configuración de Login No Presente -Si no existe branding personalizado, UMS usa la experiencia por defecto aprobada. +Si no existe configuración específica de login, UMS usa la experiencia por defecto aprobada. ### B. Ubicación de Retorno Inválida @@ -37,28 +39,27 @@ Si el sistema cliente solicita una ubicación de retorno no aprobada, UMS bloque ## 6. Reglas de Negocio -1. El login hospedado debe soportar branding por tenant y sistema. -2. Solo pueden usarse ubicaciones de retorno aprobadas. -3. La página de login no debe exponer branding o configuración de otro tenant. -4. La selección del método de autenticación sigue la política configurada por tenant/sistema. +1. Solo pueden usarse ubicaciones de retorno aprobadas. +2. La página de login no debe exponer configuración de otro tenant. +3. La selección del método de autenticación sigue la política configurada por tenant/sistema. ## 7. Criterios de Aceptación 1. Los usuarios ven la experiencia correcta para su contexto tenant/sistema. -2. Si no hay branding, se usan valores por defecto. +2. Si no hay configuración específica, se usan valores por defecto. 3. Las ubicaciones de retorno no autorizadas son rechazadas. 4. Una autenticación exitosa devuelve al usuario al sistema cliente. ## 8. Requisitos Técnicos -- Resolver branding y comportamiento de login desde configuración de sistema. -- Soportar IdP configurado y estrategias de fallback nativo. -- Validar ubicaciones de redirect/callback. -- Emitir resultado de sesión/token aprobado tras autenticación. -- Auditar intentos exitosos y fallidos de login hospedado. +* Resolver el comportamiento de login desde configuración de sistema. +* Soportar IdP configurado y estrategias de fallback nativo. +* Validar ubicaciones de redirect/callback. +* Emitir resultado de sesión/token aprobado tras autenticación. +* Auditar intentos exitosos y fallidos de login hospedado. ## 9. Trazabilidad -- Entidades: `SYSTEM_CONFIGURATION`, `IDP_CONFIGURATION`, `FEATURE_FLAG` -- ADRs: ADR-0020, ADR-0022 -- Historias relacionadas: FS-01, FS-09, FS-13 +* Entidades: `SYSTEM_CONFIGURATION`, `IDP_CONFIGURATION`, `FEATURE_FLAG` +* ADRs: ADR-0020, ADR-0022 +* Historias relacionadas: FS-01, FS-09, FS-13 diff --git a/docs/governance/requirements-es/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md b/docs/governance/requirements-es/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md index ea4cb201..db259f75 100644 --- a/docs/governance/requirements-es/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md +++ b/docs/governance/requirements-es/functional-stories/fs-09-mfa-passwordless-adaptive-auth.md @@ -1,4 +1,4 @@ -# Functional Story 9: Autenticación Adaptativa Multifactor y Sin Contraseña +# Historia Funcional 9: Autenticación Adaptativa Multifactor y Sin Contraseña ## 1. Propósito de Negocio @@ -10,11 +10,13 @@ UMS debe reforzar la autenticación cuando el riesgo o la política del tenant l | :--- | :--- | | **Usuario Final** | Completa verificación adicional o inicio sin contraseña. | | **Administrador de Tenant** | Configura la política de autenticación. | -| **UMS** | Evalúa política y riesgo antes de otorgar acceso. | ## 3. Precondiciones de Negocio +| **UMS** | Evalúa política y riesgo antes de otorgar acceso. | -- El usuario tiene cuenta en UMS. -- La política del tenant permite o exige MFA/passwordless. -- El usuario tiene o puede registrar un método aprobado de verificación. +## 3. Precondiciones de Negocio + +* El usuario tiene cuenta en UMS. +* La política del tenant permite o exige MFA/passwordless. +* El usuario tiene o puede registrar un método aprobado de verificación. ## 4. Flujo Funcional Principal @@ -55,14 +57,14 @@ Si el contexto de riesgo es elevado, UMS exige verificación más fuerte antes d ## 8. Requisitos Técnicos -- Soportar mecanismos MFA y passwordless aprobados, incluyendo WebAuthn/passkeys cuando estáé configurado. -- Evaluar política de seguridad tenant/sistema antes de emitir sesión. -- Persistir estado de enrolamiento y resultados de verificación. -- Emitir eventos de auditoría por registro, desafío, éxito, fallo y escalamiento de riesgo. -- Retornar fallo de autorización cuando la verificación requerida no se completa. +* Soportar mecanismos MFA y passwordless aprobados, incluyendo WebAuthn/passkeys cuando estáé configurado. +* Evaluar política de seguridad tenant/sistema antes de emitir sesión. +* Persistir estado de enrolamiento y resultados de verificación. +* Emitir eventos de auditoría por registro, desafío, éxito, fallo y escalamiento de riesgo. +* Retornar fallo de autorización cuando la verificación requerida no se completa. ## 9. Trazabilidad -- Entidades: `USER_ACCOUNT`, `IDP_CONFIGURATION`, `SYSTEM_CONFIGURATION` -- ADRs: ADR-0026 -- Historias relacionadas: FS-01, FS-08 +* Entidades: `USER_ACCOUNT`, `IDP_CONFIGURATION`, `SYSTEM_CONFIGURATION` +* ADRs: ADR-0026 +* Historias relacionadas: FS-01, FS-08 diff --git a/docs/governance/requirements-es/functional-stories/fs-10-external-b2b-access-request-approval.md b/docs/governance/requirements-es/functional-stories/fs-10-external-b2b-access-request-approval.md index 672b6b92..762b9507 100644 --- a/docs/governance/requirements-es/functional-stories/fs-10-external-b2b-access-request-approval.md +++ b/docs/governance/requirements-es/functional-stories/fs-10-external-b2b-access-request-approval.md @@ -1,4 +1,4 @@ -# Functional Story 10: Flujo de Aprobación y Petición de Acceso Externo B2B +# Historia Funcional 10: Flujo de Aprobación y Petición de Acceso Externo B2B ## 1. Propósito de Negocio @@ -12,12 +12,13 @@ Los usuarios internos necesitan una forma controlada de solicitar acceso para so | :--- | :--- | | **Usuario Patrocinador** | Solicita y justifica el acceso para un usuario externo. | | **Administrador PAP** | Revisa, aprueba o rechaza la solicitud. | -| **Usuario Externo** | Recibe el onboarding después de la aprobación. +| **Usuario Externo** | Recibe el onboarding después de la aprobación. | + ## 3. Precondiciones de Negocio -- El patrocinador es un usuario corporativo interno autenticado. -- El patrocinador tiene permiso para solicitar acceso externo. -- El perfil solicitado estáá disponible para usuarios externos. +* El patrocinador es un usuario corporativo interno autenticado. +* El patrocinador tiene permiso para solicitar acceso externo. +* El perfil solicitado estáá disponible para usuarios externos. --- @@ -73,17 +74,17 @@ Si la organización ya existe, el sistema vincula el nuevo usuario a la organiza ## 8. Requisitos Técnicos -- Persistir la solicitud como `EXTERNAL_ACCESS_REQUEST` / `APPROVAL_REQUEST` con estados pendiente, aprobado y rechazado. -- Registrar auditoría inmutable con patrocinador, aprobador, justificación, estado y timestaamps. -- Validar perfiles en el límite del servicio/API. -- Usar filtrado por tenant en capa de aplicación como control primario y PostgreSQL row-level security y politicas de base de datos como endurecimiento de infraestructura. -- Emitir eventos de aprovisionamiento y auditoría después de aprobar. -- Retornar fallo de autorización ante intentos de escalamiento de privilegios. +* Persistir la solicitud como `EXTERNAL_ACCESS_REQUEST` / `APPROVAL_REQUEST` con estados pendiente, aprobado y rechazado. +* Registrar auditoría inmutable con patrocinador, aprobador, justificación, estado y timestaamps. +* Validar perfiles en el límite del servicio/API. +* Usar filtrado por tenant en capa de aplicación como control primario y PostgreSQL row-level security y politicas de base de datos como endurecimiento de infraestructura. +* Emitir eventos de aprovisionamiento y auditoría después de aprobar. +* Retornar fallo de autorización ante intentos de escalamiento de privilegios. --- ## 9. Trazabilidad -- Entidades: `APPROVAL_REQUEST`, `APPROVAL_WORKFLOW`, `USER_ACCOUNT`, `PROFILE`, `TENANT` -- ADRs: ADR-0031, ADR-0032, ADR-0038, ADR-0044 -- Historias relacionadas: FS-03, FS-14 +* Entidades: `APPROVAL_REQUEST`, `APPROVAL_WORKFLOW`, `USER_ACCOUNT`, `PROFILE`, `TENANT` +* ADRs: ADR-0031, ADR-0032, ADR-0038, ADR-0044 +* Historias relacionadas: FS-03, FS-14 diff --git a/docs/governance/requirements-es/functional-stories/fs-11-user-document-upload.md b/docs/governance/requirements-es/functional-stories/fs-11-user-document-upload.md index e9a77300..57d90cd4 100644 --- a/docs/governance/requirements-es/functional-stories/fs-11-user-document-upload.md +++ b/docs/governance/requirements-es/functional-stories/fs-11-user-document-upload.md @@ -1,4 +1,4 @@ -# Functional Story 11: Cargar y Validar Documento de Usuario +# Historia Funcional 11: Cargar y Validar Documento de Usuario ## 1. Propósito de Negocio @@ -10,11 +10,13 @@ Los usuarios y administradores necesitan entregar documentos requeridos para que | :--- | :--- | | **Usuario** | Carga su propio documento requerido. | | **Administrador de Identidad** | Carga o revisa documentos en nombre de usuarios. | -| **Revisor de Cumplimiento** | Confirma si el documento es aceptable. | ## 3. Precondiciones de Negocio +| **Revisor de Cumplimiento** | Confirma si el documento es aceptable. | -- El usuario existe. -- El tipo de documento estáá configurado. -- El actor tiene permiso para cargar o revisar el documento. +## 3. Precondiciones de Negocio + +* El usuario existe. +* El tipo de documento estáá configurado. +* El actor tiene permiso para cargar o revisar el documento. ## 4. Flujo Funcional Principal @@ -53,13 +55,13 @@ Si el archivo estáá corrupto, no puede leerse o incumple reglas de carga, el s > [!NOTE] > En la implementación real de C# (base de código), los agregados de cumplimiento y aprobación están unificados bajo el espacio de nombres **Ums.Domain.Approvals**. -- Persistir metadatos en el Agregado Root `UserDocument`. -- Clasificar documentos mediante el Agregado Root `DocumentType`. -- Guardar ubicación del archivo y checksum para recuperación e integridad. -- Emitir eventos de dominio y auditoría por carga, validación, rechazo y cambios de estado. +* Persistir metadatos en el Agregado Root `UserDocument`. +* Clasificar documentos mediante el Agregado Root `DocumentType`. +* Guardar ubicación del archivo y checksum para recuperación e integridad. +* Emitir eventos de dominio y auditoría por carga, validación, rechazo y cambios de estado. ## 9. Trazabilidad -- Entidades: `UserDocument` (AR), `DocumentType` (AR) -- ADRs: ADR-0045, ADR-0016 -- Historias relacionadas: FS-15, FS-16 +* Entidades: `UserDocument` (AR), `DocumentType` (AR) +* ADRs: ADR-0045, ADR-0016 +* Historias relacionadas: FS-15, FS-16 diff --git a/docs/governance/requirements-es/functional-stories/fs-12-role-promotion-process.md b/docs/governance/requirements-es/functional-stories/fs-12-role-promotion-process.md index 5859ace0..b243c25c 100644 --- a/docs/governance/requirements-es/functional-stories/fs-12-role-promotion-process.md +++ b/docs/governance/requirements-es/functional-stories/fs-12-role-promotion-process.md @@ -1,4 +1,4 @@ -# Functional Story 12: Ejecutar Proceso de Promoción de Rol +# Historia Funcional 12: Ejecutar Proceso de Promoción de Rol ## 1. Propósito de Negocio @@ -10,11 +10,13 @@ UMS debe soportar evolución controlada de roles para que los usuarios avancen c | :--- | :--- | | **Evaluador de Promoción** | Detecta usuarios elegibles para promoción. | | **Administrador Aprobador** | Revisa y aprueba o rechaza la promoción. | -| **Usuario** | Recibe el cambio de rol resultante. | ## 3. Precondiciones de Negocio +| **Usuario** | Recibe el cambio de rol resultante. | -- La jerarquía de roles estáá definida. -- Los criterios de promoción estáán configurados. -- El usuario tiene un perfil activo elegible para promoción. +## 3. Precondiciones de Negocio + +* La jerarquía de roles estáá definida. +* Los criterios de promoción estáán configurados. +* El usuario tiene un perfil activo elegible para promoción. ## 4. Flujo Funcional Principal @@ -53,16 +55,17 @@ Si el administrador rechaza la promoción, el usuario permanece en el rol actual > [!NOTE] > En la implementación real de C# (base de código), el motor de promociones está implementado mediante dos agregados independientes en el espacio de nombres **Ums.Domain.IGA**: +> > 1. **RoleMaturityStatus**: Mantiene las capacitaciones, certificaciones, score de desempeño e invariantes de elegibilidad del usuario. > 2. **PromotionRequest**: Orquesta el flujo de aprobación transaccional y realiza análisis de riesgo automatizados. -- Monitorear la elegibilidad y métricas del usuario en el Agregado Root `RoleMaturityStatus`. -- Gestionar las etapas de la transacción de promoción y el análisis de impacto de riesgo en el Agregado Root `PromotionRequest` (con su entidad hija `PromotionImpactAnalysis`). -- Hacer cumplir las invariantes de elegibilidad (antigüedad mínima en nivel: Junior 6 meses, Intermediate 12 meses, Senior 18 meses, Lead 24 meses; score de desempeño >= 3.0; sin bloqueos de cumplimiento) antes del envío. -- Emitir Eventos de Dominio específicos: `PromotionRequestCreated`, `PromotionRequestSubmitted`, `PromotionRequestApproved`, `PromotionRequestExecuted`, `PromotionRequestVerified`. +* Monitorear la elegibilidad y métricas del usuario en el Agregado Root `RoleMaturityStatus`. +* Gestionar las etapas de la transacción de promoción y el análisis de impacto de riesgo en el Agregado Root `PromotionRequest` (con su entidad hija `PromotionImpactAnalysis`). +* Hacer cumplir las invariantes de elegibilidad (antigüedad mínima en nivel: Junior 6 meses, Intermediate 12 meses, Senior 18 meses, Lead 24 meses; score de desempeño >= 3.0; sin bloqueos de cumplimiento) antes del envío. +* Emitir Eventos de Dominio específicos: `PromotionRequestCreated`, `PromotionRequestSubmitted`, `PromotionRequestApproved`, `PromotionRequestExecuted`, `PromotionRequestVerified`. ## 9. Trazabilidad -- Entidades: `RoleMaturityStatus` (AR), `PromotionRequest` (AR), `PromotionImpactAnalysis` (Entidad Hija) -- ADRs: ADR-0046, ADR-0036 -- Historias relacionadas: FS-11, FS-14 +* Entidades: `RoleMaturityStatus` (AR), `PromotionRequest` (AR), `PromotionImpactAnalysis` (Entidad Hija) +* ADRs: ADR-0046, ADR-0036 +* Historias relacionadas: FS-11, FS-14 diff --git a/docs/governance/requirements-es/functional-stories/fs-13-hierarchical-config.md b/docs/governance/requirements-es/functional-stories/fs-13-hierarchical-config.md index 2341e220..1799324a 100644 --- a/docs/governance/requirements-es/functional-stories/fs-13-hierarchical-config.md +++ b/docs/governance/requirements-es/functional-stories/fs-13-hierarchical-config.md @@ -1,4 +1,4 @@ -# Functional Story 13: Configurar Parámetros Jerárquicos del Sistema +# Historia Funcional 13: Configurar Parámetros Jerárquicos del Sistema ## 1. Propósito de Negocio @@ -13,12 +13,13 @@ Los administradores necesitan configurar el comportamiento del sistema sin solic | **Administrador Global** | Define valores por defecto aplicables a toda la plataforma. | | **Administrador de Tenant** | Ajusta comportamiento para un tenant cuando la política global lo permite. | | **Administrador de Sistema** | Ajusta comportamiento para un sistema o suite registrada. | -| **Sistema Cliente** | Consume la configuración efectiva resuelta por UMS. +| **Sistema Cliente** | Consume la configuración efectiva resuelta por UMS. | + ## 3. Precondiciones de Negocio -- El administrador estáá autenticado. -- El administrador tiene permiso para gestionar configuración en el alcance seleccionado. -- El tenant, sistema o módulo destino estáá registrado y activo. +* El administrador estáá autenticado. +* El administrador tiene permiso para gestionar configuración en el alcance seleccionado. +* El tenant, sistema o módulo destino estáá registrado y activo. --- @@ -76,14 +77,14 @@ Si ya existe un parámetro con el mismo identificador en el alcance seleccionado > **ESTADO DE IMPLEMENTACIÓN: DIFERIDO / FUERA DE ALCANCE** > En la fase actual, la gestión activa de parámetros jerárquicos de configuración (`AppConfiguration`) está **diferida** y no está implementada dentro del proyecto principal de dominio de C#. -- Asegurar estructura para parámetros de configuración según su alcance. -- Soportar el rastreo de auditoría en sobrescrituras de configuración. +* Asegurar estructura para parámetros de configuración según su alcance. +* Soportar el rastreo de auditoría en sobrescrituras de configuración. --- ## 9. Trazabilidad -- Entidades: `AppConfiguration` (AR Diferido) -- ADRs: ADR-0024, ADR-0047 -- Technical Enabler: TE-02 Resolve Hierarchical System Configuration -- Estándar: Estándar de Redacción de Historias Funcionales; Estándar de Catálogos Paramétricos +* Entidades: `AppConfiguration` (AR Diferido) +* ADRs: ADR-0024, ADR-0047 +* Technical Enabler: TE-02 Resolve Hierarchical System Configuration +* Estándar: Estándar de Redacción de Historias Funcionales; Estándar de Catálogos Paramétricos diff --git a/docs/governance/requirements-es/functional-stories/fs-14-delegated-management.md b/docs/governance/requirements-es/functional-stories/fs-14-delegated-management.md index 658950b3..7820309f 100644 --- a/docs/governance/requirements-es/functional-stories/fs-14-delegated-management.md +++ b/docs/governance/requirements-es/functional-stories/fs-14-delegated-management.md @@ -8,25 +8,25 @@ La delegación aplica únicamente al scope interno de UMS y debe mantenerse dent ## 2. Alcance Funcional -- La delegación ocurre siempre dentro del mismo tenant. -- El usuario delegante debe ser un usuario autorizado del tenant con acceso vigente a UMS. -- El usuario receptor debe pertenecer al mismo tenant y ser elegible para recibir permisos UMS. -- La delegación puede incluir permisos para crear usuarios, gestionar usuarios, asignar perfiles permitidos, modificar permisos permitidos dentro del alcance del delegante, y revocar o bloquear usuarios si el delegante posee esas capacidades. -- La delegación puede requerir aprobación según el tipo de permiso, el nivel de riesgo o la política del tenant. -- La delegación debe ser aprobada, trazada, auditada y revocable. +* La delegación ocurre siempre dentro del mismo tenant. +* El usuario delegante debe ser un usuario autorizado del tenant con acceso vigente a UMS. +* El usuario receptor debe pertenecer al mismo tenant y ser elegible para recibir permisos UMS. +* La delegación puede incluir permisos para crear usuarios, gestionar usuarios, asignar perfiles permitidos, modificar permisos permitidos dentro del alcance del delegante, y revocar o bloquear usuarios si el delegante posee esas capacidades. +* La delegación puede requerir aprobación según el tipo de permiso, el nivel de riesgo o la política del tenant. +* La delegación debe ser aprobada, trazada, auditada y revocable. ## 3. Fuera de Alcance -- Delegación cross-tenant. -- Delegación global de administración fuera del tenant. -- Delegación por `Organization`, `Department`, `System` o `Team` si esos scopes no están habilitados explícitamente para esta historia. -- Otorgar permisos que el delegante no posee. -- Convertir la delegación en un mecanismo para saltar el modelo de aprobación de UMS. +* Delegación cross-tenant. +* Delegación global de administración fuera del tenant. +* Delegación por `Organization`, `Department`, `System` o `Team` si esos scopes no están habilitados explícitamente para esta historia. +* Otorgar permisos que el delegante no posee. +* Convertir la delegación en un mecanismo para saltar el modelo de aprobación de UMS. ## 4. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Delegante | Concede, modifica o revoca una delegación limitada dentro de su propio alcance UMS. | | Receptor | Ejecuta acciones de gestión UMS dentro de los permisos delegados y del tenant correspondiente. | | Aprobador autorizado | Aprueba la delegación cuando la política del tenant lo exige. | @@ -35,12 +35,12 @@ La delegación aplica únicamente al scope interno de UMS y debe mantenerse dent ## 5. Precondiciones de Negocio -- El delegante pertenece al mismo tenant que el receptor. -- El delegante tiene acceso vigente y efectivo a UMS. -- El delegante posee los permisos que pretende delegar. -- El receptor es elegible para recibir permisos UMS. -- No existe una restricción activa que invalide la delegación por pérdida de acceso, desactivación o revocación previa. -- La política del tenant define si la delegación requiere aprobación, vigencia temporal o validación adicional. +* El delegante pertenece al mismo tenant que el receptor. +* El delegante tiene acceso vigente y efectivo a UMS. +* El delegante posee los permisos que pretende delegar. +* El receptor es elegible para recibir permisos UMS. +* No existe una restricción activa que invalide la delegación por pérdida de acceso, desactivación o revocación previa. +* La política del tenant define si la delegación requiere aprobación, vigencia temporal o validación adicional. ## 6. Flujo Funcional Principal @@ -80,7 +80,7 @@ Si la operación produce auto-delegación, ciclo de delegación o encadenamiento ## 8. Reglas de Negocio | Regla | Descripción | -|---|---| +| --- | --- | | BR-01 | La delegación solo aplica al scope interno de UMS dentro del tenant. | | BR-02 | No se permite delegación cross-tenant. | | BR-03 | El delegante solo puede delegar permisos que ya posee en su perfil UMS efectivo. | @@ -97,7 +97,7 @@ Si la operación produce auto-delegación, ciclo de delegación o encadenamiento ## 9. Criterios de Aceptación | # | Criterio de Aceptación | -|---|---| +| --- | --- | | 1 | El sistema permite delegar gestión UMS solo dentro del mismo tenant. | | 2 | El sistema impide la delegación cross-tenant. | | 3 | El sistema impide que el delegado reciba permisos que el delegante no posee. | @@ -111,24 +111,24 @@ Si la operación produce auto-delegación, ciclo de delegación o encadenamiento ## 10. Requisitos de Auditoría y Trazabilidad -- Registrar tenant, delegante, receptor, permisos delegados, alcance, vigencia, motivo y estado. -- Registrar quién aprobó, activó, modificó, revocó, rechazó o expiró la delegación. -- Registrar fecha y hora de cada transición de estado. -- Conservar evidencia del permiso original del delegante al momento de crear o modificar la delegación. -- Mantener trazabilidad de suspensión o revisión forzada cuando el delegante pierda autoridad. +* Registrar tenant, delegante, receptor, permisos delegados, alcance, vigencia, motivo y estado. +* Registrar quién aprobó, activó, modificó, revocó, rechazó o expiró la delegación. +* Registrar fecha y hora de cada transición de estado. +* Conservar evidencia del permiso original del delegante al momento de crear o modificar la delegación. +* Mantener trazabilidad de suspensión o revisión forzada cuando el delegante pierda autoridad. ## 11. Requisitos Técnicos -- Si existe una estructura técnica previa como `UserManagementDelegation`, debe alinearse a este alcance mínimo: tenant, usuario delegante, usuario receptor, permisos UMS delegados, aprobación, auditoría y revocación. -- El modelo debe validar que el conjunto de permisos delegados sea subconjunto de los permisos efectivos del delegante. -- El modelo debe soportar estado de aprobación, activación, rechazo, revocación, expiración y suspensión. -- La lógica de prevención de ciclos y auto-delegación debe resolverse en la capa de aplicación y reforzarse en el dominio. -- No introducir scopes adicionales como Organization, Department, System o Team salvo que una historia futura los habilite explícitamente. +* Si existe una estructura técnica previa como `UserManagementDelegation`, debe alinearse a este alcance mínimo: tenant, usuario delegante, usuario receptor, permisos UMS delegados, aprobación, auditoría y revocación. +* El modelo debe validar que el conjunto de permisos delegados sea subconjunto de los permisos efectivos del delegante. +* El modelo debe soportar estado de aprobación, activación, rechazo, revocación, expiración y suspensión. +* La lógica de prevención de ciclos y auto-delegación debe resolverse en la capa de aplicación y reforzarse en el dominio. +* No introducir scopes adicionales como Organization, Department, System o Team salvo que una historia futura los habilite explícitamente. ## 12. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades | `UserManagementDelegation`, `UserAccount`, `Profile` | | Permisos UMS relacionados | Gestión de usuarios, bloqueo/revocación, asignación de perfiles, modificación de permisos permitidos | | Eventos de dominio | Creación, modificación, aprobación, activación, rechazo, revocación y expiración de la delegación | diff --git a/docs/governance/requirements-es/functional-stories/fs-15-notification-rules.md b/docs/governance/requirements-es/functional-stories/fs-15-notification-rules.md index 2a1b65ff..68bf3df7 100644 --- a/docs/governance/requirements-es/functional-stories/fs-15-notification-rules.md +++ b/docs/governance/requirements-es/functional-stories/fs-15-notification-rules.md @@ -1,4 +1,4 @@ -# Functional Story 15: Configurar Reglas de Notificación por Vencimiento +# Historia Funcional 15: Configurar Reglas de Notificación por Vencimiento ## 1. Propósito de Negocio @@ -12,11 +12,12 @@ Los administradores de cumplimiento necesitan advertir a los usuarios antes de q | :--- | :--- | | **Administrador de Cumplimiento** | Define tiempos y canales de notificación. | | **Usuario** | Recibe recordatorios de renovación. | -| **Motor de Cumplimiento** | Aplica reglas activas cuando los documentos se acercan al vencimiento. +| **Motor de Cumplimiento** | Aplica reglas activas cuando los documentos se acercan al vencimiento. | + ## 3. Precondiciones de Negocio -- El tipo de documento existe. -- El administrador tiene permiso para gestionar reglas de notificación. +* El tipo de documento existe. +* El administrador tiene permiso para gestionar reglas de notificación. --- @@ -62,16 +63,16 @@ Si ya existe una regla idéntica para el mismo documento, tenant, anticipación > [!NOTE] > En la implementación real de C# (base de código), `NotificationRule` es una Entidad hija encapsulada dentro del Agregado **DocumentType**, bajo el espacio de nombres unificado **Ums.Domain.Approvals**. -- Persistir reglas como parte del Agregado Root `DocumentType`. -- Campos obligatorios: `Code`, `Value` (JSON con tiempos y canales), `Description`. -- Aplicar unicidad por `Code`, `TenantId` y `DocumentTypeId`. -- Registrar trazabilidad de entrega de notificaciones. -- Soportar invalidación de caché cuando cambian reglas de notificación. +* Persistir reglas como parte del Agregado Root `DocumentType`. +* Campos obligatorios: `Code`, `Value` (JSON con tiempos y canales), `Description`. +* Aplicar unicidad por `Code`, `TenantId` y `DocumentTypeId`. +* Registrar trazabilidad de entrega de notificaciones. +* Soportar invalidación de caché cuando cambian reglas de notificación. --- ## 9. Trazabilidad -- Entidades: `DocumentType` (AR), `NotificationRule` (Entidad Hija), `UserDocument` (AR) -- ADRs: ADR-0045, ADR-0016 -- Historias relacionadas: FS-11, FS-16 +* Entidades: `DocumentType` (AR), `NotificationRule` (Entidad Hija), `UserDocument` (AR) +* ADRs: ADR-0045, ADR-0016 +* Historias relacionadas: FS-11, FS-16 diff --git a/docs/governance/requirements-es/functional-stories/fs-16-access-enforcement-policy.md b/docs/governance/requirements-es/functional-stories/fs-16-access-enforcement-policy.md index e5263aae..d4c26f26 100644 --- a/docs/governance/requirements-es/functional-stories/fs-16-access-enforcement-policy.md +++ b/docs/governance/requirements-es/functional-stories/fs-16-access-enforcement-policy.md @@ -1,4 +1,4 @@ -# Functional Story 16: Definir Política de Acceso por Vencimiento +# Historia Funcional 16: Definir Política de Acceso por Vencimiento > **Estado:** Implementado @@ -15,11 +15,12 @@ Los equipos de seguridad y cumplimiento necesitan definir qué debe ocurrir cuan | **Arquitecto de Seguridad** | Define el impacto de acceso por documentos críticos vencidos. | | **Administrador Global** | Publica o actualiza políticas de cumplimiento. | | **Usuario Afectado** | Recibe restricciones o advertencias según la política. | + ## 3. Precondiciones de Negocio -- La validación de cumplimiento documental está habilitada. -- El tipo de documento está marcado como relevante para control de acceso. -- El actor tiene permiso para gestionar políticas de enforcement. +* La validación de cumplimiento documental está habilitada. +* El tipo de documento está marcado como relevante para control de acceso. +* El actor tiene permiso para gestionar políticas de enforcement. --- @@ -70,25 +71,25 @@ Si el tipo de documento seleccionado no es crítico para acceso, el sistema impi > [!NOTE] > En la implementación real de C# (base de código), `AccessEnforcementPolicy` es una Entidad hija encapsulada dentro del Agregado **DocumentType**, bajo el espacio de nombres unificado **Ums.Domain.Approvals**. -- Persistir políticas como parte del Agregado Root `DocumentType`. -- Campos obligatorios: `Code`, `Value` (JSON con acciones de la política), `Description`. -- Aplicar unicidad por `Code`, alcance de tenant y `DocumentTypeId`. -- Acciones soportadas: `BLOCK_USER`, `RESTRICT_PROFILE` y `LOG_ONLY`. -- Permitir actualizaciones de la acción de la política mediante `PUT /access-enforcement-policies/{policyId}/action`. -- Registrar la ejecucion del enforcement a traves del flujo de documento de usuario para que el resultado aplicado siga siendo trazable. -- Emitir eventos de dominio y auditoría cuando se aplican o revierten restricciones. +* Persistir políticas como parte del Agregado Root `DocumentType`. +* Campos obligatorios: `Code`, `Value` (JSON con acciones de la política), `Description`. +* Aplicar unicidad por `Code`, alcance de tenant y `DocumentTypeId`. +* Acciones soportadas: `BLOCK_USER`, `RESTRICT_PROFILE` y `LOG_ONLY`. +* Permitir actualizaciones de la acción de la política mediante `PUT /access-enforcement-policies/{policyId}/action`. +* Registrar la ejecucion del enforcement a traves del flujo de documento de usuario para que el resultado aplicado siga siendo trazable. +* Emitir eventos de dominio y auditoría cuando se aplican o revierten restricciones. --- ## 9. Trazabilidad -- Entidades: `DocumentType` (AR), `AccessEnforcementPolicy` (Entidad Hija), `UserAccount` (AR), `Profile` (AR) -- ADRs: ADR-0045, ADR-0035 -- Historias relacionadas: FS-11, FS-15 +* Entidades: `DocumentType` (AR), `AccessEnforcementPolicy` (Entidad Hija), `UserAccount` (AR), `Profile` (AR) +* ADRs: ADR-0045, ADR-0035 +* Historias relacionadas: FS-11, FS-15 ## 10. Evidencia de Pruebas de Aceptacion -- [`AccessEnforcementPolicyE2ETests.cs`](../../../../src/apps/ums.api/Ums.Presentation.IntegrationTest/E2E/AccessEnforcementPolicyE2ETests.cs) cubre creacion de la politica, GET por ID, actualizacion de la accion, desactivacion y la validacion cuando no se suministra `ProfileId` ni `RoleId`. -- [`UpdateAccessEnforcementActionCommandValidatorTests.cs`](../../../../src/apps/ums.api/Ums.Application.Test/Approvals/AccessEnforcementPolicy/Commands/UpdateAccessEnforcementActionCommandValidatorTests.cs) verifica que el comando acepte los nombres de accion del dominio `BlockUser`, `RestrictProfile` y `LogOnly`. -- [`AccessEnforcementPolicyCommandHandlerTests.cs`](../../../../src/apps/ums.api/Ums.Application.Test/Approvals/AccessEnforcementPolicy/AccessEnforcementPolicyCommandHandlerTests.cs) cubre los handlers de crear, desactivar y actualizar. -- [`UserDocumentEndpoints.cs`](../../../../src/apps/ums.api/Ums.Presentation/Endpoints/Approvals/UserDocument/UserDocumentEndpoints.cs) expone la ruta de ejecucion de enforcement usada para preservar la trazabilidad cuando se aplica la politica. +* [`AccessEnforcementPolicyE2ETests.cs`](../../../src/apps/ums.api/Ums.Presentation.IntegrationTest/E2E/AccessEnforcementPolicyE2ETests.cs) cubre creacion de la politica, GET por ID, actualizacion de la accion, desactivacion y la validacion cuando no se suministra `ProfileId` ni `RoleId`. +* [`UpdateAccessEnforcementActionCommandValidatorTests.cs`](../../../src/apps/ums.api/Ums.Application.Test/Approvals/AccessEnforcementPolicy/Commands/UpdateAccessEnforcementActionCommandValidatorTests.cs) verifica que el comando acepte los nombres de accion del dominio `BlockUser`, `RestrictProfile` y `LogOnly`. +* [`AccessEnforcementPolicyCommandHandlerTests.cs`](../../../src/apps/ums.api/Ums.Application.Test/Approvals/AccessEnforcementPolicy/AccessEnforcementPolicyCommandHandlerTests.cs) cubre los handlers de crear, desactivar y actualizar. +* [`UserDocumentEndpoints.cs`](../../../src/apps/ums.api/Ums.Presentation/Endpoints/Approvals/UserDocument/UserDocumentEndpoints.cs) expone la ruta de ejecucion de enforcement usada para preservar la trazabilidad cuando se aplica la politica. diff --git a/docs/governance/requirements-es/functional-stories/fs-17-maintain-system-roles.md b/docs/governance/requirements-es/functional-stories/fs-17-maintain-system-roles.md index ba38aae2..4d0d779f 100644 --- a/docs/governance/requirements-es/functional-stories/fs-17-maintain-system-roles.md +++ b/docs/governance/requirements-es/functional-stories/fs-17-maintain-system-roles.md @@ -1,4 +1,4 @@ -# Functional Story 17: Mantener Roles de una Suite del Sistema +# Historia Funcional 17: Mantener Roles de una Suite del Sistema > **Estado:** Implementado @@ -15,8 +15,8 @@ UMS debe permitir que los administradores de seguridad mantengan el catalogo de ## 3. Precondiciones de Negocio -- Existe una suite del sistema registrada. -- El administrador esta autorizado para mantener catalogos de autorizacion. +* Existe una suite del sistema registrada. +* El administrador esta autorizado para mantener catalogos de autorizacion. ## 4. Flujo Funcional Principal @@ -55,24 +55,24 @@ Si el padre seleccionado pertenece a otra suite o genera un ciclo, UMS rechaza e ## 8. Requisitos Tecnicos -- Agregado de dominio: `Ums.Domain.Authorization.Role.Role`. -- Los comandos usan endpoints REST anidados bajo `/system-suites/{systemSuiteId}/roles`. -- Las consultas usan GraphQL `rolesBySystemSuite(systemSuiteId)`. -- SQL Server persiste `Roles` con FK a `SystemSuites` y relacion propia opcional al padre. -- El filtrado de tenant en la aplicacion es obligatorio; los controles de base de datos son resguardos secundarios. -- Los comandos de rol usan Result Pattern y emiten eventos de ciclo de vida del rol. -- Las fallas de validacion o negocio retornan causas aptas para el usuario; los detalles tecnicos inesperados quedan solo en logs Serilog/Loki correlacionados por `ErrorId`. -- La vista React se localiza en espanol e ingles y valida las respuestas en tiempo de ejecucion. +* Agregado de dominio: `Ums.Domain.Authorization.Role.Role`. +* Los comandos usan endpoints REST anidados bajo `/system-suites/{systemSuiteId}/roles`. +* Las consultas usan el endpoint REST `GET /system-suites/{systemSuiteId}/roles`, resuelto por la query CQRS `GetRolesBySystemSuiteQuery` en la capa de aplicacion. +* PostgreSQL persiste `Roles` con FK a `SystemSuites` y relacion propia opcional al padre. +* El filtrado de tenant en la aplicacion es obligatorio; los controles de base de datos son resguardos secundarios. +* Los comandos de rol usan Result Pattern y emiten eventos de ciclo de vida del rol. +* Las fallas de validacion o negocio retornan causas aptas para el usuario; los detalles tecnicos inesperados quedan solo en logs Serilog/Loki correlacionados por `ErrorId`. +* La vista React se localiza en espanol e ingles y valida las respuestas en tiempo de ejecucion. ## 9. Trazabilidad -- Entidades: `SystemSuite`, `Role`, `PermissionTemplate`, `Profile` -- Historias relacionadas: FS-02, FS-04, FS-05, FS-12 -- Estandares: catalogo `code/value/description`, respuesta de errores segura para usuario, regla de aislamiento por tenant +* Entidades: `SystemSuite`, `Role`, `PermissionTemplate`, `Profile` +* Historias relacionadas: FS-02, FS-04, FS-05, FS-12 +* Estandares: catalogo `code/value/description`, respuesta de errores segura para usuario, regla de aislamiento por tenant ## 10. Evidencia de Pruebas de Aceptacion -- [`RoleE2ETests.cs`](../../../../src/apps/ums.api/Ums.Presentation.IntegrationTest/E2E/RoleE2ETests.cs) cubre creacion de roles, visibilidad via GraphQL, actualizacion, desactivacion, reactivacion y proteccion por codigo duplicado. -- [`RoleCommandHandlerTests.cs`](../../../../src/apps/ums.api/Ums.Application.Test/Authorization/Role/RoleCommandHandlerTests.cs) cubre creacion, rechazo por codigo duplicado, validacion de alcance por tenant, rechazo de ciclos y cambios de estado. -- [`RoleQueries.cs`](../../../../src/apps/ums.api/Ums.Presentation/GraphQL/Authorization/RoleQueries.cs) y [`RoleEndpoints.cs`](../../../../src/apps/ums.api/Ums.Presentation/Endpoints/Authorization/Role/RoleEndpoints.cs) exponen el contrato de consulta `rolesBySystemSuite` y las rutas de comando usadas por la UI. -- [`SystemSuiteRolesPanel.tsx`](../../../../src/apps/ums.web-app/src/presentation/authorization/system-suite/components/SystemSuiteRolesPanel.tsx) proporciona la interfaz localizada para mantener roles en la suite del sistema seleccionada. +* [`RoleE2ETests.cs`](../../../src/apps/ums.api/Ums.Presentation.IntegrationTest/E2E/RoleE2ETests.cs) cubre creacion de roles, visibilidad via API REST, actualizacion, desactivacion, reactivacion y proteccion por codigo duplicado. +* [`RoleCommandHandlerTests.cs`](../../../src/apps/ums.api/Ums.Application.Test/Authorization/Role/RoleCommandHandlerTests.cs) cubre creacion, rechazo por codigo duplicado, validacion de alcance por tenant, rechazo de ciclos y cambios de estado. +* [`GetRolesBySystemSuiteQueryHandler.cs`](../../../src/apps/ums.api/Ums.Application/Authorization/Role/Queries/GetRolesBySystemSuiteQueryHandler.cs) y [`RoleEndpoints.cs`](../../../src/apps/ums.api/Ums.Presentation/Endpoints/Authorization/Role/RoleEndpoints.cs) exponen el endpoint REST `GET /system-suites/{systemSuiteId}/roles` y las rutas de comando usadas por la UI. +* [`SystemSuiteRolesPanel.tsx`](../../../src/apps/ums.web-app/src/presentation/authorization/system-suite/components/SystemSuiteRolesPanel.tsx) proporciona la interfaz localizada para mantener roles en la suite del sistema seleccionada. diff --git a/docs/governance/requirements-es/functional-stories/fs-18-manage-local-user-password.md b/docs/governance/requirements-es/functional-stories/fs-18-manage-local-user-password.md index ab51dece..3e8a5313 100644 --- a/docs/governance/requirements-es/functional-stories/fs-18-manage-local-user-password.md +++ b/docs/governance/requirements-es/functional-stories/fs-18-manage-local-user-password.md @@ -1,4 +1,4 @@ -# Functional Story 18: Gestionar la Contraseña Local de un Usuario +# Historia Funcional 18: Gestionar la Contraseña Local de un Usuario ## 1. Propósito de Negocio @@ -13,9 +13,9 @@ UMS debe permitir que un administrador autorizado establezca o rote la contrase ## 3. Precondiciones de Negocio -- La cuenta de usuario existe en el tenant seleccionado. -- La cuenta usa autenticación interna y no está vinculada a un proveedor de identidad externo. -- El administrador está autorizado para gestionar credenciales de usuarios. +* La cuenta de usuario existe en el tenant seleccionado. +* La cuenta usa autenticación interna y no está vinculada a un proveedor de identidad externo. +* El administrador está autorizado para gestionar credenciales de usuarios. ## 4. Flujo Funcional Principal @@ -58,17 +58,17 @@ Si la operación no puede completarse, UMS muestra una razón clara cuando está ## 8. Requisitos Técnicos -- `PasswordCredential` permanece como entidad propiedad del agregado `UserAccount` en el bounded context Identity. -- Los comandos son REST-first mediante `POST /user-accounts/{userAccountId}/passwords`; la solicitud lleva una contraseña temporal en texto claro sobre el transporte seguro y la API la protege con BCrypt antes de persistirla. -- Las consultas pueden exponer `hasActivePassword` y `passwordUpdatedAtUtc`; `PasswordHash` y los identificadores de credenciales históricas no deben exponerse al cliente web. -- SQL Server con EF Core persiste credenciales dentro del límite transaccional de `UserAccount`. -- El filtrado de tenant en aplicacion permanece como control primario; PostgreSQL row-level security y politicas de base de datos permanecen como resguardos secundarios. -- Los errores operativos siguen el estándar de respuesta segura y correlacionan el diagnóstico Serilog/Loki mediante `ErrorId`. -- La vista React está localizada en español e inglés y valida la regla mínima de contraseña antes de ejecutar el comando. +* `PasswordCredential` permanece como entidad propiedad del agregado `UserAccount` en el bounded context Identity. +* Los comandos son REST-first mediante `POST /user-accounts/{userAccountId}/passwords`; la solicitud lleva una contraseña temporal en texto claro sobre el transporte seguro y la API la protege con BCrypt antes de persistirla. +* Las consultas pueden exponer `hasActivePassword` y `passwordUpdatedAtUtc`; `PasswordHash` y los identificadores de credenciales históricas no deben exponerse al cliente web. +* PostgreSQL con EF Core persiste credenciales dentro del límite transaccional de `UserAccount`. +* El filtrado de tenant en aplicacion permanece como control primario; PostgreSQL row-level security y politicas de base de datos permanecen como resguardos secundarios. +* Los errores operativos siguen el estándar de respuesta segura y correlacionan el diagnóstico Serilog/Loki mediante `ErrorId`. +* La vista React está localizada en español e inglés y valida la regla mínima de contraseña antes de ejecutar el comando. ## 9. Trazabilidad -- Entidades: `UserAccount`, `PasswordCredential`, `IdentityProvider` -- Historias relacionadas: FS-01, FS-03, FS-08, FS-09 -- ADR relacionado: ADR-0066 contrato de errores accionables para usuario -- Actualización de diagrama: `docs/domain-es/identity/password-credential.md`, ciclo de vida y propiedad de UserAccount, motivada por FS-18 +* Entidades: `UserAccount`, `PasswordCredential`, `IdentityProvider` +* Historias relacionadas: FS-01, FS-03, FS-08, FS-09 +* ADR relacionado: ADR-UMS-066 contrato de errores accionables para usuario +* Actualización de diagrama: `docs/domain-es/identity/password-credential.md`, ciclo de vida y propiedad de UserAccount, motivada por FS-18 diff --git a/docs/governance/requirements-es/functional-stories/fs-19-admin-password-reset-validity-management.md b/docs/governance/requirements-es/functional-stories/fs-19-admin-password-reset-validity-management.md index a00b83f4..18c968bc 100644 --- a/docs/governance/requirements-es/functional-stories/fs-19-admin-password-reset-validity-management.md +++ b/docs/governance/requirements-es/functional-stories/fs-19-admin-password-reset-validity-management.md @@ -14,11 +14,11 @@ UMS debe permitir que administradores autorizados puedan restablecer contraseña ## 3. Precondiciones de Negocio -- El administrador que realiza la acción está autenticado en el portal interno de UMS o en una sesión administrativa confiable y tiene un rol ADMIN en su alcance operativo. -- La cuenta de usuario objetivo existe y pertenece a un tenant dentro del alcance operativo del administrador. -- El administrador tiene el permiso requerido (`CAN_RESET_PASSWORD` y/o `CAN_MODIFY_VALIDITY_PERIOD`) asignado a su rol. -- Los feature flags que controlan estas capacidades están habilitados para el sistema o tenant. -- Las acciones administrativas limitadas al tenant solo están permitidas cuando el tenant está marcado como `IsManagementOwner=true`. +* El administrador que realiza la acción está autenticado en el portal interno de UMS o en una sesión administrativa confiable y tiene un rol ADMIN en su alcance operativo. +* La cuenta de usuario objetivo existe y pertenece a un tenant dentro del alcance operativo del administrador. +* El administrador tiene el permiso requerido (`CAN_RESET_PASSWORD` y/o `CAN_MODIFY_VALIDITY_PERIOD`) asignado a su rol. +* Los feature flags que controlan estas capacidades están habilitados para el sistema o tenant. +* Las acciones administrativas limitadas al tenant solo están permitidas cuando el tenant está marcado como `IsManagementOwner=true`. ## 4. Flujo Funcional Principal @@ -107,33 +107,33 @@ Si la operación no puede completarse debido a un error del sistema, UMS muestra ### 8.1 Autorización -- El flujo de gestión del portal debe resolver la autorización mediante el scope interno de UMS, no mediante el flujo IDP externo del tenant. -- `ITenantContext.OrganizationId` determina el alcance de tenant para operaciones limitadas al tenant. -- El flag `Tenant.IsManagementOwner` determina si el tenant puede realizar sus propias acciones de gestión interna. -- Las verificaciones de autorización en handlers deben validar: - - `targetUser.TenantId == OrganizationId` para operaciones limitadas al tenant - - el scope de plataforma permite operaciones cross-tenant desde el portal interno - - El rol admin tiene los permisos requeridos (`CAN_RESET_PASSWORD`, `CAN_MODIFY_VALIDITY_PERIOD`) -- Feature flags para estas capacidades se almacenan en tabla `FeatureFlags` con claves `ALLOW_PASSWORD_RESET_BY_ADMIN` y `ALLOW_VALIDITY_PERIOD_MODIFICATION`. +* El flujo de gestión del portal debe resolver la autorización mediante el scope interno de UMS, no mediante el flujo IDP externo del tenant. +* `ITenantContext.OrganizationId` determina el alcance de tenant para operaciones limitadas al tenant. +* El flag `Tenant.IsManagementOwner` determina si el tenant puede realizar sus propias acciones de gestión interna. +* Las verificaciones de autorización en handlers deben validar: + * `targetUser.TenantId == OrganizationId` para operaciones limitadas al tenant + * el scope de plataforma permite operaciones cross-tenant desde el portal interno + * El rol admin tiene los permisos requeridos (`CAN_RESET_PASSWORD`, `CAN_MODIFY_VALIDITY_PERIOD`) +* Feature flags para estas capacidades se almacenan en tabla `FeatureFlags` con claves `ALLOW_PASSWORD_RESET_BY_ADMIN` y `ALLOW_VALIDITY_PERIOD_MODIFICATION`. ### 8.2 Comandos | Comando | Endpoint | Descripción | -|---|---|---| +| --- | --- | --- | | `ResetUserPasswordCommand` | `POST /user-accounts/{userAccountId}/passwords/reset` | Restablecer contraseña para usuario objetivo | | `ModifyUserValidityPeriodCommand` | `PATCH /user-accounts/{userAccountId}/validity` | Modificar período de vigencia | ### 8.3 Eventos de Auditoría | Evento | Campos | -|---|---| +| --- | --- | | `PASSWORD_RESET` | `adminUserId`, `targetUserId`, `targetTenantId`, `timestamp`, `reason`, `effectiveImmediately` | | `VALIDITY_PERIOD_MODIFIED` | `adminUserId`, `targetUserId`, `targetTenantId`, `timestamp`, `previousExpiresAt`, `newExpiresAt`, `reason` | ### 8.4 Configuración (Parámetros Configurables) | Parámetro | Ubicación de Config | Default | -|---|---|---| +| --- | --- | --- | | `MAX_VALIDITY_PERIOD_DAYS` | `AppConfiguration` | 365 | | `MIN_PASSWORD_LENGTH` | `AppConfiguration` | 12 | | `PASSWORD_RESET_NOTIFICATION_CHANNEL` | `AppConfiguration` | email | @@ -142,14 +142,14 @@ Si la operación no puede completarse debido a un error del sistema, UMS muestra ### 8.5 Modelo de Datos -- `UserAccount` aggregate incluye `ValidityPeriod` value object con `CreatedAt`, `ExpiresAt`, `LastActivityAt`, `IsActive`. -- `PasswordCredential` es una entidad owned con `IsActive`, `CreatedAt`, `Historical` flag. -- Registros de auditoría almacenados en tabla `AuditRecords` con `OperationType`, `ActorId`, `TargetId`, `TargetType`, `TenantId`, `Timestamp`, `Details` (JSON). +* `UserAccount` aggregate incluye `ValidityPeriod` value object con `CreatedAt`, `ExpiresAt`, `LastActivityAt`, `IsActive`. +* `PasswordCredential` es una entidad owned con `IsActive`, `CreatedAt`, `Historical` flag. +* Registros de auditoría almacenados en tabla `AuditRecords` con `OperationType`, `ActorId`, `TargetId`, `TargetType`, `TenantId`, `Timestamp`, `Details` (JSON). ### 8.6 Códigos de Error | Código | Descripción | -|---|---| +| --- | --- | | `AUTH_009` | Administrador carece del permiso requerido | | `AUTH_010` | Usuario objetivo fuera del alcance del administrador | | `USER_015` | Usuario federado no puede tener contraseña local restablecida | @@ -157,7 +157,7 @@ Si la operación no puede completarse debido a un error del sistema, UMS muestra ## 9. Trazabilidad -- Entidades: `UserAccount`, `PasswordCredential`, `AuditRecord`, `FeatureFlag`, `AppConfiguration` -- Historias relacionadas: FS-01 (autenticación de usuario), FS-03 (registrar organización), FS-18 (gestionar contraseña local) -- ADRs relacionadas: ADR-0012 control de acceso basado en roles, ADR-0019 requisitos de historial de auditoría -- Actualización de diagrama: `docs/domain/identity/user-account.md` - agregar gestión de período de vigencia, `docs/governance/audit/audit-events.md` - agregar nuevos tipos de eventos +* Entidades: `UserAccount`, `PasswordCredential`, `AuditRecord`, `FeatureFlag`, `AppConfiguration` +* Historias relacionadas: FS-01 (autenticación de usuario), FS-03 (registrar organización), FS-18 (gestionar contraseña local) +* ADRs relacionadas: ADR-0012 control de acceso basado en roles, ADR-0019 requisitos de historial de auditoría +* Actualización de diagrama: `docs/domain/identity/user-account.md` - agregar gestión de período de vigencia, `docs/governance/audit/audit-events.md` - agregar nuevos tipos de eventos diff --git a/docs/governance/requirements-es/functional-stories/fs-20-system-parameter-management.md b/docs/governance/requirements-es/functional-stories/fs-20-system-parameter-management.md index d006af1f..47d21e36 100644 --- a/docs/governance/requirements-es/functional-stories/fs-20-system-parameter-management.md +++ b/docs/governance/requirements-es/functional-stories/fs-20-system-parameter-management.md @@ -14,10 +14,10 @@ UMS debe proporcionar un mecanismo seguro, configurable y auditable para gestion ## 3. Precondiciones de Negocio -- El administrador está autenticado y tiene una sesión válida en el portal interno de UMS o en una sesión administrativa confiable. -- El administrador tiene el permiso `CAN_MANAGE_GLOBAL_CONFIGURATION` (para config global) o `CAN_MANAGE_TENANT_CONFIGURATION` (para config específica de tenant). -- Para operaciones de tenant gestionadas desde el portal, `Tenant.IsManagementOwner=true`. -- Para admins de tenant, `OrganizationId` coincide con el tenant objetivo para operaciones específicas de tenant. +* El administrador está autenticado y tiene una sesión válida en el portal interno de UMS o en una sesión administrativa confiable. +* El administrador tiene el permiso `CAN_MANAGE_GLOBAL_CONFIGURATION` (para config global) o `CAN_MANAGE_TENANT_CONFIGURATION` (para config específica de tenant). +* Para operaciones de tenant gestionadas desde el portal, `Tenant.IsManagementOwner=true`. +* Para admins de tenant, `OrganizationId` coincide con el tenant objetivo para operaciones específicas de tenant. ## 4. Flujo Funcional Principal @@ -91,8 +91,9 @@ Si un admin interno intenta crear un parámetro con Scope Tenant sin especificar 5. **Versionado**: Los parámetros usan versionado semántico (`Major.Minor.Patch`). Las actualizaciones a Draft incrementan la versión menor. 6. **Ciclo de Vida del Estado**: Draft → Published → Archived. Solo parámetros en Draft pueden ser modificados. 7. **Matriz de Autorización**: + | Scope de Configuración | Admin Interno | Admin de Tenant | - |---------------------|----------------|----------------| + | --------------------- | ---------------- | ---------------- | | Global | Puede gestionar | No puede acceder | | Tenant (propio) | Puede gestionar | Puede gestionar | | Tenant (otro) | Puede gestionar | No puede acceder | @@ -132,7 +133,7 @@ if (targetTenantId != organizationId && !hasInternalPortalScope) ### 8.2 Endpoints | Método | Endpoint | Descripción | Autorización | -|--------|----------|-------------|---------------| +| -------- | ---------- | ------------- | --------------- | | GET | `/app-configurations` | Listar configuraciones (filtradas por scope y permisos de usuario) | Basado en scope | | GET | `/app-configurations/{id}` | Obtener una configuración | Basado en scope y propiedad | | POST | `/app-configurations` | Crear nueva configuración | Admin interno o admin de tenant para su propio scope de gestión | @@ -143,7 +144,7 @@ if (targetTenantId != organizationId && !hasInternalPortalScope) ### 8.3 Filtros de Consulta | Parámetro | Comportamiento | -|-----------|----------| +| ----------- | ---------- | | `scope=Global` | Solo administradores del portal interno pueden consultar; retorna todas las configs globales | | `scope=Tenant&tenantId={id}` | Administradores del portal interno obtienen todas las configs de tenant; admins de tenant obtienen solo su tenant cuando está permitido | | Sin filtro de scope | Retorna configs basadas en los permisos del usuario | @@ -151,7 +152,7 @@ if (targetTenantId != organizationId && !hasInternalPortalScope) ### 8.4 Valores Hardcodeados a Migrar | Hardcode Actual | Código de Parámetro | Valor Default | -|-----------------|-------------------|---------------| +| ----------------- | ------------------- | --------------- | | `ACCESS_TOKEN_DURATION` (frontend) | `ACCESS_TOKEN_DURATION_MS` | 3600000 (1 hora) | | `REFRESH_TOKEN_DURATION` (frontend) | `REFRESH_TOKEN_DURATION_MS` | 604800000 (7 días) | | `MIN_PASSWORD_LENGTH` | `MIN_PASSWORD_LENGTH` | 12 | @@ -160,7 +161,7 @@ if (targetTenantId != organizationId && !hasInternalPortalScope) ### 8.5 Eventos de Auditoría | Evento | Campos | -|---|---| +| --- | --- | | `APP_CONFIG_CREATED` | adminUserId, configId, code, scope, timestamp | | `APP_CONFIG_UPDATED` | adminUserId, configId, code, oldVersion, newVersion, timestamp | | `APP_CONFIG_PUBLISHED` | adminUserId, configId, code, version, timestamp | @@ -175,7 +176,7 @@ if (targetTenantId != organizationId && !hasInternalPortalScope) ## 9. Trazabilidad -- Entidades: `AppConfiguration`, `AuditRecord` -- Historias relacionadas: FS-01 (autenticación), FS-17 (roles de sistema), FS-19 (reset de contraseña admin) -- ADRs relacionadas: ADR-0012 (RBAC), ADR-0019 (trail de auditoría) -- Actualización de diagrama: `docs/domain/identity/tenant.md` sección 10 - agregar reglas de gestión de parámetros +* Entidades: `AppConfiguration`, `AuditRecord` +* Historias relacionadas: FS-01 (autenticación), FS-17 (roles de sistema), FS-19 (reset de contraseña admin) +* ADRs relacionadas: ADR-0012 (RBAC), ADR-0019 (trail de auditoría) +* Actualización de diagrama: `docs/domain/identity/tenant.md` sección 10 - agregar reglas de gestión de parámetros diff --git a/docs/governance/requirements-es/functional-stories/fs-21-tenant-signup-request-approval.md b/docs/governance/requirements-es/functional-stories/fs-21-tenant-signup-request-approval.md index 93080896..1bd2e44b 100644 --- a/docs/governance/requirements-es/functional-stories/fs-21-tenant-signup-request-approval.md +++ b/docs/governance/requirements-es/functional-stories/fs-21-tenant-signup-request-approval.md @@ -7,16 +7,16 @@ Las nuevas empresas necesitan una forma controlada de solicitar acceso a UMS e i ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | System Admin | Revisa las solicitudes de alta de empresa y decide si una nueva compania ingresa a UMS. | | Contacto de la Empresa | Envia los datos de la compania y recibe el resultado del onboarding. | | Usuario Administrador del Tenant | Recibe la primera cuenta administrativa creada para la compania aprobada. | ## 3. Precondiciones de Negocio -- La compania aun no esta registrada como tenant activo en UMS. -- El solicitante cuenta con nombre de empresa, codigo de referencia, nombre de contacto y correo de contacto validos. -- El System Admin tiene acceso al area de revision de onboarding. +* La compania aun no esta registrada como tenant activo en UMS. +* El solicitante cuenta con nombre de empresa, codigo de referencia, nombre de contacto y correo de contacto validos. +* El System Admin tiene acceso al area de revision de onboarding. ## 4. Flujo Funcional Principal @@ -46,7 +46,7 @@ Si mas adelante el negocio requiere verificacion de pago antes de admitir la emp ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | Las solicitudes de alta de empresa pertenecen al alcance global y solo las revisan System Admins. | | BR-02 | Un tenant solo se crea despues de aprobar la solicitud. | | BR-03 | El tenant aprobado debe recibir su primer usuario administrativo como parte del mismo resultado de aprobacion. | @@ -56,7 +56,7 @@ Si mas adelante el negocio requiere verificacion de pago antes de admitir la emp ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Una empresa puede enviar una solicitud de alta con los datos requeridos de compania y contacto. | | 2 | La solicitud aparece como pendiente en la bandeja global de onboarding. | | 3 | Solo los System Admins pueden revisar y aprobar o rechazar la solicitud. | @@ -66,19 +66,18 @@ Si mas adelante el negocio requiere verificacion de pago antes de admitir la emp ## 8. Requisitos Tecnicos -- Persistir las solicitudes de onboarding en el agregado `TenantSignupRequest` con estados `Pending`, `Approved` y `Rejected`. -- Mantener anonimo y sin contexto de tenant el punto de entrada publico de la solicitud. -- Usar un read model compuesto de bandeja de aprobacion en la UI en lugar de una tabla generica adicional de inbox. -- Crear el tenant y el primer usuario administrativo como parte del comando de aprobacion. -- Enviar la notificacion de aprobacion con la contrasena temporal generada y los datos de la cuenta. -- Reservar espacio para futuros estados de verificacion de pago en el modelo de estados y la documentacion. +* Persistir las solicitudes de onboarding en el agregado `TenantSignupRequest` con estados `Pending`, `Approved` y `Rejected`. +* Mantener anonimo y sin contexto de tenant el punto de entrada publico de la solicitud. +* Usar un read model compuesto de bandeja de aprobacion en la UI en lugar de una tabla generica adicional de inbox. +* Crear el tenant y el primer usuario administrativo como parte del comando de aprobacion. +* Enviar la notificacion de aprobacion con la contrasena temporal generada y los datos de la cuenta. +* Reservar espacio para futuros estados de verificacion de pago en el modelo de estados y la documentacion. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Historias Funcionales | FS-22 | | Entidades de Dominio | `TenantSignupRequest`, `Tenant`, `UserAccount` | | Notificaciones | `TenantSignupRequestReceived`, `TenantSignupApproved` | -| ADRs | ADR-0075 | - +| ADRs | ADR-UMS-075 | diff --git a/docs/governance/requirements-es/functional-stories/fs-22-user-signup-request-approval.md b/docs/governance/requirements-es/functional-stories/fs-22-user-signup-request-approval.md index 8957e8f9..ccb68a8f 100644 --- a/docs/governance/requirements-es/functional-stories/fs-22-user-signup-request-approval.md +++ b/docs/governance/requirements-es/functional-stories/fs-22-user-signup-request-approval.md @@ -9,16 +9,16 @@ Los usuarios que desean unirse a un tenant existente necesitan una ruta controla ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Solicitante | Pide acceso a un tenant existente y envia los datos de identidad requeridos. | | Tenant Admin | Revisa las solicitudes pendientes de acceso del tenant y aprueba o deniega cuando corresponde. | | Solicitante | Recibe la notificacion final de onboarding despues de que la solicitud es aprobada o denegada. | ## 3. Precondiciones de Negocio -- El tenant objetivo ya existe en UMS. -- El solicitante tiene nombre, correo electronico y contrasena que cumplen las reglas de alta. -- El Tenant Admin tiene acceso a la bandeja de onboarding del tenant. +* El tenant objetivo ya existe en UMS. +* El solicitante tiene nombre, correo electronico y contrasena que cumplen las reglas de alta. +* El Tenant Admin tiene acceso a la bandeja de onboarding del tenant. ## 4. Flujo Funcional Principal @@ -52,7 +52,7 @@ Si el Tenant Admin deniega la solicitud, el requerimiento llega a un estado term ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | Las solicitudes de alta de usuario pertenecen solo al tenant objetivo. | | BR-02 | Los Tenant Admins solo pueden revisar solicitudes de su propio tenant. | | BR-03 | Una solicitud pendiente no otorga acceso hasta ser aprobada. | @@ -66,7 +66,7 @@ Si el Tenant Admin deniega la solicitud, el requerimiento llega a un estado term ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Un solicitante puede enviar una solicitud de alta completa para un tenant existente. | | 2 | La solicitud se guarda como pendiente y aparece en la bandeja de onboarding del tenant. | | 3 | Solo el tenant objetivo puede ver la solicitud. | @@ -78,26 +78,26 @@ Si el Tenant Admin deniega la solicitud, el requerimiento llega a un estado term ## 8. Requisitos Tecnicos -- Persistir la solicitud como un `UserAccount` en estado `Pending` en lugar de crear una tabla separada de onboarding. -- Mantener anonimo el endpoint publico de solicitud y usar el cliente publico sin encabezados de tenant. -- Usar scope por tenant para asegurar que las consultas de la bandeja solo devuelvan las cuentas pendientes del tenant actual. -- Reutilizar el flujo de activacion existente para aprobar la solicitud y emitir la notificacion de aprobacion. -- Agregar un comando explicito de denegacion o una operacion equivalente de aplicacion que registre denegacion terminal sin activar la cuenta. -- Persistir metadata de ciclo de vida para envio, decision, aprobador, estado final y motivo opcional de denegacion en forma auditable. -- Mantener la bandeja como una composicion UI sobre el listado de cuentas para que el flujo siga alineado con el modelo central de cuentas. -- Agregar o mapear plantillas de notificacion para resultados finales aprobados y denegados. +* Persistir la solicitud como un `UserAccount` en estado `Pending` en lugar de crear una tabla separada de onboarding. +* Mantener anonimo el endpoint publico de solicitud y usar el cliente publico sin encabezados de tenant. +* Usar scope por tenant para asegurar que las consultas de la bandeja solo devuelvan las cuentas pendientes del tenant actual. +* Reutilizar el flujo de activacion existente para aprobar la solicitud y emitir la notificacion de aprobacion. +* Agregar un comando explicito de denegacion o una operacion equivalente de aplicacion que registre denegacion terminal sin activar la cuenta. +* Persistir metadata de ciclo de vida para envio, decision, aprobador, estado final y motivo opcional de denegacion en forma auditable. +* Mantener la bandeja como una composicion UI sobre el listado de cuentas para que el flujo siga alineado con el modelo central de cuentas. +* Agregar o mapear plantillas de notificacion para resultados finales aprobados y denegados. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Historias Funcionales | FS-22 | | Entidades de Dominio | `UserAccount`, `Tenant` | | Notificaciones | `UserSignupRequestReceived`, `UserSignupApproved`, `UserSignupDenied` | -| ADRs | ADR-0075 | +| ADRs | ADR-UMS-075 | ## 10. Evidencia de Pruebas de Aceptacion -- [`UserAccountOnboardingCommandHandlerTests.cs`](../../../../src/apps/ums.api/Ums.Application.Test/Identity/UserAccount/UserAccountOnboardingCommandHandlerTests.cs) cubre visibilidad de solicitudes pendientes, denegacion, alcance por tenant y manejo de estados finales. -- [`UserAccountCommandHandlerTests.cs`](../../../../src/apps/ums.api/Ums.Application.Test/Identity/UserAccount/UserAccountCommandHandlerTests.cs) cubre la activacion de una cuenta pendiente y la transicion al estado aprobado usada por el flujo de onboarding. -- [`UserAccountEndpoints.cs`](../../../../src/apps/ums.api/Ums.Presentation/Endpoints/Identity/UserAccount/UserAccountEndpoints.cs) y [`OnboardingInboxEndpoints.cs`](../../../../src/apps/ums.api/Ums.Presentation/Endpoints/Identity/Onboarding/OnboardingInboxEndpoints.cs) exponen la bandeja y las rutas de accion terminal usadas por la historia. +* [`UserAccountOnboardingCommandHandlerTests.cs`](../../../src/apps/ums.api/Ums.Application.Test/Identity/UserAccount/UserAccountOnboardingCommandHandlerTests.cs) cubre visibilidad de solicitudes pendientes, denegacion, alcance por tenant y manejo de estados finales. +* [`UserAccountCommandHandlerTests.cs`](../../../src/apps/ums.api/Ums.Application.Test/Identity/UserAccount/UserAccountCommandHandlerTests.cs) cubre la activacion de una cuenta pendiente y la transicion al estado aprobado usada por el flujo de onboarding. +* [`UserAccountEndpoints.cs`](../../../src/apps/ums.api/Ums.Presentation/Endpoints/Identity/UserAccount/UserAccountEndpoints.cs) y [`OnboardingInboxEndpoints.cs`](../../../src/apps/ums.api/Ums.Presentation/Endpoints/Identity/Onboarding/OnboardingInboxEndpoints.cs) exponen la bandeja y las rutas de accion terminal usadas por la historia. diff --git a/docs/governance/requirements-es/functional-stories/fs-23-profile-access-request.md b/docs/governance/requirements-es/functional-stories/fs-23-profile-access-request.md index 3641cf04..bfc19f5f 100644 --- a/docs/governance/requirements-es/functional-stories/fs-23-profile-access-request.md +++ b/docs/governance/requirements-es/functional-stories/fs-23-profile-access-request.md @@ -1,89 +1,89 @@ -# FS-23: Solicitud de Perfil desde Usuario en Lobby +# FS-23: Solicitud de Acceso a Perfil desde Usuario en Lobby -## 1. Proposito de Negocio +## 1. Propósito de Negocio -Los usuarios admitidos a un tenant aun pueden necesitar un perfil de negocio antes de usar menus operativos. UMS debe permitir que un usuario autenticado sin perfil asignado solicite el acceso necesario para su trabajo, sin otorgar permisos automaticamente, y debe trazar la solicitud hasta que un aprobador autorizado la cierre. +Los usuarios admitidos a un tenant todavía pueden necesitar el perfil de negocio correcto antes de usar los menús operativos. UMS debe permitir que un usuario autenticado sin perfil asignado solicite el acceso que necesita para su trabajo, sin conceder permisos automáticamente, y debe rastrear la solicitud hasta que un aprobador autorizado la cierre. ## 2. Actores | Actor | Responsabilidad | -|---|---| -| Usuario en Lobby | Usuario autenticado y admitido al tenant, pero sin perfil activo. | -| Tenant Admin | Recibe solicitudes de perfil y valida si el acceso corresponde. | -| Gerente de Sucursal | Puede revisar solicitudes de usuarios de una sucursal especifica cuando exista delegacion del tenant. | +| --- | --- | +| Usuario en Lobby | Usuario autenticado admitido al tenant pero sin un perfil activo. | +| Administrador de Tenant | Recibe solicitudes de perfil y valida si el acceso es apropiado. | +| Administrador de Sucursal | Puede revisar solicitudes para usuarios que trabajan en una sucursal específica cuando el tenant lo delega. | ## 3. Precondiciones de Negocio -- La cuenta del usuario esta activa para el tenant. -- El usuario no tiene perfil activo para el sistema o alcance solicitado. -- El tenant tiene al menos un sistema, una sucursal y un rol disponibles para solicitud. +* La cuenta del usuario está activa para el tenant. +* El usuario no tiene un perfil activo para el sistema o alcance solicitado. +* El tenant tiene al menos un sistema, una sucursal y un rol disponibles para solicitar. ## 4. Flujo Funcional Principal -1. El usuario inicia sesion correctamente y llega a la pantalla de lobby. -2. El lobby explica que el usuario pertenece al tenant pero aun no tiene perfil asignado. +1. El usuario inicia sesión correctamente y llega a la pantalla de lobby. +2. El lobby explica que el usuario pertenece al tenant, pero aún no tiene un perfil asignado. 3. El usuario abre el formulario de solicitud de perfil. -4. El usuario selecciona el sistema, luego la sucursal y finalmente el rol sugerido. -5. El usuario puede ingresar una justificacion de negocio. -6. El sistema guarda la solicitud como pendiente de asignacion. +4. El usuario selecciona el sistema, luego la sucursal y luego el rol sugerido. +5. El usuario puede ingresar una justificación de negocio. +6. El sistema almacena la solicitud como pendiente de asignación. 7. La solicitud aparece en la bandeja de solicitudes de perfil del aprobador responsable. -8. El usuario puede ver que la solicitud sigue pendiente hasta que exista una decision final aprobada o denegada. +8. El usuario puede ver que la solicitud está pendiente hasta que se tome una decisión final aprobada o denegada. ## 5. Flujos Alternativos y Excepciones -### A. Sin Roles Disponibles +### A. No hay roles disponibles -Si no existe un rol disponible para el sistema y la sucursal seleccionados, el usuario no puede enviar la solicitud y se le indica contactar al administrador del tenant. +Si no hay ningún rol disponible para el sistema y la sucursal seleccionados, el usuario no puede enviar la solicitud y se le indica que contacte al administrador del tenant. -### B. Perfil Activo Existente +### B. Perfil activo existente -Si el usuario ya tiene un perfil activo para el mismo sistema y sucursal, el sistema evita una solicitud duplicada y muestra el estado de acceso existente. +Si el usuario ya tiene un perfil activo para el mismo sistema y la misma sucursal, el sistema impide una solicitud duplicada y muestra el estado de acceso existente. -### C. Solicitud Ya Pendiente +### C. Solicitud ya pendiente -Si el mismo usuario ya tiene una solicitud pendiente para el sistema y sucursal seleccionados, el sistema muestra la solicitud pendiente en vez de crear otra. +Si el mismo usuario ya tiene una solicitud pendiente para el sistema y la sucursal seleccionados, el sistema muestra la solicitud pendiente en lugar de crear otra. ## 6. Reglas de Negocio -| Regla | Descripcion | -|---|---| -| BR-01 | El acceso al tenant y la autorizacion por perfil son fases separadas. | -| BR-02 | Un usuario en lobby puede autenticarse pero no debe ver menus operativos hasta tener un perfil asignado. | -| BR-03 | La solicitud debe capturar sistema, sucursal, rol sugerido y justificacion opcional. | +| Regla | Descripción | +| --- | --- | +| BR-01 | El acceso al tenant y la autorización de perfil son fases separadas. | +| BR-02 | Un usuario en lobby puede autenticarse, pero no debe ver menús operativos hasta que se asigne un perfil. | +| BR-03 | La solicitud debe capturar sistema, sucursal, rol sugerido y justificación opcional. | | BR-04 | La solicitud permanece pendiente hasta que un aprobador autorizado decida. | | BR-05 | No se permiten solicitudes pendientes duplicadas para el mismo usuario, sistema y sucursal. | -| BR-06 | El ciclo de vida de cada solicitud de perfil debe ser trazable dentro del tenant desde el envio hasta el cierre final. | -| BR-07 | Los resultados finales de negocio son Aprobado y Denegado; la aprobacion puede otorgar el rol solicitado o un rol modificado. | -| BR-08 | El solicitante debe ser notificado automaticamente cuando la solicitud de perfil llegue a un resultado final. | +| BR-06 | Cada ciclo de vida de la solicitud de perfil debe ser trazable dentro del tenant desde el envío hasta el cierre final. | +| BR-07 | Los resultados finales de negocio son Aprobado y Denegado; la aprobación puede otorgar el rol solicitado o un rol modificado. | +| BR-08 | El solicitante debe ser notificado automáticamente cuando la solicitud de perfil alcance un resultado final. | -## 7. Criterios de Aceptacion +## 7. Criterios de Aceptación -| # | Criterio de Aceptacion | -|---|---| -| 1 | Un usuario activo sin perfil aterriza en el lobby despues del login. | +| # | Criterio de Aceptación | +| --- | --- | +| 1 | Un usuario activo sin perfil aterriza en el lobby después de iniciar sesión. | | 2 | El usuario en lobby puede solicitar un perfil seleccionando sistema, sucursal y rol sugerido. | | 3 | Las opciones de sucursal y rol dependen de las selecciones previas. | -| 4 | El usuario puede incluir una justificacion de negocio. | -| 5 | La solicitud se guarda como pendiente de asignacion. | -| 6 | El usuario no recibe acceso a menus operativos antes de la aprobacion. | -| 7 | El usuario puede ver el estado pendiente mientras la solicitud espera decision. | -| 8 | El usuario recibe notificacion cuando la solicitud es aprobada o denegada. | - -## 8. Requisitos Tecnicos - -- Introducir un modelo de solicitud de acceso a perfil o reutilizar el modelo existente de aprobaciones con un tipo de solicitud de asignacion de perfil. -- Persistir sistema solicitado, sucursal, rol solicitado, justificacion, solicitante, tenant y estado. -- Persistir metadata de ciclo de vida para envio, estado actual, resultado final, aprobador, fecha de decision y motivo de decision. -- Retornar una respuesta controlada de lobby cuando el grafo de autorizacion no pueda resolver un perfil activo para el usuario autenticado. -- Mantener la ruta de lobby fuera de los menus operativos y disponible solo despues de autenticacion exitosa. -- Aplicar filtrado por tenant en capa de aplicacion como mecanismo primario de aislamiento. -- Agregar o mapear plantillas de notificacion para aprobacion y denegacion final de solicitud de perfil. +| 4 | El usuario puede incluir una justificación de negocio. | +| 5 | La solicitud se almacena como asignación pendiente. | +| 6 | El usuario no recibe acceso a menús operativos antes de la aprobación. | +| 7 | El usuario puede ver el estado pendiente mientras la solicitud espera una decisión. | +| 8 | El usuario es notificado cuando la solicitud es aprobada o denegada. | + +## 8. Requisitos Técnicos + +* Introducir un modelo de solicitud de acceso a perfil o reutilizar el modelo de solicitud de aprobación existente con un tipo de solicitud de asignación de perfil. +* Persistir sistema solicitado, sucursal solicitada, rol solicitado, justificación, solicitante, tenant y estado. +* Persistir metadatos del ciclo de vida para envío, estado actual, resultado final, aprobador, fecha de decisión y motivo de decisión. +* Devolver una respuesta controlada del lobby cuando el grafo de autorización no pueda resolver un perfil activo para el usuario autenticado. +* Mantener la ruta del lobby fuera de los menús operativos y disponible solo después de autenticación correcta. +* Aplicar el filtrado de tenant en la capa de aplicación como mecanismo primario de aislamiento. +* Agregar o mapear plantillas de notificación para la aprobación y la denegación final de la solicitud de perfil. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| -| Historias Relacionadas | FS-22, FS-24, FS-05 | -| Entidades de Dominio | `UserAccount`, `Profile`, `Role`, `SystemSuite`, `Branch`, `ApprovalRequest` | +| --- | --- | +| Historias relacionadas | FS-22, FS-24, FS-05 | +| Entidades de dominio | `UserAccount`, `Profile`, `Role`, `SystemSuite`, `Branch`, `ApprovalRequest` | | Notificaciones | `ProfileRequestApproved`, `ProfileRequestDenied` | -| ADRs | ADR-0075, ADR-0071 | +| ADRs | ADR-UMS-075, ADR-UMS-088 | diff --git a/docs/governance/requirements-es/functional-stories/fs-24-profile-request-approval.md b/docs/governance/requirements-es/functional-stories/fs-24-profile-request-approval.md index 32ea0368..6c462e7d 100644 --- a/docs/governance/requirements-es/functional-stories/fs-24-profile-request-approval.md +++ b/docs/governance/requirements-es/functional-stories/fs-24-profile-request-approval.md @@ -1,92 +1,92 @@ -# FS-24: Aprobacion de Solicitud de Perfil y Asignacion Manual +# FS-24: Aprobación de Solicitud de Perfil y Asignación Manual -## 1. Proposito de Negocio +## 1. Propósito de Negocio -Los administradores de tenant y gerentes de sucursal delegados necesitan revisar solicitudes de perfil antes de que los usuarios reciban acceso operativo. UMS debe soportar aprobacion, modificacion y denegacion para que el perfil asignado corresponda a la necesidad real de negocio, el ciclo de vida de la solicitud quede cerrado y la decision quede auditada. +Los administradores de tenant y los administradores delegados de sucursal necesitan revisar las solicitudes de perfil antes de que los usuarios reciban acceso operativo. UMS debe soportar aprobación, modificación y denegación para que el perfil asignado coincida con la necesidad real del negocio, el ciclo de vida de la solicitud se cierre y la decisión quede auditable. ## 2. Actores | Actor | Responsabilidad | -|---|---| -| Tenant Admin | Revisa solicitudes de perfil en todo el tenant y asigna el perfil final. | -| Gerente de Sucursal | Revisa solicitudes de perfil dentro del alcance de sucursal delegado. | -| Usuario en Lobby | Recibe la decision y obtiene acceso solo despues de que se asigna un perfil. | -| Auditor | Revisa quien aprobo el acceso, cuando y que rol fue otorgado. | +| --- | --- | +| Administrador de Tenant | Revisa solicitudes de perfil en todo el tenant y asigna el perfil final. | +| Administrador de Sucursal | Revisa solicitudes de perfil dentro del alcance delegado de la sucursal. | +| Usuario en Lobby | Recibe la decisión y obtiene acceso solo después de que se asigne un perfil. | +| Auditor | Revisa quién aprobó el acceso, cuándo y qué rol se otorgó. | ## 3. Precondiciones de Negocio -- Existe una solicitud de perfil en estado pendiente de asignacion. -- El aprobador tiene autoridad sobre el tenant o la sucursal. -- El sistema, la sucursal y el rol solicitados siguen activos. +* Existe una solicitud de perfil en estado pendiente de asignación. +* El aprobador tiene autoridad sobre el alcance del tenant o de la sucursal. +* El sistema, la sucursal y el rol solicitados siguen activos. ## 4. Flujo Funcional Principal 1. El aprobador abre la bandeja de solicitudes de perfil. -2. El aprobador revisa usuario, sistema, sucursal, rol sugerido y justificacion. +2. El aprobador revisa el usuario, el sistema, la sucursal, el rol sugerido y la justificación. 3. El sistema advierte al aprobador sobre conflictos visibles o condiciones de riesgo de rol. -4. El aprobador elige uno de tres resultados: aprobar como fue solicitado, aprobar con un rol diferente o denegar. +4. El aprobador elige uno de tres resultados: aprobar tal como se solicitó, aprobar con un rol diferente o denegar. 5. Si se aprueba, el sistema asigna el perfil final al usuario. -6. El sistema registra quien aprobo la asignacion, cuando ocurrio y que rol fue otorgado. -7. Si se deniega, el sistema cierra la solicitud sin asignar perfil. -8. El usuario recibe una notificacion indicando que la decision del perfil fue completada. +6. El sistema registra quién aprobó la asignación, cuándo ocurrió y qué rol se otorgó. +7. Si se deniega, el sistema cierra la solicitud sin asignar un perfil. +8. El usuario es notificado de que la decisión del perfil está completa. ## 5. Flujos Alternativos y Excepciones -### A. Aprobacion con Rol Modificado +### A. Aprobación con rol modificado -El aprobador puede aprobar la solicitud con un rol distinto al solicitado cuando se requiere un nivel de acceso menor o mas adecuado. +El aprobador puede aprobar la solicitud con un rol distinto del solicitado cuando se requiere un nivel de acceso más bajo o más apropiado. -### B. Denegacion +### B. Denegación -El aprobador puede denegar la solicitud. El usuario permanece sin acceso operativo para ese sistema y sucursal. +El aprobador puede denegar la solicitud. El usuario permanece sin acceso operativo para ese sistema y esa sucursal. -### C. Advertencia de Conflicto +### C. Advertencia de conflicto -Si el rol seleccionado entra en conflicto con roles existentes o crea un riesgo de segregacion de funciones, el sistema advierte al aprobador antes de completar la decision. +Si el rol seleccionado entra en conflicto con roles existentes o crea un riesgo de segregación de funciones, el sistema advierte al aprobador antes de completar la decisión. ## 6. Reglas de Negocio -| Regla | Descripcion | -|---|---| -| BR-01 | La aprobacion debe limitarse al alcance de tenant o sucursal delegada del aprobador. | -| BR-02 | El aprobador puede otorgar el rol solicitado o un rol distinto dentro de su autoridad. | -| BR-03 | La denegacion debe mantener al usuario sin acceso operativo para el alcance solicitado. | -| BR-04 | El rol final, aprobador, fecha de decision y motivo deben quedar auditados. | -| BR-05 | Las advertencias de conflicto de roles y segregacion de funciones deben mostrarse antes de la aprobacion final cuando sean detectables. | +| Regla | Descripción | +| --- | --- | +| BR-01 | La aprobación debe limitarse al alcance del tenant o de la sucursal delegada del aprobador. | +| BR-02 | El aprobador puede otorgar el rol solicitado o un rol diferente dentro de su autoridad. | +| BR-03 | La denegación debe mantener al usuario sin acceso operativo para el alcance solicitado. | +| BR-04 | El rol final, el aprobador, la fecha de decisión y el motivo de la decisión deben ser auditables. | +| BR-05 | Las advertencias de conflicto de rol y segregación de funciones deben mostrarse antes de la aprobación final cuando puedan detectarse. | | BR-06 | Toda solicitud de perfil debe llegar a un estado terminal Aprobado o Denegado. | -| BR-07 | La decision final debe disparar una notificacion automatica al solicitante. | -| BR-08 | Las solicitudes no pueden eliminarse u ocultarse como sustituto de una decision final. | +| BR-07 | Una decisión final debe activar una notificación automática al solicitante. | +| BR-08 | Las solicitudes no pueden eliminarse ni ocultarse como sustituto de una decisión final. | -## 7. Criterios de Aceptacion +## 7. Criterios de Aceptación -| # | Criterio de Aceptacion | -|---|---| +| # | Criterio de Aceptación | +| --- | --- | | 1 | Un aprobador autorizado puede ver solicitudes de perfil pendientes dentro de su alcance. | | 2 | El aprobador puede aprobar el rol solicitado. | | 3 | El aprobador puede aprobar la solicitud con un rol diferente. | | 4 | El aprobador puede denegar la solicitud. | -| 5 | El sistema registra aprobador, fecha, rol otorgado y resultado de la decision. | -| 6 | El usuario recibe notificacion despues de aprobacion o denegacion. | -| 7 | El sistema advierte sobre conflictos de roles detectables antes de aprobar. | +| 5 | El sistema registra aprobador, fecha, rol otorgado y resultado de la decisión. | +| 6 | El usuario es notificado después de la aprobación o la denegación. | +| 7 | El sistema advierte sobre conflictos de rol detectables antes de la aprobación. | | 8 | Una solicitud decidida queda cerrada y ya no aparece como pendiente. | -## 8. Requisitos Tecnicos +## 8. Requisitos Técnicos -- Reutilizar o extender el modelo de aprobaciones para decisiones `PROFILE_ASSIGNMENT`. -- Guardar el rol solicitado y el rol otorgado por separado. -- Registrar metadata de decision en registros de auditoria inmutables. -- Invocar la asignacion de perfil solo despues de la aprobacion. -- Invalidar el grafo de autorizacion del usuario despues de asignar el perfil. -- Preparar el modelo de ruteo de aprobaciones para delegacion por sucursal. -- Exponer estados terminales como Aprobado y Denegado en vistas de usuario y auditoria, aunque eventos internos reutilicen terminologia existente de rechazo. -- Emitir eventos o plantillas de notificacion para resultados finales aprobados y denegados. +* Reutilizar o extender el modelo de solicitud de aprobación para decisiones de `PROFILE_ASSIGNMENT`. +* Almacenar por separado el rol solicitado y el rol otorgado. +* Registrar metadatos de decisión en registros de auditoría inmutables. +* Invocar la asignación de perfil solo después de aprobar. +* Invalidar el grafo de autorización del usuario después de la asignación de perfil. +* Preparar el modelo de enrutamiento de aprobación para la delegación con alcance de sucursal. +* Exponer los estados terminales como Aprobado y Denegado en las vistas de usuario y auditoría, aunque los eventos internos reutilicen la terminología de rechazo existente. +* Emitir eventos y plantillas de notificación para ambos resultados finales: aprobado y denegado. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| -| Historias Relacionadas | FS-23, FS-05, FS-07, FS-14 | -| Entidades de Dominio | `ApprovalRequest`, `Profile`, `Role`, `UserAccount`, `Branch` | -| Eventos de Dominio | `ProfileAssignedToUserEvent`, `ApprovalRequestApprovedEvent`, `ApprovalRequestDeniedEvent` | +| --- | --- | +| Historias relacionadas | FS-23, FS-05, FS-07, FS-14 | +| Entidades de dominio | `ApprovalRequest`, `Profile`, `Role`, `UserAccount`, `Branch` | +| Eventos de dominio | `ProfileAssignedToUserEvent`, `ApprovalRequestApprovedEvent`, `ApprovalRequestDeniedEvent` | | Notificaciones | `ProfileRequestApproved`, `ProfileRequestDenied` | -| ADRs | ADR-0075, ADR-0071 | +| ADRs | ADR-UMS-075, ADR-UMS-088 | diff --git a/docs/governance/requirements-es/functional-stories/fs-25-seed-dataset.md b/docs/governance/requirements-es/functional-stories/fs-25-seed-dataset.md new file mode 100644 index 00000000..c81460a9 --- /dev/null +++ b/docs/governance/requirements-es/functional-stories/fs-25-seed-dataset.md @@ -0,0 +1,270 @@ +# Historia Funcional 25: Dataset de Datos de Prueba Orientado al Negocio de BEYONDNET + +> **Estado:** Propuesta +> +> **Tipo:** Historia técnica SDLC (semilla de datos / _seed dataset_). Sigue el [Estándar de Redacción de Historias Funcionales](./estandar-redaccion-historias-funcionales.md), separando la intención de negocio de los requisitos técnicos. + +## 1. Propósito de Negocio + +BEYONDNET es un operador logístico aduanero (RUC 20100412447, en operación desde 1978) con dos sucursales: Lima (sede central) y Paita (puerto norte, agroexportación). Ofrece a sus clientes —importadores, exportadores y terminales— una suite de sistemas a la que ellos acceden como cuentas externas acotadas. UMS provee la identidad y la autorización de toda esa suite. + +El dataset de arranque (_seed_) que UMS carga hoy en entornos de desarrollo describe una organización genérica que no representa el negocio real de BEYONDNET: el RUC y las sucursales del operador son incorrectos y solo existen dos suites (UMS, WMS) con roles genéricos en inglés. Esto obliga a cada demo, prueba de aceptación y sesión de descubrimiento a explicar por qué los datos no coinciden con el dominio, y erosiona la confianza en las demostraciones. + +Esta historia especifica un **dataset demo compacto pero representativo** del negocio de BEYONDNET: el operador con sus dos sucursales reales, seis suites logístico-aduaneras, roles y perfiles del oficio (agente de aduanas, despachador, jefe de almacén, etc.), usuarios internos por sucursal, clientes externos importadores/exportadores y los parámetros operativos de impo/expo. El objetivo de negocio es que cualquier demo, prueba de aceptación o incorporación (_onboarding_) parta de datos creíbles y coherentes con la operación real, sin inventar detalles que no puedan justificarse. + +## 2. Actores + +| Actor | Tipo | Responsabilidad en la historia | +| :--- | :--- | :--- | +| **Super-administrador (`admin@ums.local`)** | Principal | Administra globalmente la plataforma desde el tenant `INTERNAL_ADMIN`. Debe permanecer intacto tras cargar el nuevo dataset (misma credencial y acceso). | +| **Operador interno BEYONDNET (por sucursal)** | Principal | Personal de BEYONDNET en Lima (`UNI_LIMA`) o Paita (`BN_PAITA`) que opera las suites logístico-aduaneras según su rol (agente de aduanas, despachador, jefe de almacén, operario, coordinador de transporte, ejecutivo de cuenta, analista documentario, auditor, administrador). | +| **Cliente externo (importador/exportador/terminal)** | Secundario | Usuario de una empresa cliente (`CLIENT`) que accede de forma acotada, típicamente solo al Portal del Cliente, para consultar el estado de sus expedientes y documentos. | +| **Administrador de seguridad de BEYONDNET** | Secundario | Mantiene el catálogo de suites, roles, perfiles y plantillas del operador una vez sembrados. | +| **Sembrador del sistema (proceso de arranque)** | Secundario | Actor técnico (`ActorId` de sistema) que materializa el dataset de forma idempotente durante el arranque cuando `Persistence.SeedDevData=true`. | + +### 2.1 Diagrama de Interacción + +```mermaid +sequenceDiagram + actor SA as Super-administrador + actor OP as Operador BEYONDNET (por sucursal) + actor CE as Cliente externo + participant SEED as Sembrador (arranque) + participant UMS as UMS (Identidad + Autorización) + + SEED->>UMS: Materializa dataset (operador, suites, roles, perfiles, usuarios, parámetros) + Note over SEED,UMS: Idempotente — no altera al super-administrador ni datos existentes + + SA->>UMS: Inicia sesión (admin@ums.local) + UMS-->>SA: 200 OK (acceso global intacto) + + OP->>UMS: Inicia sesión (usuario interno @beyondnet.com.pe) + UMS-->>OP: Perfil + permisos de su sucursal y suites + + CE->>UMS: Inicia sesión (usuario cliente) + UMS-->>CE: Acceso acotado (solo Portal del Cliente) +``` + +## 3. Precondiciones de Negocio + +* UMS está desplegado en un entorno de desarrollo o demostración con la carga de datos de prueba habilitada (`Persistence.SeedDevData=true`). +* El tenant de administración interna (`INTERNAL_ADMIN`) y el super-administrador (`admin@ums.local`) existen y deben conservarse sin cambios. +* El catálogo de acciones estándar (VIEW, CREATE, READ, UPDATE, DELETE, APPROVE, SEARCH) está disponible para componer las suites. + +### 3.1 Contexto Acotado, Dependencias y Restricciones (S-04) + +* **Contexto acotado principal:** `Identity` (tenants, sucursales, cuentas de usuario) y `Authorization` (suites, módulos, menús, opciones, acciones, roles, plantillas y perfiles). Contextos de soporte: `Configuration` (parámetros, banderas de característica) y `Approvals` (flujos de aprobación). Referencias de dominio: [tenant](../dominio/identity/tenant.md), [sucursal](../dominio/identity/branch.md), [suite del sistema](../dominio/authorization/system-suite.md), [rol](../dominio/authorization/role.md), [perfil](../dominio/authorization/profile.md), [plantilla de permiso](../dominio/authorization/permission-template.md). +* **Dependencias:** el dataset consume los invariantes ya definidos en [FS-03 (Registrar Organización)](./fs-03-registrar-organizacion.md), [FS-04 (Registrar Sistema y Topología de Menú)](./fs-04-registrar-topologia-sistema.md), [FS-17 (Mantener Roles de una Suite)](./fs-17-mantener-roles-sistema.md), [FS-20 (Gestionar Parámetros)](./fs-20-gestion-parametros-sistema.md) y [FS-21 (Alta de Empresa)](./fs-21-aprobacion-solicitud-alta-tenant.md). No introduce reglas de dominio nuevas: solo instancia datos que respetan las existentes. +* **Restricciones:** + * El operador BEYONDNET se identifica por su GUID de tenant estable ya presente en el _seed_ (`5f4e3d2c-1b0a-9f8e-7d6c-543210987654`); el dataset **corrige** su RUC y sus sucursales, no crea un tenant nuevo. + * Alcance "demo compacto": no se modela la totalidad de la operación aduanera, sino un árbol plausible y suficiente para demostración y pruebas. + * La documentación y los nombres visibles de este dataset se mantienen en español (SD-08); los códigos técnicos (`code`) usan mayúsculas ASCII por convención de catálogo. + +## 4. Flujo Funcional Principal + +1. Al arrancar UMS con la carga de datos habilitada, el sembrador materializa el operador **BEYONDNET** como tenant proveedor (`SUPPLIER`) con RUC 20100412447 y exactamente dos sucursales: `UNI_LIMA` (Sede Central Lima) y `BN_PAITA` (Sucursal Paita). +2. El sembrador registra para BEYONDNET **seis suites del sistema**, cada una con su árbol de módulos → menús → opciones y su conjunto de acciones, cubriendo el ciclo logístico-aduanero: transporte, almacén, sistema integral logístico, aduanas, portal del cliente y facturación. +3. El sembrador registra el **catálogo de roles del oficio** de BEYONDNET y los agrupa en **perfiles reutilizables** con **plantillas de permiso** publicadas. +4. El sembrador registra las **empresas cliente** (`CLIENT`): las cinco actuales y dos o tres importadores/exportadores típicos, cada una con una sucursal. +5. El sembrador crea los **usuarios**: el super-administrador (intacto), los usuarios internos de BEYONDNET por sucursal y los usuarios cliente externos, todos con contraseña de desarrollo uniforme salvo el super-administrador que conserva la suya. +6. El sembrador registra los **parámetros de operación impo/expo** (incoterms, monedas, tipos de DUA), la bandera de característica `PAITA_AGROEXPORT` y uno o dos flujos de aprobación (alta de cliente y acceso a expediente). +7. Al finalizar, cualquier consulta de solo lectura sobre BEYONDNET refleja el negocio real y el super-administrador sigue accediendo con su credencial original. + +### 4.1 Operador, Sucursales y Clientes + +| Elemento | Código | Detalle | +| :--- | :--- | :--- | +| Operador | `BEYONDNET` | BeyondNet S.A.C., tipo `SUPPLIER`, RUC 20100412447. | +| Sucursal 1 | `BN_CALLAO` | Operaciones Callao (puerto principal). | +| Sucursal 2 | `BN_PAITA` | Sucursal Paita (puerto norte, agroexport). | + +Clientes `CLIENT` conservados: `RANSA` (Ransa Comercial), `NEPTUNIA`, `APM_CALLAO`, `PAITA_PORT`, `INTRADEVCO`. Clientes añadidos (importadores/exportadores típicos, una sucursal cada uno): + +| Cliente | Código | Perfil de negocio | Sucursal | +| :--- | :--- | :--- | :--- | +| Comercializadora Andina S.A.C. | `COMEX_ANDINA` | Importador (Lima) | `CAND_LIMA` (Almacén Lima) | +| Agroexportadora del Norte S.A.C. | `AGRONORTE` | Exportador agro (Paita) | `AGRN_PAITA` (Planta Paita) | +| Frutícola Piura S.A.C. | `FRUPIURA` | Exportador agro (Paita, opcional) | `FRPI_PAITA` (Packing Paita) | +| Importadora Sub-Cliente | `IMPO_ANDINA_SUB` | **Cliente del cliente**: tenant hijo (`ParentTenantId` = `COMEX_ANDINA`) | `IASUB_LIMA` | + +**Personas de acceso** (para probar; password dev `BeyondNet.Dev.2026`, salvo el super-admin de plataforma): + +| Persona | Tenant | Usuario | Sucursal | +| :--- | :--- | :--- | :--- | +| Super-admin de plataforma | `INTERNAL_ADMIN` | `admin@ums.local` (`root`) | — | +| **BEYONDNET root admin** | `BEYONDNET` | `admin@beyondnet.com.pe` | — (transversal) | +| BEYONDNET sucursal Callao | `BEYONDNET` | p. ej. `jefe.almacen.callao@beyondnet.com.pe` | `BN_CALLAO` | +| BEYONDNET sucursal Paita | `BEYONDNET` | p. ej. `jefe.almacen.paita@beyondnet.com.pe` | `BN_PAITA` | +| Cliente externo | `COMEX_ANDINA` | `usuario.impo@comexandina.com.pe` | `CAND_LIMA` | +| Cliente de mi cliente | `IMPO_ANDINA_SUB` | `usuario@impo-subcliente.com.pe` | `IASUB_LIMA` | + +### 4.2 Suites del Sistema y Árbol de Módulos + +Las seis suites y su árbol de módulos → menús → opciones propuesto (cada suite expone las acciones VIEW, CREATE, READ, UPDATE, DELETE, APPROVE, SEARCH): + +| Suite | Código | Módulos (código) | Menús principales por módulo | +| :--- | :--- | :--- | :--- | +| Transporte | `TMS` | Planificación (`PLAN`), Flota (`FLEET`), Seguimiento (`TRACK`) | `PLAN`: Órdenes de Transporte, Rutas · `FLEET`: Vehículos, Conductores · `TRACK`: Monitoreo, Hitos | +| Almacén | `WMS` | Inventario (`INV`), Recepción/Despacho (`RCV`), Reportes (`REPORTS`) | `INV`: Stock, Operaciones · `RCV`: Recepciones, Despachos · `REPORTS`: Reportes de Inventario, Importar/Exportar | +| Sistema Integral Logístico | `SIL` | Expedientes (`FILES`), Costos (`COST`), Trazabilidad (`TRACE`) | `FILES`: Expedientes Impo, Expedientes Expo · `COST`: Liquidación de Costos · `TRACE`: Línea de Tiempo | +| Aduanas | `ADUANAS` | Declaraciones (`DECL`), Canales (`CHANNEL`), Agentes (`AGENT`) | `DECL`: DUA Importación, DAM Exportación · `CHANNEL`: Rojo, Naranja, Verde · `AGENT`: Agentes de Aduana, Poderes | +| Portal del Cliente | `PORTAL_CLIENTE` | Consultas (`QUERY`), Notificaciones (`NOTIF`) | `QUERY`: Estado de Expediente, Documentos · `NOTIF`: Avisos | +| Facturación | `FACTURACION` | Facturación (`BILL`), Liquidación (`SETTLE`), Cobranzas (`COLLECT`) | `BILL`: Facturas, Notas de Crédito · `SETTLE`: Liquidaciones · `COLLECT`: Estado de Cuenta | + +### 4.3 Roles, Perfiles y Plantillas + +Roles del oficio (~10): + +| Rol | Código | Suite(s) de anclaje | +| :--- | :--- | :--- | +| Agente de Aduanas | `AGENTE_ADUANAS` | `ADUANAS` | +| Despachador | `DESPACHADOR` | `ADUANAS`, `SIL` | +| Jefe de Almacén | `JEFE_ALMACEN` | `WMS` | +| Operario de Almacén | `OPERARIO_ALMACEN` | `WMS` | +| Coordinador de Transporte | `COORD_TRANSPORTE` | `TMS` | +| Ejecutivo de Cuenta | `EJECUTIVO_CUENTA` | `SIL`, `PORTAL_CLIENTE` | +| Analista Documentario | `ANALISTA_DOC` | `SIL`, `ADUANAS` | +| Cliente Externo | `CLIENTE_EXTERNO` | `PORTAL_CLIENTE` (exclusivo) | +| Auditor | `AUDITOR` | Transversal (solo lectura) | +| Administrador | `ADMINISTRADOR` | Transversal (acceso total) | + +Perfiles reutilizables (~5) que agrupan roles y referencian plantillas de permiso publicadas: + +| Perfil | Código | Roles agrupados | +| :--- | :--- | :--- | +| Operaciones Aduanas | `PERF_OP_ADUANAS` | Agente de Aduanas, Despachador, Analista Documentario | +| Almacén | `PERF_ALMACEN` | Jefe de Almacén, Operario de Almacén | +| Transporte | `PERF_TRANSPORTE` | Coordinador de Transporte | +| Comercial | `PERF_COMERCIAL` | Ejecutivo de Cuenta | +| Cliente Externo | `PERF_CLIENTE_EXT` | Cliente Externo (solo Portal) | +| Administración | `PERF_ADMIN` | Administrador, Auditor | + +Cada rol posee una **plantilla de permiso** publicada y reutilizable, alineada con su alcance (p. ej. `CLIENTE_EXTERNO` solo obtiene navegación y lectura en `PORTAL_CLIENTE`; `AUDITOR` obtiene lectura transversal sin acciones de escritura). + +### 4.4 Usuarios (~14 + super-administrador) + +| Sucursal / origen | Correo | Rol | +| :--- | :--- | :--- | +| INTERNAL_ADMIN | `admin@ums.local` | Super-administrador (intacto) | +| UNI_LIMA | `admin.lima@beyondnet.com.pe` | Administrador | +| UNI_LIMA | `agente.aduanas.lima@beyondnet.com.pe` | Agente de Aduanas | +| UNI_LIMA | `despachador.lima@beyondnet.com.pe` | Despachador | +| UNI_LIMA | `jefe.almacen.lima@beyondnet.com.pe` | Jefe de Almacén | +| UNI_LIMA | `coordinador.transporte.lima@beyondnet.com.pe` | Coordinador de Transporte | +| UNI_LIMA | `ejecutivo.cuenta.lima@beyondnet.com.pe` | Ejecutivo de Cuenta | +| UNI_LIMA | `analista.doc.lima@beyondnet.com.pe` | Analista Documentario | +| UNI_LIMA | `auditor.lima@beyondnet.com.pe` | Auditor | +| BN_PAITA | `jefe.almacen.paita@beyondnet.com.pe` | Jefe de Almacén | +| BN_PAITA | `operario.almacen.paita@beyondnet.com.pe` | Operario de Almacén | +| BN_PAITA | `agente.aduanas.paita@beyondnet.com.pe` | Agente de Aduanas | +| BN_PAITA | `ejecutivo.cuenta.paita@beyondnet.com.pe` | Ejecutivo de Cuenta (agroexport) | +| COMEX_ANDINA (cliente) | `usuario.impo@comexandina.com.pe` | Cliente Externo | +| AGRONORTE (cliente) | `usuario.expo@agronorte.com.pe` | Cliente Externo | + +Todos los usuarios internos y de cliente reciben una contraseña de desarrollo uniforme (mínimo 12 caracteres; p. ej. `BeyondNet.Dev.2026`). El super-administrador conserva su credencial actual (`admin@ums.local` / `root`) sin alteración. + +### 4.5 Operación Impo/Expo + +* **Parámetros:** incoterms (`INCOTERM`: FOB, CIF, EXW, FCA, CFR, CPT), monedas (`MONEDA`: USD, PEN), tipos de declaración (`TIPO_DUA`: Importación Definitiva, Exportación Definitiva, Admisión Temporal). +* **Bandera de característica:** `PAITA_AGROEXPORT`, acotada al tenant BEYONDNET (habilita comportamiento específico de agroexportación en la sucursal Paita). +* **Flujos de aprobación:** `ALTA_CLIENTE` (aprobación de alta de una empresa cliente) y `ACCESO_EXPEDIENTE` (aprobación de acceso externo a un expediente). + +## 5. Flujos Alternativos y Excepciones + +### A. Dataset ya materializado (idempotencia) + +Si el dataset ya fue cargado en un arranque previo, un nuevo arranque no duplica suites, roles, perfiles, usuarios ni parámetros: cada elemento se reconcilia por su código o identificador estable (upsert), conservando los identificadores que otros datos ya referencian. + +### B. Snapshot heredado con datos antiguos del operador + +Si la base de datos contiene una versión previa de BEYONDNET con RUC y sucursales incorrectas, el dataset corrige el RUC a 20100412447 y reconcilia las sucursales al par `UNI_LIMA`/`BN_PAITA` sin recrear el tenant ni romper referencias existentes. + +### C. Carga de datos deshabilitada + +Si `Persistence.SeedDevData` no está activo, no se materializa ningún dato; el entorno permanece con lo que exista, sin efectos colaterales. + +### D. Fallo parcial durante la carga + +Si un contexto (identidad, autorización, configuración o aprobaciones) falla al sembrar, el fallo se aísla y se reporta sin dejar al super-administrador inaccesible ni corromper los datos ya cargados por otros contextos. + +## 6. Reglas de Negocio + +1. El operador BEYONDNET es un tenant `SUPPLIER` único, con RUC 20100412447 y exactamente dos sucursales activas (`UNI_LIMA`, `BN_PAITA`). +2. El super-administrador (`admin@ums.local`, tenant `INTERNAL_ADMIN`) nunca se altera, bloquea ni pierde su perfil por efecto del dataset. +3. BEYONDNET expone exactamente seis suites con códigos `TMS`, `WMS`, `SIL`, `ADUANAS`, `PORTAL_CLIENTE` y `FACTURACION`; cada código de suite es único dentro del tenant. +4. Cada rol pertenece a una sola suite y a un tenant, con `code`, `value` y `description` definidos y código único dentro de su suite (coherente con FS-17). +5. El rol Cliente Externo solo concede navegación y lectura en `PORTAL_CLIENTE`; nunca perfiles administrativos internos. +6. Cada empresa cliente (`CLIENT`) tiene al menos una sucursal; los importadores/exportadores añadidos representan un caso impo (Lima) y un caso expo agro (Paita). +7. Los parámetros de operación impo/expo (incoterms, monedas, tipos de DUA) existen a nivel del tenant BEYONDNET con valores válidos del dominio. +8. La bandera `PAITA_AGROEXPORT` está acotada al tenant BEYONDNET. +9. La materialización del dataset es idempotente: repetir el arranque no crea duplicados ni cambia identificadores estables ya referenciados. + +## 7. Criterios de Aceptación + +Los criterios son verificables mediante los endpoints REST de UMS, ejecutados en el contexto del tenant correspondiente. `{beyondNetId}` = `5f4e3d2c-1b0a-9f8e-7d6c-543210987654`. + +1. **Super-administrador intacto:** `POST /api/v1/auth/login` con `admin@ums.local` / `root` devuelve `200 OK` y una sesión válida. +2. **Operador correcto:** `GET /tenants/{beyondNetId}` devuelve un tenant tipo `SUPPLIER` cuyo RUC es `20100412447`. +3. **Dos sucursales:** `GET /tenants/{beyondNetId}/branches` devuelve exactamente 2 sucursales con códigos `{UNI_LIMA, BN_PAITA}`. +4. **Seis suites:** en el contexto del tenant BEYONDNET, `GET /system-suites` devuelve 6 suites cuyos códigos son exactamente `{TMS, WMS, SIL, ADUANAS, PORTAL_CLIENTE, FACTURACION}`. +5. **Árbol de suite no vacío:** para cada una de las 6 suites, `GET /system-suites/{systemSuiteId}` reporta al menos 2 módulos activos, y cada módulo al menos 1 menú con al menos 1 opción. +6. **Roles de aduanas:** `GET /system-suites/{aduanasId}/roles` incluye roles con códigos `AGENTE_ADUANAS` y `DESPACHADOR`. +7. **Rol de almacén asociable a Paita:** existe un usuario interno de BEYONDNET con correo `jefe.almacen.paita@beyondnet.com.pe` cuyo perfil referencia el rol `JEFE_ALMACEN`, verificable vía `GET /user-accounts` (filtrado por tenant BEYONDNET) y `GET /profiles`. +8. **Perfiles y plantillas:** `GET /profiles` (contexto BEYONDNET) devuelve perfiles **por-usuario** que encarnan los arquetipos operativos (Operaciones Aduanas, Almacén, Transporte, Comercial, Cliente Externo, Administración), cada uno con sus roles/plantillas correctos; `GET /permission-templates` devuelve al menos 6 plantillas en estado publicado. _Nota:_ el agregado `Profile` no expone un `code` de arquetipo ([G-022](../../../GAPS.md)); la verificación por código de perfil no aplica con el modelo actual. +9. **Cliente externo acotado:** existe un usuario cliente (p. ej. `usuario.impo@comexandina.com.pe`) cuyo perfil concede acceso únicamente a la suite `PORTAL_CLIENTE` (ninguna plantilla suya referencia otra suite). +10. **Clientes importador/exportador:** `GET /tenants` incluye tenants `CLIENT` con códigos `COMEX_ANDINA` (importador Lima) y `AGRONORTE` (exportador Paita), además de los cinco preexistentes `{RANSA, NEPTUNIA, APM_CALLAO, PAITA_PORT, INTRADEVCO}`. +11. **Parámetros impo/expo:** las consultas de parámetros del tenant BEYONDNET exponen definiciones con códigos `INCOTERM`, `MONEDA` y `TIPO_DUA`; la moneda incluye los valores `USD` y `PEN`. +12. **Bandera de característica:** `GET /feature-flags` (contexto BEYONDNET) incluye una bandera con código `PAITA_AGROEXPORT`. +13. **Flujos de aprobación:** existen flujos de aprobación del tenant BEYONDNET con códigos `ALTA_CLIENTE` y `ACCESO_EXPEDIENTE`, verificables vía las consultas de aprobación. +14. **Idempotencia:** ejecutar el arranque dos veces con la carga habilitada no incrementa el número de suites, sucursales, roles ni perfiles reportados por los endpoints anteriores (los conteos de los criterios 3, 4, 8 permanecen constantes). + +## 8. Requisitos Técnicos + +* La materialización vive en los _seeders_ code-first bajo [`src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/), orquestados por [`CoreDevDataSeeder.SeedAllAsync`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/CoreDevDataSeeder.cs) y ejecutados en el arranque cuando `Persistence.SeedDevData=true`. +* _Seeders_ impactados y su alcance: + * [`IdentityDevDataSeeder`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/IdentityDevDataSeeder.cs): corrige el tenant BEYONDNET (RUC, sucursales `UNI_LIMA`/`BN_PAITA`), añade los clientes importador/exportador y crea los usuarios internos por sucursal y los usuarios cliente. El super-administrador y el patrón de upsert por correo/GUID se conservan. + * [`AuthorizationDevDataSeeder`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/AuthorizationDevDataSeeder.cs): sustituye las 2 suites genéricas por las 6 suites del dominio con su árbol módulos → menús → opciones, registra los ~10 roles del oficio, sus plantillas de permiso publicadas y los ~6 perfiles. + * [`ConfigurationDevDataSeeder`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/ConfigurationDevDataSeeder.cs) y [`ParameterCatalogSeeder`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/ParameterCatalogSeeder.cs): añaden los parámetros impo/expo (`INCOTERM`, `MONEDA`, `TIPO_DUA`) y la bandera `PAITA_AGROEXPORT` acotada a BEYONDNET. + * [`ApprovalsDevDataSeeder`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/ApprovalsDevDataSeeder.cs): añade los flujos `ALTA_CLIENTE` y `ACCESO_EXPEDIENTE` para el tenant BEYONDNET. + * [`AuditDevDataSeeder`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/AuditDevDataSeeder.cs): sin cambios funcionales; solo debe seguir corriendo sin romperse ante los nuevos datos. +* **Idempotencia (invariante técnico):** cada entidad se reconcilia por su clave estable —código de tenant/suite/rol/perfil o GUID determinista— usando upsert; nunca se recrean identificadores que perfiles, plantillas o cuentas ya referencian. El tenant BEYONDNET se reconcilia por su GUID existente `5f4e3d2c-1b0a-9f8e-7d6c-543210987654`; el super-administrador (`22222222-2222-2222-2222-222222222222`) y su perfil se preservan explícitamente. +* **Aislamiento por tenant:** todos los datos sembrados llevan el `TenantId` de BEYONDNET (o del cliente correspondiente); el filtrado por tenant en la capa de aplicación permanece como control primario. +* **Contrato de lectura:** las suites se consultan con `GET /system-suites` y `GET /system-suites/{systemSuiteId}`; roles con `GET /system-suites/{systemSuiteId}/roles`; perfiles con `GET /profiles`; plantillas con `GET /permission-templates`; tenant y sucursales con `GET /tenants/{tenantId}` y `GET /tenants/{tenantId}/branches`; banderas con `GET /feature-flags`; cuentas con `GET /user-accounts`. +* **Entidades persistidas:** PostgreSQL con EF Core; los `code` de catálogo usan mayúsculas ASCII y los nombres visibles (`value`/`Name`) se mantienen en español. + +## 9. Trazabilidad + +* Entidades: `Tenant`, `Branch`, `UserAccount`, `SystemSuite`, `Module`, `Menu`, `Option`, `Role`, `PermissionTemplate`, `Profile`, `TenantParameter`, `FeatureFlag`, `ApprovalWorkflow`. +* Historias relacionadas: [FS-03](./fs-03-registrar-organizacion.md), [FS-04](./fs-04-registrar-topologia-sistema.md), [FS-17](./fs-17-mantener-roles-sistema.md), [FS-20](./fs-20-gestion-parametros-sistema.md), [FS-21](./fs-21-aprobacion-solicitud-alta-tenant.md). +* Documentación de solución y producto: [PRD BEYONDNET UMS](../../01-concepcion/PRD-UMS-001.es.md), [Arquitectura de la solución](../arquitectura-solucion.md). +* Artefactos operativos: _seeders_ code-first en [`.../Persistence/Seeders/`](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/), activados por `Persistence.SeedDevData=true`. + +## 10. Modelo del Dataset (Operador → Suites → Clientes/Usuarios) + +```mermaid +graph TD + BEYONDNET["BEYONDNET (SUPPLIER) - RUC 20100412447"] + BEYONDNET --> LIMA["Sucursal UNI_LIMA"] + BEYONDNET --> PAITA["Sucursal BN_PAITA"] + + BEYONDNET --> SUITES{{"6 Suites del Sistema"}} + SUITES --> TMS[TMS] + SUITES --> WMS[WMS] + SUITES --> SIL[SIL] + SUITES --> ADU[ADUANAS] + SUITES --> PORTAL[PORTAL_CLIENTE] + SUITES --> FACT[FACTURACION] + + LIMA --> UINT_L["Usuarios internos Lima (Agente, Despachador, Jefe Almacen, Coord. Transporte, Ejecutivo, Analista, Auditor, Admin)"] + PAITA --> UINT_P["Usuarios internos Paita (Jefe/Operario Almacen, Agente, Ejecutivo agro)"] + + BEYONDNET --> CLIENTES{{"Empresas Cliente (CLIENT)"}} + CLIENTES --> C5["5 preexistentes: RANSA, NEPTUNIA, APM_CALLAO, PAITA_PORT, INTRADEVCO"] + CLIENTES --> IMPO["COMEX_ANDINA (impo Lima)"] + CLIENTES --> EXPO["AGRONORTE (expo Paita)"] + + IMPO --> UEXT_I["usuario.impo (Cliente Externo)"] + EXPO --> UEXT_E["usuario.expo (Cliente Externo)"] + UEXT_I -.acceso acotado.-> PORTAL + UEXT_E -.acceso acotado.-> PORTAL +``` diff --git a/docs/governance/requirements-es/functional-stories/fs-26-admin-root-tenant-owner.md b/docs/governance/requirements-es/functional-stories/fs-26-admin-root-tenant-owner.md new file mode 100644 index 00000000..dd7819e1 --- /dev/null +++ b/docs/governance/requirements-es/functional-stories/fs-26-admin-root-tenant-owner.md @@ -0,0 +1,160 @@ +# Historia Funcional 26: BEYONDNET como Admin Root y Tenant Owner en una sola identidad + +> **Estado:** Propuesta +> +> **Tipo:** Historia técnica SDLC (modelo de identidad multi-tenant). Sigue el [Estándar de Redacción de Historias Funcionales](./estandar-redaccion-historias-funcionales.md), separando la intención de negocio de los requisitos técnicos. + +## 1. Propósito de Negocio + +BEYONDNET opera el ecosistema UMS con **dos sombreros a la vez**: es el **administrador global** que da de alta y gobierna a todos los tenants (clientes, proveedores, sub-clientes), y es también **una organización operativa propia** —con RUC 20100412447, sus sucursales de Callao y Paita, sus usuarios internos, su configuración y sus parámetros— que necesita administrarse a sí misma como cualquier otro tenant. + +Hoy esos dos sombreros están repartidos entre **dos tenants distintos** que no coinciden. Al iniciar sesión como «Admin UMS» se entra al tenant sintético `INTERNAL_ADMIN` (el único con el atributo de propietario de gestión, que otorga la visión global), mientras que `BEYONDNET` existe como un tenant `SUPPLIER` separado, sin ese atributo. La consecuencia práctica es que **el administrador global no puede verse ni administrarse como el tenant BEYONDNET**: no accede a los datos generales de BEYONDNET, sus sucursales, usuarios, configuración, parámetros ni a su auditoría desde su propia sesión. La organización que gobierna el sistema es, paradójicamente, invisible para sí misma. + +Esta historia especifica la **unificación de la identidad de BEYONDNET**: un único tenant que es a la vez **Admin Root** (propietario de gestión, con gobierno transversal) y **Tenant Owner** (organización operativa administrable), con una **separación clara y controlada entre la administración global de la plataforma y la administración de la propia casa**. El objetivo de negocio es que BEYONDNET, sin perder su rol de administrador del ecosistema, pueda ver y administrar su propio tenant —incluidas sus sucursales y datos operativos— manteniendo el aislamiento multi-tenant, la trazabilidad y una gobernanza correcta. + +## 2. Actores + +| Actor | Tipo | Responsabilidad en la historia | +| :--- | :--- | :--- | +| **Admin Root BEYONDNET** | Principal | Administrador de plataforma: da de alta y gobierna a todos los tenants del ecosistema. Su poder transversal deriva de que su tenant (BEYONDNET) es propietario de gestión (`IsManagementOwner`). Activa explícitamente el modo cross-tenant para operar sobre otros tenants. | +| **Tenant Admin BEYONDNET** | Principal | Administra la propia organización BEYONDNET: datos generales, sucursales, usuarios internos, configuración, parámetros y auditoría, acotado al `OrganizationId` de BEYONDNET (sin bypass global). | +| **Branch Admin BEYONDNET** | Secundario | Administra una sucursal concreta (Callao o Paita); su perfil está acotado por `BranchId` (`ProfileScope = BranchScoped`). | +| **Usuario interno BEYONDNET** | Secundario | Personal de BEYONDNET con roles del oficio (agente de aduanas, jefe de almacén, etc.), acotado a su tenant y sucursal. | +| **Usuario externo (cliente / cliente del cliente)** | Secundario | Usuario de una empresa cliente (`CLIENT`), acotado a su propio tenant y típicamente solo al Portal del Cliente. | +| **Cuenta de emergencia de plataforma (break-glass)** | Secundario | Cuenta técnica de último recurso (`admin@ums.local` en el tenant `INTERNAL_ADMIN` degradado) para recuperación si BEYONDNET quedara inaccesible. No es la vía ordinaria de administración. | + +### 2.1 Diagrama de Interacción + +```mermaid +sequenceDiagram + actor AR as Admin Root BEYONDNET + actor TA as Tenant Admin BEYONDNET + participant UMS as UMS (Identidad + Autorización) + + AR->>UMS: Inicia sesión (admin@beyondnet.com.pe) + UMS-->>AR: Sesión con is_internal_admin=true (BEYONDNET es propietario de gestión) + + Note over AR,UMS: Sombrero Owner (por defecto) — acotado a BEYONDNET + AR->>UMS: GET /tenants/{beyondNetId} · sucursales · usuarios · parámetros · auditoría + UMS-->>AR: Datos de la propia organización BEYONDNET + + Note over AR,UMS: Sombrero Root (explícito) — cross-tenant + AR->>UMS: Activa modo global (switch-tenant / cross-tenant) + AR->>UMS: GET /tenants (todos) · alta y gobierno de otros tenants + UMS-->>AR: Visión transversal del ecosistema + + TA->>UMS: Inicia sesión (tenant-admin de BEYONDNET, sin gestión global) + UMS-->>TA: Acceso acotado a BEYONDNET y sus sucursales (sin ver otros tenants) +``` + +## 3. Precondiciones de Negocio + +* UMS está desplegado con el dataset de BEYONDNET materializado ([FS-25](./fs-25-dataset-semilla-beyondnet.md)): el operador BEYONDNET, sus dos sucursales, sus suites, roles, perfiles y usuarios existen. +* El tenant de administración interna (`INTERNAL_ADMIN`) y su super-administrador (`admin@ums.local`) existen y se conservan como cuenta de emergencia. +* El agregado `Tenant` ya soporta los conceptos necesarios: `IsManagementOwner`, `ParentTenantId`, `Type`, `Status`, y como hijos `Branch`, `TenantParameter`, `IdentityProvider`. + +### 3.1 Contexto Acotado, Dependencias y Restricciones (S-04) + +* **Contexto acotado principal:** `Identity` (tenants, sucursales, cuentas de usuario) y `Authorization` (suites, roles, plantillas, perfiles). Contextos de soporte: `Configuration` (parámetros, banderas) y `Audit` (auditoría por tenant). Referencias de dominio: [tenant](../dominio/identity/tenant.md), [sucursal](../dominio/identity/branch.md). +* **Dependencias:** consume el dataset de [FS-25](./fs-25-dataset-semilla-beyondnet.md), el registro de organización de [FS-03](./fs-03-registrar-organizacion.md), la configuración jerárquica de [FS-13](./fs-13-configuracion-jerarquica.md) y la gestión delegada de [FS-14](./fs-14-gestion-delegada.md). No introduce un agregado nuevo: reconfigura la identidad y abre operaciones de administración sobre entidades existentes. +* **Restricciones:** + * **Invariante de unicidad:** existe **exactamente un** tenant propietario de gestión (Admin Root) en el ecosistema. La promoción de BEYONDNET implica que ningún otro tenant conserve ese atributo. + * **Separación de sombreros:** administrar la propia casa de BEYONDNET opera acotado a su `OrganizationId`; el gobierno de otros tenants exige activar el modo cross-tenant de forma explícita y auditable. La administración ordinaria de BEYONDNET **no** debe requerir el bypass global. + * La documentación y los nombres visibles se mantienen en español (SD-08); los códigos técnicos usan mayúsculas ASCII. + * **Trazabilidad a decisión arquitectónica (S-06):** la promoción de BEYONDNET a Admin Root único es una decisión de arquitectura que requiere un ADR **aceptado** en `evolith-core` antes de ejecutarse en producción. No se resuelve inventando la decisión en este satélite; la dependencia queda registrada en [GAPS.md](../../../GAPS.md). + +## 4. Flujo Funcional Principal + +1. **Unificación de identidad.** El tenant `BEYONDNET` pasa a ser el **propietario de gestión** del ecosistema (`Type = INTERNAL`, `IsManagementOwner = true`, `ParentTenantId = null` → raíz). El tenant sintético `INTERNAL_ADMIN` se degrada a cuenta de emergencia (deja de ser propietario de gestión). +2. **Admin Root — sombrero Owner (por defecto).** Al iniciar sesión, el Admin Root de BEYONDNET opera acotado a su propio tenant: consulta y administra los datos generales de BEYONDNET, sus sucursales, sus usuarios internos, su configuración, sus parámetros y su auditoría, como cualquier tenant-admin. +3. **Admin Root — sombrero Root (explícito).** Cuando necesita gobernar el ecosistema, activa el modo cross-tenant de forma explícita: entonces `GET /tenants` devuelve todos los tenants y puede darlos de alta y administrarlos. Al salir del modo, vuelve a quedar acotado a BEYONDNET. +4. **Tenant Admin y Branch Admin.** Un administrador de BEYONDNET sin gestión global administra la organización (o su sucursal) sin ver otros tenants. El alcance de sucursal lo determina `BranchId`/`ProfileScope`. +5. **Interfaz separada.** La interfaz distingue de forma explícita **«Administración Global»** (solo Admin Root, en modo cross-tenant) de **«Mi Organización»** (el propio tenant BEYONDNET con sus sucursales, usuarios, configuración y auditoría), e indica visualmente que BEYONDNET es el **Tenant Root**. +6. **Persistencia de la administración.** Editar los datos generales de BEYONDNET y de sus sucursales **persiste** contra el backend (no queda como cambio local). + +## 5. Flujos Alternativos y Excepciones + +### A. Intento de crear un segundo propietario de gestión + +Si se intenta marcar un segundo tenant como propietario de gestión, la operación se rechaza: el invariante de unicidad garantiza un único Admin Root. + +### B. Administración de otro tenant sin activar el modo global + +Si el Admin Root intenta administrar otro tenant sin haber activado el modo cross-tenant, la operación queda acotada a BEYONDNET y no afecta al otro tenant. + +### C. BEYONDNET inaccesible (recuperación) + +Si BEYONDNET quedara inaccesible (p. ej. suspensión accidental), la cuenta de emergencia (`admin@ums.local` en `INTERNAL_ADMIN`) permite recuperar el acceso y reactivar BEYONDNET. + +### D. Tenant Admin intenta ver el ecosistema + +Un tenant-admin de BEYONDNET sin gestión global que consulta `GET /tenants` solo obtiene su propio tenant y sus hijos; nunca la lista completa. + +## 6. Reglas de Negocio + +1. Existe **exactamente un** tenant propietario de gestión (Admin Root) en el ecosistema; tras esta historia es **BEYONDNET**. +2. El poder de administración global (`is_internal_admin`) deriva del atributo del tenant (`IsManagementOwner`), no de un usuario suelto ni del tipo de organización. +3. El Admin Root de BEYONDNET opera **por defecto acotado** a su propio tenant; la visión y administración cross-tenant requiere activación explícita. +4. BEYONDNET es un tenant raíz (`ParentTenantId = null`) de tipo `INTERNAL`, con sus dos sucursales (`BN_CALLAO`, `BN_PAITA`) y su RUC 20100412447 intactos. +5. Editar los datos generales de un tenant o de una sucursal es una operación que **persiste** y queda auditada. +6. La administración de la propia casa de BEYONDNET está disponible para su Tenant Admin **sin** requerir el atributo de propietario de gestión. +7. La cuenta de emergencia `admin@ums.local` (`INTERNAL_ADMIN`) se conserva, degradada a último recurso, y nunca se elimina. +8. El aislamiento multi-tenant se mantiene: un tenant no propietario de gestión solo ve su propio tenant y sus hijos. + +## 7. Criterios de Aceptación + +Verificables mediante los endpoints REST de UMS en el contexto del tenant correspondiente. `{beyondNetId}` = `5f4e3d2c-1b0a-9f8e-7d6c-543210987654`; `{internalAdminId}` = `11111111-1111-1111-1111-111111111111`. + +1. **BEYONDNET es Admin Root:** `GET /tenants/{beyondNetId}` (contexto Admin Root) devuelve `isManagementOwner = true`, `type = INTERNAL` y `parentTenantId = null`. +2. **Unicidad de propietario de gestión:** `GET /tenants` (contexto Admin Root, modo global) devuelve **exactamente un** tenant con `isManagementOwner = true`, y su código es `BEYONDNET`. +3. **INTERNAL_ADMIN degradado:** `GET /tenants/{internalAdminId}` devuelve `isManagementOwner = false`. +4. **Login otorga gobierno global:** `POST /api/v1/auth/login` con `admin@beyondnet.com.pe` devuelve una sesión con `isInternalAdmin = true`. +5. **Sombrero Owner — visión propia:** en el contexto de BEYONDNET (sin modo global), `GET /tenants/{beyondNetId}/branches` devuelve las 2 sucursales `{BN_CALLAO, BN_PAITA}`, y `GET /user-accounts` devuelve los usuarios internos de BEYONDNET. +6. **Sombrero Root — visión global:** con el modo cross-tenant activo, `GET /tenants` devuelve la totalidad de los tenants del ecosistema (los 11 del dataset FS-25). +7. **Edición persistente de tenant:** una petición de actualización de los datos generales de BEYONDNET (nombre, referencia fiscal) se refleja en una consulta posterior `GET /tenants/{beyondNetId}` (no es un cambio solo-cliente). +8. **Edición persistente de sucursal:** una petición de actualización de una sucursal de BEYONDNET se refleja en `GET /tenants/{beyondNetId}/branches`. +9. **Aislamiento del tenant-admin:** en el contexto de un tenant-admin de BEYONDNET **sin** gestión global, `GET /tenants` devuelve únicamente BEYONDNET (y sus hijos, si los hubiera), nunca otros tenants. +10. **Auditoría por tenant:** las consultas de auditoría en el contexto de BEYONDNET exponen los registros de auditoría acotados a ese tenant. +11. **Break-glass operativo:** `POST /api/v1/auth/login` con `admin@ums.local` / `root` sigue devolviendo `200 OK` con acceso de recuperación. +12. **Indicador visual de Tenant Root (interfaz):** en la pantalla de administración de tenants, el tenant BEYONDNET se muestra con un indicador de «Tenant Root / Admin Root», y la navegación separa «Administración Global» de «Mi Organización». + +## 8. Requisitos Técnicos + +* **Fuente del poder global.** `is_internal_admin` se deriva en el login de `Tenant.IsManagementOwner` ([AuthEndpoints.cs](../../../src/apps/ums.api/Ums.Presentation/Endpoints/Identity/Auth/AuthEndpoints.cs)); no requiere cambio de mecanismo, solo trasladar el atributo de propietario de gestión de `INTERNAL_ADMIN` a `BEYONDNET`. +* **Seed / migración de identidad.** Ajustar los _seeders_ ([IdentityDevDataSeeder.cs](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/IdentityDevDataSeeder.cs), [CoreDevDataSeeder.cs](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/Seeders/CoreDevDataSeeder.cs)) para que `BEYONDNET` sea `INTERNAL` + propietario de gestión y `INTERNAL_ADMIN` deje de serlo, de forma idempotente y sin recrear GUID estables. Para entornos ya desplegados, la transición equivalente es una migración de datos, no de esquema. +* **Invariante de unicidad (BD).** Añadir un índice único filtrado sobre la tabla de tenants `WHERE is_management_owner = true`, de modo que la base de datos garantice un único Admin Root. No requiere columnas nuevas. +* **Persistencia de administración (huecos actuales).** Hoy la edición de datos generales de tenant y de sucursales **no persiste** (no existen endpoints de actualización; el frontend aplica un _override_ local). Introducir los comandos y endpoints de actualización de tenant y de sucursal, con su método de repositorio. Registrado en [GAPS.md](../../../GAPS.md). +* **Separación de sombreros (scoping).** La administración de la propia casa de BEYONDNET opera con `OrganizationId = BEYONDNET`; el gobierno de otros tenants usa la activación explícita de cross-tenant ya existente en [TenantContext.cs](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/TenantContext.cs) (`EnableCrossTenantAccess`). La política [TenantScopePolicy.cs](../../../src/apps/ums.api/Ums.Application/Common/Services/TenantScopePolicy.cs) (`EnsureManagementOwnerScopeAsync`) debe permitir que el Admin Root, en modo global, administre sucursales de otros tenants; el tenant-admin ordinario permanece acotado a su casa. +* **Aislamiento.** El control primario de aislamiento son los _query filters_ de EF Core ([UmsPlatformDbContext.cs](../../../src/apps/ums.api/Ums.Infrastructure/Persistence/UmsPlatformDbContext.cs)); el interceptor de BD es un no-op bajo PostgreSQL ([G-020](../../../GAPS.md)). El diseño no debilita ese control: la visión global sigue exigiendo `OrganizationId = null` bajo el sombrero Root explícito. +* **Contexto de tenant en producción.** El envío de `X-Tenant-Id` desde el frontend solo inyecta el tenant de sesión en modo desarrollo; en producción cae a un tenant por defecto. Debe configurarse el proveedor de contexto de producción desde la sesión. Registrado en [GAPS.md](../../../GAPS.md). +* **Interfaz.** El frontend ya dispone del andamiaje (master-detail de tenants con pestañas de sucursales, proveedores y configuraciones; `switchTenant` en el store; _toggle_ de propietario de gestión). Falta: una vista «Mi Organización» (atajo al propio tenant), el indicador visual de Tenant Root, las pestañas de usuarios y auditoría dentro del detalle del tenant, y un cambiador de tenant global para el Admin Root. + +## 9. Trazabilidad + +* Entidades: `Tenant`, `Branch`, `UserAccount`, `Profile`, `TenantParameter`, `AuditRecord`. +* Historias relacionadas: [FS-03](./fs-03-registrar-organizacion.md), [FS-13](./fs-13-configuracion-jerarquica.md), [FS-14](./fs-14-gestion-delegada.md), [FS-17](./fs-17-mantener-roles-sistema.md), [FS-25](./fs-25-dataset-semilla-beyondnet.md). +* Documentación de solución y producto: [PRD BEYONDNET UMS](../../01-concepcion/PRD-UMS-001.es.md), [Arquitectura de la solución](../arquitectura-solucion.md). +* **Decisión arquitectónica (S-06):** «BEYONDNET como único Admin Root con sombreros Owner/Root separados» requiere un ADR **aceptado** en `evolith-core`. No existe aún; la dependencia se registra como gap y la ejecución en producción queda condicionada a su aceptación. +* Gaps abiertos por esta historia en [GAPS.md](../../../GAPS.md): identidad dividida de BEYONDNET, edición no persistente de tenant/sucursal, unicidad de propietario de gestión, contexto de tenant en producción, auditoría por tenant no expuesta. + +## 10. Modelo de Identidad Propuesto (Admin Root + Tenant Owner) + +```mermaid +graph TD + subgraph ECOSISTEMA["Ecosistema UMS"] + BEYONDNET["BEYONDNET (INTERNAL) - Admin Root + Tenant Owner\nIsManagementOwner = true · ParentTenantId = null"] + BG["INTERNAL_ADMIN (degradado)\nBreak-glass · IsManagementOwner = false"] + CLI["Tenants CLIENT / SUPPLIER\n(COMEX_ANDINA, AGRONORTE, RANSA, ...)"] + SUB["IMPO_ANDINA_SUB\n(cliente del cliente, ParentTenantId)"] + end + + BEYONDNET --> CALLAO["Sucursal BN_CALLAO"] + BEYONDNET --> PAITA["Sucursal BN_PAITA"] + + BEYONDNET -. "sombrero Root (cross-tenant explícito)" .-> CLI + BEYONDNET -. gobierna .-> BG + CLI --> SUB + + BEYONDNET --> OWNER{{"Sombrero Owner (por defecto)\nDatos, sucursales, usuarios,\nconfiguración, parámetros, auditoría"}} + BEYONDNET --> ROOT{{"Sombrero Root (explícito)\nAlta y gobierno de todos los tenants"}} +``` diff --git a/docs/governance/requirements-es/functional-stories/fs-28-access-review-campaigns.md b/docs/governance/requirements-es/functional-stories/fs-28-access-review-campaigns.md index 0eeb944c..b8b2b537 100644 --- a/docs/governance/requirements-es/functional-stories/fs-28-access-review-campaigns.md +++ b/docs/governance/requirements-es/functional-stories/fs-28-access-review-campaigns.md @@ -9,7 +9,7 @@ Los responsables de seguridad y negocio necesitan campanas recurrentes para conf ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Administrador de Gobierno de Acceso | Crea y administra las campanas de revision. | | Propietario del Recurso / Jefe | Revisa el acceso asignado a los usuarios dentro del alcance. | | Revisor | Confirma, reduce o elimina el acceso durante la campana. | @@ -18,9 +18,9 @@ Los responsables de seguridad y negocio necesitan campanas recurrentes para conf ## 3. Precondiciones de Negocio -- El tenant tiene asignaciones activas que requieren revision periodica. -- Los revisores y propietarios del recurso estan definidos para el alcance objetivo. -- La organizacion tiene una cadencia de revision o una regla de revision disparada por evento. +* El tenant tiene asignaciones activas que requieren revision periodica. +* Los revisores y propietarios del recurso estan definidos para el alcance objetivo. +* La organizacion tiene una cadencia de revision o una regla de revision disparada por evento. ## 4. Flujo Funcional Principal @@ -48,7 +48,7 @@ Si el elemento de acceso ya fue eliminado o esta inactivo, el sistema lo omite y ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | El acceso sensible debe recertificarse periodicamente. | | BR-02 | Los revisores solo pueden actuar sobre items dentro de su alcance asignado. | | BR-03 | Una decision de revision debe cerrarse con un resultado final. | @@ -59,7 +59,7 @@ Si el elemento de acceso ya fue eliminado o esta inactivo, el sistema lo omite y ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Un administrador puede crear una campana de revision para un alcance definido. | | 2 | El revisor puede ver los items de acceso que pertenecen a la campana. | | 3 | El revisor puede aprobar, reducir o eliminar acceso para cada item. | @@ -69,16 +69,16 @@ Si el elemento de acceso ya fue eliminado o esta inactivo, el sistema lo omite y ## 8. Requisitos Tecnicos -- Introducir un modelo de campana de revision que pueda registrar alcance, asignacion de revisores, estado de items y resultado final. -- Persistir cada decision con revisor, fecha, motivo y accion de acceso resultante. -- Soportar reglas de escalamiento a nivel de campana o cierre automatico para revisiones vencidas. -- Emitir eventos auditables para la creacion de campana, la decision del item, el cierre y los cambios de enforcement. -- Mantener un tenant scoping estricto para que un revisor solo vea items dentro del tenant y del alcance de negocio asignado. +* Introducir un modelo de campana de revision que pueda registrar alcance, asignacion de revisores, estado de items y resultado final. +* Persistir cada decision con revisor, fecha, motivo y accion de acceso resultante. +* Soportar reglas de escalamiento a nivel de campana o cierre automatico para revisiones vencidas. +* Emitir eventos auditables para la creacion de campana, la decision del item, el cierre y los cambios de enforcement. +* Mantener un tenant scoping estricto para que un revisor solo vea items dentro del tenant y del alcance de negocio asignado. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `Role`, `Profile`, `PermissionTemplate`, `AccessEnforcementPolicy`, `AuditRecord` | | Historias Funcionales | FS-16, FS-24 | | ADRs | ADR-0016, ADR-0033, ADR-0035 | diff --git a/docs/governance/requirements-es/functional-stories/fs-29-entitlement-packages.md b/docs/governance/requirements-es/functional-stories/fs-29-entitlement-packages.md index 4d9268d4..3e37fc07 100644 --- a/docs/governance/requirements-es/functional-stories/fs-29-entitlement-packages.md +++ b/docs/governance/requirements-es/functional-stories/fs-29-entitlement-packages.md @@ -9,7 +9,7 @@ Los responsables de negocio necesitan bloques de acceso reutilizables que agrupe ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Administrador de Entitlements | Disena y mantiene los paquetes de acceso. | | Solicitante | Solicita un paquete en lugar de solicitar entitlements individuales. | | Aprobador | Decide si el paquete puede ser otorgado. | @@ -17,9 +17,9 @@ Los responsables de negocio necesitan bloques de acceso reutilizables que agrupe ## 3. Precondiciones de Negocio -- El catalogo de sistemas y el catalogo de autorizacion ya estan definidos. -- El propietario del paquete sabe que roles, permisos o alcances pertenecen juntos. -- La ruta de aprobacion esta configurada para el tenant o sistema objetivo. +* El catalogo de sistemas y el catalogo de autorizacion ya estan definidos. +* El propietario del paquete sabe que roles, permisos o alcances pertenecen juntos. +* La ruta de aprobacion esta configurada para el tenant o sistema objetivo. ## 4. Flujo Funcional Principal @@ -47,7 +47,7 @@ Si el paquete tiene vigencia limitada y ya vencio, el sistema no lo otorga e inf ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | Un paquete debe representar un bloque de negocio gobernado, no una lista arbitraria. | | BR-02 | Un paquete solo puede incluir entitlements permitidos por el alcance objetivo. | | BR-03 | La aprobacion debe decidir el paquete completo, no un estado parcial ambiguo. | @@ -58,7 +58,7 @@ Si el paquete tiene vigencia limitada y ya vencio, el sistema no lo otorga e inf ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Un administrador puede definir un paquete con multiples entitlements gobernados. | | 2 | Un solicitante puede pedir el paquete en lugar de seleccionar cada entitlement. | | 3 | Un aprobador puede aprobar o denegar la solicitud del paquete. | @@ -68,16 +68,16 @@ Si el paquete tiene vigencia limitada y ya vencio, el sistema no lo otorga e inf ## 8. Requisitos Tecnicos -- Introducir un modelo de paquete con definiciones versionadas y membresia de items. -- Persistir el alcance del paquete, los entitlements incluidos, el estado de aprobacion y el estado efectivo de asignacion. -- Reutilizar la ruta de aprobacion y el registro de auditoria para que las decisiones del paquete sigan siendo trazables. -- Soportar reglas de vencimiento y revocacion del paquete en la capa de enforcement de acceso. -- Mantener la composicion del paquete alineada con los catalogos de sistema y autorizacion. +* Introducir un modelo de paquete con definiciones versionadas y membresia de items. +* Persistir el alcance del paquete, los entitlements incluidos, el estado de aprobacion y el estado efectivo de asignacion. +* Reutilizar la ruta de aprobacion y el registro de auditoria para que las decisiones del paquete sigan siendo trazables. +* Soportar reglas de vencimiento y revocacion del paquete en la capa de enforcement de acceso. +* Mantener la composicion del paquete alineada con los catalogos de sistema y autorizacion. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `SystemSuite`, `Role`, `Profile`, `PermissionTemplate`, `ApprovalRequest` | | Historias Funcionales | FS-02, FS-05, FS-24 | | ADRs | ADR-0012, ADR-0015, ADR-0035 | diff --git a/docs/governance/requirements-es/functional-stories/fs-30-provisioning-deprovisioning-connectors.md b/docs/governance/requirements-es/functional-stories/fs-30-provisioning-deprovisioning-connectors.md index bd40bbe3..4ef1d2b6 100644 --- a/docs/governance/requirements-es/functional-stories/fs-30-provisioning-deprovisioning-connectors.md +++ b/docs/governance/requirements-es/functional-stories/fs-30-provisioning-deprovisioning-connectors.md @@ -9,7 +9,7 @@ Cuando el acceso cambia en UMS, los sistemas descendentes deben recibir automati ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Administrador de Operaciones de Identidad | Configura el conector y sus reglas de mapeo. | | Propietario del Sistema Externo | Confirma el destino descendente y el modelo de acceso. | | Conector de Integracion | Aplica la accion de provisioning o deprovisioning. | @@ -17,9 +17,9 @@ Cuando el acceso cambia en UMS, los sistemas descendentes deben recibir automati ## 3. Precondiciones de Negocio -- Un sistema o aplicacion descendente ya fue registrado como destino. -- Existen reglas de mapeo para los datos que deben sincronizarse. -- El tenant tiene un flujo aprobado para provisioning y deprovisioning. +* Un sistema o aplicacion descendente ya fue registrado como destino. +* Existen reglas de mapeo para los datos que deben sincronizarse. +* El tenant tiene un flujo aprobado para provisioning y deprovisioning. ## 4. Flujo Funcional Principal @@ -46,7 +46,7 @@ Si un usuario pierde el acceso, la accion de deprovisioning debe intentarse y se ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | Todo cambio de acceso gobernado debe reflejarse en el sistema descendente cuando el conector este habilitado. | | BR-02 | El deprovisioning es obligatorio cuando el acceso se revoca o expira. | | BR-03 | Los fallos deben ser visibles y reintentables; no pueden mantener acceso en silencio. | @@ -57,7 +57,7 @@ Si un usuario pierde el acceso, la accion de deprovisioning debe intentarse y se ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Se puede registrar un conector para un sistema descendente. | | 2 | Los cambios de acceso generan la accion de provisioning o deprovisioning esperada. | | 3 | La accion permanece trazable hasta que el sistema descendente confirma el cambio o se corrige. | @@ -67,16 +67,16 @@ Si un usuario pierde el acceso, la accion de deprovisioning debe intentarse y se ## 8. Requisitos Tecnicos -- Introducir un modelo de conector para destinos de provisioning descendente y sus mapeos. -- Persistir acciones de provisioning, estado de entrega, conteo de reintentos y resultado final. -- Emitir y consumir eventos de outbox para cambios de perfil, rol y entitlement. -- Soportar reintento manual y visibilidad operacional para entregas fallidas. -- Mantener los conectores aislados mediante adaptadores tipo ACL para que los esquemas externos no contaminen el dominio. +* Introducir un modelo de conector para destinos de provisioning descendente y sus mapeos. +* Persistir acciones de provisioning, estado de entrega, conteo de reintentos y resultado final. +* Emitir y consumir eventos de outbox para cambios de perfil, rol y entitlement. +* Soportar reintento manual y visibilidad operacional para entregas fallidas. +* Mantener los conectores aislados mediante adaptadores tipo ACL para que los esquemas externos no contaminen el dominio. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `UserAccount`, `Profile`, `Role`, `SystemSuite`, `IdentityProvider`, `AuditRecord` | | Historias Funcionales | FS-03, FS-05, FS-24 | -| ADRs | ADR-0015, ADR-0033, ADR-0072 | +| ADRs | ADR-0015, ADR-0033, ADR-UMS-072 | diff --git a/docs/governance/requirements-es/functional-stories/fs-31-privileged-access-time-bound-elevation.md b/docs/governance/requirements-es/functional-stories/fs-31-privileged-access-time-bound-elevation.md index c826183e..956cf7c7 100644 --- a/docs/governance/requirements-es/functional-stories/fs-31-privileged-access-time-bound-elevation.md +++ b/docs/governance/requirements-es/functional-stories/fs-31-privileged-access-time-bound-elevation.md @@ -9,7 +9,7 @@ El acceso privilegiado debe otorgarse solo durante el tiempo necesario y luego r ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Solicitante de Acceso Privilegiado | Solicita acceso elevado temporal. | | Aprobador de Seguridad | Revisa y aprueba o deniega la elevacion. | | Administrador de Seguridad | Configura la politica de acceso privilegiado. | @@ -17,9 +17,9 @@ El acceso privilegiado debe otorgarse solo durante el tiempo necesario y luego r ## 3. Precondiciones de Negocio -- El usuario ya existe en UMS y tiene una identidad base. -- El rol privilegiado o el alcance elevado ya esta definido. -- La organizacion tiene una politica de aprobacion para elevacion temporal. +* El usuario ya existe en UMS y tiene una identidad base. +* El rol privilegiado o el alcance elevado ya esta definido. +* La organizacion tiene una politica de aprobacion para elevacion temporal. ## 4. Flujo Funcional Principal @@ -46,7 +46,7 @@ Si el alcance solicitado es especialmente sensible, el sistema puede requerir un ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | El acceso privilegiado debe ser temporal y estar aprobado de forma explicita. | | BR-02 | Cada elevacion debe tener hora de inicio, hora de fin y motivo. | | BR-03 | El acceso debe eliminarse automaticamente cuando la elevacion vence. | @@ -57,7 +57,7 @@ Si el alcance solicitado es especialmente sensible, el sistema puede requerir un ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Un solicitante puede pedir acceso privilegiado temporal con motivo y duracion. | | 2 | Un aprobador puede aprobar o denegar la solicitud. | | 3 | El acceso aprobado expira automaticamente al final de la ventana aprobada. | @@ -67,16 +67,16 @@ Si el alcance solicitado es especialmente sensible, el sistema puede requerir un ## 8. Requisitos Tecnicos -- Introducir un modelo de elevacion con limite de tiempo que pueda guardar solicitante, aprobador, alcance, inicio, fin y estado. -- Integrar las decisiones de elevacion con el flujo de aprobacion y la politica de enforcement de acceso. -- Emitir eventos auditables para otorgamiento, vencimiento y retiro del acceso elevado. -- Soportar limites de duracion y umbrales de aprobacion definidos por politica. -- Mantener el modelo de acceso privilegiado separado de la asignacion permanente de roles. +* Introducir un modelo de elevacion con limite de tiempo que pueda guardar solicitante, aprobador, alcance, inicio, fin y estado. +* Integrar las decisiones de elevacion con el flujo de aprobacion y la politica de enforcement de acceso. +* Emitir eventos auditables para otorgamiento, vencimiento y retiro del acceso elevado. +* Soportar limites de duracion y umbrales de aprobacion definidos por politica. +* Mantener el modelo de acceso privilegiado separado de la asignacion permanente de roles. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `ApprovalWorkflow`, `ApprovalRequest`, `AccessEnforcementPolicy`, `Role`, `Profile` | | Historias Funcionales | FS-10, FS-16, FS-24 | | ADRs | ADR-0012, ADR-0016, ADR-0035 | diff --git a/docs/governance/requirements-es/functional-stories/fs-32-operational-reliability-guardrails.md b/docs/governance/requirements-es/functional-stories/fs-32-operational-reliability-guardrails.md index cf9b2376..f0d0eb61 100644 --- a/docs/governance/requirements-es/functional-stories/fs-32-operational-reliability-guardrails.md +++ b/docs/governance/requirements-es/functional-stories/fs-32-operational-reliability-guardrails.md @@ -9,7 +9,7 @@ Los administradores necesitan operaciones de gobierno predecibles incluso cuando ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Administrador de Plataforma | Realiza acciones de gobierno de tenant y sistema. | | Administrador de Tenant | Realiza administracion con alcance limitado al tenant. | | Ingeniero de Soporte | Investiga acciones fallidas o duplicadas. | @@ -17,9 +17,9 @@ Los administradores necesitan operaciones de gobierno predecibles incluso cuando ## 3. Precondiciones de Negocio -- El actor esta autenticado con el alcance correcto de tenant o plataforma. -- El elemento objetivo existe y es elegible para la accion solicitada. -- El contexto de tenant esta disponible antes de enviar la operacion. +* El actor esta autenticado con el alcance correcto de tenant o plataforma. +* El elemento objetivo existe y es elegible para la accion solicitada. +* El contexto de tenant esta disponible antes de enviar la operacion. ## 4. Flujo Funcional Principal @@ -47,7 +47,7 @@ Si la solicitud no trae un contexto de tenant valido, la accion se rechaza y no ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | Los envios repetidos no deben crear estado de gobierno duplicado. | | BR-02 | Las actualizaciones concurrentes no deben sobrescribir silenciosamente cambios mas nuevos. | | BR-03 | El alcance del tenant siempre debe conocerse antes de aceptar un cambio. | @@ -58,7 +58,7 @@ Si la solicitud no trae un contexto de tenant valido, la accion se rechaza y no ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Repetir la misma accion no crea estado de negocio duplicado. | | 2 | Un cambio concurrente se detecta en lugar de sobrescribirse en silencio. | | 3 | Una solicitud sin contexto de tenant se rechaza. | @@ -68,16 +68,16 @@ Si la solicitud no trae un contexto de tenant valido, la accion se rechaza y no ## 8. Requisitos Tecnicos -- Introducir deduplicacion de solicitudes para los flujos de comando soportados. -- Agregar verificacion de concurrencia optimista para registros mutables que pueden editarse al mismo tiempo. -- Aplicar tenant scoping antes de que la operacion entre en el flujo de aplicacion. -- Mantener observable la entrega de outbox o eventos para que operaciones vea cuando un cambio sigue pendiente. -- Exponer feedback accionable de conflicto y reintento en lugar de fallos genericos. +* Introducir deduplicacion de solicitudes para los flujos de comando soportados. +* Agregar verificacion de concurrencia optimista para registros mutables que pueden editarse al mismo tiempo. +* Aplicar tenant scoping antes de que la operacion entre en el flujo de aplicacion. +* Mantener observable la entrega de outbox o eventos para que operaciones vea cuando un cambio sigue pendiente. +* Exponer feedback accionable de conflicto y reintento en lugar de fallos genericos. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `Tenant`, `UserAccount`, `Profile`, `ApprovalRequest`, `AppConfiguration`, `AuditRecord` | | Historias Funcionales | FS-03, FS-05, FS-13, FS-24 | -| ADRs | ADR-0010, ADR-0033, ADR-0063, ADR-0066 | +| ADRs | ADR-0010, ADR-0033, ADR-UMS-063, ADR-UMS-066 | diff --git a/docs/governance/requirements-es/functional-stories/fs-33-authorization-graph-explorer.md b/docs/governance/requirements-es/functional-stories/fs-33-authorization-graph-explorer.md index 338914b4..5f8a0740 100644 --- a/docs/governance/requirements-es/functional-stories/fs-33-authorization-graph-explorer.md +++ b/docs/governance/requirements-es/functional-stories/fs-33-authorization-graph-explorer.md @@ -9,16 +9,16 @@ Los administradores de autorizacion y los equipos de soporte necesitan entender ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Administrador de Autorizacion | Verifica el grafo efectivo antes de aprobar cambios. | | Ingeniero de Soporte | Diagnostica problemas de acceso usando una simulacion segura. | | Auditor | Revisa por que el acceso cambio o no cambio. | ## 3. Precondiciones de Negocio -- El perfil, plantilla o paquete objetivo existe o esta siendo propuesto. -- El actor tiene acceso de diagnostico al alcance del tenant relevante. -- El grafo de autorizacion actual puede resolverse para el alcance seleccionado. +* El perfil, plantilla o paquete objetivo existe o esta siendo propuesto. +* El actor tiene acceso de diagnostico al alcance del tenant relevante. +* El grafo de autorizacion actual puede resolverse para el alcance seleccionado. ## 4. Flujo Funcional Principal @@ -46,7 +46,7 @@ Si la simulacion no tiene suficiente contexto para evaluar el grafo, el sistema ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | El explorador no debe cambiar el acceso real por si mismo. | | BR-02 | Los grafos actual y propuesto deben distinguirse claramente. | | BR-03 | La vista previa debe explicar las rutas efectivas que otorgan acceso. | @@ -56,7 +56,7 @@ Si la simulacion no tiene suficiente contexto para evaluar el grafo, el sistema ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Un actor autorizado puede previsualizar el grafo efectivo actual. | | 2 | El actor puede simular un cambio propuesto antes de aprobarlo. | | 3 | El explorador muestra la diferencia entre el acceso actual y el propuesto. | @@ -65,16 +65,16 @@ Si la simulacion no tiene suficiente contexto para evaluar el grafo, el sistema ## 8. Requisitos Tecnicos -- Reutilizar el motor de grafo de autorizacion tanto para la evaluacion en vivo como para la simulada. -- Soportar una vista diff de solo lectura que compare el grafo resuelto antes y despues del cambio propuesto. -- Mantener el endpoint o la consulta de vista previa aislado de las operaciones de escritura. -- Emitir eventos de auditoria de diagnostico para el acceso de vista previa y simulacion. -- Preservar el alcance del tenant y los permisos durante la resolucion del grafo. +* Reutilizar el motor de grafo de autorizacion tanto para la evaluacion en vivo como para la simulada. +* Soportar una vista diff de solo lectura que compare el grafo resuelto antes y despues del cambio propuesto. +* Mantener el endpoint o la consulta de vista previa aislado de las operaciones de escritura. +* Emitir eventos de auditoria de diagnostico para el acceso de vista previa y simulacion. +* Preservar el alcance del tenant y los permisos durante la resolucion del grafo. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `Profile`, `PermissionTemplate`, `Role`, `SystemSuite`, `AuditRecord` | | Historias Funcionales | FS-07, FS-24, FS-29 | -| ADRs | ADR-0021, ADR-0071, ADR-0074 | +| ADRs | ADR-0021, ADR-UMS-088, ADR-UMS-074 | diff --git a/docs/governance/requirements-es/functional-stories/fs-34-business-semantic-access-packages.md b/docs/governance/requirements-es/functional-stories/fs-34-business-semantic-access-packages.md index 56979fb7..7dd32d42 100644 --- a/docs/governance/requirements-es/functional-stories/fs-34-business-semantic-access-packages.md +++ b/docs/governance/requirements-es/functional-stories/fs-34-business-semantic-access-packages.md @@ -9,7 +9,7 @@ Los responsables de negocio necesitan paquetes de acceso definidos en lenguaje d ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Arquitecto de Entitlements | Disena la composicion del paquete. | | Propietario de Negocio | Valida que el paquete coincide con la necesidad del negocio. | | Aprobador | Confirma si el paquete puede publicarse o asignarse. | @@ -17,9 +17,9 @@ Los responsables de negocio necesitan paquetes de acceso definidos en lenguaje d ## 3. Precondiciones de Negocio -- Ya existen el catalogo de sistemas y el catalogo de autorizacion. -- El paquete puede mapearse a alcances de negocio reales como tenant, sucursal, sistema o tipo de socio. -- La aprobacion y la politica de expiracion estan configuradas. +* Ya existen el catalogo de sistemas y el catalogo de autorizacion. +* El paquete puede mapearse a alcances de negocio reales como tenant, sucursal, sistema o tipo de socio. +* La aprobacion y la politica de expiracion estan configuradas. ## 4. Flujo Funcional Principal @@ -46,7 +46,7 @@ Si una version anterior ya no es valida, el sistema no permite reutilizarla sin ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | Los paquetes deben nombrarse y modelarse en lenguaje de negocio. | | BR-02 | Las versiones del paquete deben ser inmutables una vez publicadas. | | BR-03 | El paquete debe reflejar solo el alcance de negocio permitido. | @@ -56,7 +56,7 @@ Si una version anterior ya no es valida, el sistema no permite reutilizarla sin ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Un paquete puede modelarse con alcance de negocio y entitlements tecnicos juntos. | | 2 | Un paquete puede versionarse y publicarse sin perder historial. | | 3 | Un propietario de negocio puede confirmar que el paquete coincide con el patron de acceso esperado. | @@ -65,16 +65,16 @@ Si una version anterior ya no es valida, el sistema no permite reutilizarla sin ## 8. Requisitos Tecnicos -- Agregar metadatos del paquete para terminos de negocio, alcance, version y estado de ciclo de vida. -- Mantener inmutable la composicion del paquete despues de su publicacion. -- Soportar la composicion por roles, permisos y reglas de acceso. -- Reutilizar aprobacion y auditoria para que la publicacion y asignacion del paquete sean trazables. -- Permitir que la resolucion del paquete se evalúe por alcance de negocio sin filtrar detalles de implementacion interna. +* Agregar metadatos del paquete para terminos de negocio, alcance, version y estado de ciclo de vida. +* Mantener inmutable la composicion del paquete despues de su publicacion. +* Soportar la composicion por roles, permisos y reglas de acceso. +* Reutilizar aprobacion y auditoria para que la publicacion y asignacion del paquete sean trazables. +* Permitir que la resolucion del paquete se evalúe por alcance de negocio sin filtrar detalles de implementacion interna. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `SystemSuite`, `Role`, `PermissionTemplate`, `Profile`, `ApprovalRequest` | | Historias Funcionales | FS-02, FS-24, FS-29 | | ADRs | ADR-0012, ADR-0015, ADR-0035 | diff --git a/docs/governance/requirements-es/functional-stories/fs-35-continuous-access-health.md b/docs/governance/requirements-es/functional-stories/fs-35-continuous-access-health.md index 25cbcb54..9c1c64a4 100644 --- a/docs/governance/requirements-es/functional-stories/fs-35-continuous-access-health.md +++ b/docs/governance/requirements-es/functional-stories/fs-35-continuous-access-health.md @@ -9,16 +9,16 @@ Los equipos de seguridad y gobierno necesitan una vista continua de la calidad d ## 2. Actores | Actor | Responsabilidad | -|---|---| +| --- | --- | | Administrador de Seguridad | Revisa las senales de salud y los umbrales. | | Administrador IGA | Usa las recomendaciones para lanzar acciones de limpieza o revision. | | Auditor | Revisa la tendencia de salud y el historial de remediacion. | ## 3. Precondiciones de Negocio -- UMS tiene suficientes datos de acceso, auditoria y revision para evaluar senales de salud. -- El tenant tiene una politica que define que es saludable, riesgoso o obsoleto. -- El actor puede acceder al area de diagnostico de gobierno. +* UMS tiene suficientes datos de acceso, auditoria y revision para evaluar senales de salud. +* El tenant tiene una politica que define que es saludable, riesgoso o obsoleto. +* El actor puede acceder al area de diagnostico de gobierno. ## 4. Flujo Funcional Principal @@ -45,7 +45,7 @@ Si el acceso esta saludable, el sistema lo explica y mantiene el puntaje visible ## 6. Reglas de Negocio | Regla | Descripcion | -|---|---| +| --- | --- | | BR-01 | El puntaje de salud del acceso debe ser explicable. | | BR-02 | Las recomendaciones deben derivarse de senales observables de acceso y auditoria. | | BR-03 | El sistema no debe remover acceso automaticamente salvo que la politica lo permita explicitamente. | @@ -55,7 +55,7 @@ Si el acceso esta saludable, el sistema lo explica y mantiene el puntaje visible ## 7. Criterios de Aceptacion | # | Criterio de Aceptacion | -|---|---| +| --- | --- | | 1 | Un actor puede ver un puntaje de salud para el acceso dentro de un tenant o alcance. | | 2 | El sistema explica las senales que influyeron en el puntaje. | | 3 | El sistema recomienda una siguiente accion de gobierno. | @@ -64,16 +64,16 @@ Si el acceso esta saludable, el sistema lo explica y mantiene el puntaje visible ## 8. Requisitos Tecnicos -- Calcular la salud del acceso a partir de auditoria, asignacion, revision y vencimiento. -- Proveer reglas y umbrales de puntuacion explicables. -- Soportar recomendaciones sin cambiar automaticamente el acceso. -- Permitir que los resultados de salud alimenten campanas de revision, limpieza de paquetes y expiracion de accesos privilegiados. -- Preservar el aislamiento por tenant y el recalculo deterministico con las mismas entradas. +* Calcular la salud del acceso a partir de auditoria, asignacion, revision y vencimiento. +* Proveer reglas y umbrales de puntuacion explicables. +* Soportar recomendaciones sin cambiar automaticamente el acceso. +* Permitir que los resultados de salud alimenten campanas de revision, limpieza de paquetes y expiracion de accesos privilegiados. +* Preservar el aislamiento por tenant y el recalculo deterministico con las mismas entradas. ## 9. Trazabilidad | Tipo | Referencias | -|---|---| +| --- | --- | | Entidades de Dominio | `AuditRecord`, `Profile`, `Role`, `ApprovalRequest`, `AccessEnforcementPolicy` | | Historias Funcionales | FS-16, FS-28, FS-31, FS-32 | -| ADRs | ADR-0016, ADR-0033, ADR-0066 | +| ADRs | ADR-0016, ADR-0033, ADR-UMS-066 | diff --git a/docs/governance/requirements-es/functional-stories/fs-36-configurable-refresh-token.md b/docs/governance/requirements-es/functional-stories/fs-36-configurable-refresh-token.md new file mode 100644 index 00000000..09832684 --- /dev/null +++ b/docs/governance/requirements-es/functional-stories/fs-36-configurable-refresh-token.md @@ -0,0 +1,95 @@ +# Historia Funcional 36: Refresh Token Configurable por Inquilino con Regeneración del Grafo + +> **Trazabilidad:** FR-015 · [D-012](../../../DECISIONS.md) · [G-034](../../../GAPS.md) · revisa **ADR-UMS-088** ([evolith-core#17](https://github.com/beyondnetcode/evolith-core/issues/17)) · relacionada con [fs-01](./fs-01-autenticacion-usuario.md), [fs-37](./fs-37-revocacion-refresh-token.md) + +## Tabla de Navegación + +* [#2-actores](#2-actores) +* [#4-flujo](#4-flujo-funcional-principal) +* [#7-criterios](#7-criterios-de-aceptación) +* [#8-tecnicos](#8-requisitos-técnicos) + +## 1. Propósito de Negocio + +Hoy el Grafo de Autorización vence por expiración (`validUntil`) y el cliente debe **re-autenticarse por completo** al caducar. Los inquilinos que operan sesiones largas quieren **renovar sin re-login**, y al mismo tiempo que la renovación **refleje el estado de permisos actual** (no uno congelado). Esta capacidad, **activable por configuración del propio inquilino**, emite un refresh token y, al renovar, **regenera el grafo completo** desde el estado vigente — cerrando la brecha de latencia de permisos sin perder la inmutabilidad por instancia de ADR-UMS-088. + +## 2. Actores + +| Actor | Responsabilidad | +| :--- | :--- | +| **Usuario autenticado** | Mantiene una sesión que puede renovarse sin re-login. | +| **Sistema cliente / API** | Presenta el refresh token al vencer el grafo y consume el grafo regenerado. | +| **Administrador del inquilino** | Activa la capacidad y parametriza su comportamiento (vida, rotación, reuso, tope). | +| **UMS** | Emite/rota el refresh, valida su vigencia y **regenera el grafo completo** desde el estado actual. | + +## 3. Precondiciones de Negocio + +* El usuario se autenticó correctamente (local o federado, [fs-01](./fs-01-autenticacion-usuario.md)). +* El inquilino tiene resuelta su configuración jerárquica (Global > Suite > Tenant > Module). +* El flag `AUTH_REFRESH_TOKEN_ENABLED` está **publicado** para el inquilino; si está apagado o mal configurado, aplica el modelo actual (solo expiración) — **fail-closed**. + +## 4. Flujo Funcional Principal + +```mermaid +sequenceDiagram + participant C as Cliente + participant U as UMS + participant CFG as Configuration + C->>U: Autenticación (fs-01) + U->>CFG: ¿AUTH_REFRESH_TOKEN_ENABLED (efectivo)? + CFG-->>U: ON + parámetros (vida, rotación, reuso, tope) + U-->>C: Grafo de Autorización + refresh token + Note over C: Opera con el grafo hasta validUntil + C->>U: Renovar (presenta refresh token) + U->>U: Validar refresh (vigente, no revocado, no reusado) + U->>U: Regenerar GRAFO COMPLETO (estado actual) + alt rotación activada + U-->>C: Grafo nuevo + refresh rotado + else sin rotación + U-->>C: Grafo nuevo (mismo refresh) + end +``` + +1. El usuario se autentica; UMS resuelve la configuración efectiva del inquilino. +2. Si el flag está **ON**, UMS emite, junto al grafo, un **refresh token** según los parámetros del tenant. +3. El cliente opera con el grafo hasta `validUntil`. +4. Al vencer, el cliente **renueva** presentando el refresh token. +5. UMS valida el refresh (vigente, no revocado, no previamente consumido) y **regenera el grafo COMPLETO** consultando permisos, roles, plantillas, overrides, feature flags y configuración efectiva **actuales**. +6. Si la rotación está activada, UMS emite un refresh nuevo e invalida el anterior; si no, conserva el mismo. + +## 5. Flujos Alternativos y Excepciones + +* **A. Flag OFF (default):** no se emite refresh; al vencer el grafo el cliente **re-autentica por completo** (modelo actual del PRD). +* **B. Refresh reusado:** si llega un refresh ya consumido (rotación activa), UMS **invalida toda la familia** de tokens y fuerza re-login (mitigación de robo). +* **C. Refresh expirado o revocado:** la renovación falla; se exige re-autenticación completa (revocación en [fs-37](./fs-37-revocacion-refresh-token.md)). +* **D. Tope de renovaciones alcanzado:** si se configuró un máximo, agotarlo fuerza re-login. + +## 6. Reglas de Negocio + +1. El comportamiento (vida, rotación, detección de reuso, tope) lo fija la **configuración del inquilino**, versionada (Draft → Published → Archived). +2. La renovación **regenera** el grafo entero desde el estado vigente; **nunca** extiende ni reutiliza el grafo previo. Cada grafo emitido sigue siendo **inmutable** (ADR-UMS-088). +3. El refresh token **nunca** aparece en logs, proyecciones ni en el grafo; se guarda **hasheado/cifrado** en reposo. +4. Refresh y renovación **nunca cruzan de inquilino** (aislamiento multi-tenant). +5. Compatible con autenticación **local y federada**, resuelta por configuración en tiempo de login. + +## 7. Criterios de Aceptación + +Verificables por el agente BMAD Tester en **ambos modos**: + +1. **OFF (default):** con el flag apagado, la autenticación **no** devuelve refresh token; al expirar el grafo, la renovación no está disponible y se exige re-login → grafo nuevo. +2. **ON — emisión:** con el flag publicado, la autenticación devuelve grafo **y** refresh token acorde a los parámetros del tenant. +3. **ON — regeneración:** tras `validUntil`, renovar con un refresh válido devuelve un **grafo regenerado que refleja el estado actual** — caso: revocar un permiso o cambiar una plantilla y confirmar que la renovación **ya lo aplica** (con OFF, solo tras re-login). +4. **ON — rotación:** si la rotación está activada, cada renovación entrega un refresh nuevo y el anterior deja de servir. +5. **ON — expiración del refresh:** un refresh vencido no renueva → re-login. +6. **ON — reuso:** presentar un refresh ya consumido **invalida la familia** y fuerza re-login. +7. **Aislamiento:** un refresh de un inquilino no renueva en otro. +8. **Auditoría:** emisión, rotación, renovación, expiración y reuso quedan registrados (append-only, acotado por inquilino), sin exponer el token. +9. **Seguridad:** el refresh no aparece en ningún log, proyección ni en el grafo. + +## 8. Requisitos Técnicos + +* **Bounded context principal:** `Identity`/`Authentication` (emisión y validación del refresh, regeneración del grafo). **Soporte:** `Configuration` (flag + parámetros jerárquicos), `Audit` (eventos). +* **Dependencias:** [fs-01](./fs-01-autenticacion-usuario.md) (login), [fs-13](./fs-13-configuracion-jerarquica.md)/[fs-20](./fs-20-gestion-parametros-sistema.md) (configuración jerárquica), motor del grafo (ADR-UMS-088). +* **Restricciones:** fail-closed ante flag ausente o inválido; inmutabilidad por instancia del grafo; secreto del refresh hasheado/cifrado; sin cruce de inquilino. +* **ADRs relevantes:** **ADR-UMS-088** (motor/vigencia del grafo — **revisado** por esta capacidad), ADR-UMS-074 (versionado del esquema del grafo), ADR-UMS-072 (resolución dinámica del método de auth). La decisión técnica **cumple [ADR-UMS-091](../../../reference/architecture/adrs/UMS-091-refresh-token-configurable-revocacion.es.md) (Aceptado)**, que revisa ADR-UMS-088 (procedencia [evolith-core#17](https://github.com/beyondnetcode/evolith-core/issues/17), S-06). +* **Notas:** con ADR-UMS-091 aceptado, la **implementación** (endpoints de emisión/renovación, familia de tokens, persistencia cifrada, auditoría) está **en curso** ([G-034](../../../GAPS.md)). diff --git a/docs/governance/requirements-es/functional-stories/fs-37-refresh-token-revocation.md b/docs/governance/requirements-es/functional-stories/fs-37-refresh-token-revocation.md new file mode 100644 index 00000000..cdda860c --- /dev/null +++ b/docs/governance/requirements-es/functional-stories/fs-37-refresh-token-revocation.md @@ -0,0 +1,82 @@ +# Historia Funcional 37: Revocación de Refresh Token y Sesión + +> **Trazabilidad:** FR-016 · [D-012](../../../DECISIONS.md) · [G-034](../../../GAPS.md) · revisa **ADR-UMS-088** ([evolith-core#17](https://github.com/beyondnetcode/evolith-core/issues/17)) · depende de [fs-36](./fs-36-refresh-token-configurable.md) + +## Tabla de Navegación + +* [#2-actores](#2-actores) +* [#4-flujo](#4-flujo-funcional-principal) +* [#7-criterios](#7-criterios-de-aceptación) +* [#8-tecnicos](#8-requisitos-técnicos) + +## 1. Propósito de Negocio + +Cuando el flag de refresh está activo ([fs-36](./fs-36-refresh-token-configurable.md)), una sesión puede renovarse sin re-login. El negocio necesita poder **cortar esa capacidad en caliente**: un logout real, el bloqueo o suspensión de una cuenta, o un cambio crítico de permisos deben **impedir que el refresh siga regenerando grafos**. Sin revocación, un token robado o una cuenta comprometida seguirían renovando hasta la expiración del refresh. + +## 2. Actores + +| Actor | Responsabilidad | +| :--- | :--- | +| **Usuario** | Cierra sesión (logout real) o ve su acceso cortado. | +| **Administrador del inquilino / seguridad** | Revoca por bloqueo/suspensión o por cambio crítico de permisos. | +| **Sistema cliente / API** | Deja de poder renovar cuando el refresh está revocado. | +| **UMS** | Marca el refresh como revocado y rechaza toda renovación posterior; audita el evento. | + +## 3. Precondiciones de Negocio + +* La capacidad de refresh está **activa** para el inquilino ([fs-36](./fs-36-refresh-token-configurable.md)); sin refresh no hay nada que revocar (el modelo de solo expiración ya obliga a re-login). +* Existe un refresh token vigente asociado a la sesión/usuario/cuenta objetivo. + +## 4. Flujo Funcional Principal + +```mermaid +sequenceDiagram + participant A as Actor (usuario/admin/evento) + participant U as UMS + participant C as Cliente + A->>U: Revocar (logout / bloqueo / cambio de permisos) + U->>U: Marcar refresh (o familia) como revocado + U->>U: Auditar evento de revocación (por tenant) + Note over C: El grafo emitido sigue válido hasta validUntil + C->>U: Renovar (presenta refresh revocado) + U-->>C: Falla → re-autenticación completa requerida +``` + +1. Un actor (usuario en logout, admin por bloqueo/suspensión, o un evento de cambio crítico de permisos) dispara la revocación. +2. UMS marca el refresh (o la **familia** completa) como **revocado** y audita el evento acotado al inquilino. +3. El grafo ya emitido **sigue válido hasta su `validUntil`** (alcance explícito; ver Reglas). +4. En la siguiente renovación, el refresh revocado **falla** y UMS exige re-autenticación completa. + +## 5. Flujos Alternativos y Excepciones + +* **A. Logout real:** cerrar sesión revoca el refresh de esa sesión; renovar después falla. +* **B. Cuenta bloqueada/suspendida:** revoca todos los refresh de la cuenta; ninguna sesión puede renovar. +* **C. Cambio crítico de permisos:** revoca para forzar que la próxima sesión parta de permisos actuales (con refresh activo, la renovación de [fs-36](./fs-36-refresh-token-configurable.md) también los aplicaría al regenerar; la revocación es el corte inmediato). +* **D. Flag OFF:** no aplica — no hay refresh; el corte de acceso se da por expiración + re-login. + +## 6. Reglas de Negocio + +1. Un refresh **revocado no puede regenerar grafo**: la renovación falla y exige re-login. +2. **Alcance explícito:** la revocación actúa sobre la **capacidad de renovar** (el refresh), **no** sobre un grafo ya emitido, que sigue válido hasta su `validUntil` — salvo que el cliente valide la sesión en cada operación. Este límite se documenta para los sistemas cliente. +3. La revocación puede ser por **token, familia, sesión, usuario o cuenta**, y **nunca cruza de inquilino**. +4. Todo evento de revocación se **audita** (append-only, no repudiable, acotado por inquilino), sin exponer el token. + +## 7. Criterios de Aceptación + +Verificables por el agente BMAD Tester en **ambos modos**: + +1. **ON — logout:** tras logout real, renovar con ese refresh **falla** → re-login. +2. **ON — bloqueo:** al bloquear/suspender la cuenta, **ningún** refresh de esa cuenta renueva. +3. **ON — cambio de permisos:** revocar por cambio crítico corta la renovación con el refresh previo; la nueva sesión refleja los permisos actuales. +4. **Alcance:** un grafo ya emitido **sigue funcionando hasta `validUntil`** tras revocar el refresh (comportamiento documentado, no un fallo). +5. **Aislamiento:** revocar en un inquilino no afecta a otro. +6. **Auditoría:** cada revocación queda registrada (append-only, por inquilino), sin exponer el token. +7. **OFF (default):** con el flag apagado no hay refresh que revocar; el corte se da por expiración + re-login (sin endpoint de revocación de refresh). + +## 8. Requisitos Técnicos + +* **Bounded context principal:** `Identity`/`Authentication` (estado de revocación del refresh/familia). **Soporte:** `Audit` (eventos), `Configuration` (la capacidad depende del flag de [fs-36](./fs-36-refresh-token-configurable.md)). +* **Dependencias:** [fs-36](./fs-36-refresh-token-configurable.md) (emisión/rotación del refresh), ciclo de vida de cuenta ([fs-07](./fs-07-resolvedor-grafo-visual.md) no; ver bloqueo/suspensión en gestión de usuarios). +* **Restricciones:** la revocación es sobre la renovación, no sobre grafos vivos; sin cruce de inquilino; auditoría obligatoria. +* **ADRs relevantes:** **ADR-UMS-088** (vigencia del grafo — **revisado**), ADR-UMS-052 (auditoría inmutable). Cumple **[ADR-UMS-091](../../../reference/architecture/adrs/UMS-091-refresh-token-configurable-revocacion.es.md) (Aceptado)**, que revisa ADR-UMS-088 (procedencia [evolith-core#17](https://github.com/beyondnetcode/evolith-core/issues/17), S-06). +* **Notas:** con ADR-UMS-091 aceptado, la implementación (estado de revocación, su verificación en la renovación y la auditoría) está **en curso** ([G-034](../../../GAPS.md)). diff --git a/docs/governance/requirements/functional-stories/fs-25-ddd-domain-resource-hierarchy.es.md b/docs/governance/requirements-es/functional-stories/fs-38-ddd-domain-resource-hierarchy.md similarity index 57% rename from docs/governance/requirements/functional-stories/fs-25-ddd-domain-resource-hierarchy.es.md rename to docs/governance/requirements-es/functional-stories/fs-38-ddd-domain-resource-hierarchy.md index 34fbd7bc..67d35b4c 100644 --- a/docs/governance/requirements/functional-stories/fs-25-ddd-domain-resource-hierarchy.es.md +++ b/docs/governance/requirements-es/functional-stories/fs-38-ddd-domain-resource-hierarchy.md @@ -1,12 +1,12 @@ # Fs 25 Ddd Domain Resource Hierarchy (Espanol) -> Esta pagina es el espejo en espanol de [fs-25-ddd-domain-resource-hierarchy.md](fs-25-ddd-domain-resource-hierarchy.md). +> Esta pagina es el espejo en espanol de [fs-38-ddd-domain-resource-hierarchy.md](fs-38-ddd-domain-resource-hierarchy.md). > El contenido detallado permanece en la version en ingles hasta completar la traduccion completa. ## Idioma -- Ingles: [fs-25-ddd-domain-resource-hierarchy.md](fs-25-ddd-domain-resource-hierarchy.md) -- Espanol: [fs-25-ddd-domain-resource-hierarchy.es.md] +- Ingles: [fs-38-ddd-domain-resource-hierarchy.md](fs-38-ddd-domain-resource-hierarchy.md) +- Espanol: [fs-38-ddd-domain-resource-hierarchy.es.md] ## Resumen diff --git a/docs/governance/requirements/functional-stories/fs-26-auth-graph-preview-from-profile.es.md b/docs/governance/requirements-es/functional-stories/fs-39-auth-graph-preview-from-profile.md similarity index 57% rename from docs/governance/requirements/functional-stories/fs-26-auth-graph-preview-from-profile.es.md rename to docs/governance/requirements-es/functional-stories/fs-39-auth-graph-preview-from-profile.md index a542b626..a6c2eb40 100644 --- a/docs/governance/requirements/functional-stories/fs-26-auth-graph-preview-from-profile.es.md +++ b/docs/governance/requirements-es/functional-stories/fs-39-auth-graph-preview-from-profile.md @@ -1,12 +1,12 @@ # Fs 26 Auth Graph Preview From Profile (Espanol) -> Esta pagina es el espejo en espanol de [fs-26-auth-graph-preview-from-profile.md](fs-26-auth-graph-preview-from-profile.md). +> Esta pagina es el espejo en espanol de [fs-39-auth-graph-preview-from-profile.md](fs-39-auth-graph-preview-from-profile.md). > El contenido detallado permanece en la version en ingles hasta completar la traduccion completa. ## Idioma -- Ingles: [fs-26-auth-graph-preview-from-profile.md](fs-26-auth-graph-preview-from-profile.md) -- Espanol: [fs-26-auth-graph-preview-from-profile.es.md] +- Ingles: [fs-39-auth-graph-preview-from-profile.md](fs-39-auth-graph-preview-from-profile.md) +- Espanol: [fs-39-auth-graph-preview-from-profile.es.md] ## Resumen diff --git a/docs/governance/requirements/functional-stories/fs-27-state-change-consistency-broken-rules.es.md b/docs/governance/requirements-es/functional-stories/fs-40-state-change-consistency-broken-rules.md similarity index 59% rename from docs/governance/requirements/functional-stories/fs-27-state-change-consistency-broken-rules.es.md rename to docs/governance/requirements-es/functional-stories/fs-40-state-change-consistency-broken-rules.md index 368b88a0..95c42f1b 100644 --- a/docs/governance/requirements/functional-stories/fs-27-state-change-consistency-broken-rules.es.md +++ b/docs/governance/requirements-es/functional-stories/fs-40-state-change-consistency-broken-rules.md @@ -1,12 +1,12 @@ # Fs 27 State Change Consistency Broken Rules (Espanol) -> Esta pagina es el espejo en espanol de [fs-27-state-change-consistency-broken-rules.md](fs-27-state-change-consistency-broken-rules.md). +> Esta pagina es el espejo en espanol de [fs-40-state-change-consistency-broken-rules.md](fs-40-state-change-consistency-broken-rules.md). > El contenido detallado permanece en la version en ingles hasta completar la traduccion completa. ## Idioma -- Ingles: [fs-27-state-change-consistency-broken-rules.md](fs-27-state-change-consistency-broken-rules.md) -- Espanol: [fs-27-state-change-consistency-broken-rules.es.md] +- Ingles: [fs-40-state-change-consistency-broken-rules.md](fs-40-state-change-consistency-broken-rules.md) +- Espanol: [fs-40-state-change-consistency-broken-rules.es.md] ## Resumen diff --git a/docs/governance/requirements-es/functional-stories/functional-story-standard.md b/docs/governance/requirements-es/functional-stories/functional-story-standard.md index 898c0c0e..e99ac9a4 100644 --- a/docs/governance/requirements-es/functional-stories/functional-story-standard.md +++ b/docs/governance/requirements-es/functional-stories/functional-story-standard.md @@ -1,6 +1,6 @@ # Estándar de Redacción de Historias Funcionales -> **Fuente corporativa:** Este estándar local de UMS implementa el estándar base EVOLITH/BMAD-METHOD definido en [evolith_arch32/reference/governance/sdlc-es/03-documentation/functional-story-writing-standard.md](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/sdlc-es/03-documentation/functional-story-writing-standard.md). +> **Fuente corporativa:** Este estándar local de UMS implementa el estándar base BEYONDNET/BMAD-METHOD definido en [BeyondNet Arch/reference/governance/sdlc-es/03-documentation/functional-story-writing-standard.md](https://github.com/beyondnetcode/evolith-core/blob/main/reference/governance/sdlc-es/03-documentation/functional-story-writing-standard.md). Este estándar define cómo deben redactarse las Historias Funcionales de UMS para que Product Owners, Analistas de Negocio, QA y Desarrolladores puedan usar el mismo documento sin mezclar intención de negocio con detalle de implementación. @@ -28,14 +28,14 @@ Las secciones funcionales DEBEN usar lenguaje entendible para Product Owner o An Las secciones funcionales NO DEBEN iniciar con: -- rutas de API o métodos HTTP, -- nombres de protocolos, -- detalles de motor de base de datos, -- detalles de caché, -- ejemplos de payload, -- nombres de excepciones, -- frameworks o librerías, -- comportamiento específico de infraestructura. +* rutas de API o métodos HTTP, +* nombres de protocolos, +* detalles de motor de base de datos, +* detalles de caché, +* ejemplos de payload, +* nombres de excepciones, +* frameworks o librerías, +* comportamiento específico de infraestructura. Esos detalles pertenecen a **Requisitos Técnicos**. @@ -45,15 +45,15 @@ Esos detalles pertenecen a **Requisitos Técnicos**. La sección de Requisitos Técnicos DEBE capturar: -- APIs/endpoints, -- entidades y tablas, -- persistencia, caché e invalidación, -- controles de seguridad, -- eventos de auditoría, -- códigos de error, -- requisitos de protocolos o tokens, -- contratos de integración, -- restricciónes derivadas de ADRs o Technical Enablers. +* APIs/endpoints, +* entidades y tablas, +* persistencia, caché e invalidación, +* controles de seguridad, +* eventos de auditoría, +* códigos de error, +* requisitos de protocolos o tokens, +* contratos de integración, +* restricciónes derivadas de ADRs o Technical Enablers. Esta sección permite que desarrollo tenga precisión sin hacer más difícil la lectura funcional. @@ -65,13 +65,13 @@ Los criterios de aceptación DEBEN ser observables y validables desde negocio. D Correcto: -- "El patrocinador puede ver si la solicitud fue aprobada o rechazada." -- "El sistema evita que usuarios externos reciban perfiles administrativos internos." +* "El patrocinador puede ver si la solicitud fue aprobada o rechazada." +* "El sistema evita que usuarios externos reciban perfiles administrativos internos." Evitar en criterios funcionales: -- "La API retorna `403 Forbidden`." -- "Se invalidan llaves de Redis." -- "La base de datos escribe en `APPROVAL_REQUEST`." +* "La API retorna `403 Forbidden`." +* "Se invalidan llaves de Redis." +* "La base de datos escribe en `APPROVAL_REQUEST`." Mover esos detalles a Requisitos Técnicos. diff --git a/docs/governance/requirements-es/functional-stories/index.md b/docs/governance/requirements-es/functional-stories/index.md index d92187ce..4667eb88 100644 --- a/docs/governance/requirements-es/functional-stories/index.md +++ b/docs/governance/requirements-es/functional-stories/index.md @@ -34,6 +34,8 @@ Bienvenido al índice maestro de **Functional Stories** para el Sistema de Gesti * **[FS-22: Solicitud y Aprobacion de Alta de Usuario](./fs-22-user-signup-request-approval.md)** * **[FS-23: Solicitud de Perfil desde Usuario en Lobby](./fs-23-profile-access-request.es.md)** * **[FS-24: Aprobación de Solicitud de Perfil y Asignación Manual](./fs-24-profile-request-approval.es.md)** +* **[FS-25: Dataset Semilla de Desarrollo](./fs-25-seed-dataset.md)** +* **[FS-26: Admin Root — el Inquilino Raíz Administra su Propia Casa](./fs-26-admin-root-tenant-owner.md)** * **[FS-28: Campanas de Revision de Acceso para Recertificacion de Roles y Permisos](./fs-28-access-review-campaigns.md)** * **[FS-29: Paquetes de Entitlements para Bloques de Acceso Gobernados](./fs-29-entitlement-packages.md)** * **[FS-30: Conectores de Provisioning y Deprovisioning para Sistemas Descendentes](./fs-30-provisioning-deprovisioning-connectors.md)** @@ -42,6 +44,11 @@ Bienvenido al índice maestro de **Functional Stories** para el Sistema de Gesti * **[FS-33: Explorador de Grafo de Autorizacion con Simulacion What-If](./fs-33-authorization-graph-explorer.md)** * **[FS-34: Paquetes de Acceso con Semantica de Negocio y Compositor de Politicas](./fs-34-business-semantic-access-packages.md)** * **[FS-35: Salud Continua de Acceso y Recomendaciones](./fs-35-continuous-access-health.md)** +* **[FS-36: Refresh Token Configurable por Inquilino](./fs-36-configurable-refresh-token.md)** +* **[FS-37: Revocación de Refresh Token](./fs-37-refresh-token-revocation.md)** +* **[FS-38: Gestionar Recursos de Dominio con Jerarquía DDD](./fs-38-ddd-domain-resource-hierarchy.md)** +* **[FS-39: Previsualizar el Grafo de Autorización desde Mantenimiento de Perfil](./fs-39-auth-graph-preview-from-profile.md)** +* **[FS-40: Consistencia en Cambios de Estado — Broken Rules sobre Dependencias Activas](./fs-40-state-change-consistency-broken-rules.md)** --- diff --git a/docs/governance/requirements-es/permission-matrix-example.md b/docs/governance/requirements-es/permission-matrix-example.md index 1be6267a..9068dcbf 100644 --- a/docs/governance/requirements-es/permission-matrix-example.md +++ b/docs/governance/requirements-es/permission-matrix-example.md @@ -10,7 +10,7 @@ This document presents a practical demonstration of how the **ULPMS Resolution E Let's evaluate the permissions resolved for the following user session: * **User Name**: `Alex Arroyo` -* **Tenant / Organization**: `Unimar LIMA-01` +* **Tenant / Organization**: `BeyondNet LIMA-01` * **Assigned Profiles**: 1. `Terminal Operator Profile` (Linked to Template: `OperatorBaseline_v1.0.0`) 2. `Billing Guest Profile` (Custom Local Profile) diff --git a/docs/governance/requirements/conceptual-data-model.md b/docs/governance/requirements/conceptual-data-model.md index 6f8819ed..e1b433c8 100644 --- a/docs/governance/requirements/conceptual-data-model.md +++ b/docs/governance/requirements/conceptual-data-model.md @@ -1,5 +1,10 @@ # Conceptual Data Model +> **Superseded in part (ADR-0090).** Rows describing `MENU` / `SUBMENU` / `OPTION` as distinct +> required levels no longer reflect the model: navigation is one recursive entity, `MenuNode`, +> whose `kind` classifies the role without fixing the depth. See +> [ADR-0090](../../architecture/adrs/0090-recursive-menu-node-tree.md). + This document describes the **business-readable conceptual data model** for the User Management System (UMS). It intentionally uses business-friendly names, but every concept must map to the DDD aggregate model and to the physical ER model. diff --git a/docs/governance/requirements/functional-stories/fs-04-register-system-topology.md b/docs/governance/requirements/functional-stories/fs-04-register-system-topology.md index b7f34e52..dda13cb6 100644 --- a/docs/governance/requirements/functional-stories/fs-04-register-system-topology.md +++ b/docs/governance/requirements/functional-stories/fs-04-register-system-topology.md @@ -59,6 +59,6 @@ If a topology node is incomplete, UMS can save it as draft but prevents its use ## 9. Traceability -- Entities: `SystemSuite`, `Module`, `Menu`, `SubMenu`, `Option`, `Action` +- Entities: `SystemSuite`, `Module`, `MenuNode` (recursive tree, ADR-0090), `Action`, `DomainResource` - ADRs: ADR-0032, ADR-0034, ADR-0047 - Related Stories: FS-02, FS-07, FS-17 diff --git a/docs/governance/requirements/functional-stories/fs-25-ddd-domain-resource-hierarchy.md b/docs/governance/requirements/functional-stories/fs-38-ddd-domain-resource-hierarchy.md similarity index 100% rename from docs/governance/requirements/functional-stories/fs-25-ddd-domain-resource-hierarchy.md rename to docs/governance/requirements/functional-stories/fs-38-ddd-domain-resource-hierarchy.md diff --git a/docs/governance/requirements/functional-stories/fs-26-auth-graph-preview-from-profile.md b/docs/governance/requirements/functional-stories/fs-39-auth-graph-preview-from-profile.md similarity index 100% rename from docs/governance/requirements/functional-stories/fs-26-auth-graph-preview-from-profile.md rename to docs/governance/requirements/functional-stories/fs-39-auth-graph-preview-from-profile.md diff --git a/docs/governance/requirements/functional-stories/fs-27-state-change-consistency-broken-rules.md b/docs/governance/requirements/functional-stories/fs-40-state-change-consistency-broken-rules.md similarity index 100% rename from docs/governance/requirements/functional-stories/fs-27-state-change-consistency-broken-rules.md rename to docs/governance/requirements/functional-stories/fs-40-state-change-consistency-broken-rules.md diff --git a/docs/governance/requirements/functional-stories/index.md b/docs/governance/requirements/functional-stories/index.md index 889774cf..934a21bb 100644 --- a/docs/governance/requirements/functional-stories/index.md +++ b/docs/governance/requirements/functional-stories/index.md @@ -34,9 +34,8 @@ Welcome to the master **Functional Stories** index for the User Management Syste * **[FS-22: User Signup Request and Approval](./fs-22-user-signup-request-approval.md)** * **[FS-23: Profile Access Request from Lobby User](./fs-23-profile-access-request.md)** * **[FS-24: Profile Request Approval and Manual Assignment](./fs-24-profile-request-approval.md)** -* **[FS-25: Manage Domain Resources with DDD Hierarchy](./fs-25-ddd-domain-resource-hierarchy.md)** -* **[FS-26: Preview Auth Graph from Profile Maintenance](./fs-26-auth-graph-preview-from-profile.md)** -* **[FS-27: State-Change Consistency — Broken Rules on Active Dependencies](./fs-27-state-change-consistency-broken-rules.md)** +* **FS-25: Development Seed Dataset** — Spanish only: [fs-25-seed-dataset.md](../../requirements-es/functional-stories/fs-25-seed-dataset.md) +* **FS-26: Admin Root — the Root Tenant Administers its Own House** — Spanish only: [fs-26-admin-root-tenant-owner.md](../../requirements-es/functional-stories/fs-26-admin-root-tenant-owner.md) * **[FS-28: Access Review Campaigns for Role and Permission Recertification](./fs-28-access-review-campaigns.md)** * **[FS-29: Entitlement Packages for Governed Access Bundles](./fs-29-entitlement-packages.md)** * **[FS-30: Provisioning and Deprovisioning Connectors for Downstream Systems](./fs-30-provisioning-deprovisioning-connectors.md)** @@ -45,6 +44,11 @@ Welcome to the master **Functional Stories** index for the User Management Syste * **[FS-33: Authorization Graph Explorer with What-If Simulation](./fs-33-authorization-graph-explorer.md)** * **[FS-34: Business-Semantic Access Packages and Policy Composer](./fs-34-business-semantic-access-packages.md)** * **[FS-35: Continuous Access Health and Recommendations](./fs-35-continuous-access-health.md)** +* **FS-36: Tenant-Configurable Refresh Token** — Spanish only: [fs-36-configurable-refresh-token.md](../../requirements-es/functional-stories/fs-36-configurable-refresh-token.md) +* **FS-37: Refresh Token Revocation** — Spanish only: [fs-37-refresh-token-revocation.md](../../requirements-es/functional-stories/fs-37-refresh-token-revocation.md) +* **[FS-38: Manage Domain Resources with DDD Hierarchy](./fs-38-ddd-domain-resource-hierarchy.md)** +* **[FS-39: Preview Auth Graph from Profile Maintenance](./fs-39-auth-graph-preview-from-profile.md)** +* **[FS-40: State-Change Consistency — Broken Rules on Active Dependencies](./fs-40-state-change-consistency-broken-rules.md)** --- diff --git a/docs/governance/requirements/permission-matrix-example.md b/docs/governance/requirements/permission-matrix-example.md index 542c79ac..a79424ba 100644 --- a/docs/governance/requirements/permission-matrix-example.md +++ b/docs/governance/requirements/permission-matrix-example.md @@ -8,7 +8,7 @@ This document presents a practical demonstration of how the **ULPMS Resolution E Let's evaluate the permissions resolved for the following user session: * **User Name**: `Alex Arroyo` -* **Tenant / Organization**: `Unimar LIMA-01` +* **Tenant / Organization**: `BeyondNet LIMA-01` * **Assigned Profiles**: 1. `Terminal Operator Profile` (Linked to Template: `OperatorBaseline_v1.0.0`) 2. `Billing Guest Profile` (Custom Local Profile) diff --git a/docs/qa/phase1-authentication-e2e-plan.es.md b/docs/qa/phase1-authentication-e2e-plan.es.md new file mode 100644 index 00000000..dc4b043b --- /dev/null +++ b/docs/qa/phase1-authentication-e2e-plan.es.md @@ -0,0 +1,277 @@ +# Plan de pruebas E2E — Fase 1: autenticación UMS ↔ Tablero SDLC + +> Redactado el 2026-08-01 como **propuesta**. Alcance: **solo autenticación**; autorización (grafo, +> menús, controles por rol) queda para la Fase 2 y el diseño se hace modular para admitirla sin +> reestructurar. +> +> ## Estado — 2026-08-03: IMPLEMENTADO, y con partes de este plan retiradas +> +> Los 19 escenarios existen y corren: **carril D** del arnés, +> `src/tests/e2e-functional/robosoft/integracion-tablero/escenarios/`, enganchado a +> `scripts/certify-e2e.sh --carril d`. Medido contra el clúster: **19/19**. +> +> **Qué de este documento NO se implementó, y por qué** (cierra [G-221](../../GAPS.md)): +> +> * **§3.1 y §8 — CORS, la CSP de UMS y `SameSite=None`.** No aplican. El navegador nunca habla con +> UMS: la CSP del Tablero fija `connect-src 'self'` y la llamada la hace `fetch` de Node, servidor +> a servidor. Añadir el origen del Tablero a los orígenes permitidos de UMS abriría una superficie +> que la arquitectura cierra a propósito. No hay escenario multi-origen que probar. +> * **§5.1 — la comparativa de herramienta.** ADR-0109 ya decidió Playwright y el arnés ya lo usa. +> * **§5.2 — el árbol `tests/e2e/` nuevo.** Se construyó DENTRO del arnés existente. Un árbol +> paralelo es el mecanismo por el que se vuelve a construir lo ya construido, que es justo lo que +> documenta [G-189](../../GAPS.md). +> +> **Qué sobrevive y se respetó:** las cinco capas de §5.3 —visual, HTTP, API, almacenamiento y +> experiencia—, los datos sembrados por código de §5.4, y la simulación de §5.5 provocando la caída +> DE VERDAD (escalar réplicas a 0) en vez de interceptar. Esos dos escenarios de caída son **opt-in** +> (`E2E_PERMITE_CAIDA=1`) porque tumban UMS para todo el clúster; sin la variable se omiten y la +> omisión sale en el informe. + +## 1. Hallazgo que condicionaba la fase — INVALIDADO (2026-08-01) + +> **Corrección.** Lo que sigue en esta sección es **falso** y se conserva como registro. La +> comprobación se hizo sobre el árbol de `evolith-core` en la rama +> `arquitectura/design-review-baseline-onprem`, desactualizada; `develop` —en otro worktree— ya +> tenía el gate de identidad desde `3f51815` (ADR-0155): proxy servidor-a-servidor a +> `/client/authenticate`, cookie `httpOnly` con el JWT y verificación HS256. +> +> **Consecuencia para el plan:** la Fase 1a no había que construirla, solo completarla. Lo que +> faltaba —alta de cuenta y recuperación de contraseña— se añadió sobre `evolith-core@develop`. +> La secuencia real pasa a ser: **completar 1a → robot 1b**. Ver G-189 en [GAPS.md](../../GAPS.md). + +**El Tablero SDLC no tiene autenticación.** Verificado sobre +`evolith-core/reference/governance/tablero-ejecutivo/app`: + +| Comprobación | Resultado | +| :--- | :--- | +| Pantalla de acceso en `web/src` | No existe | +| Manejo de sesión o token en el cliente | No existe: `web/src/api.js` compone cabeceras con `Content-Type` y `baggage`, nunca `Authorization` | +| Endpoints de sesión en el servidor | No existen en `server/src` (no hay `login`, `session` ni verificación de JWT) | +| Middleware de autenticación | No existe; la API responde a cualquier llamante | + +De los 19 flujos pedidos —login, contraseña incorrecta, usuario inexistente, bloqueado, inactivo, +signup, confirmación, lost/reset password, refresh, logout, expiración de JWT, errores de +comunicación, timeouts, indisponibilidad de UMS, mensajes, redirecciones, almacenamiento de tokens +y cierre de sesión— **cero son ejecutables hoy contra el Tablero**: no hay superficie que ejercitar. + +Escribir el robot antes que la integración produciría 19 pruebas rojas que no describen un defecto, +sino una funcionalidad ausente. La secuencia correcta es: + +1. **Fase 1a — integración.** Dotar al Tablero de autenticación contra UMS. +2. **Fase 1b — robot.** Automatizar los 19 escenarios sobre esa integración. + +El resto de este plan detalla ambas, porque la 1b solo es diseñable sabiendo qué construye la 1a. + +## 2. Arquitectura actual verificada + +### 2.1 UMS + +| Aspecto | Estado | +| :--- | :--- | +| Backend | .NET 10, Clean Architecture + CQRS. Migraciones EF y siembra determinista al arrancar (`SeedDevData`) | +| Frontend | React 19 + Vite, SPA servida por nginx en producción | +| Autenticación | `POST /api/v1/auth/login` (BCrypt local o IdP federado), refresco, `POST /auth/switch-profile`, `POST /api/v1/client/authenticate` para sistemas satélite | +| Contrato de sesión | Grafo de autorización `2.3.0` — contexto, perfiles, navegación, permisos de dominio, banderas y `settings` | +| Despliegue | Chart Helm `src/infra/ums-helm`, imágenes `ums/backend` y `ums/frontend` con `pullPolicy: Never` (precargadas con `kind load`) | +| Clúster local | `kind` `evolith-ums-cluster`, namespaces `ums` (con observabilidad) y `ums-uat` | +| Ciclo reproducible | `scripts/uat-env.sh` (`up`, `reset`, `smoke`, `status`) — BD fresca → migraciones → siembra → smoke | + +**Se despliega de forma independiente: verificado.** El namespace `ums-uat` corre hoy backend, +frontend, PostgreSQL y Redis sin depender de ningún otro sistema. + +### 2.2 Tablero SDLC + +| Aspecto | Estado | +| :--- | :--- | +| Estructura | Monorepo npm con workspaces `shared`, `server`, `web` | +| Backend | Node.js, API REST en el puerto 4317 | +| Persistencia | PostgreSQL 16 (`docker-compose.yml`), con SQLite como origen histórico | +| Despliegue | Manifiestos en `k8s/` (`app.yaml`, `web.yaml`, `postgres.yaml`, `observability.yaml`) y `kind-cluster.yaml` del clúster `beyondnet-arch-management` | +| Autenticación | **Ausente** (ver §1) | + +**Se despliega de forma independiente: verificado.** Su clúster `kind` ya existe y es distinto del +de UMS. + +### 2.3 Consecuencia para el escenario de dos clústeres + +Ambos sistemas ya viven en clústeres `kind` separados —`evolith-ums-cluster` y +`beyondnet-arch-management`—, de modo que el punto 3 del encargo está cubierto en su mayor parte. Lo +que falta no es infraestructura sino **conectividad entre clústeres y una integración que la use**. + +## 3. Estrategia de comunicación entre clústeres + +Dos clústeres `kind` son dos redes Docker distintas. Tres opciones, con su veredicto: + +| Opción | Cómo | Veredicto | +| :--- | :--- | :--- | +| **A. Host como punto de encuentro** | Cada clúster expone su ingress en un puerto del host (`extraPortMappings`); el Tablero llama a UMS por `http://host.docker.internal:8080` | **Elegida.** Es la que menos piezas añade, funciona en macOS y Linux, y reproduce la topología real —dos sistemas que se hablan por HTTP a través de un borde— sin simularla | +| B. Red Docker compartida | Conectar ambos nodos `kind` a una red Docker común y resolver por nombre de contenedor | Frágil: `kind` recrea la red al recrear el clúster y el DNS entre nodos no es estable | +| C. Un solo clúster, dos namespaces | `ums` y `tablero` en el mismo clúster, comunicación por DNS interno | Más simple, pero **contradice el encargo** y esconde justo los problemas que la Fase 1 debe descubrir: CORS entre orígenes, certificados, latencia de borde | + +### 3.1 Problemas a resolver, ya identificados + +| Riesgo | Detalle | Mitigación | +| :--- | :--- | :--- | +| **CORS** | UMS restringe orígenes con `AllowedOrigins` (`appsettings`). El origen del Tablero no está en la lista | Añadir el origen del Tablero a la configuración del despliegue, no al código | +| **CSP** | La CSP del frontend de UMS limita `connect-src` a `'self' https: ws: wss:`. Un destino `http://` de otro origen **se bloquea en el navegador**, no en el servidor. Verificado en este entorno: costó un ciclo entero de diagnóstico | El Tablero debe llamar a UMS por su propio proxy (mismo origen) o por HTTPS | +| **DNS** | `host.docker.internal` no existe por defecto en Linux | `--add-host=host.docker.internal:host-gateway` en el nodo `kind`, o la IP del gateway | +| **Puertos** | `evolith-ums-cluster` ya mapea 8080; el Tablero mapea 4317 | Mantener el mapa de puertos documentado en un solo sitio | +| **Certificados** | Sin TLS entre clústeres, las cookies `Secure` de UMS no viajan | Fase 1: cookies no `Secure` en el perfil local, declarado explícitamente. Fase 2: `mkcert` + ingress TLS | +| **Cookie de sesión** | UMS emite cookie `HttpOnly` de sesión; entre orígenes distintos exige `SameSite=None; Secure` | Decidir en 1a: token en cabecera `Authorization` (recomendado para satélites) en vez de cookie | +| **Arranque** | El backend de UMS aplica migraciones y siembra al arrancar; el primer arranque tarda | El robot espera a `/health` antes de empezar, con reintento exponencial | + +## 4. Fase 1a — integración de autenticación en el Tablero + +Alcance mínimo para que los 19 escenarios existan: + +| Pieza | Descripción | +| :--- | :--- | +| Cliente UMS en `server/` | Envuelve `POST /api/v1/client/authenticate` (o `/auth/login`), refresco y cierre. Único punto que conoce UMS | +| Sesión | Token en memoria del cliente + `refresh` en cookie `HttpOnly` del propio Tablero, de modo que el token de UMS nunca toque `localStorage` | +| Middleware | Verifica el JWT en cada ruta de la API del Tablero; 401 con cuerpo tipado | +| Pantalla de acceso | Formulario, mensajes de error, bloqueo por intentos, redirección a la ruta pedida | +| Recuperación | Signup, confirmación, lost y reset password: **delegados a UMS**; el Tablero solo enlaza y recibe el retorno | +| Errores | Distinguir credencial inválida (401), usuario bloqueado/inactivo (403 con código), indisponibilidad (503/red) y timeout | + +**Restricción de fase:** nada de esto lee el grafo de autorización. El Tablero recibe el grafo y lo +guarda sin usarlo; la Fase 2 lo consumirá para menús y controles. Guardarlo desde ya evita rehacer +el contrato de sesión después. + +## 5. Fase 1b — el robot + +### 5.1 Tecnología: **Playwright** + +| Criterio | Playwright | Cypress | Selenium | +| :--- | :--- | :--- | :--- | +| Velocidad | Paralelismo real por _workers_ y navegador | Un navegador por proceso | Lento; depende de la malla | +| Estabilidad | Espera automática por estado, sin `sleep` | Buena, con reintentos | Frágil; esperas manuales | +| Interceptar red | `page.route` y `request` de primera clase: exige el contrato HTTP, no solo el píxel | `cy.intercept`, sólido | Requiere proxy externo | +| Evidencia | Vídeo, captura y **traza navegable** (DOM + red + consola por paso) | Vídeo y captura | Captura | +| Multi-origen | Soporta varios orígenes y pestañas en una prueba — **decisivo aquí**: la prueba cruza Tablero y UMS | Limitado históricamente entre dominios | Soportado | +| CI/CD | Imagen oficial con navegadores; `--shard` para repartir | Requiere servicio propio para paralelizar bien | Pesado | +| Mantenibilidad | TypeScript de origen, _fixtures_ componibles, POM natural | JS/TS | Verboso | + +**Decisión: Playwright.** Pesa sobre todo la traza —una prueba roja se diagnostica sin +reproducirla— y el soporte multi-origen, que aquí no es un lujo: el flujo de autenticación cruza +dos sistemas en dos orígenes distintos. + +Ya existe base instalada en el repositorio (`src/tests`), de modo que la decisión también evita +introducir una segunda herramienta. + +### 5.2 Estructura + +```text +tests/e2e/ +├─ playwright.config.ts # proyectos: chromium, webkit; shards; reporters +├─ fixtures/ +│ ├─ entorno.ts # URLs de ambos sistemas, resueltas por variable de entorno +│ ├─ usuarios.ts # personas sembradas: válido, bloqueado, inactivo, inexistente +│ ├─ sesion.ts # fixture que autentica por API y reutiliza estado +│ └─ red.ts # simulación de caída, latencia y timeout de UMS +├─ paginas/ # Page Objects — una clase por pantalla, sin aserciones +│ ├─ acceso.pagina.ts +│ └─ tablero.pagina.ts +├─ escenarios/ +│ ├─ 01-login.spec.ts +│ ├─ 02-credenciales.spec.ts # incorrecta, inexistente, bloqueado, inactivo +│ ├─ 03-alta.spec.ts # signup + confirmación +│ ├─ 04-password.spec.ts # lost + reset +│ ├─ 05-sesion.spec.ts # refresh, expiración, logout +│ ├─ 06-resiliencia.spec.ts # UMS caído, timeout, error de red +│ └─ 07-seguridad.spec.ts # almacenamiento del token, cierre de sesión +└─ soporte/ + ├─ aserciones.ts # aserciones de dominio reutilizables + └─ evidencia.ts # adjunta HAR, respuestas y capturas al informe +``` + +`escenarios/` numerado no impone orden de ejecución —las pruebas son independientes— sino orden de +lectura: quien abra la carpeta ve el recorrido del usuario. + +### 5.3 Qué valida cada escenario + +Cada prueba comprueba las **cinco capas** que pide el encargo, no solo la visual: + +1. **Visual** — el estado que ve el usuario (mensaje, redirección, elemento habilitado). +2. **HTTP** — método, URL, cabeceras y cuerpo de la llamada, capturados con `page.route`. +3. **API** — el código y el cuerpo que devuelve UMS, contrastados contra el contrato publicado. +4. **Almacenamiento** — que el token **no** esté en `localStorage`, que la cookie sea `HttpOnly`, y + que al cerrar sesión no quede rastro. +5. **Experiencia** — que el mensaje sea accionable y no filtre detalle interno (un «usuario + inexistente» y una «contraseña incorrecta» deben ser indistinguibles para no enumerar cuentas). + +### 5.4 Datos de prueba + +Sembrados por código, nunca preparados a mano (misma regla que `uat-env.sh`): un usuario válido, +uno bloqueado, uno inactivo y un correo inexistente, en el tenant `BEYONDNET`. Cada ejecución parte de +BD fresca; el robot **no** limpia lo que ensucia, se reconstruye el entorno. + +### 5.5 Simulación + +Solo donde el escenario lo exige y no se puede provocar de verdad: + +| Escenario | Cómo | +| :--- | :--- | +| UMS indisponible | Escalar el _deployment_ a 0 réplicas — indisponibilidad real, no simulada | +| Timeout | `page.route` con retardo por encima del umbral del cliente | +| JWT expirado | Emitir un token de vida corta por configuración del tenant, y esperar | + +Escalar réplicas en vez de interceptar es deliberado: prueba también que el Tablero distingue «no +responde» de «responde error», que es donde suelen fallar estos clientes. + +### 5.6 Informes, métricas y evidencia + +* Reporter HTML de Playwright + JUnit XML para integrarlo donde haga falta. +* Traza, vídeo y captura **solo de lo que falla** (`retain-on-failure`), para que el artefacto no + crezca sin control. +* HAR por escenario, adjunto al informe: deja auditable la conversación HTTP completa. +* Métricas por ejecución: duración por escenario, tasa de reintento y _flakiness_ acumulada. Una + prueba que necesita reintento no es verde: es una deuda registrada. + +### 5.7 Recuperación ante fallos + +* Reintento **1** en CI y **0** en local: en local un fallo debe verse. +* El robot verifica la salud de ambos sistemas antes de empezar y aborta con diagnóstico —qué + sistema, qué endpoint, qué código— en vez de encadenar 19 fallos que dicen lo mismo. +* Si un escenario deja el entorno inconsistente, la suite lo declara y fuerza `uat-env.sh reset` en + vez de continuar sobre datos sucios. + +## 6. Ciclo de ejecución + +```text +1. build imágenes de UMS y del Tablero +2. kind load precarga en cada clúster (pullPolicy: Never) +3. deploy helm upgrade --install (UMS) + kubectl apply (Tablero) +4. wait /health de ambos, con reintento exponencial +5. seed datos deterministas por código +6. e2e playwright test --shard +7. report HTML + JUnit + HAR + métricas +8. teardown opcional; por defecto el entorno queda en pie para inspección +``` + +Ejecutable en un solo comando (`scripts/e2e-env.sh up|test|down`), en la línea de `uat-env.sh` que +ya existe y funciona. + +## 7. Preparado para la Fase 2 + +Tres decisiones de este plan existen para que la autorización entre sin reestructurar: + +1. El Tablero **guarda el grafo desde la Fase 1** aunque no lo use: el contrato de sesión no cambia + al llegar la Fase 2. +2. Los Page Objects no conocen permisos; exponen elementos. Una prueba de Fase 2 afirmará sobre los + mismos objetos con otro usuario. +3. Las _fixtures_ de usuario ya llevan tenant y perfil, aunque la Fase 1 solo use el primero. + +## 8. Qué falta decidir + +| Punto | Opciones | +| :--- | :--- | +| Endpoint que usa el Tablero | `/api/v1/client/authenticate` (pensado para satélites, devuelve grafo) o `/auth/login` (portal). **Recomendado: el de cliente** | +| Transporte del token | Cabecera `Authorization` (recomendado entre orígenes) o cookie con `SameSite=None; Secure` (exige TLS local) | +| Signup y recuperación | ¿Los sirve UMS con su propia interfaz —y el Tablero solo enlaza— o el Tablero replica los formularios? **Recomendado: los sirve UMS** | +| Alcance del robot | ¿Solo el Tablero, o también el portal de UMS? El plan cubre el Tablero; añadir el portal es un proyecto más en la misma configuración | + +--- + ++ © BeyondNet S.A.C. · RUC 20100412447 · Operador Logístico Aduanero desde 1978 +
diff --git a/docs/sdk-es/contracts/schema-overview.md b/docs/sdk-es/contracts/schema-overview.md index d8a059cf..d439e98c 100644 --- a/docs/sdk-es/contracts/schema-overview.md +++ b/docs/sdk-es/contracts/schema-overview.md @@ -105,29 +105,26 @@ Catálogo de todas las entidades `Action` registradas en el `SystemSuite`. Usado ### 3.5 `menuAccess` (array, requerido, puede estar vacío) -Árbol de navegación UI: `Module → Menu → SubMenu → Option`, con el `AccessEffect` resuelto y `source` a nivel de hoja. +Árbol de navegación recursivo (v2.0.0, ADR-0090). Cada módulo lleva `nodes`; cada nodo puede +anidar `children` a profundidad arbitraria. `kind` clasifica el papel del nodo (`Menu`, `SubMenu`, +`Option`) **sin fijar dónde aparece**: no presupongas tres niveles, recorre `children` hasta +agotarlo. Solo viaja lo ALCANZABLE: una hoja sin acción resuelta se omite, y una rama que se queda +sin hojas se omite con ella. La ausencia significa «no concedido». ```jsonc "menuAccess": [ { - "module": { "id": "uuid", "code": "string", "name": "string", - "sortOrder": 0, "status": "PUBLISHED" }, - "menus": [ + "id": "uuid", "code": "string", "value": "string", + "sortOrder": 0, "status": "Active", "icon": "string|null", + "nodes": [ { - "id": "uuid", "code": "string", "label": "string", "sortOrder": 0, - "subMenus": [ - { - "id": "uuid", "code": "string", "label": "string", "sortOrder": 0, - "options": [ - { - "id": "uuid", "code": "string", "label": "string", - "actionCode": "VIEW", - "effect": "Allow" | "Deny" | "NotGranted", - "source": "Template" | "Override" - } - ] - } - ] + "id": "uuid", "code": "string", "value": "string", + "kind": "Menu" | "SubMenu" | "Option", + "sortOrder": 0, "icon": "string|null", "route": "string|null", + "actions": [ + { "actionCode": "VIEW", "effect": "Allow" | "Deny", "source": "Template" | "Override" } + ], + "children": [ /* misma forma, recursivamente */ ] } ] } diff --git a/docs/sdk-es/dotnet/README.md b/docs/sdk-es/dotnet/README.md index dd39c8bf..b8b66b10 100644 --- a/docs/sdk-es/dotnet/README.md +++ b/docs/sdk-es/dotnet/README.md @@ -99,7 +99,7 @@ Mapea a la sección `scopes[]` del grafo. El aspecto verifica que el string de s public Task
+
+# UMS: Enterprise User Management System
+
+> **Bilingual Navigation:** [Versión en Español](../reference/indices/index.md)
+
+[]()
+[]()
+[](https://github.com/beyondnetcode/evolith-core)
+[](../reference/architecture/adrs/)
+[]()
+
+
+ + +
+
+
+BeyondNet E2E Architecture Framework - UMS official satellite product - click to enlarge
+
+
+ +**UMS is a modular monolith for identity, authorization, configuration, approvals, compliance, IGA, and audit.**
+Built on **.NET 10, PostgreSQL, EF Core through Npgsql, React 18, TypeScript, and Nx**.
+It specializes the [BeyondNet](https://github.com/beyondnetcode/evolith-core) corporate architecture reference for a product-grade user management system. + +> *Inherit the standard, specialize the product.* + +
+
+---
+
+## Start Here
+
++ + +
+
+
+BeyondNet E2E Architecture Framework - UMS official satellite product - click to enlarge
+
++ +**UMS is a modular monolith for identity, authorization, configuration, approvals, compliance, IGA, and audit.**
+Built on **.NET 10, PostgreSQL, EF Core through Npgsql, React 18, TypeScript, and Nx**.
+It specializes the [BeyondNet](https://github.com/beyondnetcode/evolith-core) corporate architecture reference for a product-grade user management system. + +> *Inherit the standard, specialize the product.* + +
+
+
+Primary entry points
+ +- [Product Vision](../reference/gobernanza/product/vision-producto.md) - strategy, product goals, and business positioning. +- [Architecture Portal](../reference/architecture/index.md) - architectural overview, ADRs, blueprints, and applied reference material. +- [Domain Model](../docs/02-diseno/dominio/index.md) - bounded contexts, aggregates, entities, and domain rules. +- [Functional Stories](../docs/02-diseno/historias-funcionales/index.md) - business-readable product backlog. +- [Master Index](../reference/indices/indice-maestro.md) - complete documentation navigation. +- [BeyondNet Upstream](https://github.com/beyondnetcode/evolith-core) - corporate reference base inherited by UMS. + +
+
+
+## SDLC Navigation
+
+Open the lifecycle area you are working in. Each section groups the documents and repository anchors that support its gate.
+
+Getting started by role
+ +- **Architects:** start with [Architecture Portal](../reference/architecture/index.md), then review [ADR Registry](../reference/architecture/adrs/) and [Traceability Matrix](../reference/architecture/matriz-trazabilidad.md). +- **Backend developers:** start with [API .NET Reference](../reference/architecture/api-dotnet/README.md), then review [Domain Aggregates](../docs/02-diseno/dominio/index.md) and [.NET SDK](../reference/sdk/dotnet/README.md). +- **Frontend developers:** start with [Frontend Clean Architecture ADR](../reference/architecture/adrs/UMS-056-arquitectura-limpia-frontend.es.md), then review [TypeScript SDK](../reference/sdk/typescript/README.md) and [State Management ADR](../reference/architecture/adrs/UMS-057-estado-zustand-tanstack-query.es.md). +- **Product and PM:** start with [Product Vision](../reference/gobernanza/product/vision-producto.md), then review [Scope](../reference/gobernanza/product/alcance.md), [Objectives](../reference/gobernanza/product/objetivos.md), and [Gap Tracker](../reference/gobernanza/project/seguimiento-gaps-historias-funcionales.md). +- **DevOps and SRE:** start with [Infrastructure Plan](./infra/infrastructure_plan.md), then review [Operations Portal](../reference/operaciones/index.md), [Runbooks](../reference/operaciones/runbooks/index.md), and [Metrics](../reference/operaciones/metrics/index.md). +- **AI contributors:** start with [AGENTS.md](./AGENTS.md), then review [Documentation Control Agents](../reference/gobernanza/documentation-control-agents.md) and [ADR Template](../reference/gobernanza/sdlc/plantilla-adr.md). + +
+
+
+Phase 00 - Product and Governance
+ +| Documento | Tipo | +| :--- | :--- | +| [Product Vision](../reference/gobernanza/product/vision-producto.md) | Guía | +| [Business Context](../reference/gobernanza/product/contexto-negocio.md) | Guía | +| [Scope and Boundaries](../reference/gobernanza/product/alcance.md) | Guía | +| [Objectives](../reference/gobernanza/product/objetivos.md) | Guía | +| [Governance Hub](../reference/gobernanza/index.md) | Índice | +| [Stakeholders](../reference/gobernanza/product/partes-interesadas.md) | Registro | + +
+
+
+Phase 01 - Requirements
+ +| Documento | Tipo | +| :--- | :--- | +| [Functional Story Standard](../docs/02-diseno/historias-funcionales/estandar-redaccion-historias-funcionales.md) | Estándar | +| [Requirements Hub](../reference/gobernanza/requirements/index.md) | Índice | +| [Functional Stories](../docs/02-diseno/historias-funcionales/index.md) | Índice | +| [Permission Matrix Example](../reference/gobernanza/requirements/ejemplo-matriz-permisos.md) | Matriz | +| [Conceptual Data Model](../reference/gobernanza/requirements/modelo-datos-conceptual.md) | Referencia | +| [Glossary](../reference/gobernanza/requirements/glosario.md) | Referencia | + +
+
+
+Phase 02 - Design and Architecture
+ +| Documento | Tipo | +| :--- | :--- | +| [Canonical Patterns](../reference/architecture/artifacts/canonical-patterns/index.md) | Guía | +| [Architecture Portal](../reference/architecture/index.md) | Índice | +| [ADR Registry](../reference/architecture/adrs/) | Índice | +| [DDD Design Hub](../reference/gobernanza/construction/ddd-design/index.md) | Índice | +| [Traceability Matrix](../reference/architecture/matriz-trazabilidad.md) | Matriz | +| [BeyondNet ADR Matrix](https://github.com/beyondnetcode/evolith-core/blob/main/reference/architecture/adrs/adr-matrix.md) | Matriz | +| [Architecture Overview](../reference/architecture/vision-general.md) | Referencia | +| [Blueprints](../reference/architecture/blueprints/) | Referencia | + +
+
+
+Phase 03 - Construction
+ +| Documento | Tipo | +| :--- | :--- | +| [Construction Hub](../reference/gobernanza/construction/index.md) | Índice | +| [SDK Portal](../reference/sdk/index.md) | Índice | +| [Bounded Context Map](../reference/gobernanza/construction/ddd-design/01-mapa-contextos-delimitados.md) | Referencia | +| [Cross-Context Flows](../reference/gobernanza/construction/ddd-design/10-flujos-entre-contextos.md) | Referencia | +| [DDD Primitives](../reference/gobernanza/construction/ddd-design/11-primitivas-ddd.md) | Referencia | +| [API .NET Applied Reference](../reference/architecture/api-dotnet/referencia-aplicada-api-dotnet.md) | Referencia | +| [Project Backlog](../reference/gobernanza/project/index.md) | Registro | + +
+
+
+Phase 04 - Validation and QA
+ +| Documento | Tipo | +| :--- | :--- | +| [Performance Testing Plan](../reference/gobernanza/testing/plan-pruebas-rendimiento.md) | Guía | +| [QA Report](../reference/qa/reporte-qa.md) | Registro | +| [Unit Testing Results](../reference/gobernanza/testing/resultados-pruebas-unitarias.md) | Registro | +| [Integration Testing Results](../reference/gobernanza/testing/resultados-pruebas-integracion.md) | Registro | +| [Performance Testing Results](../reference/gobernanza/testing/resultados-pruebas-rendimiento.md) | Registro | +| [QA Evidences](../reference/qa/evidences/) | Registro | + +
+
+
+## Cross-Cutting References
+
+Phase 05 - Delivery and Operations
+ +| Documento | Tipo | +| :--- | :--- | +| [Runbooks](../reference/operaciones/runbooks/index.md) | Guía | +| [Kubernetes Deployment Plan](./infra/UMS_K8s_Deployment_Plan.md) | Guía | +| [Infrastructure Plan](./infra/infrastructure_plan.md) | Guía | +| [Implementation Plan](./infra/implementation_plan.md) | Guía | +| [Documentation Release Process](../reference/releases/proceso-publicacion-documentacion.md) | Guía | +| [Operations Portal](../reference/operaciones/index.md) | Índice | +| [Metrics](../reference/operaciones/metrics/index.md) | Referencia | + +
+
+
+Architecture, domain, and product reference
+ +- [Identity Domain](../docs/02-diseno/dominio/identity/index.md) +- [Authorization Domain](../docs/02-diseno/dominio/authorization/index.md) +- [Configuration Domain](../docs/02-diseno/dominio/configuration/index.md) +- [Approvals Domain](../docs/02-diseno/dominio/approvals/index.md) +- [IGA Domain](../docs/02-diseno/dominio/iga/index.md) +- [Audit Domain](../docs/02-diseno/dominio/audit/index.md) +- [Consistency Rules](../docs/02-diseno/dominio/consistency-rules/index.md) +- [SDK Contracts](../reference/sdk/contracts/resumen-esquema.md) +- [Documentation Standards](../reference/indices/estandares.md) +- [Bilingual Documentation Control](../reference/gobernanza/documentation-control-agents.md) + +
+
+
+## Tools and Automation
+
+UMS and BeyondNet inheritance
+ +- UMS inherits reusable architecture standards, governance rules, ADR patterns, and documentation practices from [BeyondNet](https://github.com/beyondnetcode/evolith-core). +- UMS keeps product-specific implementation, bounded contexts, schemas, seed strategy, and runtime behavior in this repository. +- Product ADRs may be promoted upstream when UMS provides executable evidence that the decision is reusable across products. +- Multi-tenancy is enforced primarily at the application layer. PostgreSQL policies, constraints, schema ownership, and row-level security are secondary infrastructure failsafes. + +
+
+
+Local development commands
+ +Run technical commands from `src/` unless the command explicitly targets the backend solution. + +```bash +# Install frontend dependencies +cd src +npm install + +# Frontend: React 18 and Vite +npx nx run app-web:dev + +# Backend: .NET 10 +cd apps/ums.api +dotnet build +dotnet run + +# Backend tests +dotnet test +``` + +
+
+
+---
+
+## Contribution
+
+Before contributing, read:
+
+- [AGENTS.md](./AGENTS.md) - agent rules and repository conventions.
+- [Standards](../reference/indices/estandares.md) - engineering and documentation standards.
+- [ADR Template](../reference/gobernanza/sdlc/plantilla-adr.md) - how to propose a decision.
+- [Child Repository Inheritance Guide](https://github.com/beyondnetcode/evolith-core/blob/main/reference/governance/standards/onboarding/child-repository-inheritance-guide.md) - how UMS inherits from BeyondNet.
+
+---
+
+## License
+
+This repository is proprietary unless a separate license file states otherwise.
+
+---
+
+Documentation validation
+ +```bash +# From the repository root +python3 .bmad-core/scripts/cleanup_markdown_encoding.py + +# From src/, when Context7 setup is needed +cd src +npx ctx7 setup +``` + +Documentation changes must keep English and Spanish artifacts synchronized, preserve UTF-8 integrity, and avoid decorative icons or non-standard Markdown characters. + +
+ UMS - Enterprise User Management System | BeyondNet Satellite Product | .NET 10, React 18, PostgreSQL
+
diff --git a/src/Ums.ReadModels/ReadModelDbContextFactory.cs b/src/Ums.ReadModels/ReadModelDbContextFactory.cs
deleted file mode 100644
index 5dd3c19a..00000000
--- a/src/Ums.ReadModels/ReadModelDbContextFactory.cs
+++ /dev/null
@@ -1,15 +0,0 @@
-using Microsoft.EntityFrameworkCore;
-using Microsoft.EntityFrameworkCore.Design;
-
-namespace Ums.ReadModels;
-
-public class ReadModelDbContextFactory : IDesignTimeDbContextFactory