fix: config JWT/storage/piv/SECRET_KEY; docs: USER_GUIDE.md, DEMO_INFRASTRUCTURE_CONCLUSION.md

- config: JWT_SECRET, JWT_ALG, allow_hs256_dev_tokens, SECRET_KEY, storage_dir, piv_base_url, piv_timeout_s - docs/USER_GUIDE.md: руководство пользователя КЛГ АСУ ТК (16 разделов) - docs/DEMO_INFRASTRUCTURE_CONCLUSION.md: заключение по demo-инфраструктуре Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-15 13:13:23 +03:00 · 2026-02-15 13:13:23 +03:00 · 0e93bb9433
commit 0e93bb9433
parent 2a030d2cac
3 changed files with 421 additions and 89 deletions
--- a/backend/app/core/config.py
+++ b/backend/app/core/config.py
@ -34,7 +34,13 @@ class Settings(BaseSettings):
    OIDC_AUDIENCE: str = "account"
    ENABLE_DEV_AUTH: bool = False  # ONLY for development
    DEV_TOKEN: str = "dev"
-    
+    # JWT (dev mode — HS256 токены)
+    JWT_SECRET: str = ""
+    JWT_ALG: str = "HS256"
+    allow_hs256_dev_tokens: bool = False
+    # Secret key (подпись, сессии)
+    SECRET_KEY: str = "change-me-in-production"
+
    # Rate limiting
    RATE_LIMIT_PER_MINUTE: int = 60
    
@ -48,7 +54,13 @@ class Settings(BaseSettings):
    # Inbox (COD-004)
    INBOX_DATA_DIR: str = "./data"
    INBOX_UPLOAD_MAX_MB: int = 50
-    
+    # Хранилище файлов (attachments, storage.py)
+    storage_dir: str = "./data/storage"
+
+    # П-ИВ интеграция
+    piv_base_url: str = "http://localhost:9090/piv"
+    piv_timeout_s: float = 10.0
+
    # Multi-tenancy
    ENABLE_RLS: bool = True
    
