diff --git a/docs/superpowers/NEXT-SESSION.md b/docs/superpowers/NEXT-SESSION.md index e31b38a..00ac155 100644 --- a/docs/superpowers/NEXT-SESSION.md +++ b/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`), `.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(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` (вставка детали из файла в сборку).