86 lines
8.4 KiB
Markdown
86 lines
8.4 KiB
Markdown
# Системные паттерны Mastermind
|
||
|
||
Этот документ описывает нормативные паттерны взаимодействия подсистем Mastermind.
|
||
|
||
## 1. Capability-Oriented Clean Architecture
|
||
|
||
**Problem**: Высокая связность между захватом, хранилищем и UI мешает тестированию и безопасности.
|
||
**Rule**: Каждая функциональная область (Capability) инкапсулирована в отдельный модуль с чёткими границами. Взаимодействие происходит через порты (протоколы).
|
||
**Apply when**: При добавлении новой крупной функциональности (например, новый вид захвата).
|
||
**Avoid**: Прямой импорт конкретных реализаций (Adapters) между модулями.
|
||
**Trade-offs**: Требует больше кода для инициализации (Dependency Injection).
|
||
**Verification**: Запрещены перекрёстные импорты в Swift модулях; Unit-тесты используют Mock-реализации портов.
|
||
|
||
## 2. Ports & Async Events
|
||
|
||
**Problem**: Глобальные шины событий (EventBus) делают зависимости неявными и затрудняют отладку.
|
||
**Rule**: Запросы и команды идут через явные порты (Application Ports). Факты о произошедшем передаются через типизированные асинхронные потоки событий (Typed Async Events). Глобальная шина запрещена.
|
||
**Apply when**: Для межмодульного взаимодействия.
|
||
**Avoid**: Использование `NotificationCenter` или глобальных `ObservableObject`.
|
||
**Trade-offs**: Требует явной оркестрации в Composition Root.
|
||
**Verification**: Каждый исходящий поток событий должен быть частью интерфейса порта модуля.
|
||
|
||
## 3. Observation Ledger
|
||
|
||
**Problem**: Прямая запись результатов захвата в граф знаний приводит к потере контекста и невозможности переобработки данных.
|
||
**Rule**: Collectors записывают только неизменяемые "свидетельства" (Observations) в лог (Ledger). Только Knowledge Pipeline читает этот лог.
|
||
**Apply when**: При обработке любого потока данных из источников (Sources).
|
||
**Avoid**: Прямое обновление Facts или Entities из Collectors.
|
||
**Trade-offs**: Увеличивает объём хранимых данных на диске до момента очистки (Retention).
|
||
**Verification**: База данных содержит таблицу `Observations` с Provenance.
|
||
|
||
## 4. Idempotent Projectors & Durable Checkpoints
|
||
|
||
**Problem**: Сбой во время обработки Observations может привести к дублированию или потере знаний в графе.
|
||
**Rule**: Проекторы (Projectors) читают лог Observations и обновляют граф, сохраняя контрольные точки (Checkpoints). Процесс должен быть идемпотентным.
|
||
**Apply when**: При преобразовании сырых данных в Assertions и Facts.
|
||
**Avoid**: Логика проекции, зависящая от текущего времени или внешнего состояния вне лога.
|
||
**Trade-offs**: Усложняет логику обновления графа.
|
||
**Verification**: Перезапуск проектора с одного и того же чекпоинта должен приводить к идентичному состоянию графа.
|
||
|
||
## 5. Capability-Specific Persistence Ports
|
||
|
||
**Problem**: Общие репозитории (Generic Repository<T>) скрывают специфичные требования к данным и производительности.
|
||
**Rule**: Каждый модуль определяет свои узкие порты для работы с данными (например, `AppendObservation`, `QueryContext`). Реализация за скрытым SQLite/SQLCipher адаптером.
|
||
**Avoid**: Использование общего DAO или прямого доступа к БД вне адаптера.
|
||
**Verification**: Интерфейсы портов содержат только те методы, которые реально нужны данному модулю.
|
||
|
||
## 6. Central Egress Gate & Privacy Envelopes
|
||
|
||
**Problem**: Риск случайной отправки конфиденциальных данных (PII) в облако.
|
||
**Rule**: Весь исходящий трафик к внешним провайдерам проходит через единый Egress Gate. Данные передаются в типизированных конвертах (Privacy Envelopes) с метаданными о классификации.
|
||
**Apply when**: Любая передача данных за пределы Mac (Cloud Providers).
|
||
**Avoid**: Прямые сетевые запросы из Assistant или других модулей.
|
||
**Trade-offs**: Единая точка отказа и бутылочное горлышко производительности.
|
||
**Verification**: Egress Gate блокирует любые данные без явного Provider Context Permission.
|
||
|
||
## 7. Work Scheduler & Budgets
|
||
|
||
**Problem**: Непрерывный захват и ML-обработка могут замедлять UI или разряжать батарею.
|
||
**Rule**: Центральный планировщик распределяет задачи по приоритетам и бюджетам ресурсов. Аудио и интерактив всегда выше фоновой индексации.
|
||
**Avoid**: Запуск `Task.detached` без указания приоритета и лимитов.
|
||
**Trade-offs**: Может увеличивать задержку (latency) для фоновых задач.
|
||
**Verification**: Приложение снижает активность в Low Power Mode.
|
||
|
||
## 8. Bounded Derived Caches
|
||
|
||
**Problem**: Кэширование может приводить к несогласованности данных и утечкам памяти.
|
||
**Rule**: Все кэши ограничены (bounded), принадлежат конкретным акторам (actor-owned) и могут быть полностью перестроены из Context Store.
|
||
**Apply when**: Для OCR, embeddings и UI элементов.
|
||
**Avoid**: Использование глобального `NSCache` без ограничений по времени и размеру.
|
||
**Verification**: Unit-тесты проверяют очистку кэша при достижении лимитов.
|
||
|
||
## 9. Structured Local Tracing
|
||
|
||
**Problem**: Текстовые логи бесполезны для отладки сложных распределённых процессов без передачи контента.
|
||
**Rule**: Использование структурированных спанов и событий с Correlation IDs (SourceID, ObservationID). Redacted metadata — только технические детали.
|
||
**Avoid**: Логирование распознанного текста или аудио-транскриптов.
|
||
**Verification**: Логи не содержат персональных данных пользователя, но позволяют проследить путь конкретной Observation.
|
||
|
||
## 10. Versioned Boundaries
|
||
|
||
**Problem**: Изменение формата данных (ASR, LLM, Export) ломает совместимость.
|
||
**Rule**: Все границы (Sidecars, Providers, Archives) используют типизированные DTO с версионированием и Contract Tests. Tolerant Reader обязателен.
|
||
**Avoid**: Сериализация внутренних доменных типов напрямую.
|
||
**Verification**: Наличие тестов на обратную совместимость схем.
|