klg-asutk-app/docs/ДЕМОНСТРАЦИЯ_ПРОЕКТА.md

Демонстрация проекта: Система контроля лётной годности (КЛГ)

Обзор проекта

Система контроля лётной годности воздушных судов — это комплексное веб-приложение для управления данными о воздушных судах, организациях, сертификатах и документации в соответствии с требованиями ИКАО, МАК, EASA и Росавиации.

Заказчик: АО «REFLY»
Вариант развертывания: В составе АСУ ТК
Статус: Прототип (MVP)

---

🚀 Быстрый старт

Требования

• Docker и Docker Compose
• 4 ГБ свободной оперативной памяти
• Порты 8080 (frontend) и 8000 (backend) должны быть свободны

Запуск проекта

# Клонирование репозитория (если необходимо)
cd klg_asutk_app

# Запуск всех сервисов
docker compose up --build

# Или в фоновом режиме
docker compose up -d --build

Доступ к приложению

После запуска доступны следующие адреса:

• Frontend (веб-интерфейс): http://localhost:8080
• Backend API: http://localhost:8000
• API документация (Swagger): http://localhost:8000/docs
• API документация (ReDoc): http://localhost:8000/redoc

---

📋 Основные функции системы

1. Дашборд (Главная страница)

URL: http://localhost:8080/

Функциональность:

• Отображение ключевых показателей (KPI):

  • Количество организаций
  • Количество воздушных судов
  • Количество заявок на сертификацию
  • Количество одобренных заявок
  • Количество пользователей
  • ВС в эксплуатации
  • ВС на обслуживании
  • Сертификаты с истекающим сроком действия

• Поиск по воздушным судам и организациям

• Быстрый доступ к функциям:

  • Загрузка данных — загрузка файлов (текст, PDF, XLS, PNG) для воздушных судов
  • Документы — переход к нормативным документам

Дизайн:

• Небесный градиентный фон с анимацией облаков
• Белые карточки с тенями для лучшей читаемости
• Крупные зеленые кнопки для основных действий
• Глянцевые кнопки для дополнительных функций

2. Воздушные суда

URL: http://localhost:8080/aircraft

Функциональность:

• Просмотр списка всех воздушных судов с фильтрацией

• Отображение информации:

  • Регистрационный номер
  • Серийный номер
  • Тип ВС (производитель и модель)
  • Оператор
  • Статус (в эксплуатации, на обслуживании, на хранении, списан)
  • Налет (часы)
  • Количество циклов
  • Чертежные номера
  • Дата выполненных работ

• Создание нового воздушного судна

• Редактирование существующих записей

• Просмотр детальной информации о ВС

Типы воздушных судов:

• Самолеты: Boeing 737, Airbus A320, Sukhoi Superjet 100, MC-21-300, Ил-96-300, Ту-204, Ан-148 и др.
• Вертолеты: Ми-8, Ми-26, Ка-32, Ка-226, AW139, EC225 и др.

3. Организации

URL: http://localhost:8080/organizations

Функциональность:

• Управление организациями трех типов:

  • Операторы — авиакомпании и эксплуатанты
  • MRO — организации технического обслуживания
  • Органы власти — регулирующие органы

• Создание, редактирование и удаление организаций

• Просмотр списка всех организаций с фильтрацией

Примеры организаций в системе:

• Аэрофлот
• S7 Airlines
• Уральские авиалинии
• Авиакомпания "Якутия"
• Авиакомпания "Победа"
• И другие

4. Заявки на сертификацию

URL: http://localhost:8080/applications

Функциональность:

• Просмотр заявок на сертификацию организаций по техническому обслуживанию

• Отслеживание статусов:

  • draft — черновик
  • submitted — подана
  • under_review — на рассмотрении
  • remarks — есть замечания
  • approved — одобрена
  • rejected — отклонена
  • expired — истекла

• Автоматическая нумерация заявок

• Система замечаний и уведомлений

• Автоматический таймер (30 дней на исправление замечаний)

5. Пользователи

URL: http://localhost:8080/users

Функциональность:

• Просмотр списка пользователей системы
• Фильтрация по:
  • Организации
  • Роли

Роли пользователей:

• Администратор — полный доступ
• Инспектор органа — проверка и одобрение заявок
• Менеджер оператора — управление ВС оператора
• Пользователь оператора — просмотр данных оператора
• Менеджер MRO — управление данными MRO
• Пользователь MRO — просмотр данных MRO

6. Нормативные документы

URL: http://localhost:8080/regulations

Функциональность:

• Просмотр нормативных документов от:

  • ИКАО (ICAO) — международные стандарты
  • МАК — Межгосударственный авиационный комитет
  • EASA — Европейское агентство авиационной безопасности
  • Росавиация — Федеральное агентство воздушного транспорта

