@ozdao/martyrs 0.2.518 → 0.2.520

package/src/modules/inventory/docs/02-architecture.md

@@ -0,0 +1,266 @@
+# 2. Архитектура системы
+
+## Общие архитектурные принципы
+
+Модуль Inventory построен на основе **многослойной архитектуры** с четким разделением ответственности между слоями. Система использует **materialized views** для оптимизированного хранения расчетных данных доступности товаров.
+
+Ключевой особенностью архитектуры является **синхронная модель данных**, где изменения в остатках товаров автоматически запускают пересчет доступности с учетом ингредиентов в рамках той же транзакции.
+
+## Архитектурные слои
+
+```
+┌─────────────────────────────────────┐
+│           UI Layer (Vue.js)         │
+│  components/pages/, components/forms/  │
+└─────────────────┬───────────────────┘
+                  │ API Calls
+┌─────────────────▼───────────────────┐
+│    Store Layer (Vue 3 Reactive)     │
+│     store/inventory.store.js        │
+└─────────────────┬───────────────────┘
+                  │ HTTP Requests
+┌─────────────────▼───────────────────┐
+│         API Layer (Express)         │
+│      routes/inventory.routes.js     │
+└─────────────────┬───────────────────┘
+                  │ Business Logic
+┌─────────────────▼───────────────────┐
+│       Service Layer                 │
+│  adjustment.service.js              │
+│  availability.service.js            │
+│  audit.service.js                   │
+│  inventory.helpers.js               │
+└─────────────────┬───────────────────┘
+                  │ Data Operations
+┌─────────────────▼───────────────────┐
+│       Data Layer (MongoDB)          │
+│         models/*.model.js           │
+└─────────────────────────────────────┘
+```
+
+## Инициализация серверной части
+
+Серверная инициализация происходит в файле `inventory.server.js` через функцию `initializeInventory`:
+
+```javascript
+function initializeInventory(app, db, origins, publicPath) {
+  // 1. Регистрация моделей в глобальном объекте db
+  db.stockAdjustment = StockAdjustmentModel(db);
+  db.stockAvailability = StockAvailabilityModel(db);
+  db.stockAudit = StockAuditModel(db);
+  db.stockAlert = StockAlertModel(db);
+  
+  // 2. Подключение маршрутов и политик безопасности
+  if (app) {
+    inventoryRoutes(app, db, origins, publicPath);
+    inventoryPolicies(db);
+    
+    // 3. Инициализация Change Streams для автоматического пересчёта
+    const { cache, logger } = createSharedServices(db);
+    initChangeStreams(db, logger, recalculateAvailability, (tags) => invalidateCache(cache, logger, tags));
+  }
+}
+```
+
+**Почему такая последовательность**: Сначала регистрируются модели, чтобы они стали доступны через глобальный объект `db` во всех слоях приложения. Только после этого подключаются маршруты, которые зависят от наличия моделей. Политики безопасности инициализируются вместе с маршрутами. В конце запускаются Change Streams для автоматического пересчёта доступности при изменении ингредиентов товаров.
+
+## Инициализация клиентской части
+
+Клиентская инициализация в `inventory.client.js` настраивает Vue-роутинг для двух различных контекстов:
+
+```javascript
+function initializeInventory(app, store, router, options = {}) {
+  // Backoffice routes - полный доступ для администраторов
+  if (!options.withBackoffice) {
+    addRoutes(router, {
+      parentName: options.routeBackoffice || 'Backoffice Root',
+      basePath: 'inventory',
+      routes: routerInventory,
+      routeNamePrefix: 'Backoffice',
+      filterConfig: {
+        include: ['InventoryList', 'InventoryAudit']
+      },
+      meta: { context: 'backoffice' }
+    });
+  }
+
+  // Organization routes - ограниченный доступ для организаций
+  if (!options.withOrganizationRoutes) {
+    addRoutes(router, {
+      parentName: options.routeOrganizations || 'OrganizationRoot',
+      basePath: 'inventory', 
+      routes: routerInventory,
+      routeNamePrefix: 'Organization',
+      filterConfig: {
+        include: ['InventoryList', 'InventoryAudit']
+      },
+      meta: { context: 'organization' }
+    });
+  }
+}
+```
+
+**Зачем два контекста**: 
+- **Backoffice context**: административный интерфейс с полным доступом ко всем функциям
+- **Organization context**: клиентский интерфейс с ограничениями по ownership и функциональности
+
+Фильтрация маршрутов через `filterConfig.include` позволяет включать только необходимые страницы для каждого контекста.
+
+## Синхронная система пересчета доступности
+
+Пересчет доступности товаров происходит **синхронно** в рамках транзакций изменения остатков и **асинхронно** через Change Streams при изменении ингредиентов. Функция `recalculateAvailability` в `inventory.helpers.js` обновляет данные доступности в `StockAvailability`:
+
+```javascript
+// В adjustment.service.js - create
+async create(req, res) {
+  const session = await db.mongoose.startSession();
+  session.startTransaction();
+  
+  try {
+    // 1. Создание adjustment
+    const [adjustment] = await db.stockAdjustment.create([adjustmentData], { session });
+    
+    // 2. Обновление количества в StockAvailability
+    const availability = await updateStockQuantity(
+      db,
+      adjustmentData.product,
+      adjustmentData.variant,
+      adjustmentData.storage,
+      adjustmentData.quantity,
+      adjustmentData.owner,
+      adjustmentData.creator,
+      session
+    );
+    
+    // 3. Пересчет доступности в той же транзакции
+    if (affectedVariants.length) {
+      await recalculateAvailability(db, logger, affectedVariants, adjustmentData.storage, session);
+    }
+    
+    await session.commitTransaction();
+  } catch (error) {
+    await session.abortTransaction();
+    throw error;
+  }
+}
+```
+
+**Преимущества синхронного подхода**:
+- **Консистентность данных**: доступность всегда соответствует текущим остаткам
+- **Атомарность**: все изменения происходят в одной транзакции
+- **Простота отладки**: нет асинхронных race conditions
+
+### Автоматический пересчёт через Change Streams
+
+Система использует MongoDB Change Streams для автоматического пересчёта доступности при изменении ингредиентов товаров. Реализация находится в `inventory.helpers.js`:
+
+```javascript
+// inventory.helpers.js - активно используется
+export function initChangeStreams(db, logger, recalculateAvailability, invalidateCache) {
+  const pipeline = [
+    { $match: { 
+      operationType: { $in: ['insert', 'update', 'replace', 'delete'] },
+      'fullDocument.ingredients': { $exists: true }
+    }}
+  ];
+  
+  const changeStream = db.variant.collection.watch(pipeline, { 
+    fullDocument: 'updateLookup' 
+  });
+  
+  changeStream.on('change', async (change) => {
+    // Асинхронный пересчет при изменении ингредиентов
+    const variantId = change.documentKey._id;
+    const storages = await db.stockAvailability.distinct('storage', {
+      variant: variantId
+    });
+    
+    for (const storage of storages) {
+      await recalculateAvailability(db, logger, [variantId], storage);
+    }
+    
+    invalidateCache(['availability', `variant:${variantId}`]);
+  });
+}
+```
+
+**Преимущества интегрированной системы**:
+- Автоматический пересчет при изменении рецептов без задержки основных операций
+- Консистентность данных между ингредиентами и доступностью
+- Асинхронная обработка не блокирует основные операции
+
+## Паттерн Observer для межмодульного взаимодействия
+
+Система использует Observer pattern для уведомления других модулей о важных событиях:
+
+```javascript
+// В adjustment.service.js
+observer.notify('stock.adjusted', {
+  adjustment,
+  availability,
+  affectedVariants
+});
+
+// В audit.service.js
+observer.notify('inventory.completed', {
+  inventory,
+  affectedVariants
+});
+```
+
+**Зачем Observer**: Прямые вызовы между модулями создают tight coupling. Observer позволяет:
+- **Расширяемость**: новые модули могут подписываться на события без изменения inventory
+- **Асинхронность**: события обрабатываются через `setImmediate()`, не блокируя основной поток
+- **Отказоустойчивость**: падение одного обработчика не влияет на других
+
+## Кеширование и производительность
+
+Архитектура включает многоуровневое кеширование для обеспечения производительности:
+
+```javascript
+// Кеширование в service layer (availability.service.js)
+const { cache, logger } = createSharedServices(db);
+const cacheKey = JSON.stringify({ type: 'availability', ...req.verifiedQuery });
+
+let data = await cache.get(cacheKey);
+if (!data) {
+  data = await db.stockAvailability.aggregate(pipeline).exec();
+  await cache.setWithTags(cacheKey, data, ['availability']);
+}
+```
+
+**Стратегия инвалидации**: Используется tag-based invalidation через функцию `invalidateCache` из `inventory.helpers.js`:
+- Изменение количества → инвалидация тегов `['availability']`
+- Создание adjustment → инвалидация тегов `['adjustments', 'availability']`
+- Завершение инвентаризации → инвалидация тегов `['adjustments', 'availability', 'inventories']`
+
+## Транзакционная целостность
+
+Критические операции (adjustments, audit completion) выполняются в MongoDB транзакциях:
+
+```javascript
+const session = await db.mongoose.startSession();
+session.startTransaction();
+
+try {
+  // 1. Создание adjustment
+  const [adjustment] = await db.stockAdjustment.create([adjustmentData], { session });
+  
+  // 2. Обновление количества в StockAvailability
+  const availability = await updateStockQuantity(
+    db, product, variant, storage, quantity, owner, creator, session
+  );
+  
+  // 3. Пересчет доступности с учётом ингредиентов
+  await recalculateAvailability(db, logger, affectedVariants, storage, session);
+  
+  await session.commitTransaction();
+} catch (error) {
+  await session.abortTransaction();
+  throw error;
+} finally {
+  session.endSession();
+}
+```
+
+**Атомарность операций**: Без транзакций возможны race conditions, когда количество обновилось, но доступность еще не пересчиталась. Транзакции гарантируют, что система никогда не находится в inconsistent состоянии. Все операции изменения остатков выполняются атомарно вместе с пересчётом доступности.

