autodesk/Plant3D2026/P_Rec_Annot/AGENTS.md

AGENTS.md — P_Rec_Annot

Назначение и package

P_Rec_Annot — приоритетный Plant 3D 2026 plugin для чтения, планирования и последующего создания Ortho-аннотаций; это перенос активного legacy поведения Plant 3D 2019 на .NET 8/Plant 3D 2026.

Единственная assembly для NETLOAD — PRecAnnot.Plant3D2026.dll. PRecAnnot.*.dll — internal managed dependencies, их нельзя NETLOAD по одной. Использовать Autodesk 2026 references; Autodesk DLL не включать в bundle.

Commands и context

Поддерживаемые команды: PHP_REC_ANNOT, PXP-AAV, PXP-OA. Все регистрируются реальным Autodesk API, работают в Smoke/DryRun, не изменяют DWG в этих режимах и создают одно usage event на явный вызов.

Project status: NotFound, FoundWithName, FoundWithoutDisplayName, Ambiguous, Failed. Никогда не выводить проект '' найден; для пустого display name: Plant 3D-проект открыт; отображаемое имя не определено. Diagnostic code: PLANT_PROJECT_DISPLAY_NAME_EMPTY.

Drawing states: Ortho, NotOrtho, Ambiguous, Failed. Обычный DWG не классифицируется как Ortho; для реального Ortho применять Autodesk API и OrthoDocUtils.IsValidOrthoDrawing.

DryRun и determinism

Pipeline: Plant context → Ortho detection → sheet/view definitions → viewport snapshots → DataLinks → Plant properties → independent DTO → deterministic AnnotationPlan → diagnostics → no write.

Autodesk objects, transactions и database handles остаются в adapter layer; Core/Application используют только независимые DTO. На неизменном fixture повторный DryRun обязан давать тот же PlanId, counts, порядок операций и warning codes, без side effects. PlanId не включает время, GUID, absolute path, нестабильный ObjectId или пользовательские данные.

Write guard, Ribbon, tests

Все writes проходят централизованный write guard; в Smoke/DryRun он всегда запрещает изменения. Apply не обходится через command handler/adapter.

Ожидаемый Ribbon путь: Промхимпроект → Аннотации → Аннотировать. Требуются stable IDs, отсутствие дублей, binding к PHP_REC_ANNOT, устойчивость к документам/workspace и корректный Terminate.

Unit tests не требуют Autodesk runtime. Runtime evidence отдельно фиксирует initialization, commands, context, Ortho, DataLinks, plan, Ribbon, DBMOD, telemetry и shutdown.

Bundle содержит только фактический runtime dependency graph и никогда не содержит Autodesk DLL, PDB, test assemblies, legacy 2019 assemblies, bin/obj или production configuration.

Fixture: local Plant 3D 2026 project вне Git с настоящей Pipe, synthetic line number, Ortho drawing/viewport и SHA baseline до DryRun.

Viewport membership and source DataLinks

Legacy P_Rec_Annot source for read-only analysis is \\phpsrv03\NBIM\code\CS\P_Rec_Annot\v1.0.4\repo.

A source object is not a member of an Ortho viewport without confirmed evidence. A geometry-only filter is at most PartiallyResolved. Apply is blocked by any PLUGIN_ONLY_CHANGE in a DWG, DCF, or project metadata found by a paired CONTROL/DryRun comparison.

Ortho source DataLinks and DCF control

DataLinks активного Ortho drawing не являются источником Piping rows. Piping rows читаются из source model drawing и Piping project part, разрешённых через Ortho sheet/view definitions.

Перед предположениями об Autodesk runtime API необходимо исследовать текущий код, доступный legacy usage, assembly metadata и реальные runtime types. Reflection/runtime inspection применяется только для подтверждения данных, которых нельзя установить статически. Production resolver не угадывает Autodesk properties по строковым именам.

Подтверждённый контракт Plant 3D 2026: IDwgViewDef.DwgQuery → IDwgQuery.ModelFiles → ModelFile[].ModelFileName. При несовпадении типа возвращать ORTHO_MODEL_FILES_API_UNSUPPORTED, без fallback-эвристики.

Проверка DCF выполняется на парных control и DryRun fixtures, созданных из одного закрытого состояния проекта. Сравнивать нужно control delta с DryRun delta: одинаковые изменения классифицируются как baseline behavior Plant 3D, а plugin-only изменения блокируют дальнейшую работу.

Общая карта проекта

Каноническая общая карта проекта: https://drive.google.com/drive/folders/1avnR0V8q7y5pfWRYwB6LPBEEyfpN7PpV. Необязательная локальная копия доступна только через PHIM_PLANT3D_PROJECT_MAP_ROOT; локальный путь синхронизации не хардкодить.

До изменения P_Rec_Annot читать доступные индекс карты, запись архитектуры и статуса P_Rec_Annot, DryRun/Apply contract, карту Ortho/DataLinks и связанный runtime evidence index. Сверять их с фактическим Git HEAD, текущими plugin code/tests/configuration и runtime evidence конкретной fixture.

Приоритет источников: runtime evidence, затем code/tests/configuration на проверенном HEAD, затем tracked repository documentation, затем общая карта. Карта не является build/runtime dependency и не заменяет фактический код либо runtime evidence. Недоступную карту отмечать PROJECT_MAP_UNAVAILABLE; несовпадение её commit/runtime status с фактическими данными — PROJECT_MAP_STALE.

Инварианты P_Rec_Annot: остаётся единственная NETLOAD entry assembly, aliases и статусы команд не исчезают молча, Smoke/DryRun не пишут DWG, а Apply требует явного разрешения, локальной fixture, ограниченной transaction, evidence и проверяемого rollback/UNDO. Не ослаблять подтверждённый Ortho source/DataLinks контракт и DCF control comparison ради сведений из карты.

После изменения plugin architecture или runtime-status в отчёте перечислять документы карты, требующие обновления: запись P_Rec_Annot, command/status, Ortho/DataLinks contract, DryRun/Apply/UNDO evidence и migration status. Не утверждать обновление внешней документации без фактического изменения.