From 0e93bb9433864f412e23b61ed4f1b0336a483bb6 Mon Sep 17 00:00:00 2001 From: Yuriy Date: Sun, 15 Feb 2026 13:13:23 +0300 Subject: [PATCH] fix: config JWT/storage/piv/SECRET_KEY; docs: USER_GUIDE.md, DEMO_INFRASTRUCTURE_CONCLUSION.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- backend/app/core/config.py | 16 +- docs/DEMO_INFRASTRUCTURE_CONCLUSION.md | 130 +++++++++ docs/USER_GUIDE.md | 364 +++++++++++++++++++------ 3 files changed, 421 insertions(+), 89 deletions(-) create mode 100644 docs/DEMO_INFRASTRUCTURE_CONCLUSION.md diff --git a/backend/app/core/config.py b/backend/app/core/config.py index c102e8c..92ab55b 100644 --- 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 diff --git a/docs/DEMO_INFRASTRUCTURE_CONCLUSION.md b/docs/DEMO_INFRASTRUCTURE_CONCLUSION.md new file mode 100644 index 0000000..71cf2bc --- /dev/null +++ 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/*`). diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index e1e8aa7..f6325bb 100644 --- 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 `. + +Пример: +```bash +curl -H "Authorization: Bearer " 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» — Разработчик АСУ ТК КЛГ*