docs: define Plant 3D 2026 migration agent contract
This commit is contained in:
codex
@@ -0,0 +1,129 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Назначение проекта
|
||||
|
||||
Этот репозиторий содержит аудит, архитектуру, исходный код, тесты, runtime
|
||||
evidence и документацию миграции корпоративной экосистемы Autodesk AutoCAD
|
||||
Plant 3D 2019 на Autodesk AutoCAD Plant 3D 2026.
|
||||
|
||||
Конечная цель — функционально эквивалентная рабочая схема Plant 3D 2026:
|
||||
корпоративный Launcher, локальная доставка и активация пакетов, managed
|
||||
плагины, команды, Ribbon, Plant project integration, DataLinks, Ortho,
|
||||
аннотации, обновление, диагностика и rollback. Миграция не считается
|
||||
завершённой после успешной компиляции: необходима runtime-проверка реальных
|
||||
сценариев в Plant 3D 2026.
|
||||
|
||||
## Связанные репозитории
|
||||
|
||||
- основной Autodesk-репозиторий: `C:\dev\autodesk`;
|
||||
- Launcher Next: `C:\dev\launcher-next`;
|
||||
- legacy launcher (read-only): `C:\dev\launcher\git`, `C:\dev\p_serv_starter`;
|
||||
- legacy P_Rec_Annot (read-only): `C:\dev\autodesk\link\P_Rec_Annot\v1.0.4\repo`.
|
||||
|
||||
Legacy и deployed-файлы нельзя изменять без отдельного прямого задания.
|
||||
|
||||
## Целевая платформа и принцип миграции
|
||||
|
||||
- Autodesk AutoCAD Plant 3D 2026, series R25.1, Windows x64, .NET 8;
|
||||
- использовать реальные Autodesk 2026 managed assemblies;
|
||||
- managed package загружается локально, не напрямую с UNC;
|
||||
- Autodesk DLL нельзя коммитить, помещать в package/fixture или публиковать.
|
||||
|
||||
Переносится функциональное поведение, а не историческая структура файлов. Не
|
||||
воспроизводить без отдельного доказательства 20 последовательных `NETLOAD`,
|
||||
legacy LISP bootstrap, `OrthoLoader.dll`, загрузку с сети или прежние
|
||||
workaround. Предпочтительная цепочка:
|
||||
|
||||
`Launcher Next → versioned local package → один managed entry assembly → internal dependencies → commands and Ribbon`.
|
||||
|
||||
## Статус legacy-команд
|
||||
|
||||
Ни одна активная команда Plant 3D 2019 не исчезает молча. Для каждой команды
|
||||
фиксируется ровно один статус: `IMPLEMENTED`, `RUNTIME_VERIFIED`,
|
||||
`REPLACED_WITH_NATIVE`, `RETIRED_APPROVED` или `BLOCKED_WITH_REASON`.
|
||||
Aliases сохраняются, пока их удаление не утверждено отдельно.
|
||||
|
||||
## Runtime уровни
|
||||
|
||||
`Smoke` проверяет assembly load, регистрацию команд, Plant context, Ribbon,
|
||||
отсутствие необработанных исключений и отсутствие записи в DWG.
|
||||
|
||||
`DryRun` проверяет реальные Plant data, Ortho/sheet/view definitions, DataLinks,
|
||||
Plant objects, детерминированный план и отсутствие записи в DWG/project DB.
|
||||
|
||||
`Apply` разрешается только отдельным явным заданием: write guard, ограниченная
|
||||
DWG transaction, тестовая копия проекта, baseline, rollback/UNDO, duplicate
|
||||
protection и runtime evidence обязательны. Apply нельзя включать только
|
||||
локальной конфигурацией.
|
||||
|
||||
## Runtime важнее предположений
|
||||
|
||||
Build и unit tests не доказывают Autodesk integration. Для
|
||||
`RUNTIME_VERIFIED` необходимы фактические результаты: команда, module path,
|
||||
DBMOD, Ribbon, DataLinks, Ortho status, telemetry и состояние файлов после
|
||||
закрытия. Не выдумывать UI evidence: использовать `null`, `NOT VERIFIED` или
|
||||
`BLOCKED WITH REASON`.
|
||||
|
||||
На тестовой машине реальный Plant 3D запуск разрешён, если он входит в задачу
|
||||
и есть test branch, локальный fixture, пройденные build/tests, rollback и нет
|
||||
production deploy. Не создавать искусственный review-gate перед Process.Start.
|
||||
Остановка допустима лишь после завершения доступной части работы и при
|
||||
конкретном внешнем blocker: установка, ОС, права, Autodesk runtime, fixture или
|
||||
необходимость production-данных.
|
||||
|
||||
## Test fixtures и отсутствие записи
|
||||
|
||||
Fixtures создаются вне Git, например `<TEST_FIXTURE_ROOT>`. Ortho fixture —
|
||||
настоящий Plant project с Pipe, DataLinks row, line group, Ortho drawing,
|
||||
Ortho viewport и source-model connection; обычный AutoCAD viewport не годится.
|
||||
Production DWG/project использовать нельзя без прямого разрешения.
|
||||
|
||||
Нельзя коммитить DWG, DCF, Project.xml с runtime-data, project DB, Ortho
|
||||
generated files или реальные engineering values.
|
||||
|
||||
Для Smoke/DryRun проверять DBMOD до/после, SHA-256 содержательных project
|
||||
files, отсутствие непредусмотренных transactions/DCF/project-metadata writes.
|
||||
`LastWriteTime` недостаточен. Отделять служебные Plant cache/session files от
|
||||
содержательных данных.
|
||||
|
||||
## Ribbon, механика и evidence
|
||||
|
||||
Ribbon — часть продукта: проверять tab, panel, button, command binding, stable
|
||||
IDs, отсутствие дубликатов при документах/workspace/reinitialization. Команда
|
||||
может быть отдельно рабочей, но plugin slice не завершён без Ribbon evidence
|
||||
или отдельного UI defect.
|
||||
|
||||
Документировать каждую runtime-цепочку: component/project/class/method,
|
||||
input/output, Autodesk transaction mode, writes, telemetry, failure code и
|
||||
rollback action. Документация соответствует фактическому коду.
|
||||
|
||||
Evidence содержит только проверенные значения. Не добавлять username, permit,
|
||||
полный environment, real project paths/line numbers/ObjectId/RowId/properties,
|
||||
полные logs, local manifest или startup scripts. Путь fixture заменять на
|
||||
`<TEST_FIXTURE_ROOT>`.
|
||||
|
||||
## Warnings и Git
|
||||
|
||||
Известный `MSB3277` WindowsBase 4.0.0.0/8.0.0.0 допустим только при полном
|
||||
совпадении с ранее зафиксированным warning. Новые warnings исследовать; не
|
||||
подавлять `NoWarn` без причины.
|
||||
|
||||
Запрещены force push, amend/rebase опубликованной истории, push binaries,
|
||||
изменение неизвестного remote и production deployment из test branch. Перед
|
||||
commit выполнять:
|
||||
|
||||
```powershell
|
||||
git diff --check
|
||||
git status --short
|
||||
git diff --cached --check
|
||||
```
|
||||
|
||||
Не смешивать Launcher defect, plugin defect, runtime evidence и unrelated
|
||||
formatting в одном commit.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Срез завершён, когда реализованы код, build/tests, валидный package и требуемый
|
||||
runtime-сценарий; записаны фактические результаты; выполнен rollback; fixture и
|
||||
production изолированы; механика документирована; ветка опубликована обычным
|
||||
push.
|
||||
@@ -0,0 +1,58 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user