corp-app/TECHDOC/ARCHITECTURE.md

Архитектура приложения

📋 Структура проекта

CORP-MAUI/
├── Models/                    # Модели данных
│   ├── User.cs               # Модель пользователя
│   ├── Message.cs            # Модель сообщения
│   └── AuthResponse.cs       # Ответ аутентификации
├── Services/                  # Сервисы
│   ├── ApiService.cs         # HTTP-клиент для REST API
│   └── WebSocketService.cs   # WebSocket-клиент
├── Pages/                     # Страницы приложения
│   ├── LoginPage.xaml        # Страница входа
│   ├── ProfilePage.xaml      # Профиль пользователя
│   ├── EmployeesPage.xaml        # Список сотрудников
│   └── ChatPage.xaml         # Чат с сотрудником
├── Platforms/                 # Платформенно-специфичный код
│   ├── Android/
│   ├── iOS/
│   ├── MacCatalyst/
│   ├── Windows/
│   └── Tizen/
├── Resources/                 # Ресурсы приложения
│   ├── AppIcon/
│   ├── Fonts/
│   ├── Images/
│   ├── Splash/
│   └── Styles/
├── ServiceProvider.cs         # Глобальный провайдер сервисов
├── App.xaml.cs               # Точка входа приложения
└── AppShell.xaml             # Навигационная структура

🏛️ Ключевые компоненты

1. ApiService - REST API клиент

Назначение: HTTP-клиент для взаимодействия с REST API сервера.

Основные функции:

• Аутентификация пользователей (POST /auth/login)
• Получение списка пользователей (GET /users)
• Получение сообщений (GET /messages)
• Отправка сообщений (POST /messages)
• Поиск пользователей (GET /users/search)
• Обновление статуса (PUT /users/status)

Особенности:

• Автоматическое управление JWT токенами (access/refresh)
• Автоматическое обновление токена при истечении (401/403)
• Безопасное хранение токенов в SecureStorage
• Повторная отправка запроса после обновления токена
• Настраиваемая конфигурация (BaseUrl, Timeout, Headers)

Используемые технологии:

• HttpClient для HTTP запросов
• SecureStorage для хранения токенов
• Newtonsoft.Json для сериализации/десериализации

2. WebSocketService - WebSocket клиент

Назначение: Real-time коммуникация через WebSocket.

Основные функции:

• Подключение к WebSocket серверу
• Отправка и получение сообщений в реальном времени
• Индикаторы набора текста ("печатает...")
• Обновление статусов пользователей (онлайн/оффлайн)
• Автоматическое переподключение при разрыве соединения

Особенности:

• Автоматический подбор рабочего WebSocket URL
• Поддержка WSS (WebSocket Secure)
• Передача Bearer токена при подключении
• Event-based архитектура для обработки сообщений

События:

• MessageReceived - получено новое сообщение
• UserStatusChanged - изменился статус пользователя
• TypingIndicatorReceived - пользователь печатает

Используемые технологии:

• System.Net.WebSockets.ClientWebSocket
• Newtonsoft.Json для работы с JSON

3. ServiceProvider - Singleton провайдер

Назначение: Централизованный доступ к сервисам приложения.

Преимущества:

• Единая точка доступа к ApiService и WebSocketService
• Гарантия единственного экземпляра сервисов
• Упрощение dependency injection

Использование:

var apiService = ServiceProvider.ApiService;
var wsService = ServiceProvider.WebSocketService;

🎯 Паттерны проектирования

Singleton

Используется для ServiceProvider, ApiService и WebSocketService для обеспечения единственного экземпляра в приложении.

Repository Pattern

ApiService действует как репозиторий для работы с данными сервера.

Observer Pattern

WebSocketService использует события (Events) для уведомления UI о новых сообщениях и изменениях статусов.

MVVM (Model-View-ViewModel)

Архитектура страниц следует паттерну MVVM:

• Model: классы в папке Models
• View: XAML файлы в папке Pages
• ViewModel: code-behind файлы (.xaml.cs)

🔧 Используемые технологии

Фреймворки

• .NET 9.0 - платформа разработки
• .NET MAUI - кроссплатформенный UI фреймворк

Библиотеки

• Newtonsoft.Json - JSON сериализация/десериализация
• System.Net.WebSockets - WebSocket клиент
• Microsoft.Maui.Essentials.SecureStorage - безопасное хранение данных

Языки и стандарты

• C# 12 - язык программирования
• XAML - разметка пользовательского интерфейса
• JSON - формат обмена данными
• JWT - токены аутентификации
• WebSocket Protocol - real-time коммуникация

🔐 Безопасность

Хранение токенов

• JWT токены (access/refresh) хранятся в SecureStorage
• SecureStorage использует платформенные механизмы шифрования:
  • Android: KeyStore
  • iOS: Keychain
  • Windows: Data Protection API

Коммуникация

• HTTPS для REST API (TLS/SSL)
• WSS для WebSocket (WebSocket Secure)
• Bearer Authentication для всех защищенных endpoints

Автоматический выход

• При истечении refresh токена пользователь перенаправляется на страницу входа
• Токены очищаются при выходе из системы

🎨 UI/UX архитектура

Навигация

• AppShell - основная навигационная структура
• FlyoutMenu - боковое меню
• TabBar - нижняя панель вкладок

Страницы

1. LoginPage - аутентификация
2. EmployeesPage - список сотрудников с поиском
3. ChatPage - личные сообщения
4. ProfilePage - профиль пользователя

UI особенности

• Material Design стиль
• Адаптивный дизайн для разных экранов
• Плавные анимации и переходы
• Индикаторы загрузки
• Pull-to-refresh для обновления данных
• User-friendly сообщения об ошибках

📱 Платформенная специфика

Android

• Минимальная версия: API 21 (Android 5.0)
• Target версия: API 34 (Android 14)
• Разрешения: INTERNET, ACCESS_NETWORK_STATE

iOS

• Минимальная версия: iOS 11.0
• Требуется Xcode и Mac для сборки
• Разрешения для фоновой работы

Windows

• Минимальная версия: Windows 10.0.19041.0
• UWP приложение

MacCatalyst

• Минимальная версия: macOS 10.15

🔄 Жизненный цикл приложения

1. Запуск (App.xaml.cs)

   • Инициализация сервисов
   • Проверка сохраненных токенов
   • Определение стартовой страницы (Login/Main)

2. Аутентификация (LoginPage)

   • Ввод учетных данных
   • Получение JWT токенов
   • Сохранение в SecureStorage
   • Подключение к WebSocket
   • Переход к главному экрану

3. Работа с данными

   • REST API для запросов данных
   • WebSocket для real-time обновлений
   • Автоматическое обновление токенов

4. Выход

   • Обновление статуса на "офлайн"
   • Отключение WebSocket
   • Очистка токенов
   • Возврат к LoginPage

---

Последнее обновление: 2026-01-12