@ozdao/martyrs 0.2.518 → 0.2.520

package/src/modules/inventory/docs/05-api-specification.md

@@ -0,0 +1,356 @@
+# 5. API спецификация
+
+## Обзор API endpoints
+
+Модуль Inventory предоставляет RESTful API для управления складскими запасами. Все endpoints требуют аутентификации через JWT токен и поддерживают ABAC авторизацию.
+
+**Base URL**: `/api/inventory`
+
+## Stock Adjustments API
+
+### GET /api/inventory/adjustments
+Получение списка движений товаров с фильтрацией и пагинацией.
+
+**Аутентификация**: Требуется JWT (`jwt.verifyToken(true)`)  
+**Авторизация**: Не требуется (только фильтрация по owner)
+
+**Query параметры**:
+```javascript
+{
+  product?: string,     // ObjectId товара
+  variant?: string,     // ObjectId варианта
+  storage?: string,     // ObjectId склада
+  reason?: string,      // Причина движения
+  dateStart?: date,     // Начало периода
+  dateEnd?: date,       // Конец периода
+  skip?: integer,       // Offset для пагинации (default: 0)
+  limit?: integer       // Лимит записей (default: 20, max: 100)
+}
+```
+
+**Пример запроса**:
+```bash
+GET /api/inventory/adjustments?storage=507f1f77bcf86cd799439011&reason=restock&limit=10
+Authorization: Bearer <jwt_token>
+```
+
+**Пример ответа**:
+```json
+[
+  {
+    "_id": "507f1f77bcf86cd799439012",
+    "product": "507f1f77bcf86cd799439013",
+    "variant": "507f1f77bcf86cd799439014",
+    "storage": "507f1f77bcf86cd799439011",
+    "source": {
+      "type": "User",
+      "target": "507f1f77bcf86cd799439015"
+    },
+    "reason": "restock",
+    "quantity": 50,
+    "cost": 1000,
+    "comment": "Поступление от поставщика",
+    "productData": {
+      "name": "Пицца Маргарита",
+      "sku": "PIZZA-001"
+    },
+    "createdAt": "2023-12-01T10:30:00Z",
+    "owner": { "type": "organization", "target": "..." },
+    "creator": { "type": "user", "target": "..." }
+  }
+]
+```
+
+### POST /api/inventory/adjustments/create
+Создание движения товара (поступление/расход).
+
+**Аутентификация**: Требуется JWT (`jwt.verifyToken()`)  
+**Авторизация**: ABAC `stockAdjustment:create`
+
+**Request Body**:
+```javascript
+{
+  product: string,           // ObjectId товара (required)
+  variant?: string,          // ObjectId варианта
+  storage: string,           // ObjectId склада (required)
+  source: {                  // Источник движения (required)
+    type: 'User' | 'Order' | 'Inventory',
+    target: string           // ObjectId источника
+  },
+  reason: 'restock' | 'sale' | 'return' | 'damage' | 'transfer' | 'custom',
+  quantity: integer,         // Изменение количества (+/-) (required)
+  cost?: number,            // Стоимость (>=0)
+  comment?: string          // Комментарий
+}
+```
+
+**Пример запроса**:
+```bash
+POST /api/inventory/adjustments/create
+Authorization: Bearer <jwt_token>
+Content-Type: application/json
+
+{
+  "product": "507f1f77bcf86cd799439013",
+  "variant": "507f1f77bcf86cd799439014",
+  "storage": "507f1f77bcf86cd799439011",
+  "source": {
+    "type": "User",
+    "target": "507f1f77bcf86cd799439015"
+  },
+  "reason": "restock",
+  "quantity": 100,
+  "cost": 2500,
+  "comment": "Поступление товара на склад"
+}
+```
+
+**Пример ответа**:
+```json
+{
+  "_id": "507f1f77bcf86cd799439016",
+  "product": "507f1f77bcf86cd799439013",
+  "variant": "507f1f77bcf86cd799439014",
+  "storage": "507f1f77bcf86cd799439011",
+  "source": {
+    "type": "User",
+    "target": "507f1f77bcf86cd799439015"
+  },
+  "reason": "restock",
+  "quantity": 100,
+  "cost": 2500,
+  "comment": "Поступление товара на склад",
+  "createdAt": "2023-12-01T10:30:00Z",
+  "owner": { "type": "organization", "target": "..." },
+  "creator": { "type": "user", "target": "..." }
+}
+```
+
+**Побочные эффекты**:
+- Обновляется количество в `StockAvailability` для товара
+- Пересчитывается доступность в `StockAvailability` для всех зависимых вариантов
+- Проверяются и отправляются `StockAlert` уведомления
+- Генерируется событие `stock.adjusted`
+- Инвалидируется кеш с тегами `['adjustments', 'availability']`
+
+
+## Stock Availability API
+
+### GET /api/inventory/availability
+Получение текущих остатков и доступности товаров для продажи с учетом ингредиентов.
+
+**Аутентификация**: Не требуется (публичный endpoint)  
+**Авторизация**: Не требуется
+
+**Query параметры**:
+```javascript
+{
+  product?: string,     // Фильтр по товару
+  storage?: string,     // Фильтр по складу
+  skip?: integer,       // Offset (default: 0)
+  limit?: integer,      // Лимит (default: 50, max: 100)
+  details?: string,     // Дополнительная детализация
+  search?: string,      // Поиск по названию
+  sortParam?: string,   // Поле сортировки
+  sortOrder?: 'asc' | 'desc'  // Направление сортировки
+}
+```
+
+**Особенности ответа**:
+- Включает поле `quantity` (физический остаток)
+- Включает расчетные поля `available` и `constraints`
+- Показывает ограничения по ингредиентам
+- Оптимизирован для e-commerce интеграции
+
+**Пример ответа**:
+```json
+[
+  {
+    "_id": "507f1f77bcf86cd799439018",
+    "product": "507f1f77bcf86cd799439013",
+    "variant": "507f1f77bcf86cd799439014",
+    "storage": "507f1f77bcf86cd799439011",
+    "quantity": 10,         // Физический остаток
+    "available": 8,         // Доступно для продажи
+    "reservations": 2,      // Зарезервировано
+    "constraints": [        // Ограничения по ингредиентам
+      {
+        "ingredient": "507f1f77bcf86cd799439019",
+        "stock": 50,        // Остаток ингредиента
+        "required": 2,      // Требуется на единицу
+        "available": 25     // Можно произвести единиц
+      }
+    ],
+    "calculatedAt": "2023-12-01T10:35:00Z"
+  }
+]
+```
+
+## Stock Audit API
+
+### GET /api/inventory/audits
+Получение списка инвентаризаций.
+
+**Аутентификация**: Требуется JWT  
+**Авторизация**: Не требуется (фильтрация по owner)
+
+**Query параметры**: Стандартные для листинга
+
+**Пример ответа**:
+```json
+[
+  {
+    "_id": "507f1f77bcf86cd79943901A",
+    "storage": "507f1f77bcf86cd799439011",
+    "status": "published",
+    "positions": [
+      {
+        "product": "507f1f77bcf86cd799439013",
+        "variant": "507f1f77bcf86cd799439014",
+        "quantity": 5,
+        "reason": "custom",
+        "comment": "Недостача при инвентаризации"
+      }
+    ],
+    "comment": "Плановая инвентаризация декабрь 2023",
+    "createdAt": "2023-12-01T09:00:00Z",
+    "owner": { "type": "organization", "target": "..." },
+    "creator": { "type": "user", "target": "..." }
+  }
+]
+```
+
+### POST /api/inventory/audits/create
+Создание новой инвентаризации.
+
+**Аутентификация**: Требуется JWT  
+**Авторизация**: ABAC `stockAudit:create`
+
+**Request Body**:
+```javascript
+{
+  storage: string,           // ObjectId склада (required)
+  comment?: string,          // Комментарий к инвентаризации
+  status?: 'draft' | 'published',  // Статус (default: 'draft')
+  positions: [               // Массив позиций (required)
+    {
+      product: string,       // ObjectId товара (required)
+      variant?: string,      // ObjectId варианта
+      quantity: integer      // Количество для корректировки (required)
+    }
+  ]
+}
+```
+
+**Поведение в зависимости от статуса**:
+- **draft**: Сохраняет данные без влияния на остатки
+- **published**: Сразу создает adjustments и обновляет балансы
+
+### POST /api/inventory/audits/complete
+Публикация (завершение) инвентаризации.
+
+**Аутентификация**: Требуется JWT  
+**Авторизация**: ABAC `stockAudit:edit`
+
+**Request Body**:
+```javascript
+{
+  _id: string               // ObjectId инвентаризации
+}
+```
+
+**Выполняемые операции**:
+1. Создание `StockAdjustment` для каждой позиции
+2. Batch обновление количества в `StockAvailability`
+3. Пересчет доступности в `StockAvailability` для затронутых товаров
+4. Изменение статуса audit на `published`
+5. Генерация события `inventory.completed`
+
+## Stock Alerts API
+
+### Полный CRUD через универсальный контроллер
+**Base Path**: `/api/inventory/alerts`
+
+**Доступные endpoints**:
+- `GET /api/inventory/alerts` - Список алертов
+- `POST /api/inventory/alerts` - Создание алерта
+- `GET /api/inventory/alerts/:id` - Получение алерта
+- `PUT /api/inventory/alerts/:id` - Обновление алерта
+- `DELETE /api/inventory/alerts/:id` - Удаление алерта
+
+**Схема алерта**:
+```javascript
+{
+  product: string,          // ObjectId товара (required)
+  variant?: string,         // ObjectId варианта (null = все варианты)
+  storage?: string,         // ObjectId склада (null = все склады)
+  threshold: number,        // Пороговое значение (required, >=0)
+  enabled: boolean          // Активность алерта (default: true)
+}
+```
+
+**Пример создания алерта**:
+```bash
+POST /api/inventory/alerts
+Authorization: Bearer <jwt_token>
+Content-Type: application/json
+
+{
+  "product": "507f1f77bcf86cd799439013",
+  "variant": null,
+  "storage": "507f1f77bcf86cd799439011", 
+  "threshold": 10,
+  "enabled": true
+}
+```
+
+## Коды ошибок и обработка
+
+### Стандартные HTTP коды
+- `200` - Успешная операция
+- `201` - Создание ресурса
+- `400` - Ошибка валидации
+- `401` - Не авторизован
+- `403` - Доступ запрещен
+- `404` - Ресурс не найден
+- `500` - Внутренняя ошибка сервера
+
+### Формат ошибок валидации
+```json
+{
+  "errors": [
+    {
+      "field": "quantity",
+      "message": "Quantity must be an integer",
+      "value": "invalid_value"
+    }
+  ]
+}
+```
+
+### Формат серверных ошибок  
+```json
+{
+  "message": "Internal server error occurred",
+  "code": "INVENTORY_ERROR",
+  "details": "Additional error context"
+}
+```
+
+## Производительность и кеширование
+
+### Кешируемые endpoints
+- `GET /api/inventory/adjustments` - TTL 300 секунд, теги `['adjustments']`
+- `GET /api/inventory/availability` - TTL 300 секунд, теги `['availability']`
+- `GET /api/inventory/alerts` - TTL 300 секунд, теги `['stockAlerts', 'inventory']`
+
+### Инвалидация кеша
+- **Stock Adjustment операции** → инвалидация `['adjustments', 'availability']`
+- **Inventory Audit операции** → инвалидация `['inventories', 'availability']`
+- **Alert операции** → инвалидация `['stockAlerts', 'inventory']`
+
+### Рекомендации по использованию
+- Используйте пагинацию для больших наборов данных
+- Применяйте фильтры для снижения объема трафика
+- Кешируйте результаты на клиенте с учетом TTL
+- Подписывайтесь на события через WebSocket для real-time обновлений

