Восстановить docs/ как зеркало для агентов (ревью МР #11)

Ревью rust: перенос в вики не должен удалять из репозитория то, что нужно агенту для работы (бэклог, статус, планы, код-стайл, спеки). Дублирование вики и репы разрешено и обязательно: вики — актуальные версии для людей, docs/ — зеркало для контекста агентов. README разведён по ролям.
2026-09-13 00:03:43 +03:00
parent 3a26f8d4a5
commit 45065d3202
36 changed files with 10373 additions and 1 deletions
@@ -0,0 +1,53 @@
+# Дизайн: разбиение проектов на логические папки (namespace = папка)
+
+Дата: 2026-09-11. Статус: согласовано владельцем (решения 1–5).
+
+## 1. Цель
+
+Упорядочить код по назначению: вместо «свалки» файлов разных видов в одной папке с единым
+`namespace` — подпапки по назначению, при этом `namespace` соответствует пути папки.
+
+## 2. Таксономия папок (по назначению)
+
+| Папка | Что кладём |
+| --- | --- |
+| `Abstractions/` | интерфейсы `I*.cs` |
+| `Services/` | прикладная логика: `*Service`, `*WorkerService.*`, `*Guard`, `*Pacer`, `*Evaluator`, `*Counter`, `*Detector`, `*Normalizer`, `*Matcher`, `*Composer`, `*Cleaner`, `*Classifier`, `*Mapper`, `*Builder`, `*Writer`, `*Recomputer`, `*Suggester`, `*Filler`, `*Generator`, `*Hasher` и аналогичные исполнители |
+| `Models/` | доменные типы: сущности, value-объекты, enum, статусы/виды, константные реестры (`*Statuses`, `*Kinds`, `*Prefixes`, `*Keys`, `*Events`, `*Periods`, `*Sources`, `*Field`, `*Defaults`) |
+| `Dtos/` | транспортные типы: `*Dto`, `*Request`, `*Response`, `*Patch` |
+| `Extensions/` | `*Extensions` |
+| `Options/` | `*Options` |
+| `Exceptions/` | `*Exception` |
+| `Registrars/` | `*ModuleRegistrar` |
+
+Существующие feature-папки (`ColumnRules`, `Parse`, существующие `Models`) сохраняются.
+
+## 3. Правила
+
+1. `namespace` строго соответствует пути папки.
+2. Имена типов и публичные контракты не меняются — только расположение и `namespace`.
+3. Один тип = один файл (уже соблюдается).
+4. Частичные классы (`Foo.cs`, `Foo.Part.cs`) переносятся вместе.
+5. Тестовые проекты группируются по областям: `Modules/<X>`, `Api`, `Infrastructure` и т.п.,
+   `namespace` = `Deal.Tests.Unit.<Область>`.
+
+## 4. Механика переноса (на проект)
+
+1. Классифицировать файлы по таблице §2.
+2. Перенести файлы в подпапки и заменить `namespace`.
+3. Миграция `using`: в файлах-потребителях заменить несуществующий старый `using <OldNs>;` на
+   `using` всех новых подпространств (пере-добавление безопасно; при коллизии имён — ручное разрешение).
+   Файлы внутри проекта-источника получают `using` соседних подпространств.
+4. `dotnet build` → исправить остатки (полные имена, `cref`), `dotnet test`.
+5. Отдельный коммит (русский) после каждого проекта.
+
+## 5. Порядок
+
+Пилот — `Deal.Modules.Cards` (чистый домен). Далее: остальные `Deal.Modules.*`, затем
+`Deal.Infrastructure`, `Deal.Api`, `Deal.Contracts`/`Deal.SharedKernel`, сервисы `telegram/ai/ml`,
+затем тестовые проекты. После каждого шага — сборка + тесты + коммит.
+
+## 6. Риски
+
+- Коллизия простых имён при пере-добавлении `using` → разрешается вручную по ошибкам сборки.
+- Не забыть `cref`/полные имена в XML-док и `nameof` — выявляются сборкой.