kompas3d-mcp/docs/superpowers/specs/2026-05-27-drawing-text-annotations-design.md

Дизайн: текстовые обозначения чертежа — шероховатость, текст, тех. требования (API7)

Дата: 2026-05-27 Статус: дизайн согласован (все три в одном инкременте), спайк проведён, ревью Codex спека учтено — к реализации

Правки по ревью Codex (спек)

• #4 параметр height у drawing_add_text убран: IDrawingText.Height — высота блока форматирования, НЕ размер шрифта (шрифт задаётся на уровне ITextItem, вне объёма). Текст ставится стилем по умолчанию. (Снимает и #10 — валидация height не нужна.)
• #3/#11 сервис возвращает значение, прочитанное обратно из COM после Update (rough — RoughParamText.Str; text — ((IText)dt).Str) — как NominalValue у размеров. Тест Value==вход доказывает round-trip. Пост-Add откат Delete есть в коде; не форсируется тестом (для валидных параметров COM всегда Valid — как решено у диаметрального; путь идентичен протестированному угловому).
• #1 value шероховатости нормализуется (null/whitespace → ""); возвращается нормализованное (read-back), контракт Value непустой не нарушается.
• #2/#5/#7 добавлены null/QI-guards: Roughs/(IRoughParams)/RoughParamText; (IDrawingContainer)/DrawingTexts/(IText); (IDrawingDocument)/TechnicalDemand/Text — каждый с раздельной диагностикой (как RequireStampCell/RequireSymbols2DContainer).
• #6 тесты текста дополнены: многострочный round-trip (\n), несуществующий viewNumber>0.
• #8 добавлен helper ReadTechnicalRequirementsAsync — тест читает td.Text.Str и проверяет перезапись (как DrawingStampTests перечитывают графы).
• #9 подсчёт строк тех. требований нормализован: text.Replace("\r\n","\n"), хвостовые пустые строки отбрасываются ("a\n" → 1 строка).

Цель

Веха 2D-ЧЕРТЁЖ, инкремент 6. После завершения базового семейства размеров — текстовые обозначения: знак шероховатости, свободная текстовая надпись, технические требования. Три инструмента покрывают самые частые «не-размерные» элементы конструкторского чертежа.

Спайк: все три механизма подтверждены вживую (НЕ разучивать)

Спайк (_SpikeAnnotations, прогнан на реальном КОМПАС v24, затем удалён) на коробке 40×30×20 с тремя стандартными видами.

Шероховатость — на виде (ISymbols2DContainer.Roughs)

IRough rough = symbols.Roughs.Add();             // без параметров
rough.BranchX0 = 20; rough.BranchY0 = 25;        // положение знака (ЛОКАЛЬНАЯ СК вида, мм)
rough.Angle = 0;                                  // угол наклона оси знака (градусы)
IRoughParams rp = (IRoughParams)rough;            // QI (как IDimensionText у размеров)
rp.SignType = ksRoughSignEnum.ksDeleteMaterial;   // тип знака
rp.RoughParamText.Str = "Ra 1.6";                 // значение (Ra/Rz) — текст
rough.Update();   // True, rough.Valid == True

Проверено: Update=True, Valid=True, RoughParamText.Str round-trip = "Ra 1.6", Roughs.Count → 1. ksRoughSignEnum: ksNoProcessingType=0 (без указания обработки), ksDeleteMaterial=1 (с удалением слоя материала), ksWithoutDeleteMaterial=2 (без удаления). Положение — свободные координаты (BranchX0/Y0); BaseObject (привязка к контуру) не задаём — будущее.

Свободный текст — на виде (IDrawingContainer.DrawingTexts, НЕ Symbols!)

IDrawingContainer dc = (IDrawingContainer)view;   // ВНИМАНИЕ: текст в контейнере геометрии,
IDrawingText dt = dc.DrawingTexts.Add();          //   а НЕ в ISymbols2DContainer
dt.X = 30; dt.Y = 45; dt.Angle = 0;               // точка привязки (ЛОКАЛЬНАЯ СК вида, мм)
((IText)dt).Str = "Образец надписи";              // содержимое (QI к IText), \n — многострочно
dt.Update();   // True, dt.Valid == True