package/src/modules/inventory/docs/06-access-control.md

@@ -0,0 +1,320 @@
+# 6. Права доступа
+
+## Архитектура системы авторизации
+
+Модуль Inventory использует многоуровневую систему контроля доступа, основанную на трех основных принципах:
+
+1. **JWT Authentication** - Базовая аутентификация пользователей
+2. **ABAC Authorization** - Attribute-Based Access Control для fine-grained permissions
+3. **Owner-based filtering** - Мультитенантная изоляция данных
+
+## JWT Authentication Layer
+
+### Типы аутентификации по endpoints
+
+```javascript
+// Строгая аутентификация - только авторизованные пользователи
+app.post('/api/inventory/adjustments/create', 
+  jwt.verifyToken(),                    // Требует валидный JWT
+  // ... other middleware
+);
+
+// Мягкая аутентификация - поддержка анонимных запросов с фильтрацией
+app.get('/api/inventory/adjustments', 
+  jwt.verifyToken(true),               // true = не блокирует анонимов
+  // ... other middleware
+);
+
+// Публичный доступ - без аутентификации
+app.get('/api/inventory/availability', 
+  // Нет jwt.verifyToken() - публичный endpoint
+  verifier.verifyAvailabilityQuery,
+  controller.availability.read
+);
+```
+
+### Извлечение пользователя из JWT
+
+После успешной аутентификации JWT middleware устанавливает:
+- `req.userId` - ObjectId текущего пользователя
+- `req.userDoc` - (опционально) полный объект пользователя с ролями
+
+## ABAC Authorization System
+
+### Текущее состояние политик
+
+**Важно**: В текущей версии все ABAC политики в файле `inventory.policies.js` **закомментированы**, что означает **permissive mode** - все операции разрешены после JWT аутентификации.
+
+```javascript
+// Эти политики готовы к активации, но сейчас отключены:
+
+// abac.registerResourcePolicy('stockAdjustment', async context => {
+//   const { user, action, data } = context;
+//   
+//   if (action === 'create') {
+//     const userDoc = context.userDoc || await db.user.findById(user).populate('roles');
+//     const hasWarehouseRole = userDoc?.roles?.some(r => 
+//       ['warehouse', 'admin', 'moderator'].includes(r.name || r)
+//     );
+//     
+//     if (!hasWarehouseRole) {
+//       return { allow: false, reason: 'WAREHOUSE_ROLE_REQUIRED' };
+//     }
+//   }
+//   
+//   return { allow: true, force: false };
+// });
+```
+
+### Middleware интеграция ABAC
+
+В маршрутах ABAC middleware активно используется:
+
+```javascript
+// Stock Adjustment creation
+app.post('/api/inventory/adjustments/create', 
+  jwt.verifyToken(), 
+  verifier.verifyAdjustmentBody, 
+  abac.middleware('stockAdjustment', 'create'),  // ABAC проверка
+  controller.adjustments.create
+);
+
+// Stock Audit completion
+app.post('/api/inventory/audits/complete', 
+  jwt.verifyToken(), 
+  verifier.verifyInventoryComplete, 
+  abac.middleware('stockAudit', 'edit'),        // ABAC проверка
+  controller.inventory.complete
+);
+```
+
+### Потенциальные политики доступа
+
+#### Stock Adjustment Policies
+
+**Концепция**: Только складские работники могут изменять остатки товаров.
+
+```javascript
+// Готовая к активации политика
+abac.registerResourcePolicy('stockAdjustment', async context => {
+  const { user, action, data } = context;
+  
+  if (action === 'create') {
+    // Проверка роли пользователя
+    const userDoc = context.userDoc || await db.user.findById(user).populate('roles');
+    const hasWarehouseRole = userDoc?.roles?.some(r => 
+      ['warehouse', 'admin', 'moderator'].includes(r.name || r)
+    );
+    
+    if (!hasWarehouseRole) {
+      return { allow: false, reason: 'WAREHOUSE_ROLE_REQUIRED' };
+    }
+  }
+  
+  return { allow: true, force: false };
+});
+```
+
+**Применение**:
+- `warehouse` role - основные складские операции
+- `admin` role - полный доступ ко всем операциям
+- `moderator` role - надзорные функции
+
+#### Stock Audit Policies
+
+**Концепция**: Только создатель инвентаризации или администратор может ее завершить.
+
+```javascript
+// Готовая к активации политика
+abac.registerResourcePolicy('stockAudit', async context => {
+  const { user, action, currentResource } = context;
+  
+  if (action === 'edit' && currentResource) {
+    // Проверка ownership или admin прав
+    if (currentResource.creator.target.toString() !== user) {
+      const userDoc = context.userDoc || await db.user.findById(user).populate('roles');
+      const isAdmin = userDoc?.roles?.some(r => r.name === 'admin' || r === 'admin');
+      
+      if (!isAdmin) {
+        return { allow: false, reason: 'NOT_INVENTORY_CREATOR' };
+      }
+    }
+  }
+  
+  return { allow: true, force: false };
+});
+```
+
+**Применение**:
+- Создатель audit может его завершить
+- Admin может завершать любые audit
+- Другие пользователи получают отказ
+
+## Owner-based Data Isolation
+
+### Мультитенантная архитектура
+
+Все основные модели используют `ownership.schema` для изоляции данных:
+
+```javascript
+// В каждой модели (кроме StockAvailability)
+applyOwnershipSchema(StockAdjustmentSchema, db);
+
+// Структура ownership
+{
+  owner: {
+    type: 'organization' | 'user',
+    target: ObjectId                    // ID организации или пользователя
+  },
+  creator: {
+    type: 'user',
+    target: ObjectId                    // ID создавшего пользователя
+  }
+}
+```
+
+### Автоматическая фильтрация по owner
+
+В контроллерах происходит неявная фильтрация данных:
+
+```javascript
+// Пример из availability controller
+const matchConditions = {
+  ...(req.verifiedQuery?.owner && { 
+    'owner.target': new db.mongoose.Types.ObjectId(req.verifiedQuery.owner) 
+  })
+};
+
+// Пользователи видят только свои данные или данные своей организации
+```
+
+### Наследование ownership
+
+При создании ресурсов owner наследуется:
+
+```javascript
+// В adjustment creation
+const adjustmentData = {
+  ...req.verifiedBody,
+  creator: { type: 'user', target: req.userId },      // Создатель = текущий пользователь
+  owner: req.verifiedBody.owner                       // Owner передается в запросе
+};
+```
+
+## Права доступа по операциям
+
+### Матрица доступа
+
+| Операция | Аутентификация | ABAC Policy | Owner Filter | Публичный доступ |
+|----------|---------------|-------------|--------------|------------------|
+| **GET /adjustments** | Мягкая ✓ | Нет | ✓ | Частично |
+| **POST /adjustments/create** | Строгая ✓ | stockAdjustment:create | ✓ | Нет |
+| **GET /balance** | Мягкая ✓ | Нет | ✓ | Частично |
+| **GET /availability** | Нет | Нет | Частично | ✓ |
+| **GET /audits** | Строгая ✓ | Нет | ✓ | Нет |
+| **POST /audits/create** | Строгая ✓ | stockAudit:create | ✓ | Нет |
+| **POST /audits/complete** | Строгая ✓ | stockAudit:edit | ✓ | Нет |
+| **CRUD /alerts/** | Строгая ✓ | Настраиваемо | ✓ | Нет |
+
+### Особенности доступа
+
+#### Публичный endpoint availability
+```javascript
+// Единственный endpoint без аутентификации
+app.get('/api/inventory/availability', 
+  verifier.verifyAvailabilityQuery,    // Только валидация
+  controller.availability.read         // Без auth/abac middleware
+);
+```
+
+**Назначение**: Поддержка e-commerce интеграций, где внешние системы должны проверять доступность товаров без аутентификации.
+
+#### Мягкая аутентификация для чтения
+```javascript
+// Поддерживает и авторизованных, и анонимных пользователей
+app.get('/api/inventory/adjustments', 
+  jwt.verifyToken(true),               // true = не блокирует анонимов
+  verifier.verifyAdjustmentQuery, 
+  controller.adjustments.read
+);
+```
+
+**Логика**: 
+- Авторизованные пользователи видят данные своей организации
+- Анонимные пользователи получают пустые результаты (owner filter блокирует)
+
+## Context-aware авторизация
+
+### Различия контекстов
+
+Клиентская часть поддерживает два контекста с разными правами:
+
+```javascript
+// Backoffice context - админская панель
+meta: { context: 'backoffice' }
+// Полный доступ ко всем функциям, cross-organization просмотр
+
+// Organization context - клиентский интерфейс  
+meta: { context: 'organization' }
+// Ограниченный доступ только к данным своей организации
+```
+
+### Влияние на UI
+
+```vue
+<!-- Условный рендеринг на основе контекста -->
+<button
+  v-if="route.meta.context === 'backoffice'"
+  @click="router.push({ name: 'BackofficeInventoryAudit' })"
+/>
+
+<button
+  v-if="route.meta.context === 'organization'"
+  @click="router.push({ 
+    name: 'OrganizationInventoryAudit', 
+    params: { _id: route.params._id } 
+  })"
+/>
+```
+
+## Активация политик безопасности
+
+### Пошаговая активация ABAC
+
+Для включения строгих политик доступа:
+
+1. **Раскомментировать политики** в `inventory.policies.js`
+2. **Настроить роли пользователей** в системе управления ролями
+3. **Протестировать политики** на тестовой среде
+4. **Задокументировать изменения** для команды
+
+### Пример активации
+
+```javascript
+// 1. Раскомментировать политику
+abac.registerResourcePolicy('stockAdjustment', async context => {
+  // ... policy logic
+});
+
+// 2. Обновить тесты
+it('should deny access for non-warehouse users', async () => {
+  const response = await request(app)
+    .post('/api/inventory/adjustments/create')
+    .set('Authorization', `Bearer ${regularUserToken}`)
+    .send(adjustmentData);
+  
+  expect(response.status).toBe(403);
+  expect(response.body.reason).toBe('WAREHOUSE_ROLE_REQUIRED');
+});
+```
+
+### Мигграционные соображения
+
+**Текущее состояние**: Permissive mode позволяет всем аутентифицированным пользователям выполнять любые операции.
+
+**После активации**: Потребуется:
+- Назначить роли существующим пользователям
+- Обновить интеграции для обработки 403 ошибок
+- Подготовить документацию по ролям для бизнес-пользователей
+
+Эта архитектура обеспечивает гибкость настройки прав доступа от полностью открытой системы до строго регламентированной с детальным контролем на уровне операций и ресурсов.