docs: handoff переписан под новую веху — сборки и 2D-чертёж (точки входа API7, инкременты, процесс)

docs/superpowers/NEXT-SESSION.md

@@ -8,96 +8,117 @@
 с коммитами и пушами в `main`; используй Codex для ревью каждой реализованной фичи.
 КОМПАС-3D должен быть запущен (нужен для интеграционных тестов).
 
+**Фокус этой сессии — два новых крупных класса: СБОРКИ и 2D-ЧЕРТЁЖ.** До сих пор сделана
+только геометрия ДЕТАЛИ (она близка к насыщению). Сборки и чертёж — самый ценный
+нереализованный функционал. Начни со СБОРОК (тестируются объёмом/габаритом/числом компонентов),
+затем ЧЕРТЁЖ.
+
 ## Текущее состояние (main, синхронизирован с origin)
-- 70 MCP-инструментов, 119 тестов зелёных (69 unit + 50 integration).
-- Пакет A «богаче эскизы» — готов (дуга×2, эллипс, ломаная, многоугольник, сплайн, точка).
-- Пакет B «формообразующие» — основная часть готова: shell, rib, sweep, loft.
-- Пакет C «массивы и зеркало» — ГОТОВ: `linear_pattern`, `circular_pattern`,
-  `mirror_operation`, `mirror_body`. Источник копирования — id операций из реестра `_features`
-  (хелпер `RequireFeature`); оси — `CoordinateAxis`/`CoordinateAxes` (`Core/Modeling`).
-- `hole` — отверстия ГОТОВЫ (через **API7**, в API5 определения нет): `HoleService`
-  (`Core/Modeling/HoleService.cs`). Все типы: простое (`hole`), цековка (`hole_counterbore`,
-  `ksHTCounterbore`), зенковка (`hole_countersink`, `ksHTCountersinking`), коническое
-  (`hole_conic`, `ksHTConic`). `HoleCore` рефакторен под `configure`-колбэк (`HoleParameters`
-  после `HoleType`). Прецедент: первая формообразующая на API7. Направление в тело — по убыли
-  объёма. Ещё не сделано: резьба (`ShowThread`/`IThread`) — трудно тестировать (нет Δобъёма).
-- `draft` — уклон граней ГОТОВ (через **API5** `ksInclineDefinition`/`o3d_incline=42` — операция
-  «Incline», не «Draft»; стандартный паттерн `PartModeler.Features.cs`, регистрируется в `_features`).
-  Эмпирика: `direction=false`=расширение, `true`=сужение → маппинг `!outward`.
-- Пакет D «параметрика» НАЧАТ: переменные модели — `create_variable`, `set_variable`,
-  `delete_variable` (`VariableService`, API5 `ksVariable`). Создание на коллекции корневого
-  `ksFeature` (СВОЙСТВО `VariableCollection`); `Expression` ведущее; `RebuildModel`+re-fetch.
-  `list_variables` починен (видит все переменные). ОГРАНИЧЕНИЕ: переменные драйвят геометрию лишь
-  в параметрических эскизах (у нас эскизы на литералах — пока не драйвят).
-- Пакет E начат: смещённая плоскость (`sketch_create_on_offset_plane`).
-- `PartModeler` разбит на partial: `PartModeler.cs` (ядро + helpers `SelectFaceByIndex`/
-  `SelectEdgeByIndex` + `RequireFeature` + `NewParam<T>`), `.Sketch.cs` (эскизы/примитивы),
-  `.Features.cs` (операции, включая массивы/зеркало/уклон). API7-сервисы: `HoleService`, `FaceEditService`.
-- Чистые маппинги/валидация — в `SketchGeometry` (Core/Modeling); тип точки — `SketchPoint` (Host).
-- Прочитай память: `kompas-formative-features-api5` (definition в API5; draft=Incline есть),
-  `kompas-pattern-mirror-api5` (пакет C), `kompas-hole-api7` (hole + цековка/зенковка),
-  `kompas-variables-api5` (переменные), `kompas-parametric-sketch-findings` (тупик — не повторять).
+- 70 MCP-инструментов, 119 тестов зелёных (69 unit + 50 integration). Только ДЕТАЛЬ (`ksDocumentPart`).
+- Деталь: эскизы (пакет A), формообразующие (extrude/revolve/fillet/chamfer/shell/rib/sweep/loft),
+  массивы и зеркало (пакет C), уклон (`draft`), все типы отверстий (`hole`/`_counterbore`/
+  `_countersink`/`_conic`, API7), переменные (`create/set/delete_variable`), STEP import/export,
+  прямое редактирование B-rep (`move_face`/`split_solid_by_plane`/`move_body`/`boolean_union`),
+  структурный осмотр (`describe_model`/`list_*`/`measure`).
+- **`list_components` УЖЕ ЕСТЬ** (читает сборку: `IKompasDocument3D.TopPart → IPart7.Parts (IParts7)`).
+- Документы: `DocumentService` уже умеет создавать `Assembly` и `Drawing`
+  (`KompasDocumentType.Assembly/Drawing` → `DocumentTypeEnum.ksDocumentAssembly/ksDocumentDrawing`).
+  Есть `document_save_as` (сохранить деталь в файл — нужно, чтобы вставить её в сборку/на чертёж).
+- API7-сервисы существуют как образец: `HoleService`, `FaceEditService` (паттерн: `(IXxx)part`
+  через COM-QI, операции на STA-потоке `KompasDispatcher`).
+- Прочитай память: `kompas-step-and-assembly-api` (обход сборки, извлечение компонента, STEP),
+  `kompas-hole-api7` (паттерн API7-сервиса), `kompas-parametric-sketch-findings` (тупик — не повторять).
 
 ## ОТРИЦАТЕЛЬНЫЙ результат (не повторять)