--- a/docs/DEMO_INFRASTRUCTURE_CONCLUSION.md
+++ b/docs/DEMO_INFRASTRUCTURE_CONCLUSION.md
@ -0,0 +1,130 @@
+# Заключение: Demo-инфраструктура КЛГ АСУ ТК
+
+**Дата:** 15 февраля 2026  
+**Задача:** Подготовка к подключению до 5 удалённых клиентов для демонстрации, тестирования и проверки работоспособности
+
+---
+
+## Сводка: все 9 блоков реализованы
+
+| # | Блок | Файлы | Статус |
+|---|------|-------|--------|
+| 1 | Dockerfile frontend | `Dockerfile` (корень) — multi-stage builder + runner | ✅ |
+| 2 | Docker Compose demo | `docker-compose.demo.yml` — Caddy, seed, env override | ✅ |
+| 3 | Reverse proxy | `demo/Caddyfile` — авто-HTTPS, проксирование, безопасность | ✅ |
+| 4 | 5 пользователей + токены | `demo/users.json`, `demo/generate_tokens.py` | ✅ |
+| 5 | Demo seed | `backend/app/demo/seed.py` — адаптирован под модели | ✅ |
+| 6 | Скрипт развёртывания | `demo/deploy.sh` — one-command deploy | ✅ |
+| 7 | Документация | `docs/DEMO.md` — 3 варианта хостинга, сценарии | ✅ |
+| 8 | .gitignore | `demo/tokens.json` добавлен | ✅ |
+| 9 | Адаптация seed под модели | Organization.kind, AircraftType без name, Aircraft без flight_hours, 5 User | ✅ |
+
+---
+
+## Архитектура demo-стенда
+
+```
+Удалённый клиент (браузер)
+    │ HTTPS / WSS
+    ▼
+┌─────────────────────────────┐
+│  Caddy (порты 80/443)       │ ← авто-сертификат Let's Encrypt
+│  reverse proxy + TLS        │
+├─────────────────────────────┤
+│  /          → frontend:3000 │ Next.js (SSR)
+│  /api/*     → backend:8000  │ FastAPI (4 workers)
+│  /ws/*      → backend:8000  │ WebSocket
+│  /docs      → backend:8000  │ Swagger UI
+│  /auth/*    → keycloak:8080 │ (опционально)
+└─────────────────────────────┘
+         │              │
+    ┌────┘              └────┐
+    ▼                        ▼
+┌──────────┐          ┌──────────┐
+│ PostgreSQL│          │  Redis   │
+│  + RLS    │          │  cache   │
+└──────────┘          └──────────┘
+    ▲
+    │
+┌──────────────┐
+│ Keycloak DB  │ (отдельная БД)
+│ (опционально)│
+└──────────────┘
+```
+
+## 5 тестовых пользователей
+
+| # | Имя | Роль | Организация | Ключевые возможности |
+|---|-----|------|-------------|---------------------|
+| 1 | Админ Системы | `admin` | — | Полный доступ, dashboard, аналитика |
+| 2 | Иванов И.П. | `authority_inspector` | ФАВТ | Инспекция, одобрение заявок, аудиты, панель ФАВТ |
+| 3 | Петров А.С. | `operator_manager` | КалинингрАвиа | Парк ВС (4 борта), заявки, модификации |
+| 4 | Сидоров В.Н. | `mro_manager` | Балтик Техник | Наряды ТО, чек-листы, CRS, дефекты |
+| 5 | Козлова Е.А. | `operator_user` | КалинингрАвиа | Просмотр ВС, создание заявок |
+
+## Демо-данные (seed)
+
+- **3 организации:** АК «КалинингрАвиа», ТОиР «Балтик Техник», МТУ ФАВТ Северо-Запад
+- **3 типа ВС:** SSJ100, МС-21-300, L-410
+- **4 воздушных судна:** RA-89001, RA-89002, RA-73001, RA-67001
+- **2 заявки:** одна submitted (ТОиР по ФАП-145), одна draft (продление СЭ)
+- **2 уведомления:** новая заявка для инспектора, приближающаяся инспекция для оператора
+
+## Два режима авторизации
+
+### Режим 1: Dev-токены (по умолчанию)
+```bash
+bash demo/deploy.sh --domain demo.klg.refly.ru
+# Генерирует JWT HS256 токены на 30 дней для каждого пользователя
+# Токены сохраняются в demo/tokens.json
+```
+
+### Режим 2: Keycloak OIDC
+```bash
+bash demo/deploy.sh --domain demo.klg.refly.ru --with-keycloak
+# Поднимает Keycloak на отдельной БД
+# Доступ: https://demo.klg.refly.ru/auth
+```
+
+## Три варианта хостинга
+
+| Вариант | Подходит для | Стоимость | Сложность |
+|---------|-------------|-----------|-----------|
+| **VPS/VDS** (Timeweb, Selectel, Hetzner) | Постоянный demo-стенд | от 500₽/мес | Низкая |
+| **Локальный + Cloudflare Tunnel** | Быстрая демонстрация | Бесплатно | Минимальная |
+| **Yandex Cloud / Selectel Cloud** | Масштабирование, SLA | от 2000₽/мес | Средняя |
+
+**Минимальные требования:** 2 vCPU, 4 GB RAM, 10 GB SSD, Docker 24+
+
+## Команды управления
+
+```bash
+# Запуск
+bash demo/deploy.sh [--domain DOMAIN] [--with-keycloak]
+
+# Генерация токенов (повторно)
+python3 demo/generate_tokens.py --format table
+
+# Логи
+docker compose -f docker-compose.yml -f docker-compose.demo.yml --profile demo logs -f
+
+# Остановка
+docker compose -f docker-compose.yml -f docker-compose.demo.yml --profile demo down
+
+# Полный сброс (с удалением данных)
+docker compose -f docker-compose.yml -f docker-compose.demo.yml --profile demo down -v
+```
+
+---
+
+## Рекомендации перед запуском demo
+
+1. **Проверить seed.py** — убедиться что все модели совпадают с текущими миграциями (поля Organization.kind, AircraftType, Aircraft). При ошибках seed логирует и завершается с ненулевым кодом.
+
+2. **Frontend login-страница** — страница `/login` уже поддерживает ввод токена (поле «Токен доступа»), вызывает `login(token)` из auth-context, который сохраняет токен через `setAuthToken()` из `api-client.ts`. Для demo подставьте токен из `demo/tokens.json`.
+
+3. **CORS** — при использовании домена добавить его в `CORS_ORIGINS` в `.env` (deploy.sh делает это автоматически при создании .env).
+
+4. **Firewall** — на VPS открыть порты 80 и 443 для Caddy.
+
+5. **WebSocket** — проверить что `wss://` проходит через Caddy (Caddyfile уже настроен на `/ws/*`).
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@ -1,124 +1,314 @@
-# Руководство пользователя
+# КЛГ АСУ ТК — Руководство пользователя

