docs(architecture): record profile creator route retirement

2026-11-10 02:17:22 +08:00 · 2026-09-04 22:31:26 +08:00
parent 88baffa876
commit 6a70075fba
3 changed files with 183 additions and 0 deletions
@@ -0,0 +1,5 @@
+# Bilingual-pair consistency record: the git blob hash of each side as of the last
+# confirmed-consistent state. Both languages carry equal authority. Update both files
+# and re-record their hashes with git hash-object after editing either side.
+2026-09-04-obsolete-profile-creator-route.md: 9bdb8020100af93bc8bfd9607c24fb7e93a5903a
+2026-09-04-obsolete-profile-creator-route.zh.md: 9700409ebde7c666e91c7b17913f6f68b678c3bd
@@ -0,0 +1,89 @@
+# Agent Note: Retire the obsolete Profile creator route
+
+Status: proposed
+
+English | [中文](2026-09-04-obsolete-profile-creator-route.zh.md)
+
+## Problem
+
+`POST /api/desktop/profiles/create-window` was added for the old boot-recovery page. It let Renderer code ask the Electron Host to open `ProfileCreateWindow`:
+
+```mermaid
+flowchart LR
+  Recovery[Old boot-recovery UI] -. removed caller .-> Route[POST profiles/create-window]
+  Route --> Handler[Route handler]
+  Handler --> Controller[DesktopSettingsController]
+  Controller --> Bootstrap[Bootstrap callback]
+  Bootstrap --> Runtime[Desktop Runtime]
+  Runtime --> Window[ProfileCreateWindow]
+
+  Tray[Tray] --> Runtime
+  Startup[Startup recovery] --> Window
+```
+
+The boot-recovery page later changed to a single "Open Recovery Mode" action. Its Profile creator call was removed, but the route and every pass-through behind it remained.
+
+Current Profile entry points do not use this chain:
+
+- the tray calls `DesktopRuntime.openProfileCreateWindow()` directly;
+- startup recovery constructs `ProfileCreateWindow` directly;
+- Client settings creates Profile data through `POST /api/desktop/profiles/create`.
+
+The desktop settings HTTP interface is private. `create-window` is not exposed by the Client settings module and has no documented external contract.
+
+## Decision
+
+Remove the `create-window` route and the implementation used only to carry that request:
+
+- the path constant and request/response types;
+- the route handler;
+- `DesktopSettingsController.openProfileCreator()`;
+- the bootstrap `openProfileCreator` callback;
+- route registration and route-specific tests.
+
+Stable and Beta must make the same change.
+
+Keep `ProfileCreateWindow`, the tray and startup-recovery entry points, and `POST /api/desktop/profiles/create`.
+
+After the change, window ownership stays in Electron and Profile data creation keeps its existing interface:
+
+```mermaid
+flowchart LR
+  Tray[Tray] --> Runtime[Desktop Runtime]
+  Runtime --> Window[ProfileCreateWindow]
+  Startup[Startup recovery] --> Window
+
+  Settings[Client settings] --> Create[POST profiles/create]
+
+  Renderer[Renderer-to-Electron open-window route]:::removed
+  classDef removed fill:#7f1d1d,color:#fff,stroke:#450a0a,stroke-width:2px,stroke-dasharray:5 5;
+```
+
+## Deletion test
+
+The route handler, controller method, and bootstrap callback do not hide policy or reusable behavior. Each layer forwards the same operation to the next one. Deleting the chain makes its complexity disappear; no caller needs a replacement and no implementation moves elsewhere.
+
+The useful modules remain in place. `ProfileCreateWindow` still owns the native creation flow, while the Desktop Runtime remains the interface used by native callers that need to open it.
+
+## Unchanged behavior
+
+- Tray users can still open the native Profile creator.
+- Startup recovery can still open the native Profile creator.
+- Client settings can still create Profile data.
+- Profile validation, persistence, selection, and restart behavior do not change.
+- The pinned upstream checkout remains unmodified.
+
+## Compatibility
+
+A repository-external caller that hard-codes the private `create-window` path will receive `404` after this change. The path has never been a supported public interface, so no compatibility adapter or deprecation period is added.
+
+## Verification plan
+
+- Confirm that neither desktop package contains the old path or its route-specific symbols.
+- Run the affected route, boot-recovery, and plugin tests in Stable and Beta.
+- Run root typecheck and build.
+- Run the architecture and bilingual-document checks.
+
+## Consequences
+
+Renderer code no longer has an HTTP command for opening this native window. Future native Profile entry points must call the Electron-owned Profile interface instead of restoring a private Renderer-to-Electron pass-through.
@@ -0,0 +1,89 @@
+# Agent Note：移除废弃的 Profile 创建窗口路由
+
+状态：拟议
+
+[English](2026-09-04-obsolete-profile-creator-route.md) | 中文
+
+## 问题
+
+`POST /api/desktop/profiles/create-window` 最初供旧版启动恢复页面使用。Renderer 通过它请求 Electron Host 打开 `ProfileCreateWindow`：
+
+```mermaid
+flowchart LR
+  Recovery[旧版启动恢复页面] -. 调用方已删除 .-> Route[POST profiles/create-window]
+  Route --> Handler[路由处理器]
+  Handler --> Controller[DesktopSettingsController]
+  Controller --> Bootstrap[bootstrap 回调]
+  Bootstrap --> Runtime[Desktop Runtime]
+  Runtime --> Window[ProfileCreateWindow]
+
+  Tray[托盘] --> Runtime
+  Startup[启动恢复] --> Window
+```
+
+启动恢复页面后来改成了单一的“打开恢复模式”操作。原来的 Profile 创建窗口调用被删除，路由及其后面的逐层转发却保留了下来。
+
+当前的 Profile 入口不使用这条链：
+
+- 托盘直接调用 `DesktopRuntime.openProfileCreateWindow()`；
+- 启动恢复直接创建 `ProfileCreateWindow`；
+- Client 设置页通过 `POST /api/desktop/profiles/create` 创建 Profile 数据。
+
+Desktop settings HTTP interface 是私有接口。Client settings module 没有暴露 `create-window`，项目也没有把它记录为对外契约。
+
+## 决策
+
+删除 `create-window` 路由，以及只为转发该请求而存在的实现：
+
+- 路径常量和请求、响应类型；
+- 路由处理器；
+- `DesktopSettingsController.openProfileCreator()`；
+- bootstrap 的 `openProfileCreator` 回调；
+- 路由注册和只覆盖这条路由的测试。
+
+Stable 和 Beta 同步修改。
+
+保留 `ProfileCreateWindow`、托盘与启动恢复入口，以及 `POST /api/desktop/profiles/create`。
+
+修改后，窗口所有权留在 Electron，Profile 数据创建继续使用现有 interface：
+
+```mermaid
+flowchart LR
+  Tray[托盘] --> Runtime[Desktop Runtime]
+  Runtime --> Window[ProfileCreateWindow]
+  Startup[启动恢复] --> Window
+
+  Settings[Client 设置页] --> Create[POST profiles/create]
+
+  Renderer[Renderer 到 Electron 的开窗路由]:::removed
+  classDef removed fill:#7f1d1d,color:#fff,stroke:#450a0a,stroke-width:2px,stroke-dasharray:5 5;
+```
+
+## 删除测试
+
+路由处理器、controller method 和 bootstrap callback 没有隐藏策略，也没有提供可复用行为。每一层都只是把同一个操作交给下一层。删掉整条链后，复杂度随之消失；没有调用方需要替代实现，也没有 implementation 被转移到别处。
+
+有实际作用的 module 继续保留。`ProfileCreateWindow` 仍负责原生创建流程，Desktop Runtime 仍是需要打开该窗口的原生调用方所使用的 interface。
+
+## 保持不变
+
+- 托盘仍可打开原生 Profile 创建窗口。
+- 启动恢复仍可打开原生 Profile 创建窗口。
+- Client 设置页仍可创建 Profile 数据。
+- Profile 校验、持久化、选择和重启行为不变。
+- pinned upstream checkout 不做修改。
+
+## 兼容性
+
+仓库外如果有代码硬编码调用私有 `create-window` 地址，修改后会收到 `404`。该地址从未是受支持的公开 interface，因此不增加兼容 adapter，也不设置弃用期。
+
+## 验证计划
+
+- 确认两套 desktop package 都不再包含旧路径和路由专属符号。
+- 在 Stable 和 Beta 中运行受影响的路由、启动恢复和插件测试。
+- 运行根目录 typecheck 和 build。
+- 运行 architecture 与双语文档检查。
+
+## 后果
+
+Renderer 不再持有用于打开该原生窗口的 HTTP 命令。以后新增原生 Profile 入口时，应调用由 Electron 侧持有的 Profile interface，而不是重新增加 Renderer 到 Electron 的私有透传链。