Перевод на доменную архитектуру

2026-04-26 23:37:50 +09:00
parent 75ca01ffd8
commit f107ebd167
70 changed files with 4656 additions and 2070 deletions
--- a/docs/report-domain-migration-handoff.md
+++ b/docs/report-domain-migration-handoff.md
@@ -0,0 +1,170 @@
+# Handoff: миграция отчётов на Domain-архитектуру
+
+Дата: 2026-04-26
+
+## Что уже сделано
+
+### 1. Базовый каркас Domain / Application / Infrastructure
+Добавлены новые слои:
+
+- `app/Domain/Reports`
+- `app/Application/Reports`
+- `app/Infrastructure/Reports`
+
+Ключевые элементы:
+
+- `Domain/Reports/ValueObjects/MetrikaConfig`
+- `Domain/Reports/Models/ReportSnapshot`
+- `Domain/Reports/Contracts/*`
+- `Application/Reports/DTO/*`
+- `Application/Reports/GenerateReportUseCase`
+- `Application/Reports/CompareLegacyAndNewReportUseCase`
+- `Infrastructure/Reports/Repositories/EloquentReportRepository`
+- `Infrastructure/Reports/Adapters/LegacyReportServiceAdapter`
+- `Infrastructure/Reports/Logging/ReportsAuditLogger`
+
+### 2. Save-path уже переведён на strangler-схему
+Новый save-flow работает рядом со старым кодом:
+
+- старый `ReportService` не удалён
+- новый путь включается через feature-flag
+- legacy остаётся fallback
+- сравнение old/new идёт через comparator и audit logger
+
+Точки входа уже знают про новый flow:
+
+- `app/Http/Controllers/Web/ReportController.php`
+- `app/Http/Controllers/Api/ReportController.php`
+- `app/Services/AutoReportService.php`
+
+### 3. Вынесена существенная часть persistence и orchestration
+Из `ReportService` уже выделены:
+
+- `Infrastructure/Reports/Services/ReportStorageService`
+- `Infrastructure/Reports/Services/ReportMetricsFinalizer`
+- `Infrastructure/Reports/Services/CalculatedMetricsSynchronizer`
+- `Infrastructure/Reports/Services/SnapshotPersistenceService`
+- `Infrastructure/Reports/Services/AutoFillReportPayloadBuilder`
+
+### 4. Вынесены источники данных
+Сейчас выделены отдельные источники:
+
+- `Infrastructure/Reports/Sources/MisPatientSource`
+- `Infrastructure/Reports/Sources/SpecialPatientSource`
+- `Infrastructure/Reports/Sources/SnapshotPatientSource`
+- `Infrastructure/Reports/Sources/MisClinicalDataSource`
+- `Infrastructure/Reports/Sources/LegacyAutoFillPatientSource`
+
+### 5. Вынесены Domain-calculators
+Сейчас в Domain уже есть:
+
+- `BedDaysCalculator`
+- `PreoperativeDaysCalculator`
+- `DepartmentLoadCalculator`
+
+### 6. Read-path пациентов тоже вынесен
+Добавлены:
+
+- `Infrastructure/Reports/Services/ReportPatientsReadService`
+- `Infrastructure/Reports/Services/ReportReadContextResolver`
+
+Теперь `ReportService` уже делегирует туда:
+
+- `getPatientsByStatus`
+- `getPatientsCountByStatus`
+- `getPatientsCountsMap`
+- `getPatientsFromSnapshots`
+
+Это важный шаг: `ReportService` постепенно становится legacy facade, а не местом, где живёт вся логика.
+
+## Что ещё специально НЕ сделано
+
+- старый код не удалён
+- полный cutover на новую архитектуру не выполнен
+- `getReportStatistics` пока ещё остаётся внутри `ReportService`
+- часть legacy read/statistics логики ещё не вынесена в отдельный infrastructure/application слой
+- integration tests на SQLite здесь не гонялись, потому что в окружении нет `pdo_sqlite`
+
+## Проверки и тесты
+
+Проходит:
+
+```bash
+php artisan test tests/Unit/Reports
+```
+
+Сейчас зелёные unit-тесты для:
+
+- `MetrikaConfig`
+- `ReportSnapshot`
+- `GenerateReportUseCase`
+- `CompareLegacyAndNewReportUseCase`
+- `ReportInputFactory`
+- `ReportPatientsReadService`
+- domain calculators
+
+## Важный контекст по БД и тестам
+
+Основное приложение работает с `pgsql` из `.env`, но тесты не обязаны использовать это окружение.
+
+Важно:
+
+- в `phpunit.xml` тестовый runtime жёстко переключён на `sqlite`
+- в текущем окружении отсутствует `pdo_sqlite`
+- поэтому feature/integration тесты здесь не были полноценно прогнаны
+
+Если завтра нужно будет запускать integration-тесты на PostgreSQL, надо отдельно переводить test-конфиг.
+
+## Дополнительные важные замечания
+
+### 1. В worktree есть изменённые файлы
+Нужно быть осторожным и не перетирать чужие правки.
+
+Особенно внимательно смотреть на:
+
+- `app/Http/Controllers/Api/ReportController.php`
+- `app/Services/ReportService.php`
+- `app/Services/Reports/PatientQueryBuilder.php`
+
+### 2. Есть защитный фикс в конфиге Excel
+Ранее был добавлен безопасный guard в `config/excel.php`, чтобы bootstrap не падал, если в окружении нет нужных excel-классов.
+
+### 3. Комментарии в новом слое частично русифицированы
+Русифицированы PHPDoc в основных новых infrastructure/application классах миграции.
+При желании можно отдельным проходом довести до конца все новые DTO, адаптеры и domain models.
+
+## Самый логичный следующий шаг
+
+Следующая итерация:
+
+1. Вынести `getReportStatistics` из `ReportService` в отдельный read-service.
+2. Затем вынести snapshot/replica statistics orchestration в новый infrastructure/application слой.
+3. После этого ещё сильнее сузить `ReportService` до legacy facade.
+
+Рекомендуемое направление:
+
+- создать что-то вроде `Infrastructure/Reports/Services/ReportStatisticsReadService`
+- перевести туда:
+  - `getStatisticsFromSnapshots`
+  - `getStatisticsFromReplica`
+  - вспомогательные read-context части, если они ещё не покрыты `ReportReadContextResolver`
+
+## Если нужно быстро продолжить завтра
+
+Сначала открыть:
+
+- `docs/report-domain-migration-handoff.md`
+- `app/Services/ReportService.php`
+- `app/Infrastructure/Reports/Services/ReportPatientsReadService.php`
+- `app/Infrastructure/Reports/Services/ReportReadContextResolver.php`
+
+Потом проверить:
+
+```bash
+php artisan test tests/Unit/Reports
+```
+
+И дальше брать следующий шаг:
+
+- перенос `getReportStatistics` в отдельный сервис
+