-## Вход в систему
+> Система автоматизированного управления техническим контролем  
+> Калининградский филиал · АО «REFLY»  
+> Версия 2.1.0

-> **Примечание:** Аутентификация будет реализована в будущих версиях.
+---

-## Навигация
+## 1. Введение

-### Дашборд
+КЛГ АСУ ТК — веб-приложение для контроля лётной годности воздушных судов, сертификации эксплуатантов и организаций ТОиР, управления рисками и ведения нормативной базы.

-Главная страница системы отображает:
- Статистику по воздушным судам
- Статистику по рискам
- Статистику по аудитам
- Быстрые действия
+Система разработана в соответствии с требованиями Воздушного кодекса РФ, ФАП-145, ФАП-147, ФАП-148, ФАП-246, стандартов ICAO и EASA.

-### Воздушные суда
+### Для кого предназначена система

-Просмотр и управление воздушными судами:
- Список всех ВС
- Поиск по номеру, типу, оператору
- Фильтрация по статусу
+| Роль | Описание |
+|------|----------|
+| Администратор | Полный доступ ко всем модулям и данным всех организаций |
+| Инспектор ФАВТ | Рассмотрение заявок, инспекции, аудиты, панель регулятора |
+| Руководитель эксплуатанта | Управление парком ВС, подача заявок на сертификацию |
+| Специалист эксплуатанта | Просмотр данных, создание заявок |
+| Руководитель ТОиР | Наряды на ТО, чек-листы, управление дефектами |
+| Специалист ТОиР | Выполнение задач ТО, заполнение чек-листов |

-### Организации
+---

-Управление организациями:
- Список организаций
- Просмотр ВС организации
- Редактирование данных
+## 2. Вход в систему

-### Риски
+1. Откройте адрес системы в браузере (например, `https://demo.klg.refly.ru`)
+2. На странице **Вход** введите ваш токен доступа в поле «Токен доступа»
+3. Нажмите **Войти**
+4. При успешной авторизации вы попадёте на главную страницу (Dashboard)

-Управление рисками:
- Просмотр всех рисков
- Фильтрация по уровню (Критические, Высокие, Средние, Низкие)
- Создание и редактирование рисков
+> **Для demo-режима:** токены для каждого пользователя находятся в файле `demo/tokens.json`. Скопируйте нужный токен и вставьте в поле.

-### Аудиты
+> **Для production:** используется авторизация через Keycloak. Вы будете перенаправлены на страницу входа Keycloak для ввода логина и пароля.

-Управление аудитами:
- Просмотр текущих аудитов
- Создание новых аудитов
- Отслеживание статусов
+### Выход из системы

