feat.文档更新

docs/archive/EXTERNAL_IPC_ARCHITECTURE.md

@@ -0,0 +1,127 @@
+# External IPC Architecture
+
+## Scope
+
+This document defines the current external integration IPC baseline for LanMountainDesktop.
+
+- The delivery focus is external application integration, not plugin process isolation.
+- `dotnetCampus.Ipc` is the single IPC foundation for Host public APIs, Launcher/OOBE startup notifications, and plugin-contributed external services.
+- Process isolation remains a future track and stays documented in `docs/PLUGIN_PROCESS_ISOLATION_ARCHITECTURE.md`.
+
+## Design Summary
+
+The public IPC stack is split into two complementary layers:
+
+1. Strongly typed public services
+   - Contracts are marked with `[IpcPublic]`.
+   - Host exposes service instances through `CreateIpcJoint<TContract>(instance)`.
+   - .NET clients connect once and obtain strong typed proxies through `CreateIpcProxy<TContract>(peer)`.
+2. Routed notifications
+   - `JsonIpcDirectRoutedProvider.NotifyAsync` is used for one-way event delivery.
+   - Startup progress, loading-state updates, catalog changed events, and plugin live events all use routed notify IDs.
+
+This keeps command/query calls explicit and strongly typed while still giving plugins and Launcher a lightweight event channel.
+
+## Projects
+
+- `LanMountainDesktop.Shared.IPC`
+  - Public IPC constants, routed notify IDs, DTOs, strong-typed public service contracts, host/client helpers, and DI registration helpers.
+- `LanMountainDesktop`
+  - Runs `PublicIpcHostService`, exposes built-in public services, and folds plugin-contributed services into one external catalog.
+- `LanMountainDesktop.Launcher`
+  - Connects to the Host public pipe and listens for startup and loading-state notifications instead of running a custom length-prefixed IPC server.
+- `LanMountainDesktop.PluginSdk`
+  - Adds `IPluginPublicIpcContributor`, `IPluginPublicIpcBuilder`, and `AddPluginPublicIpc(...)`.
+
+## Built-in Public Services
+
+Current built-in `[IpcPublic]` contracts:
+
+- `IPublicAppInfoService`
+  - Returns application metadata such as version, codename, process id, pipe name, and startup time.
+- `IPublicShellControlService`
+  - Allows external .NET clients to query shell status, activate the shell, repair tray readiness, repair taskbar entry visibility, open settings, request restart, and request exit.
+- `IPublicPluginCatalogService`
+  - Returns the merged public IPC catalog snapshot exposed by Host.
+
+## Routed Notify IDs
+
+Current fixed routed notify IDs:
+
+- `lanmountain.catalog.changed`
+- `lanmountain.launcher.startup-progress`
+- `lanmountain.launcher.loading-state`
+
+The fixed routed surface is intentionally small. Runtime variation happens in the service catalog and in plugin-contributed service instances, not in ad-hoc top-level route registration after startup.
+
+## Host Lifecycle
+
+`PublicIpcHostService` is started during Host application startup and remains the single external IPC entry point.
+
+Responsibilities:
+
+- Start a named `dotnetCampus.Ipc` provider.
+- Register fixed request routes before `StartServer()`.
+- Expose built-in strong-typed public services.
+- Maintain the merged service catalog.
+- Publish startup and loading-state notifications to connected clients.
+- Accept plugin-contributed public services after plugin load.
+
+## Launcher / OOBE Migration
+
+Launcher no longer depends on the previous custom named-pipe length-prefixed protocol as the primary path.
+
+- Host publishes `StartupProgressMessage` through `lanmountain.launcher.startup-progress`.
+- Host publishes `LoadingStateMessage` through `lanmountain.launcher.loading-state`.
+- Launcher connects as a normal public IPC client and subscribes to those routed notifications.
+
+This means Splash/OOBE is now just another IPC consumer on the same base transport used by external integrators.
+
+Launcher-to-launcher de-duplication is intentionally separate from Host Public IPC. The active Launcher coordinator uses a per-user local pipe and `startup-attempt.json` heartbeat so secondary Launchers attach to the coordinator before any host process can be started twice.
+
+## Plugin Public IPC Contribution Model
+
+Plugins can contribute new external IPC services in two ways:
+
+1. Declarative registration
+   - `services.AddPluginPublicIpc<TContract, TImplementation>(...)`
+2. Advanced contributor
+   - Register `IPluginPublicIpcContributor`
+   - Use `IPluginPublicIpcBuilder` to contribute services from plugin DI
+
+At plugin load time the Host runtime:
+
+- discovers `PluginPublicIpcServiceRegistration`
+- executes `IPluginPublicIpcContributor`
+- validates that contributed contracts are `[IpcPublic]` interfaces
+- registers the resolved instances into `PublicIpcHostService`
+- emits `lanmountain.catalog.changed`
+
+Plugins can also inject `IExternalIpcNotificationPublisher` and translate internal DI/message-bus events into routed notifications such as:
+
+- `lanmountain.plugin.{pluginId}.attendance.updated`
+- `lanmountain.plugin.{pluginId}.status.changed`
+
+## Service Catalog
+
+The public catalog is represented by `PublicIpcCatalogSnapshot` and includes:
+
+- built-in and plugin-provided public services
+- contract type metadata
+- optional object id
+- owning `pluginId` for plugin services
+- declared notify IDs
+- current loaded/enabled plugin list
+
+This catalog is available through:
+
+- strong-typed public service `IPublicPluginCatalogService`
+- fixed request route `lanmountain.catalog.get`
+- routed notify `lanmountain.catalog.changed`
+
+## Current Limitations
+
+- Strong-typed proxy/joint support is .NET-first.
+- Plugin service removal is still restart-bound. New services can be added at runtime, but service removal is not yet modeled as a live unload contract.
+- Cross-language clients still need a .NET bridge or sidecar if they want to consume `[IpcPublic]` contracts directly.
+- Plugin process isolation is not part of this delivery. That remains future work.