refactor: использовать Expression<Func<Project, DateTime, bool>> в KogdaIgraMissingGamesPredicate

github-actions[bot] · leotsarev · github-actions[bot] · commit 1b4320c05f53 · 2026-04-07T10:23:06.000Z
- GetPredicate() возвращает Expression для трансляции в SQL через LinqKit
- DisableKogdaIgraMapping и Active перенесены внутрь предиката
- ProjectRepository.GetKogdaIgraMissingGames использует predicate.Invoke()
- Тесты обновлены: создают Project-объекты и вызывают GetPredicate().Compile()()
- Добавлены тесты на DisableKogdaIgraMapping=true и Active=false
- Создан docs/linq-queries.md с документацией по LinqKit-паттерну
- CLAUDE.md обновлён со ссылкой на docs/linq-queries.md

Co-authored-by: Leonid Tsarev &lt;leotsarev@users.noreply.github.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -64,6 +64,11 @@ dotnet test src/JoinRpg.Domain.Test              # Конкретный тест
 
 При создании новых классов или проектов — читать [docs/structure.md](docs/structure.md).
 
+### LINQ-запросы и LinqKit
+
+EF-предикаты и проекции пишутся через `Expression<Func<...>>` + LinqKit.
+Подробнее — [docs/linq-queries.md](docs/linq-queries.md).
+
 ### Blazor WebAssembly (islands, ADR001)
 
 Небольшие интерактивные виджеты Blazor встраиваются в Razor-страницы.
@@ -83,6 +88,10 @@ dotnet test src/JoinRpg.Domain.Test              # Конкретный тест
 
 Для понимания кода предпочитай **cwm-roslyn-navigator** (MCP) перед чтением файлов. Roslyn понимает семантику C#: типы, иерархии наследования, реальные использования символов. Используй `find_symbol`, `find_references`, `find_callers`, `find_implementations`, `get_type_hierarchy` и другие инструменты навигатора для навигации по коду. Чтение файлов — только когда нужен полный контекст, которого навигатор не даёт.
 
+## Фикс багов
+
+При исправлении бага **всегда рассматривать добавление юнит теста**, который воспроизводит баг до фикса и проходит после. Это предотвращает регрессии. Тест добавляется в соответствующий тестовый проект.
+
 ## Правила кода
 
 - **Без regex** — по возможности избегать регулярных выражений.