package/src/modules/inventory/docs/03-components-and-relationships.md

@@ -0,0 +1,338 @@
+# 3. Компоненты и их взаимодействие
+
+## Route Layer - HTTP API endpoints
+
+### Основные маршруты инвентаризации
+
+Файл `inventory.routes.js` определяет основные HTTP endpoints с полной middleware цепочкой:
+
+```javascript
+export default function(app, db) {
+  const jwt = jwtFactory(db);
+  const verifier = verifierFactory(db);
+  const abac = getInstance(db);
+  const adjustmentService = adjustmentServiceFactory(db);
+  const availabilityService = availabilityServiceFactory(db);
+  const auditService = auditServiceFactory(db);
+  
+  // Типичная цепочка middleware: Auth → Validation → Authorization → Business Logic
+  app.post('/api/inventory/adjustments/create', 
+    jwt.verifyToken(),                        // JWT аутентификация
+    verifier.verifyAdjustmentBody,            // Валидация входных данных
+    abac.middleware('stockAdjustment', 'create'), // ABAC авторизация
+    adjustmentService.create                  // Бизнес-логика
+  );
+}
+```
+
+**Архитектурная особенность**: Каждый маршрут проходит через стандартизированную цепочку middleware, что обеспечивает:
+- **Единообразие**: одинаковая схема безопасности для всех endpoints
+- **Расширяемость**: легко добавить новые middleware без изменения бизнес-логики
+- **Тестируемость**: каждый слой можно тестировать изолированно
+
+### Группировка endpoints по сущностям
+
+```javascript
+// StockAdjustment routes
+app.get('/api/inventory/adjustments', ...)        // Чтение списка движений
+app.post('/api/inventory/adjustments/create', ...)  // Создание движения
+
+// StockAvailability routes  
+app.get('/api/inventory/availability', ...)        // Текущие остатки и доступность
+
+// StockAudit routes
+app.get('/api/inventory/audits', ...)              // Список инвентаризаций
+app.post('/api/inventory/audits/create', ...)      // Создание инвентаризации
+app.post('/api/inventory/audits/complete', ...)    // Завершение инвентаризации
+```
+
+**Зачем такая группировка**: Каждая группа endpoints соответствует отдельной бизнес-сущности, что упрощает:
+- **API discovery**: разработчикам понятно, где искать нужную функциональность
+- **Версионирование**: можно изменять API для одной сущности независимо от других
+- **Мониторинг**: метрики можно собирать по типам операций
+
+### CRUD паттерн для Stock Alerts
+
+Файл `stock.alerts.routes.js` демонстрирует использование универсального CRUD класса:
+
+```javascript
+const stockAlertsCRUD = new CRUD({
+  app, db,
+  model: db.stockAlert,
+  modelName: 'stockAlert',
+  basePath: '/api/inventory/alerts',
+  
+  auth: true,                    // Требует аутентификации
+  
+  verifiers: {                   // Кастомные валидаторы для каждой операции
+    create: verifier.createVerifier,
+    read: verifier.readVerifier,
+    update: verifier.updateVerifier,
+    delete: verifier.deleteVerifier
+  },
+  
+  abac: abac,                    // ABAC авторизация
+  
+  cache: {                       // Конфигурация кеширования
+    enabled: true,
+    ttl: 300,
+    tags: ['stockAlerts', 'inventory']
+  },
+  
+  events: {                      // Система событий
+    enabled: true,
+    logReads: false              // Не логировать чтение (слишком много событий)
+  }
+});
+```
+
+**Преимущества CRUD паттерна**:
+- **Стандартизация**: все CRUD операции работают одинаково
+- **Конфигурируемость**: можно настроить кеширование, события, валидацию отдельно для каждой сущности
+- **DRY принцип**: не нужно дублировать код для базовых операций
+
+## Store Layer - Клиентское состояние
+
+### Reactive State Management
+
+Файл ` inventory.store.js` использует Vue 3 Composition API для управления состоянием:
+
+```javascript
+const state = reactive({
+  // Основные коллекции данных
+  adjustments: [],      // История движений товаров
+  availability: [],     // Текущие остатки и доступность для продажи
+  inventories: [],      // Список инвентаризаций
+  
+  // Состояние текущей операции (например, создание инвентаризации)
+  current: {
+    storage: null,      // Выбранный склад
+    positions: [],      // Позиции в инвентаризации
+    comment: '',        // Комментарий
+    status: 'draft'     // Статус draft/published
+  },
+  
+  // Фильтры для поиска и сортировки
+  filters: {
+    storage: null,      // Фильтр по складу
+    product: null,      // Фильтр по товару
+    dateStart: null,    // Период от
+    dateEnd: null       // Период до
+  }
+});
+```
+
+**Почему reactive**: Vue 3 reactive обеспечивает автоматическое обновление UI при изменении данных без необходимости вызывать специальные методы обновления.
+
+### Actions - API Integration
+
+```javascript
+const actions = {
+  async createAdjustment(data) {
+    try {
+      const response = await $axios.post('/api/inventory/adjustments/create', data);
+      state.adjustments.unshift(response.data);  // Добавляем в начало списка
+      return response.data;
+    } catch (error) {
+      setError(error);                           // Глобальная обработка ошибок
+      throw error;                               // Пробрасываем для компонента
+    }
+  }
+};
+```
+
+**Паттерн обработки**: Каждый action выполняет три операции:
+1. **API запрос**: отправка данных на сервер
+2. **State update**: обновление локального состояния
+3. **Error handling**: обработка ошибок через глобальную систему
+
+### Mutations - State Modifications
+
+```javascript
+const mutations = {
+  addPosition(position) {
+    state.current.positions.push(position);     // Добавление позиции в инвентаризацию
+  },
+  
+  removePosition(index) {
+    state.current.positions.splice(index, 1);  // Удаление позиции
+  },
+  
+  resetCurrent() {                              // Сброс текущей операции
+    state.current = {
+      storage: null,
+      positions: [],
+      comment: '',
+      status: 'draft'
+    };
+  }
+};
+```
+
+**Separation of Concerns**: Mutations отвечают только за изменение состояния, а actions - за взаимодействие с API. Это упрощает тестирование и отладку.
+
+## Component Layer - UI интеграция
+
+### Context-Aware Navigation
+
+Компонент `Inventory.vue` адаптируется к контексту выполнения:
+
+```vue
+<template>
+  <header class="mn-b-medium flex-v-center flex-nowrap flex">
+    <h2>Inventory</h2>
+    
+    <!-- Кнопка создания инвентаризации - зависит от контекста -->
+    <button
+      v-if="route.meta.context === 'backoffice'"
+      @click="router.push({ name: 'BackofficeInventoryAudit' })"
+      class="mn-l-small radius-100 i-big hover-scale-1 cursor-pointer t-white bg-second"
+    />
+    
+    <button
+      v-if="route.meta.context === 'organization'"
+      @click="router.push({ name: 'OrganizationInventoryAudit', params: { _id: route.params._id } })"
+      class="mn-l-small radius-100 i-big hover-scale-1 cursor-pointer t-white bg-second"
+    />
+  </header>
+</template>
+```
+
+**Адаптивность**: Один компонент работает в двух режимах:
+- **Backoffice**: полные админские права без привязки к конкретной организации
+- **Organization**: работа в рамках конкретной организации (параметр `_id`)
+
+### Feed Integration Pattern
+
+```vue
+<Feed
+  :search="true"
+  v-model:sort="sort"
+  :store="{
+    read: (options) => products.actions.read(options),  // Делегирование чтения в products store
+    state: products.state
+  }"
+  :options="{
+    limit: 15,
+    lookup: ['inventory','categories'],                  // Подключение инвентарных данных
+    owner: route.params._id,                            // Фильтрация по владельцу
+    sortParam: sort.param,
+    sortOrder: sort.order
+  }"
+  v-slot="{ items }"
+>
+```
+
+**Паттерн интеграции**: Компонент Inventory не работает напрямую с товарами, а делегирует это Products store. При этом он добавляет lookup для инвентарных данных, получая комбинированную информацию.
+
+### Table Customization
+
+```vue
+<Table
+  :columns="columns.filter(col => col.visible)"          // Динамические колонки
+  :items="items"
+  class="bg-white z-index-1 br-solid br-1px br-light radius-medium"
+>
+  <!-- Кастомная ячейка для отображения доступности -->
+  <template #cell-available="{ row }">
+    <div class="flex-column flex">
+      <span class="d-block mn-b-thin">
+        {{ row.totalAvailable || 0 }}
+      </span>
+      
+      <!-- Прогресс-бар уровня запасов -->
+      <div class="w-full h-0-5r bg-light radius-small overflow-hidden">
+        <div 
+          class="h-full radius-small"
+          :class="getStockLevelClass(row.totalAvailable)"
+          :style="{ width: getStockLevelPercent(row.totalAvailable) + '%' }"
+        />
+      </div>
+    </div>
+  </template>
+  
+  <!-- Кастомная ячейка для складов -->
+  <template #cell-storages="{ row }">
+    <div class="w-max-10r flex-nowrap flex t-trim">
+      <p
+        v-if="row.availabilityDetails?.length"
+        v-for="avail in row.availabilityDetails" 
+        :key="avail._id"
+        class="w-max t-trim pd-small mn-r-micro radius-small bg-light t-small"
+      >
+        <span class="t-medium">{{ avail.available || 0 }}</span> ·  
+        <span class="t-small">{{ avail.storageName || avail.storage }}:</span>
+      </p>
+      <p v-else>No stock</p>
+    </div>
+  </template>
+</Table>
+```
+
+**Rich Data Presentation**: Компонент не только отображает сырые данные, но и:
+- **Визуализирует уровни запасов** через цветовые индикаторы и прогресс-бары
+- **Группирует данные по складам** для удобного восприятия
+- **Позволяет настраивать видимость колонок** через `columns.filter(col => col.visible)`
+
+## Межкомпонентное взаимодействие
+
+### Цепочка передачи данных
+
+```
+User Action (click) → Component Event Handler → Store Action → API Request → Server Controller → Database → Response → Store State Update → Component Re-render
+```
+
+**Конкретный пример - создание stock adjustment**:
+
+1. **User Action**: Пользователь заполняет `AdjustmentForm.vue` и нажимает "Save"
+2. **Component**: `AdjustmentForm.vue` эмитит событие `@save` с данными adjustment
+3. **Parent Component**: `Inventory.vue` получает событие и вызывает `inventory.actions.createAdjustment(data)`
+4. **Store Action**: Отправляет POST `/api/inventory/adjustments/create`
+5. **Server Route**: `jwt.verifyToken() → verifier.verifyAdjustmentBody → abac.middleware → adjustmentService.create`
+6. **Business Logic**: Создает adjustment, обновляет количество в StockAvailability, пересчитывает доступность
+7. **Response**: Возвращает созданный объekt adjustment
+8. **Store Update**: `state.adjustments.unshift(response.data)`
+9. **UI Update**: Таблица автоматически обновляется через reactive связь
+
+### Event Bus Pattern
+
+```javascript
+// В adjustment.service.js
+observer.notify('stock.adjusted', {
+  adjustment,
+  availability,
+  affectedVariants
+});
+
+// В другом модуле
+observer.on('stock.adjusted', (data) => {
+  // Реакция на изменение остатков
+  updateRelatedData(data.affectedVariants);
+});
+```
+
+**Слабая связанность**: Компоненты не знают друг о друге напрямую, что позволяет:
+- **Легко добавлять новые обработчики** без изменения основного кода
+- **Изолировать ошибки**: падение одного обработчика не влияет на другие
+- **Упрощать тестирование**: можно мокать события
+
+## Dependency Injection Pattern
+
+### Factory Pattern для Services
+
+```javascript
+// В routes/inventory.routes.js
+const jwt = jwtFactory(db);          // Создание JWT service с доступом к db
+const verifier = verifierFactory(db); // Создание validator service
+const abac = getInstance(db);        // Singleton ABAC instance
+const adjustmentService = adjustmentServiceFactory(db); // Создание adjustment service
+const availabilityService = availabilityServiceFactory(db); // Создание availability service
+const auditService = auditServiceFactory(db); // Создание audit service
+```
+
+**Преимущества**:
+- **Тестируемость**: легко подставить моки вместо реальных services
+- **Конфигурируемость**: можно передавать разные конфигурации через параметры
+- **Отложенная инициализация**: services создаются только когда нужны
+
+Эта архитектура обеспечивает высокую модульность и maintainability кода, позволяя легко тестировать, расширять и модифицировать отдельные компоненты без влияния на систему в целом.