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

v2/src/admin/index.js

@@ -1,25 +1,42 @@
 // ═══════════════════════════════════════════════════════════════════════════════
-// V2 — Админка (Dashboard, аудит, лимиты, все компании)
+// V2 — Админка
 //
-// Вход: req.isAdmin, req.email, req.clientId из resolveContext.
-// Только для админов (isAdmin=true).
-// Через crud/ для CRUD, через db/queries для admin-specific (аудит, лимиты).
+// ЭТО: Express-роутер для администратора (isAdmin=true).
+// НЕ: доступно обычным юзерам (middleware проверяет req.isAdmin).
+//
+// ЗАЧЕМ:
+//   1. Видеть ВСЕ компании и их статистику (дашборд).
+//   2. Смотреть аудит любой компании.
+//   3. Устанавливать персональные лимиты.
+//   4. Просматривать записи любой компании.
+//
+// ДАННЫЕ:
+//   crud.list(clientId)   — записи компании (через API-слой)
+//   q.getAllCompanies()   — все компании со счётчиками
+//   q.getAudit(companyId) — аудит (null = все компании)
+//   q.setLimit(id, limit) — персональный лимит
+//
+// МАРШРУТЫ:
+//   GET  /admin             — дашборд: таблица всех компаний
+//   GET  /admin/audit       — аудит (?companyId=X — фильтр)
+//   POST /admin/limit       — установить лимит (body: companyId, limit)
+//   GET  /admin/entries     — записи компании (?companyId=X)
 // ═══════════════════════════════════════════════════════════════════════════════
 
 const express = require('express');
-const q = require('../db/queries');
-const crud = require('../crud');
+const q = require('../db/queries');   // admin-specific: аудит, лимиты, все компании
+const crud = require('../crud');       // CRUD для просмотра записей
 
 function createAdminRouter() {
   const router = express.Router();
 
-  // ── middleware: только админы ───────────────────────────────────────────
+  // ── middleware: только админы ───────────────────────────────────────
   router.use((req, res, next) => {
     if (!req.isAdmin) return res.redirect('/v2/app');
     next();
   });
 
-  // ── GET / — дашборд: все компании ──────────────────────────────────────
+  // ── GET / — дашборд: все компании ──────────────────────────────────
   router.get('/', async (req, res) => {
     try {
       const companies = await q.getAllCompanies();
@@ -30,7 +47,7 @@ function createAdminRouter() {
     }
   });
 
-  // ── GET /audit?companyId=X ─────────────────────────────────────────────
+  // ── GET /audit?companyId=X — журнал действий ───────────────────────
   router.get('/audit', async (req, res) => {
     try {
       const companyId = req.query.companyId ? parseInt(req.query.companyId) : null;
@@ -42,7 +59,7 @@ function createAdminRouter() {
     }
   });
 
-  // ── POST /limit ────────────────────────────────────────────────────────
+  // ── POST /limit — установить персональный лимит ────────────────────
   router.post('/limit', async (req, res) => {
     try {
       const companyId = parseInt(req.body.companyId);
@@ -55,12 +72,13 @@ function createAdminRouter() {
     }
   });
 
-  // ── GET /entries?companyId=X — записи любой компании ───────────────────
+  // ── GET /entries?companyId=X — записи любой компании ───────────────
   router.get('/entries', async (req, res) => {
     try {
       const companyId = parseInt(req.query.companyId);
       const company = companyId ? await q.getCompanyById(companyId) : null;
       if (!company) return res.redirect('/v2/admin');
+      // crud.list принимает clientId (W-номер), не внутренний id
       const { entries, used, limit } = await crud.list(company.client_id, req.query.deleted === '1');
       const version = require('../config').version;
       res.send(renderEntries({ entries, company, used, limit, includeDeleted: req.query.deleted === '1', version }));
@@ -72,7 +90,9 @@ function createAdminRouter() {
   return router;
 }
 
-// ── HTML-рендеринг ─────────────────────────────────────────────────────────
+// ═══════════════════════════════════════════════════════════════════════════
+// HTML-рендеринг (временный, будет заменён на EJS)
+// ═══════════════════════════════════════════════════════════════════════════
 
 function renderDashboard({ companies, user, version }) {
   const rows = companies.map(c => `
@@ -183,6 +203,7 @@ function renderEntries({ entries, company, used, limit, includeDeleted, version
 </body></html>`;
 }
 
+// ── msgHtml() — скрипт для показа зелёных/красных плашек ──────────────
 function msgHtml() {
   return `<script>
     const p=new URLSearchParams(location.search);