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

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

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

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

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

---

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

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

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

```bash
# Клонирование репозитория (если необходимо)
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 токена:**

```json
{
  "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:**
   ```bash
   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. **Поиск:**
   - На главной странице введите запрос в поле поиска
   - Нажмите "Найти"
   - Проверьте результаты

---

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

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

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

# Логи backend
docker compose logs backend

# Логи frontend
docker compose logs frontend

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

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

```bash
# Остановка всех сервисов
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