diff --git a/docs/linq-queries.md b/docs/linq-queries.md
@@ -0,0 +1,81 @@
+# LINQ-запросы и LinqKit
+
+## Зачем LinqKit
+
+Entity Framework транслирует LINQ-выражения (`Expression<Func<...>>`) в SQL.
+Обычные методы C# (`Func<...>`) — **не транслируются**: они выполняются в памяти после загрузки всех данных.
+
+LinqKit позволяет **переиспользовать** Expression-предикаты и проекции в EF-запросах:
+- `AsExpandable()` — расширяет `IQueryable` для поддержки `Invoke`
+- `.Invoke(args...)` — вызывает Expression внутри другого Expression; LinqKit встраивает тело предиката в запрос
+
+## Шаблон использования
+
+### 1. Определить предикат как Expression
+
+```csharp
+internal static class MyPredicate
+{
+    public static Expression<Func<MyEntity, bool>> GetPredicate(DateTime now)
+    {
+        return entity => entity.Active && entity.EndDate >= now;
+    }
+}
+```
+
+Если нужно передать несколько параметров (например, сущность + вычисленное значение из join):
+
+```csharp
+public static Expression<Func<Project, DateTime, bool>> GetPredicate(DateTime now)
+{
+    var threshold = now.AddDays(-60);
+    return (project, lastUpdated) =>
+        project.Active && lastUpdated > threshold;
+}
+```
+
+### 2. Использовать предикат в EF-запросе
+
+```csharp
+// Обязательно: AsExpandable() на IQueryable
+private IQueryable<Project> AllProjects => Ctx.ProjectsSet.AsExpandable();
+
+private async Task<List<MyDto>> GetFiltered()
+{
+    var predicate = MyPredicate.GetPredicate(DateTime.Now);
+
+    var query = from project in AllProjects
+                join update in GetLastUpdateQuery() on project.ProjectId equals update.ProjectId
+                where predicate.Invoke(project, update.LastUpdated)  // Invoke = встраивание в SQL
+                select new MyDto { ... };
+
+    return await query.ToListAsync();
+}
+```
+
+### 3. Тестировать предикат напрямую
+
+```csharp
+[Fact]
+public void ActiveProject_ShouldMatch()
+{
+    var project = new Project { Active = true, ... };
+    var result = MyPredicate.GetPredicate(Now).Compile()(project, RecentlyUpdated);
+    result.ShouldBeTrue();
+}
+```
+
+`.Compile()` превращает Expression в обычный делегат для выполнения в тестах (без EF).
+
+## Правила
+
+- Все предикаты и проекции для EF-запросов — только `Expression<Func<...>>`, **не** `Func<...>`
+- Если метод возвращает `bool` (не Expression) — он выполняется **в памяти**, EF его не видит
+- `AsExpandable()` ставится один раз на `IQueryable` (обычно в свойстве репозитория)
+- LinqKit подключён в `JoinRpg.Dal.Impl` как `LinqKit.EntityFramework`
+
+## Примеры в коде
+
+- `KogdaIgraMissingGamesPredicate` — предикат с двумя параметрами (Project + DateTime)
+- `ProjectPredicates`, `ClaimPredicates`, `CharacterPredicates` — предикаты по сущностям
+- `ProjectRepository.GetLastUpdateQuery` — проекция с `Expression<Func<T, DateTime>>`
diff --git a/src/JoinRpg.Dal.Impl/Repositories/KogdaIgraMissingGamesPredicate.cs b/src/JoinRpg.Dal.Impl/Repositories/KogdaIgraMissingGamesPredicate.cs
@@ -1,23 +1,24 @@
-using JoinRpg.DataModel.Projects;
-
 namespace JoinRpg.Dal.Impl.Repositories;
 
 internal static class KogdaIgraMissingGamesPredicate
 {
     /// <summary>
-    /// Определяет, нуждается ли проект в привязке к КогдаИгра.
+    /// Возвращает Expression-предикат для фильтрации проектов, нуждающихся в привязке к КогдаИгра.
+    /// Используется с LinqKit (.AsExpandable() + .Invoke()) для трансляции запроса в SQL.
+    /// См. docs/linq-queries.md
+    ///
     /// Проект попадает в выборку если:
-    /// 1. Нет активных КИ-привязок вообще, ИЛИ
-    /// 2. Все привязанные КИ-игры уже завершились (End &lt; now) И проект недавно обновлялся (&lt;60 дней)
+    /// 1. Проект активен и не отключена привязка к КогдаИгра
+    /// 2. Нет активных КИ-привязок вообще, ИЛИ
+    ///    все привязанные КИ-игры уже завершились (End &lt; now) И проект недавно обновлялся (&lt;60 дней)
     /// </summary>
-    public static bool NeedsBinding(
-        IEnumerable<KogdaIgraGame> games,
-        DateTime lastUpdated,
-        DateTime now)
+    public static Expression<Func<Project, DateTime, bool>> GetPredicate(DateTime now)
     {
         var lastUpdateMax = now.AddDays(-60);
-        var hasActiveOrFutureGame = games.Any(g => g.Active && g.End >= now);
-        var hasAnyGame = games.Any(g => g.Active);
-        return !hasActiveOrFutureGame && (!hasAnyGame || lastUpdated > lastUpdateMax);
+        return (project, lastUpdated) =>
+            project.Active &&
+            !project.Details.DisableKogdaIgraMapping &&
+            !project.KogdaIgraGames.Any(g => g.Active && g.End >= now) &&
+            (!project.KogdaIgraGames.Any(g => g.Active) || lastUpdated > lastUpdateMax);
     }
 }
