# 如梦 — 架构文档

## 总览

```
iPhone (如梦.app)
  │
  ├─ HTTP ── Tailscale ── Mac (push.py :8795)
  │                          ├── /tmux/capture   ─→ tmux capture-pane
  │                          ├── /tmux/send      ─→ tmux send-keys
  │                          └── /health         ─→ 健康检查
  │
  └─ 网络层: ServerConfig → URLSession → push.py
```

## 文件清单

| 文件 | 职责 | 依赖 |
|------|------|------|
| `如梦App.swift` | @main 入口，WindowGroup → ContentView | ContentView |
| `ContentView.swift` | 页面路由 + 手势导航菜单 + ZStack 层级 | 所有页面 View |
| `ChatPlaceholderView.swift` | 聊天占位（待开发） | 无 |
| `TerminalView.swift` | tmux 终端 UI（黑底浅灰字） | TerminalViewModel |
| `TerminalViewModel.swift` | tmux 网络层：轮询 capture-pane + 发送 send-keys | ServerConfig |
| `ServerConfig.swift` | endpoint 列表 + 当前选中 + URL 构建 | UserDefaults |
| `SettingsView.swift` | 设置页：endpoint 管理 + 主题切换 | ServerConfig, EndpointChecker |
| `EndpointResolver.swift` | 异步 ping /health，返回每个 endpoint 状态 | ServerConfig |
| `ThemeManager.swift` | 白天/夜间两套色板定义 | UserDefaults |

## 数据流

### 1. 网络请求

```
TerminalView / SettingsView
  → ServerConfig.makeRequest(path:)
    → ServerConfig.activeHost (从 UserDefaults 读)
      → URLSession 请求 push.py
```

- `ServerConfig.endpoints` 是预定义列表，顺序可被 SettingsView 的上下箭头重排
- 重排结果持久化到 `endpoint_urls` / `endpoint_labels`（UserDefaults）
- `active_endpoint`（UserDefaults）决定当前用哪个
- `EndpointChecker` 定期 ping 所有 endpoint，更新状态灯（绿/红/灰）

### 2. 主题

```
SettingsView 点击「夜间/白天」
  → setTheme() → UserDefaults("active_theme")
    → ContentView 监听 UserDefaults.didChangeNotification
      → theme = currentTheme()
        → 所有颜色从 theme.bg / theme.text / theme.textDim 读取
```

- `AppTheme.dark` 和 `AppTheme.light` 各自定义完整色板
- 目前只有 dark 在用，light 是 placeholder

### 3. 菜单导航

```
用户左边缘右滑
  → DragGesture → menuX 跟踪手势
    → 松手 → snapTo(.open) 或 snapTo(.closed)
      → spring 动画 → menuX 归位
        → ContentView 根据 currentPage 切换页面
```

- `menuX` 是菜单唯一的状态源（-200 隐藏，0 打开，>0 弹性过冲）
- `menuOpen` 是辅助状态（控制触控条激活/禁用）
- 页面切换是 `@State currentPage` 驱动 `@ViewBuilder pageView`

## ZStack 层级（自上而下）

```
4. 左边缘触控条 (HStack 24pt) — allowsHitTesting(!menuOpen)
3. 页面标题 (VStack) — menuX < -150 时显示
2. 菜单层 (if menuX > -200):
   ├── 遮罩 Color.black 0.15 — allowsHitTesting(false)
   ├── 关闭热区 Color.clear.contentShape — onTapGesture → snapTo(.closed)
   └── 图标列 VStack — Button × 4，点击切换页面
1. 当前页面 (pageView) — Termina​lView / Chat / 阅读 / 设置
```

**规则**：
- 菜单打开时触控条失活，避免抢手势
- 遮罩背景不拦截触摸，关闭热区在图标列下面
- 图标列在最上层，按钮始终可点

## 各页面状态

| 页面 | 状态 | 备注 |
|------|------|------|
| 聊天 | 占位 | 纯黑 + "聊天" 文字，待开发 |
| 终端 | 完成 | tmux capture-pane 轮询 + send-keys 发送，带时间戳 |
| 阅读 | 占位 | 待开发 Coffee Time |
| 设置 | 开发中 | endpoint 管理 + 主题切换，功能可用但 UI 需继续 |

## 设计原则

- **单一状态源**：menuX 驱动菜单，currentPage 驱动页面，UserDefaults 驱动配置
- **无 Combine**：不用 @StateObject/@Published，用 @State + UserDefaults 通知
- **零第三方依赖**：纯 SwiftUI + Foundation
- **不向后兼容**：部署目标 iOS 26.4，不考虑旧版本 API
- **所有网络走 push.py**：不直连 DeepSeek，不引入新服务端

## 更新日志

- 2026-05-22 — 初始架构。ZStack 菜单导航 + endpoint 切换 + 主题系统骨架。