-- **Параметрические эскизы (переменная двигает геометрию) — НЕДОСТИЖИМЫ через доступный COM-API.**
-  Решающий spike: `ksCDimWithVariable` (`IDrawingObject1.NewConstraint`) `Create()`=FALSE из внешней
-  автоматизации; `ksCFixedLenght` строится, но игнорирует `Expression` со ссылкой на переменную.
-  Полная разведка: `docs/superpowers/specs/2026-05-27-parametric-sketch-findings.md`. Параметрика
-  ограничена CRUD переменных (готово). НЕ тратить время на этот путь повторно.
+- **Параметрические эскизы (переменная двигает геометрию) — НЕДОСТИЖИМЫ через COM-API.**
+  `ksCDimWithVariable` (`IDrawingObject1.NewConstraint`) `Create()`=FALSE из внешней автоматизации;
+  `ksCFixedLenght` игнорирует `Expression`-ссылку на переменную. См.
+  `docs/superpowers/specs/2026-05-27-parametric-sketch-findings.md`. НЕ трогать повторно.
 
-## Задача следующей сессии (по приоритету)
-1. Расширения пакета C: **2D-сетка линейного массива** (2-я ось у `ksMeshCopyDefinition` —
-   `SetAxis2`+`count2`), выбор оси массива/нейтральной плоскости по ребру/грани, массив вдоль
-   кривой (`o3d_curveCopy=37`/`ksCurveCopyDefinition`). Низкий риск (паттерн пакета C известен).
-2. Расширения draft: уклон от ребра (`IDraftFromEdges`, API7); нейтральная плоскость по грани.
-3. **2D-чертёж** / **сборки** — крупные отдельные вехи (ассоциативные виды детали; вставка
-   компонентов, сопряжения). Самый ценный нереализованный класс после геометрии детали.
-4. Резьба отверстия (`ShowThread`/`IThread`) — мелочь, трудно тестировать.
+## Веха 1 — СБОРКИ (начать отсюда; новый `AssemblyService` на API7)
 
-Типы отверстий завершены (простое/цековка/зенковка/коническое). Параметрика — CRUD переменных
-(управление геометрией недостижимо, см. findings). Деталь как класс операций близка к насыщению —
-дальше логично 2D-чертёж и сборки.
+Точки входа (проверено рефлексией interop, всё есть):
+- Создать сборку: `DocumentService.CreateAsync(KompasDocumentType.Assembly)`.
+- `IKompasDocument3D.TopPart → IPart7` → `IPart7.Parts` (это `IParts7`).
+- **Вставка компонента из файла:** `IParts7.AddFromFile(string fileName, bool, bool)` или
+  `AddFromFileWithParam(string fileName, IPlacement3D placement, IInsertPartParameters prm, bool)`.
+  Позиция/ориентация — `IPlacement3D` (есть `IPlacement3DManipulator`).
+- **Сопряжения (mates):** `IMateConstraints3D`/`IMateConstraint3D` + типы `IMate3DByAngle`,
+  `IMate3DByTangent`, `IMate3DSymmetry`, и др. (совпадение/параллельность/расстояние/угол).
 
