docs: define Autodesk launcher next architecture

2026-07-31 14:30:19 +03:00
parent 36178374db
commit 1127a8376f
30 changed files with 298 additions and 0 deletions
@@ -0,0 +1,13 @@
+# Launcher Next target architecture
+
+Launcher Next is a parallel .NET 8 foundation: one visible x64 application, immutable versioned local packages, manifest/hash validation, atomic activation, rollback pointer, explicit dry-run Plant launch preparation and structured local logs. It does not deploy, alter profiles, start AutoCAD or change legacy files in this foundation.
+
+```text
+Launcher.Next.App -> Application orchestration -> Infrastructure adapters
+  -> product discovery (registry abstraction)
+  -> package catalog / local synchronizer / versioned store
+  -> manifest validation / SHA-256
+  -> startup script builder -> Process launcher dry-run
+```
+
+For P_Rec_Annot, one local entry `PRecAnnot.Plant3D2026.dll` replaces legacy `OrthoLoader -> Settings.xml -> 20 NETLOAD` orchestration. Its internal dependencies are CLR dependencies; Autodesk assemblies remain supplied by AutoCAD.
@@ -0,0 +1,11 @@
+# Compatibility matrix
+
+| Dimension | Legacy | Next foundation | Pilot decision |
+|---|---|---|---|
+| UI | WinForms installer | WPF shell | parallel |
+| Runtime | .NET Framework 4.7 | .NET 8 x64 | separate EXE |
+| Plugin load | generated multi-NETLOAD | one local NETLOAD | validate first |
+| Package source | network copy | manifest + local cache | no production UNC client yet |
+| Offline | unknown | last valid local version | design policy |
+| Rollback | manual/unknown | previous pointer | foundation tested |
+| AutoCAD version | historical 2019 evidence | discovery for Plant 2026 | require runtime confirmation |
@@ -0,0 +1,12 @@
+# Target component model
+
+| Component | Responsibility | Boundary | Side effects |
+|---|---|---|---|
+| Launcher.Next.App | minimal WPF shell and view model | UI only | none until explicit action |
+| Core | contracts, manifest models, validation policy | no WPF/registry/process/filesystem/Autodesk | none |
+| Application | synchronize/activate/prepare workflows | ports only | none directly |
+| Infrastructure | local files, hashes, catalog implementation | filesystem/network behind interfaces | staging/cache writes |
+| Autodesk | registry discovery, script construction, ProcessStartInfo | OS/process boundary | dry-run only in foundation |
+| Observability | redacted JSONL events | local logging | log file write |
+
+Feature flag: `Legacy`, `NextPilot`, `NextPreferred`; default is `Legacy`. No production configuration changes occur without explicit authorization.
@@ -0,0 +1,11 @@
+# Local cache
+
+The configurable root defaults by policy to the corporate local support root:
+
+```text
+<SupportRoot>/Launcher/{config,logs,state,staging,rollback}
+<SupportRoot>/Applications/<PackageId>/versions/<version>/
+<SupportRoot>/Applications/<PackageId>/current.json
+```
+
+Keep `current`, `previous` and incomplete `staging` separate. Activated directories are immutable; do not overwrite a DLL used by AutoCAD. A valid cache permits offline use; an invalid or partial staging directory never becomes current.
@@ -0,0 +1,9 @@
+# Migration strategy
+
+1. Preserve legacy unchanged and default `LauncherMode=Legacy`.
+2. Pilot an isolated group with `NextPilot`, local cache and one P_Rec entry assembly.
+3. Validate package/hash/rollback and dry-run launch preparation before any runtime use.
+4. Test actual bootstrap only with separate authorization and non-production Plant data.
+5. Move to `NextPreferred` only after operational evidence; retain immediate Legacy fallback.
+
+No AppLoader, registry demand-loading or direct UNC deployment decision is implied by this foundation.
@@ -0,0 +1,5 @@
+# Observability
+
+Write best-effort JSONL records under `%LOCALAPPDATA%\Promhimproekt\LauncherNext\Logs`. Events: `LauncherStarted`, `ConfigurationLoaded`, `ProductDiscoveryStarted`, `ProductDiscovered`, `CatalogReadStarted`, `CatalogReadCompleted`, `PackageValidationStarted`, `PackageValidationCompleted`, `SynchronizationStarted`, `SynchronizationCompleted`, `ActivationCompleted`, `RollbackStarted`, `RollbackCompleted`, `LaunchPrepared`, `LaunchBlocked`, `LauncherFailed`.
+
+Records exclude user identity, tokens, passwords, full Plant project paths, project numbers and engineering-file content. Logs must never block a launch decision.
@@ -0,0 +1,26 @@
+# Package manifest
+
+```json
+{
+  "schemaVersion": 1,
+  "packageId": "P_Rec_Annot",
+  "version": "2026.1.0",
+  "product": "Plant3D",
+  "productYear": 2026,
+  "architecture": "x64",
+  "minimumLauncherVersion": "1.0.0",
+  "compatibleAutoCadSeries": ["R25.1"],
+  "requiredRuntime": ".NET 8",
+  "entryAssembly": "PRecAnnot.Plant3D2026.dll",
+  "files": [{ "path": "PRecAnnot.Plant3D2026.dll", "length": 0, "sha256": "<64 hex>" }],
+  "dependencies": [],
+  "optionalResources": [],
+  "rolloutChannel": "pilot",
+  "disabled": false,
+  "rollbackSafe": true,
+  "releaseNotesReference": "relative-release-notes.md",
+  "startup": { "type": "netload", "command": "PHP_REC_ANNOT" }
+}
+```
+
+Validation rejects absolute/traversal/duplicate paths, missing entry assembly, incompatible product/year/architecture, and Autodesk/Plant managed assemblies (`AcMgd`, `AcDbMgd`, `AcCoreMgd`, `AdWindows`, `PnP*`, `Autodesk.ProcessPower*`). No absolute paths belong in a manifest.
@@ -0,0 +1,5 @@
+# Plugin bootstrap
+
+Generate a temporary, locally stored startup script only from a validated package root. It contains exactly one escaped `NETLOAD` for the entry assembly and no separate dependency loads. The script is not executed by foundation tests.
+
+`PRecAnnot.Plant3D2026.dll` is the only managed entry. `PRecAnnot.Application`, `PRecAnnot.Core` and allowed third-party libraries resolve as CLR dependencies. Autodesk managed assemblies are neither copied nor included in package manifests; they load from the installed AutoCAD/Plant runtime.
@@ -0,0 +1,9 @@
+# Target security model
+
+- Load managed assemblies only from validated local version directories, never directly from UNC.
+- Hash every packaged file with SHA-256 before activation.
+- Validate package paths against traversal and package-root escape.
+- Forbid Autodesk runtime DLLs in packages.
+- Detect Autodesk installations through a read-only registry abstraction with configuration override for diagnostics.
+- Do not change `TRUSTEDPATHS`, registry, profiles or production deployment without explicit approval.
+- Keep credentials/secrets out of source, manifests and telemetry.
@@ -0,0 +1,22 @@
+# Target startup sequence
+
+```mermaid
+sequenceDiagram
+ participant U as User
+ participant L as Launcher Next
+ participant D as Product discovery
+ participant C as Package catalog
+ participant S as Local store
+ participant A as Plant 3D
+ participant P as PRecAnnot entry
+ U->>L: Prepare launch (NextPilot)
+ L->>D: discover installed Plant 3D
+ L->>C: read package manifest when network is available
+ L->>S: stage, hash-validate, activate package atomically
+ L->>L: build one validated NETLOAD startup script
+ L->>A: ProcessStartInfo (explicit profile/script)
+ A->>P: one NETLOAD local PRecAnnot.Plant3D2026.dll
+ P->>A: commands and Ribbon registry
+```
+
+Foundation performs through `LaunchPrepared`; real process start remains dry-run only.
@@ -0,0 +1,10 @@
+# Atomic update and rollback
+
+1. Read and validate manifest.
+2. Copy/download into a new staging directory with cancellation and bounded parallelism.
+3. Validate file length, SHA-256, required files, entry metadata and forbidden DLLs.
+4. Write local manifest, close streams and rename staging to `versions/<version>`.
+5. Atomically replace `current.json`; preserve prior pointer.
+6. On bootstrap failure, offer rollback by atomically restoring the prior pointer.
+
+Never update an active directory in place. Locked files leave the current version intact and yield a diagnostic status. Network failure uses the last valid local version; when none exists, policy is to launch Plant without the corporate plugin or offer Legacy fallback, never a partial Next package.