Проверено: Update=True, Valid=True, Str round-trip, DrawingTexts.Count → 2 (вид уже содержал 1 текст — авто-подпись вида; проверять по ДЕЛЬТЕ before+1, не по абсолюту). ObjectCount 4→4 — текст НЕ входит в IView.ObjectCount (как и размеры) → проверять DrawingTexts.Count.

Технические требования — на уровне ДОКУМЕНТА (IDrawingDocument.TechnicalDemand)

IDrawingDocument dd = (IDrawingDocument)doc;       // QI от активного IKompasDocument2D
ITechnicalDemand td = dd.TechnicalDemand;          // единый блок на документ
td.Text.Str = "1. Общие допуски по ГОСТ 30893.1.\n2. Острые кромки притупить.";  // \n — строки
td.Update();   // True

Проверено: IsCreated False→True (первый Text.Str+Update() создаёт блок), Update=True, текст с \n сохранён построчно. Объект уровня документа (не вида), единственный, над основной надписью. Str замещает содержимое (как у штампа) → инструмент set (перезапись).

MCP-инструменты

Инструмент	Параметры	Поведение
drawing_add_rough	x,y (положение знака), value="" (Ra/Rz, напр. "Ra 1.6"), signType="delete" (delete|without|none), angle=0 (°), viewNumber=0	Поставить знак шероховатости на виде. Положение x,y в ЛСК вида (мм). value — текст параметра (пусто = знак без значения). Возвращает значение и номер вида.
drawing_add_text	x,y (точка привязки), text, angle=0 (°), viewNumber=0	Поставить свободную текстовую надпись на виде стилем по умолчанию. text — содержимое (\n — многострочно). Возвращает текст (read-back) и номер вида.
drawing_set_technical_requirements	text	Задать технические требования активного чертежа (единый блок над штампом; перезаписывает прежние). text — строки через \n. Возвращает число строк.

Архитектура

В существующем DrawingService (namespace Kompas.Mcp.Core.Drawings). Шероховатость/текст — per-view; тех. требования — per-document.

• AddRoughAsync(viewNumber, x, y, value, signType, angleDeg, ct) → DrawingAnnotationResult. Введём record DrawingAnnotationResult { string Value; int ViewNumber } (универсальный для rough/text — Value=строка, прочитанная обратно из COM; ViewNumber). Тех. требования возвращают число строк (int).
• AddTextAsync(viewNumber, x, y, text, angleDeg, ct) → DrawingAnnotationResult.
• SetTechnicalRequirementsAsync(text, ct) → int (число строк).
• ReadTechnicalRequirementsAsync(ct) → string (для теста — td.Text.Str).
• Helpers: RequireSymbols2DContainer (есть, для rough), новый RequireDrawingContainer(viewNumber) = guarded (IDrawingContainer)FindView(...) (для text), новый RequireDrawingDocument() = guarded (IDrawingDocument)RequireActiveDrawing() (для тех. требований). Все QI с раздельной диагностикой.
• Счётчики для тестов: GetViewRoughCountAsync, GetViewTextCountAsync.
• Новый enum-файл RoughSignType.cs: enum RoughSignType {NoProcessing, DeleteMaterial, WithoutDeleteMaterial}
  • RoughSignTypes.Parse(string)/ToKompas(...) (→ ksRoughSignEnum), по образцу AngleDimensionTypes.
• Новый файл DrawingAnnotationResult.cs.
• Инструменты в DrawingTools.cs.

Валидация (чистые static, unit-тест)