-Бери по одной операции за инкремент, доводи до зелёного и merge+push, потом следующую.
-Не пытайся сделать весь пакет одним заходом — инкремент надёжнее.
+Рекомендуемые инкременты (по одному, до зелёного → merge):
+1. `assembly_add_component(filePath, x, y, z)` — вставить деталь из `.m3d`-файла в активную сборку.
+   Тест: построить деталь → `document_save_as` во временный файл (`.scratch/`) → создать сборку →
+   вставить компонент → `list_components` показывает 1 компонент, габарит/объём сборки ≈ детали.
+   (Эталон обхода/извлечения — память `kompas-step-and-assembly-api`.)
+2. `assembly_add_mate(...)` — сопряжение между гранями/рёбрами двух компонентов (начни с
+   совпадения/coincidence или расстояния). Тест: 2 компонента → сопряжение → положение/габарит
+   меняется предсказуемо.
+3. Перемещение/массив компонентов, фиксация — при необходимости.
+
+Тонкости: компоненту нужен сохранённый файл-источник (сначала сохрани деталь). Уточни через
+`kompas-sdk-research` точные сигнатуры `AddFromFile`/`AddFromFileWithParam`, что такое
+`IInsertPartParameters` и как задать `IPlacement3D` (СК вставки).
+
+## Веха 2 — 2D-ЧЕРТЁЖ (после сборок; новый `DrawingService` на API7)
+
+Точки входа (проверено):
+- Создать чертёж: `DocumentService.CreateAsync(KompasDocumentType.Drawing)`.
+- `IKompasDocument2D.ViewsAndLayersManager.Views` (это `IViews`).
+- **Стандартные ассоциативные виды детали из файла:**
+  `IViews.AddStandartViews(string FileName, string ProjectionName, object ProjectionsTypes,
+  double X, double Y, double Scale, double DX, double DY)` — создаёт виды (спереди/сверху/слева)
+  по сохранённой модели.
+- Отдельный вид: `IViews.Add(LtViewType)`; геометрия/размеры вида — через `IDrawingContainer`
+  вида (`LineSegments`/`Circles`/… — как в разведке параметрики).
+
+Рекомендуемые инкременты:
+1. `drawing_create_standard_views(partFilePath, scale)` — чертёж со стандартными видами детали.
+   Тест: построить деталь → сохранить → создать чертёж → `AddStandartViews` → проверить
+   `Views.Count > 0` (виды созданы). Объёмом не проверить — считать виды/объекты.
+2. Размеры/обозначения на видах (линейные/диаметральные), рамка/основная надпись — по мере надобности.
+
+Тонкости: чертёж проверяется не объёмом, а числом видов/объектов; ассоциативные виды требуют
+сохранённого `.m3d`-файла детали. Уточни workflow через `kompas-sdk-research`.
 
 ## Процесс на каждую операцию (отлажен в прошлых сессиях)
-1. Рефлексия interop — найди definition и `Obj3dType`. Пример команды (PowerShell):
+Сборки/чертёж — это НЕ `PartModeler` (он API5-деталь). Заводи НОВЫЕ сервисы (`AssemblyService`,
+`DrawingService`) и НОВЫЕ классы инструментов (`AssemblyTools`, `DrawingTools`); регистрируй
+сервисы в DI (`Program.cs`, `AddSingleton`). Образец API7-сервиса — `HoleService`.
+
+1. Рефлексия interop — подтверди сигнатуры (`AddFromFile`, `AddStandartViews`, mate-типы):
    ```powershell
-   $a5=[Reflection.Assembly]::LoadFrom((Resolve-Path 'libs/kompas-interop/Kompas6API5.dll'))
-   $c3=[Reflection.Assembly]::LoadFrom((Resolve-Path 'libs/kompas-interop/Kompas6Constants3D.dll'))
-   # перечисли Obj3dType со словом array/pattern/mirror; покажи свойства/методы ksXxxDefinition
+   $a7=[Reflection.Assembly]::LoadFrom((Resolve-Path 'libs/kompas-interop/KompasAPI7.dll'))
+   # члены IParts7 / IMateConstraints3D / IViews — имена методов, типы параметров
    ```
-   Если definition в API5 нет — проверь API7 или отметь блокером (как draft).
-2. Семантику параметров уточняй через навык `kompas-sdk-research` (субагент Sonnet),
-   не рой справку сам.
+   Если высокая неопределённость (как было с параметрикой) — сделай spike ДО спека.
+2. Семантику API уточняй через навык `kompas-sdk-research` (субагент Sonnet), не рой справку сам.
 3. Краткий спек в `docs/superpowers/specs/` → коммит → ОТДАЙ НА РЕВЬЮ Codex (`codex:rescue`,
    `--fresh` для новой темы) → внеси обоснованные правки (оценивай технически, не слепо).
