chore: initialize qiming workspace repository

qimingclaw/crates/agent-electron-client/docs/REG-FLOW.md

@@ -0,0 +1,117 @@
+# reg 调用流程说明
+
+## 概述
+
+`reg` 接口（`POST /api/sandbox/config/reg`）用于同步本地配置到后端，并获取最新的服务器配置（`serverHost`/`serverPort`）。**所有启动服务的场景都必须先调用 reg，返回后再启动服务**，确保 lanproxy 使用最新的代理服务器地址。
+
+---
+
+## 统一流程
+
+```
+reg 调用 → mcpProxy → agent → fileServer → lanproxy
+```
+
+**核心原则**：reg 必须在 lanproxy 启动之前完成，因为 lanproxy 依赖 reg 返回的 `serverHost`/`serverPort`。
+
+---
+
+## 各场景流程
+
+| 场景 | 触发位置 | 流程 |
+|------|----------|------|
+| **登录** | `ClientPage.handleLogin` | `loginAndRegister` → **reg** → mcpProxy → agent → fileServer → lanproxy |
+| **启动全部** | `ClientPage.handleStartAll` | **reg** → mcpProxy → agent → fileServer → lanproxy |
+| **手动启动单个** | `ClientPage.handleStartServiceManual` | 直接启动指定服务（不调用 reg） |
+| **自动重连** | `App.tsx autoReconnect` | **reg** → mcpProxy → agent → fileServer → lanproxy |
+| **退出登录** | `ClientPage.handleLogout` | 不调用 reg，停止所有服务 |
+
+**说明**：手动启动单个服务时不调用 reg，因为用户通常在已登录状态下操作，配置已是最新。
+
+---
+
+## 代码位置
+
+| 场景 | 文件 | 函数 |
+|------|------|------|
+| 登录 | `src/renderer/components/pages/ClientPage.tsx` | `handleLogin` |
+| 启动全部 | `src/renderer/components/pages/ClientPage.tsx` | `handleStartAll` |
+| 手动启动单个 | `src/renderer/components/pages/ClientPage.tsx` | `handleStartServiceManual` |
+| 自动重连 | `src/renderer/App.tsx` | `autoReconnect` (useEffect) |
+| reg 实现 | `src/renderer/services/core/auth.ts` | `syncConfigToServer` |
+| 服务启动 | `src/renderer/components/pages/ClientPage.tsx` | `handleStartService` |
+
+---
+
+## reg 接口参数
+
+```typescript
+interface ClientRegisterParams {
+  username: string;
+  password: string;        // 手动登录时传入，自动认证时为空字符串
+  savedKey?: string;       // 持久化密钥，跨会话有效（用于自动认证）
+  deviceId?: string;
+  sandboxConfigValue: {
+    hostWithScheme: string;
+    agentPort: number;      // 从 step1_config 读取
+    vncPort: number;
+    fileServerPort: number; // 从 step1_config 读取
+    apiKey?: string;
+    maxUsers?: number;
+  };
+}
+```
+
+**注意**：密码不持久化保存。首次登录后，后续自动认证仅依赖 `savedKey`。
+
+## reg 接口返回
+
+```typescript
+interface ClientRegisterResponse {
+  id: number;
+  configKey: string;
+  serverHost?: string;     // lanproxy 连接地址
+  serverPort?: number;     // lanproxy 连接端口
+  online: boolean;
+  name: string;
+  token?: string;          // webview cookie 同步用
+  // ...
+}
+```
+
+---
+
+## 状态管理
+
+### Loading 状态
+
+- **不使用全局 loading**（已移除 `regSyncing` 状态和 "正在同步配置..." overlay）
+- 使用服务项局部 loading（`startingServices` Set），覆盖 reg + 启动整个流程
+
+### 防止重复启动
+
+- 登录流程调用 `onLoginStarted()` 设置内存变量 `loginStartedRef.current = true`
+- App.tsx 自动重连检查该内存变量，若为 true 则跳过（同一会话内有效，不持久化）
+
+---
+
+## 失败处理
+
+| 场景 | reg 失败时行为 |
+|------|---------------|
+| 登录 | 继续启动服务（使用本地已保存配置） |
+| 启动全部 | 继续启动服务（使用本地已保存配置） |
+| 手动启动单个 | 不调用 reg，直接启动 |
+| 自动重连 | 显示 notification，使用本地配置尝试启动 |
+
+**设计原则**：reg 失败不应阻止服务启动，允许用户在离线环境下使用。
+
+---
+
+## 相关文档
+
+- [review-reg-and-autoreconnect.md](./review-reg-and-autoreconnect.md) - 历史代码审查记录
+
+---
+
+*最后更新：2026-03-19*