• Информация о каждом документе:

  • Название и номер
  • Тип документа
  • Дата публикации/обновления
  • Статус (действует, обновлен, новый)
  • Категория
  • Описание
  • Ссылка на официальный сайт

Примеры документов:

• ИКАО Annex 8 — Воздушная годность воздушных судов
• ИКАО Doc 9760 — Руководство по поддержанию летной годности
• EASA Part M — Continuing Airworthiness
• EASA Part 145 — Maintenance Organisation Approvals
• ФАП-128 — Поддержание летной годности воздушных судов

---

🎨 Дизайн и пользовательский интерфейс

Цветовая схема

Фон страниц:

• Небесный градиент: от небесно-голубого (#87CEEB) вверху до белого (#FFFFFF) внизу
• Анимированные облака для визуального эффекта

Карточки и элементы:

• Белый фон для карточек и таблиц
• Тени для создания глубины
• Синие акценты для интерактивных элементов

Кнопки:

• Основные действия: Крупные круглые зеленые кнопки с белым текстом
• Дополнительные действия: Глянцевые прямоугольные кнопки различных цветов (бирюзовый, фиолетовый, синий, оранжевый)

Типографика

• Заголовки: Шрифт Unbounded (Bold, Regular)
• Основной текст: Шрифт Montserrat (Regular, Medium, Bold)

Адаптивность

• Интерфейс адаптирован для различных размеров экранов
• Таблицы с горизонтальной прокруткой на мобильных устройствах

---

🔧 Технические детали

Backend

Технологии:

• FastAPI — веб-фреймворк
• SQLAlchemy — ORM для работы с БД
• PostgreSQL — база данных
• APScheduler — планировщик задач
• Pydantic — валидация данных

Основные модули:

• app/api/routes/ — API endpoints
• app/models/ — модели данных SQLAlchemy
• app/schemas/ — Pydantic схемы
• app/services/ — бизнес-логика
• app/db/ — работа с базой данных
• app/integration/ — интеграции (П-ИВ АСУ ТК)

Frontend

Технологии:

• React 18 — библиотека для UI
• TypeScript — типизация
• Ant Design — UI компоненты
• Vite — сборщик
• React Router — маршрутизация

Структура:

• src/pages/ — страницы приложения
• src/components/ — переиспользуемые компоненты
• src/api/ — клиенты для API
• src/assets/ — стили, шрифты, изображения
• src/layout/ — компоненты макета

База данных

Основные таблицы:

• organizations — организации
• aircraft — воздушные суда
• aircraft_types — типы воздушных судов
• cert_applications — заявки на сертификацию
• users — пользователи
• attachments — вложения (файлы)
• notifications — уведомления
• airworthiness_certificates — сертификаты летной годности

---

📊 Примеры данных

Воздушные суда

Система содержит данные о различных типах воздушных судов:

Самолеты:

• Boeing 737-800 (Аэрофлот, S7 Airlines)
• Airbus A320 (Аэрофлот, Победа)
• Sukhoi Superjet 100 (Аэрофлот, Якутия)
• MC-21-300 (Аэрофлот)
• Ил-96-300 (Аэрофлот)
• Ту-204 (Уральские авиалинии)
• Ан-148 (Якутия)

Вертолеты:

• Ми-8 (различные операторы)
• Ми-26
• Ка-32
• Ка-226
• AW139
• EC225

Организации

Операторы:

• Аэрофлот — Российские авиалинии
• S7 Airlines
• Уральские авиалинии
• Авиакомпания "Якутия"
• Авиакомпания "Победа"

MRO:

• Авиационный технический центр
• Сервисный центр технического обслуживания

Органы власти:

• Росавиация
• МАК

---

🔐 Авторизация

Режим разработки

В режиме разработки включена поддержка HS256 токенов (ALLOW_HS256_DEV_TOKENS=true).

Минимальный набор claims для JWT токена:

{
  "sub": "user-1",
  "name": "Иван Иванов",
  "email": "ivan@example.com",
  "role": "operator_manager",
  "org_id": "<ID организации>"
}

Роли:

• admin — администратор
• authority_inspector — инспектор органа
• operator_manager — менеджер оператора
• operator_user — пользователь оператора
• mro_manager — менеджер MRO
• mro_user — пользователь MRO

Production

В production режиме используется OIDC/JWKS валидация через АСУ ТК-ИБ.

---

📡 API Endpoints

Организации

• GET /api/v1/organizations — список организаций
• POST /api/v1/organizations — создание (admin/authority_inspector)
• GET /api/v1/organizations/{id} — детали организации
• PATCH /api/v1/organizations/{id} — обновление
• DELETE /api/v1/organizations/{id} — удаление

Воздушные суда

• GET /api/v1/aircraft — список ВС
• POST /api/v1/aircraft — создание (operator/admin)
• GET /api/v1/aircraft/{id} — детали ВС
• PATCH /api/v1/aircraft/{id} — обновление
• GET /api/v1/aircraft/types — список типов ВС

Заявки на сертификацию

• GET /api/v1/cert-applications — список заявок
• POST /api/v1/cert-applications — создание заявки
• GET /api/v1/cert-applications/{id} — детали заявки
• POST /api/v1/cert-applications/{id}/submit — подача заявки
• POST /api/v1/cert-applications/{id}/start-review — начало рассмотрения (authority)
• POST /api/v1/cert-applications/{id}/remarks — добавление замечаний (authority)
• GET /api/v1/cert-applications/{id}/remarks — список замечаний
• POST /api/v1/cert-applications/{id}/approve — одобрение (authority)
• POST /api/v1/cert-applications/{id}/reject — отклонение (authority)

Вложения

• POST /api/v1/attachments/{owner_kind}/{owner_id} — загрузка файла
• GET /api/v1/attachments/{owner_kind}/{owner_id} — список вложений
• GET /api/v1/attachments/{id} — метаданные вложения
• GET /api/v1/attachments/{id}/download — скачивание файла

Уведомления

• GET /api/v1/notifications — список уведомлений

Пользователи

• GET /api/v1/users — список пользователей
• GET /api/v1/users/{id} — детали пользователя

Летная годность

• GET /api/v1/airworthiness/certificates — список сертификатов
• POST /api/v1/airworthiness/certificates — создание сертификата
• GET /api/v1/airworthiness/certificates/{id} — детали сертификата

Модификации

• GET /api/v1/modifications — список модификаций
• POST /api/v1/modifications — создание модификации

---

🧪 Тестирование

Проверка работоспособности

1. Проверка health endpoint:

   curl http://localhost:8000/api/v1/health
   

2. Проверка frontend:

   • Откройте http://localhost:8080 в браузере
   • Убедитесь, что загружается главная страница

3. Проверка API документации:

   • Откройте http://localhost:8000/docs
   • Попробуйте выполнить запросы через Swagger UI

Тестовые сценарии

1. Создание организации:

   • Перейдите в раздел "Организации"
   • Нажмите "Создать"
   • Заполните форму и сохраните

2. Добавление воздушного судна:

   • Перейдите в раздел "Воздушные суда"
   • Нажмите "Добавить ВС"
   • Заполните форму и сохраните

3. Загрузка файла:

   • На главной странице нажмите "Загрузка данных"
   • Выберите воздушное судно
   • Загрузите файл (текст, PDF, XLS или PNG)

4. Поиск:

   • На главной странице введите запрос в поле поиска
   • Нажмите "Найти"
   • Проверьте результаты

---

📝 Логи и отладка

Просмотр логов

# Логи всех сервисов
docker compose logs

# Логи backend
docker compose logs backend

# Логи frontend
docker compose logs frontend

# Логи в реальном времени
docker compose logs -f

Очистка и перезапуск

# Остановка всех сервисов
docker compose down

# Остановка с удалением volumes (ОСТОРОЖНО: удалит данные БД)
docker compose down -v

# Пересборка без кэша
docker compose build --no-cache

# Полный перезапуск
docker compose down
docker compose up --build

---

🔄 Интеграции

П-ИВ АСУ ТК

Система поддерживает интеграцию с протоколом интеграции и взаимодействия АСУ ТК:

• Модуль: app/integration/piv.py
• Функция push_event() — отправка событий
• Логирование интеграционных процессов в ingest_job_logs

ЦХД АСУ ТК

База данных PostgreSQL используется как модель центрального хранилища данных АСУ ТК.

---

🚧 Планы развития

Реализовано (MVP)

✅ Управление организациями
✅ Управление воздушными судами и типами
✅ Заявки на сертификацию с workflow
✅ Загрузка и управление файлами
✅ Система уведомлений
✅ Дашборд с KPI
✅ Нормативные документы
✅ Управление пользователями

В разработке / Планируется

• Документ лётной годности (ДЛГ)
• Контрольные данные (КД)
• Модификации воздушных судов (полная реализация)
• Инспекции
• Контрольные карты программы ТО
• Отслеживание компонентов с ограниченным ресурсом (LLP, HT)
• Отчеты по ремонтам и повреждениям конструкции
• Отчеты по дефектам
• Отслеживание комплектующих изделий с ограниченным ресурсом (шасси)
• Полная ролевая модель и матрица прав
• Интеграция с П-НСИ (справочники)
• Автотесты
• Программно-методические инструкции (ПМИ)

---

📞 Контакты и поддержка

Заказчик: АО «REFLY»

Для вопросов и предложений обращайтесь к команде разработки.

---

📄 Лицензия

Проект разработан для АО «REFLY» согласно техническому заданию.

---

Версия документа: 1.0
Дата обновления: 2024