-### Чек-листы
+Нажмите на своё имя в правом верхнем углу → **Выйти**. Токен будет удалён из памяти, потребуется повторный вход.

-Управление чек-листами:
- Просмотр чек-листов
- Создание новых чек-листов
- Отметка о выполнении
+---

-### Заявки
+## 3. Главная страница (Dashboard)

-Управление заявками:
- Просмотр заявок
- Создание новых заявок
- Отслеживание статусов
+После входа отображается сводная панель:

-### Документы
+- **Статистика**: количество ВС, активных заявок, открытых рисков, предстоящих инспекций
+- **Последние уведомления**: новые заявки, замечания, приближающиеся сроки
+- **Быстрые действия**: кнопки перехода к основным модулям

-Управление документами:
- Просмотр документов
- Загрузка документов
- Скачивание документов
- Изменение статуса
+---

-### Нормативные документы
+## 4. Парк воздушных судов

-Просмотр нормативных документов:
- Фильтрация по источнику (ICAO, EASA, FAA, МАК, АРМАК)
- Поиск по документам
- Просмотр деталей
+### 4.1 Просмотр списка ВС

-## ИИ Агент
+Перейдите в раздел **Воздушные суда** в боковом меню.

-ИИ агент помогает с:
- Поиском информации
- Анализом данных
- Добавлением данных в систему
- Ответами на вопросы
+Отображается таблица со столбцами:
+- Регистрационный номер (например, RA-89001)
+- Тип ВС (SSJ100, МС-21, L-410)
+- Оператор (название организации)
+- Статус (active / maintenance / grounded / storage)
+- Год выпуска

-### Использование ИИ агента
+Используйте поиск и фильтры для нахождения нужного ВС.

-1. Нажмите кнопку "ИИ Агент" на дашборде
-2. Введите ваш вопрос или команду
-3. При необходимости прикрепите файлы
-4. Получите ответ от ИИ агента
+### 4.2 Карточка ВС

-### Примеры запросов
+Нажмите на регистрационный номер для просмотра подробной информации:

- "Сколько воздушных судов у Аэрофлота?"
- "Покажи все критические риски"
- "Найди ВС RA-12345"
- "Какие требования ФАП-128?"
+- **Основные данные**: серийный номер, тип, оператор, год выпуска
+- **Наработка**: часы налёта, циклы
+- **Сертификаты лётной годности**: действующие и истёкшие
+- **Директивы ЛГ (AD)**: применённые и открытые
+- **Модификации**: выполненные SB и AD
+- **История обслуживания**: наряды на ТО

-## Поиск
+### 4.3 Добавление ВС (оператор/администратор)

-Глобальный поиск доступен:
- На дашборде (кнопка "Поиск")
- На странице ВС и типы
- В разделе Организации
+1. Нажмите кнопку **+ Добавить ВС**
+2. Заполните обязательные поля: регистрационный номер, тип ВС
+3. Укажите оператора (вашу организацию)
+4. Нажмите **Сохранить**

-Поиск работает по:
- Номеру ВС
- Типу ВС
- Названию компании
- Номеру организации
+---

-## Горячие клавиши
+## 5. Заявки на сертификацию

- `Ctrl+K` - Глобальный поиск (в разработке)
- `Esc` - Закрыть модальное окно
- `Ctrl+S` - Сохранить форму (в разработке)
+### 5.1 Создание заявки

-## Экспорт данных
+1. Перейдите в раздел **Сертификация**
+2. Нажмите **+ Новая заявка**
+3. Заполните:
+   - **Тема** — краткое описание (например, «Продление СЭ»)
+   - **Описание** — подробности, scope, перечень ВС
+4. Нажмите **Сохранить** — заявка создаётся в статусе **Черновик**

-> **Примечание:** Функция экспорта будет реализована в будущих версиях.
+### 5.2 Подача заявки

