v2: подробные комментарии во всех модулях — что, зачем, контракты

v2/src/router/index.js

@@ -1,29 +1,50 @@
 // ═══════════════════════════════════════════════════════════════════════════════
-// V2 — роутер по роли
-// Определяет контекст (admin/user/impersonation) и направляет куда нужно.
+// V2 — resolveContext middleware
+//
+// ЭТО: Express middleware — извлекает контекст из сессии.
+// НЕ: БД, бизнес-логика.
+//
+// ЗАЧЕМ:
+//   1. Единственное место где сессия превращается в req.* поля.
+//   2. user/ и admin/ не парсят сессию сами — получают готовые req.email, req.clientId.
+//   3. Поддержка имперсонации (админ действует от имени компании).
+//
+// ПОРЯДОК:
+//   1. Нет сессии → 302 /v2/login
+//   2. Обычный юзер → req.email = session.user.email, req.clientId = activeClientId
+//   3. Админ → req.isAdmin = true (если adminMode в сессии)
+//   4. Имперсонация → req.email = originalUserEmail, req.impersonatedBy = админ
+//
+// ВЫХОД (поля на req):
+//   req.email            — почта (при имперсонации — originalUserEmail)
+//   req.clientId         — W-номер текущей компании
+//   req.companyName      — название компании
+//   req.isAdmin          — флаг админа
+//   req.isImpersonated   — флаг имперсонации
+//   req.impersonatedBy   — почта админа (null если нет имперсонации)
+//   req.allClientIds     — все W-номера юзера
+//   req.profiles         — профили из IAM
 // ═══════════════════════════════════════════════════════════════════════════════
 
-/**
- * middleware — извлекает контекст из сессии и кладёт в req.*
- * Вызывается перед всеми маршрутами v2.
- */
 function resolveContext(req, res, next) {
   const u = req.session && req.session.user;
+
+  // Нет сессии — нет доступа
   if (!u) return res.redirect('/v2/login');
 
-  const isAdmin   = !!(u.isAdmin && req.session.adminMode);
-  const isImpersonated = !!u.isImpersonated;
+  // Имперсонация: админ действует от имени компании
+  // u.originalUserEmail — реальный админ
+  // u.impersonatedCompanyId — W-номер компании
+  const isImpersonated = !!(u.originalUserEmail && u.impersonatedCompanyId);
 
-  // Контекст для CRUD
-  req.email     = isImpersonated ? (u.originalUserEmail || u.email) : u.email;
-  req.clientId  = isImpersonated ? (u.impersonatedCompanyId || u.activeClientId || u.clientId) : (u.activeClientId || u.clientId);
-  req.isAdmin   = isAdmin;
-  req.isImpersonated = isImpersonated;
-  req.impersonatedBy = isImpersonated ? u.email : null;  // кто реально (для аудита)
-  req.user      = u;
-  req.allClientIds = u.allClientIds || [];
-  req.profiles  = u.profiles || [];
-  req.companyName = u.companyName || u.clientId;
+  req.email            = isImpersonated ? u.originalUserEmail : (u.email || '');
+  req.clientId         = isImpersonated ? u.impersonatedCompanyId : (u.activeClientId || u.clientId || '');
+  req.companyName      = u.companyName || req.clientId;
+  req.isAdmin          = !!(u.isAdmin && u.adminMode);
+  req.isImpersonated   = isImpersonated;
+  req.impersonatedBy   = isImpersonated ? u.email : null;
+  req.allClientIds     = u.allClientIds || [req.clientId];
+  req.profiles         = u.profiles || [];
 
   next();
 }