-4. Реализация TDD: метод в `PartModeler.Features.cs` (паттерн `NewEntity(o3d_*)` →
-   `GetDefinition` → настройка → `Create` → регистрация в `_features`, возврат id), инструмент
-   в `FeatureTools.cs`, интеграционный тест в `FeatureOpsTests.cs`.
+4. Реализация TDD: метод в новом сервисе (паттерн API7 как в `HoleService`), инструмент в новом
+   классе `*Tools.cs`, интеграционный тест в новом `*Tests.cs` (Collection `KompasCollection`).
 5. Codex-ревью реализации (`--resume` того же треда) → правки.
 6. Документация через навык `docs-delegate` (Sonnet обновит README/CLAUDE/ARCHITECTURE/
-   presentation.html, сверит счётчики по факту).
-7. `merge --no-ff` в main, удали ветку, `push origin main`.
+   presentation.html). **ВАЖНО:** число тестов задавай субагенту ТОЧНО (по `dotnet test` раннеру,
+   НЕ по числу `[Fact]`/`[Theory]` — теории разворачиваются в несколько кейсов).
+7. `merge --no-ff` в main, удали ветку, `push origin main`. Обнови этот handoff.
 
 ## Паттерн интеграционного теста
-`CreateAsync(Part)` → построить геометрию → операция → `RebuildAsync` →
-проверить объём (`GetPartInfoAsync`) и/или габарит (`GetBoundingBoxAsync`); `finally CloseAsync`.
-Считай ожидаемый объём аналитически и сверяй `InRange ±5%`; для нестрогих форм — ±10% или
-проверка габарита / «after vs before».
+`CreateAsync(...)` → построить/вставить → операция → `RebuildAsync`/`Update` →
+проверить результат; `finally CloseAsync`. Для СБОРКИ — объём/габарит сборки или `list_components`
+(число компонентов). Для ЧЕРТЕЖА — число видов (`Views.Count`)/объектов (объёмом не проверить).
+Артефакты (сохранённые `.m3d`) — в gitignored `.scratch/`.
 
 ## Ключевые ловушки (проверено)
-- Выбор грани/ребра — по стабильному индексу из `list_faces`/`list_edges` (helper'ы
-  `SelectFaceByIndex`/`SelectEdgeByIndex` в ядре); индекс валиден, пока геометрия не менялась.
-- Углы у эскизных/формообразующих — в градусах.
-- param-структуры (эллипс/полигон/nurbs) — через `NewParam<T>(StructType2DEnum)`, освобождать.
-- Валидацию выноси в `SketchGeometry` как чистые static (unit-тестируемо); проверяй
-  `double.IsFinite` (NaN проходит через `<= 0`), дедуплицируй списки индексов.
-- НЕ освобождай транзитные RCW точечно в одной операции — это общий отложенный долг
-  (OPEN_QUESTIONS v2-2), консистентность важнее; единый рефакторинг — отдельной задачей.
+- Все COM-вызовы — на STA-потоке (`KompasDispatcher.InvokeAsync`). Контейнеры API7 берём
+  COM-QI: `(IModelContainer)part`, `(IParts7)part.Parts` и т.п.
+- Выбор грани/ребра — по стабильному индексу из `list_faces`/`list_edges`; для сопряжений
+  объекты компонентов искать через их `IPart7`/`FindObjectsByPoint`.
+- Углы — в градусах. Валидацию — в чистые static (unit-тестируемо), проверяй `double.IsFinite`.
+- НЕ освобождай транзитные RCW точечно — общий отложенный долг (OPEN_QUESTIONS v2-2).
 - Команды: `dotnet build -c Release`; `dotnet test --filter "Category=Unit"`;
   `dotnet test --filter "Category=Integration"` (нужен запущенный КОМПАС).
 
-Начни с рефлексии interop для массивов (пакет C) и `kompas-sdk-research` по найденному
-definition, затем первый инкремент — линейный массив.
+Начни с рефлексии interop `IParts7` (вставка компонента) + `kompas-sdk-research` по
+`AddFromFile`/`AddFromFileWithParam`/`IPlacement3D`, затем первый инкремент —
+`assembly_add_component` (вставка детали из файла в сборку).