-## Поддержка
+В карточке заявки нажмите **Подать заявку**. Статус изменится на **Подана**. Инспектор ФАВТ получит уведомление.
+
+### 5.3 Рассмотрение (инспектор)
+
+1. Инспектор открывает заявку и нажимает **Начать рассмотрение** → статус **На рассмотрении**
+2. При наличии замечаний — нажмите **Добавить замечание**, введите текст
+   - Заявителю автоматически устанавливается срок 30 дней на устранение
+   - Статус меняется на **Замечания**
+3. После устранения заявитель повторно подаёт заявку
+4. Инспектор принимает решение:
+   - **Одобрить** → статус **Одобрена**
+   - **Отклонить** → статус **Отклонена**
+
+### 5.4 Жизненный цикл заявки
+
+```
+Черновик → Подана → На рассмотрении → Одобрена
+                                     → Замечания → Подана (повторно)
+                                     → Отклонена
+```
+
+---
+
+## 6. Наряды на техническое обслуживание (Work Orders)
+
+### 6.1 Создание наряда
+
+1. Перейдите в **Наряды на ТО**
+2. Нажмите **+ Новый наряд**
+3. Выберите:
+   - **ВС** (из списка)
+   - **Тип**: плановый / внеплановый / AOG (Aircraft on Ground)
+   - **Приоритет**: обычный / высокий / критический
+   - **Описание** работ
+4. Нажмите **Создать**
+
+### 6.2 Выполнение наряда
+
+1. Назначенный специалист открывает наряд
+2. Выполняет работы согласно описанию и чек-листу
+3. После завершения — подписывает CRS (Certificate of Release to Service):
+   - Нажмите **Закрыть с CRS**
+   - Укажите данные подписанта
+
+### 6.3 Статусы нарядов
+
+| Статус | Описание |
+|--------|----------|
+| open | Создан, ожидает выполнения |
+| in_progress | В работе |
+| completed | Выполнен, CRS подписан |
+| cancelled | Отменён |
+
+---
+
+## 7. Дефекты
+
+### 7.1 Регистрация дефекта
+
+1. Перейдите в **Дефекты**
+2. Нажмите **+ Зарегистрировать дефект**
+3. Укажите:
+   - **ВС**
+   - **Глава ATA** (по классификации)
+   - **Описание** дефекта
+   - **Критичность**: критический / значительный / незначительный
+4. Для критических дефектов автоматически создаётся risk alert
+
+### 7.2 MEL Deferral
+
+Если дефект допускает отложенное устранение по MEL (Minimum Equipment List):
+1. Откройте карточку дефекта
+2. Нажмите **Отложить по MEL**
+3. Укажите категорию MEL (A/B/C/D) и срок
+
+---
+
+## 8. Чек-листы и аудиты
+
+### 8.1 Шаблоны чек-листов
+
+В разделе **Чек-листы** доступны шаблоны по стандартам:
+- ФАП-М (поддержание лётной годности)
+- ATA chapters
+- CSV (загрузка собственных)
+
+### 8.2 Проведение аудита
+
+1. Перейдите в **Аудиты** → **+ Новый аудит**
+2. Выберите тип, ВС или организацию, шаблон чек-листа
+3. Заполняйте пункты: ✅ Соответствует / ❌ Не соответствует / ⚠️ Замечание
+4. При завершении нажмите **Закрыть аудит**
+5. Результаты сохраняются в журнале
+
+---
+
+## 9. Управление рисками
+
+### 9.1 Панель рисков
+
+Раздел **Риски** отображает:
+- Автоматически обнаруженные risk alerts (истекающие ресурсы, просроченные квалификации, новые обязательные AD)
+- Ручные записи от инспекторов
+
+### 9.2 Обработка риска
+
+1. Откройте карточку риска
+2. Проанализируйте описание и связанные сущности
+3. Выполните корректирующие действия
+4. Нажмите **Закрыть риск** с описанием принятых мер
+
+---
+
+## 10. Нормативная база
+
+Раздел **Нормативная база** содержит 19 базовых документов:
+
+- Воздушный кодекс РФ (60-ФЗ)
+- ФАП-10/246, ФАП-21, ФАП-128, ФАП-145, ФАП-147, ФАП-148, ФАП-149
+- ICAO Annex 1, 6, 7, 8, 19
+- EASA Part-21, Part-66, Part-M, Part-145
+- ФЗ-152, ФЗ-149
+
+Для каждого документа доступны: текст, перекрёстные ссылки, комментарии, судебная практика.
+
+---
+
+## 11. Уведомления
+
+Система уведомляет в реальном времени (WebSocket) о:
+- Новых заявках и изменении статуса
+- Замечаниях с дедлайнами
+- Приближающихся инспекциях
+- Критических рисках
+- Новых обязательных директивах ЛГ
+
+Уведомления отображаются в виде значка 🔔 в шапке. Нажмите для просмотра списка. Кнопка **Прочитать все** отмечает все как прочитанные.
+
+---
+
+## 12. Панель ФАВТ (только для инспекторов)
+
+Инспекторы ФАВТ имеют доступ к read-only панели со сводной информацией:
+- Все организации и их парки ВС
+- Все заявки на сертификацию (по всем организациям)
+- Результаты аудитов
+- Статистика рисков
+
+Эта панель соответствует требованиям ВК РФ ст. 8.
+
+---
+
+## 13. Импорт и экспорт данных
+
+### Импорт
+- **CSV/XLSX**: загрузка данных о ВС, компонентах, персонале
+- **PDF/DOCX**: входящие документы (через раздел «Входящие»)
+- **ZIP**: массовый импорт
+
+### Экспорт
+- Таблицы можно экспортировать в CSV/XLSX
+- Заявки — в PDF
+- Аудиты — в PDF с результатами
+
+---
+
+## 14. API (для разработчиков)
+
+Полная документация API доступна по адресам:
+- **Swagger UI**: `/docs`
+- **ReDoc**: `/redoc`
+- **OpenAPI JSON**: `/openapi.json`
+
+Все запросы требуют заголовок `Authorization: Bearer <TOKEN>`.
+
+Пример:
+```bash
+curl -H "Authorization: Bearer <TOKEN>" https://demo.klg.refly.ru/api/v1/aircraft
+```
+
+---
+
+## 15. Частые вопросы
+
+**В: Как получить токен для входа?**  
+О: В demo-режиме токены генерируются командой `python demo/generate_tokens.py`. В production токены выдаёт Keycloak после аутентификации.
+
+**В: Почему я не вижу ВС других организаций?**  
+О: Система использует мультитенантность (RLS). Каждый пользователь видит только данные своей организации. Администратор и инспектор ФАВТ видят данные всех организаций.
+
+**В: Как изменить свою роль?**  
+О: Роли назначаются администратором. Обратитесь к администратору системы.
+
+**В: Что делать при ошибке 401 (Unauthorized)?**  
+О: Срок действия токена истёк. Получите новый токен и войдите заново.
+
+**В: Поддерживаются ли мобильные устройства?**  
+О: Да, интерфейс адаптивный (responsive). Рекомендуется использовать на экранах шириной от 768px.
+
+---
+
+## 16. Техническая поддержка

 При возникновении проблем:
-1. Проверьте, что вы используете последнюю версию браузера
-2. Очистите кэш браузера
-3. Обратитесь к администратору системы
+1. Проверьте раздел «Частые вопросы» выше
+2. Проверьте статус системы: `/api/v1/health`
+3. Свяжитесь с администратором системы
+4. Для разработчиков: логи доступны через `docker compose logs -f`
+
+---
+
+*© АО «REFLY» — Разработчик АСУ ТК КЛГ*