diff --git a/src/JoinRpg.Dal.Impl/Repositories/ProjectRepository.cs b/src/JoinRpg.Dal.Impl/Repositories/ProjectRepository.cs
@@ -233,17 +233,11 @@ async Task<ProjectShortInfo[]> IProjectRepository.GetProjectsBySpecification(Pro
     private async Task<ProjectShortInfo[]> GetKogdaIgraMissingGames()
     {
         var projection = GetProjectListProjection();
-
-        var now = DateTime.Now;
-        var lastUpdateMax = now.AddDays(-60);
+        var predicate = KogdaIgraMissingGamesPredicate.GetPredicate(DateTime.Now);
 
         var query = from project in AllProjects
                     join update in GetProjectWithLastUpdateQuery() on project.ProjectId equals update.ProjectId
-                    where project.Active && !project.Details.DisableKogdaIgraMapping
-                    let hasActiveOrFutureGame = project.KogdaIgraGames.Any(g => g.Active && g.End >= now)
-                    let hasAnyGame = project.KogdaIgraGames.Any(g => g.Active)
-                    where !hasActiveOrFutureGame
-                    where !hasAnyGame || update.LastUpdated > lastUpdateMax
+                    where predicate.Invoke(project, update.LastUpdated)
                     select projection.Invoke(project, update);
 
         var result = await query.ToListAsync();
diff --git a/src/JoinRpg.DataModel.Mocks/KogdaIgraMissingGamesPredicateTest.cs b/src/JoinRpg.DataModel.Mocks/KogdaIgraMissingGamesPredicateTest.cs
@@ -35,119 +35,128 @@ public class KogdaIgraMissingGamesPredicateTest
         Name = "Inactive Game",
     };
 
+    private static Project CreateProject(
+        IEnumerable<KogdaIgraGame>? games = null,
+        bool active = true,
+        bool disableKogdaIgraMapping = false) => new()
+        {
+            Active = active,
+            Details = new ProjectDetails { DisableKogdaIgraMapping = disableKogdaIgraMapping },
+            KogdaIgraGames = [.. (games ?? [])],
+        };
+
+    private static bool TestPredicate(Project project, DateTime lastUpdated)
+        => KogdaIgraMissingGamesPredicate.GetPredicate(Now).Compile()(project, lastUpdated);
+
     // --- Нет привязок ---
 
     [Fact]
     public void NoGames_RecentlyUpdated_ShouldNeedBinding()
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([], RecentlyUpdated, Now)
-            .ShouldBeTrue();
+        => TestPredicate(CreateProject(), RecentlyUpdated).ShouldBeTrue();
 
     [Fact]
     public void NoGames_StaleProject_ShouldNeedBinding()
         // Даже устаревший проект без привязки — кандидат (нужна привязка)
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([], StaleUpdated, Now)
-            .ShouldBeTrue();
+        => TestPredicate(CreateProject(), StaleUpdated).ShouldBeTrue();
 
     // --- Будущие игры (ещё не прошли) ---
 
     [Fact]
     public void FutureGame_RecentlyUpdated_ShouldNotNeedBinding()
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([GameEndingIn(30)], RecentlyUpdated, Now)
-            .ShouldBeFalse();
+        => TestPredicate(CreateProject([GameEndingIn(30)]), RecentlyUpdated).ShouldBeFalse();
 
     [Fact]
     public void FutureGame_StaleProject_ShouldNotNeedBinding()
         // Привязан к будущей игре — не нужна новая привязка
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([GameEndingIn(30)], StaleUpdated, Now)
-            .ShouldBeFalse();
+        => TestPredicate(CreateProject([GameEndingIn(30)]), StaleUpdated).ShouldBeFalse();
 
     [Fact]
     public void GameEndingToday_ShouldNotNeedBinding()
         // End == Now: граница, игра «ещё не закончилась»
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([GameEndingIn(0)], RecentlyUpdated, Now)
-            .ShouldBeFalse();
+        => TestPredicate(CreateProject([GameEndingIn(0)]), RecentlyUpdated).ShouldBeFalse();
 
     // --- Прошедшие игры ---
 
     [Fact]
     public void PastGame_RecentlyUpdated_ShouldNeedBinding()
         // Сериал: игра прошла, проект активен → надо привязать следующую
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([GameEndingIn(-1)], RecentlyUpdated, Now)
-            .ShouldBeTrue();
+        => TestPredicate(CreateProject([GameEndingIn(-1)]), RecentlyUpdated).ShouldBeTrue();
 
     [Fact]
     public void PastGame_StaleProject_ShouldNotNeedBinding()
         // Игра прошла, проект неактивен — не показывать в выборке
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([GameEndingIn(-1)], StaleUpdated, Now)
-            .ShouldBeFalse();
+        => TestPredicate(CreateProject([GameEndingIn(-1)]), StaleUpdated).ShouldBeFalse();
 
     [Fact]
     public void PastGame_UpdatedExactlyAtBoundary_ShouldNotNeedBinding()
     {
         // Граница: обновлено ровно 60 дней назад — не попадает в выборку
         var updatedAt60DaysAgo = Now.AddDays(-60);
-        KogdaIgraMissingGamesPredicate.NeedsBinding([GameEndingIn(-1)], updatedAt60DaysAgo, Now)
-            .ShouldBeFalse();
+        TestPredicate(CreateProject([GameEndingIn(-1)]), updatedAt60DaysAgo).ShouldBeFalse();
     }
 
     [Fact]
     public void PastGame_UpdatedJustUnderBoundary_ShouldNeedBinding()
     {
         // Граница: обновлено 59 дней назад — попадает в выборку
         var updatedAt59DaysAgo = Now.AddDays(-59);
-        KogdaIgraMissingGamesPredicate.NeedsBinding([GameEndingIn(-1)], updatedAt59DaysAgo, Now)
-            .ShouldBeTrue();
+        TestPredicate(CreateProject([GameEndingIn(-1)]), updatedAt59DaysAgo).ShouldBeTrue();
     }
 
     // --- Неактивные привязки ---
 
     [Fact]
     public void OnlyInactiveGame_RecentlyUpdated_ShouldNeedBinding()
         // Привязка помечена как неактивная — игнорируется, как нет привязки
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([InactiveGame(30)], RecentlyUpdated, Now)
-            .ShouldBeTrue();
+        => TestPredicate(CreateProject([InactiveGame(30)]), RecentlyUpdated).ShouldBeTrue();
 
     [Fact]
     public void OnlyInactiveGame_StaleProject_ShouldNeedBinding()
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([InactiveGame(30)], StaleUpdated, Now)
-            .ShouldBeTrue();
+        => TestPredicate(CreateProject([InactiveGame(30)]), StaleUpdated).ShouldBeTrue();
 
     // --- Несколько игр (сериал) ---
 
     [Fact]
     public void MixedGames_OnePastOneFuture_ShouldNotNeedBinding()
         // Есть и прошедшая и будущая игра — привязан, не нуждается
-        => KogdaIgraMissingGamesPredicate.NeedsBinding(
-            [GameEndingIn(-30), GameEndingIn(30)],
-            RecentlyUpdated, Now)
-            .ShouldBeFalse();
+        => TestPredicate(CreateProject([GameEndingIn(-30), GameEndingIn(30)]), RecentlyUpdated).ShouldBeFalse();
 
     [Fact]
     public void MultiplePastGames_RecentlyUpdated_ShouldNeedBinding()
         // Все игры прошли, проект активен → нужна новая привязка
-        => KogdaIgraMissingGamesPredicate.NeedsBinding(
-            [GameEndingIn(-60), GameEndingIn(-30), GameEndingIn(-1)],
-            RecentlyUpdated, Now)
-            .ShouldBeTrue();
+        => TestPredicate(
+            CreateProject([GameEndingIn(-60), GameEndingIn(-30), GameEndingIn(-1)]),
+            RecentlyUpdated).ShouldBeTrue();
 
     [Fact]
     public void MultiplePastGames_StaleProject_ShouldNotNeedBinding()
-        => KogdaIgraMissingGamesPredicate.NeedsBinding(
-            [GameEndingIn(-60), GameEndingIn(-30), GameEndingIn(-1)],
-            StaleUpdated, Now)
-            .ShouldBeFalse();
+        => TestPredicate(
+            CreateProject([GameEndingIn(-60), GameEndingIn(-30), GameEndingIn(-1)]),
+            StaleUpdated).ShouldBeFalse();
 
     // --- Граничный случай: End = null ---
 
     [Fact]
     public void GameWithNullEnd_RecentlyUpdated_ShouldNeedBinding()
         // Игра без даты окончания: End=null → null >= now = false → hasActiveOrFutureGame=false
         // Но hasAnyGame=true, поэтому проверяется активность проекта
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([GameWithNullEnd()], RecentlyUpdated, Now)
-            .ShouldBeTrue();
+        => TestPredicate(CreateProject([GameWithNullEnd()]), RecentlyUpdated).ShouldBeTrue();
 
     [Fact]
     public void GameWithNullEnd_StaleProject_ShouldNotNeedBinding()
-        => KogdaIgraMissingGamesPredicate.NeedsBinding([GameWithNullEnd()], StaleUpdated, Now)
-            .ShouldBeFalse();
+        => TestPredicate(CreateProject([GameWithNullEnd()]), StaleUpdated).ShouldBeFalse();
+
+    // --- Проект с DisableKogdaIgraMapping ---
+
+    [Fact]
+    public void DisableKogdaIgraMapping_ShouldNotNeedBinding()
+        // Проект с отключённой привязкой к КогдаИгра — не попадает в выборку
+        => TestPredicate(CreateProject(disableKogdaIgraMapping: true), RecentlyUpdated).ShouldBeFalse();
+
+    // --- Неактивный проект ---
+
+    [Fact]
+    public void InactiveProject_ShouldNotNeedBinding()
+        // Неактивный проект — не попадает в выборку
+        => TestPredicate(CreateProject(active: false), RecentlyUpdated).ShouldBeFalse();
 }