• RequireFiniteCoords (есть) — координаты rough/text.
• Новый RequireNonEmptyText(string, paramName) — для text (drawing_add_text, тех. требования). value шероховатости НЕ обязателен (знак без значения допустим; null/whitespace → "").
• RoughSignTypes.Parse — разбор строки (unit-тест; ToKompas → ksRoughSignEnum НЕ покрываем unit — граница проекта, как у AngleDimensionTypes/DimensionOrientations).

Реализация

AddRoughCore: нормализация value (null/whitespace → "") → RequireFiniteCoords(x,y,angleDeg) → RequireSymbols2DContainer → symbols.Roughs (null-check) → .Add() (null-check) → BranchX0/Y0/Angle → (IRoughParams)rough (null-check QI) → SignType=ToKompas, rp.RoughParamText (null-check) .Str = value → Update() (FALSE → откат Delete) → Valid (false → откат) → читаем rp.RoughParamText.Str обратно → DrawingAnnotationResult{Value=read-back, ViewNumber}.

AddTextCore: RequireNonEmptyText(text) + RequireFiniteCoords(x,y,angleDeg) → RequireDrawingContainer → dc.DrawingTexts (null-check) → .Add() (null-check) → X/Y/Angle → (IText)dt (null-check QI) .Str = text → Update() (FALSE → откат Delete) → Valid (false → откат) → читаем ((IText)dt).Str обратно → DrawingAnnotationResult{Value=read-back, ViewNumber}.

SetTechnicalRequirementsCore: RequireNonEmptyText(text) → нормализация text.Replace("\r\n","\n") → RequireDrawingDocument() → dd.TechnicalDemand (null-check) → td.Text (null-check) .Str = text → td.Update() (FALSE → ошибка; объект уровня документа — отката Delete НЕ делаем, перезапись идемпотентна) → вернуть число непустых-после-trim хвоста строк (TrimEnd('\n').Split('\n').Length).

RequireDrawingContainer(viewNumber) = FindView → (IDrawingContainer)view (null → «вид не приводится к IDrawingContainer»). RequireDrawingDocument() = RequireActiveDrawing() → (IDrawingDocument)doc (null → «чертёж не приводится к IDrawingDocument»).

RCW точечно не освобождаем (консистентно с остальным DrawingService; долг v2-2).

Тестирование

Unit (RoughSignTypesTests, DrawingValidationTests)

• RoughSignTypes.Parse: delete/without/none (+ рус. синонимы) → enum; неизвестное → ArgumentException; null → ArgumentNullException.
• RequireNonEmptyText: бросает на null/пусто/пробелы; пропускает непустое.

Integration (DrawingRoughTests, DrawingTextTests, DrawingTechReqTests; наследуют IntegrationTestBase)

Шероховатость:

1. Ставится + round-trip: value="Ra 1.6", signType=delete → Value=="Ra 1.6" (read-back из COM), попадание в целевой вид (Roughs.Count +1, адресация по viewNumber).
2. Знак без значения: value="" → ставится (Valid), Roughs.Count +1.
3. Нет видов → понятная ошибка. 4. Несуществующий viewNumber>0 → ошибка.

Текст: 5. Ставится + round-trip: text → Value==text (read-back), DrawingTexts.Count +1 (по ДЕЛЬТЕ — вид уже мог содержать подпись), адресация по целевому viewNumber. 6. Многострочный ("строка1\nстрока2") → Value сохраняет обе строки (round-trip \n). 7. Пустой текст → ArgumentException (до Add). 8. Нет видов → ошибка. 9. Несуществующий viewNumber>0 → ошибка.

Тех. требования: 10. Задаются + round-trip: многострочный текст → lines==2; ReadTechnicalRequirementsAsync возвращает тот же текст; повторный вызов с другим текстом перезаписывает (read-back = новый, без накопления). 11. Пустой текст → ArgumentException. 12. Активный документ не чертёж → понятная ошибка.

Дальнейшее (вне спека)

• Привязка шероховатости/выносок к геометрии (BaseObject); выноски (Leaders), обозначения баз (Bases), допуски формы (Tolerances); рамка/формат листа; ассоциативная привязка размеров.