# dsh Mobile App 设计文档（手机远程连接 dsh）

> 结论先行：**做 PWA（移动 Web App），由 dsh 服务端自带、零额外部署**，已实现并通过手机视口实测。
> 团队私有工具不值得走应用商店分发；等需求稳定后再考虑用同一套 API 套原生壳。

---

## 1. 方案选型

| 方案 | 评价 |
|---|---|
| **A. PWA 移动 Web App（已实现）** | 服务端直接在 `GET /app` 托管页面，手机浏览器打开即用、"添加到主屏幕"后全屏运行。零安装、零上架、更新即刷新。单文件无外部依赖（LAN 内网也能用，不依赖 CDN） |
| B. Flutter / React Native 原生 App | 体验和推送能力更好，但要维护双端构建与分发（MDM/内测分发），对"管理设置和插件"这类低频管理场景过度 |
| C. 套壳 WebView（如 Capacitor） | 折中：复用 PWA 代码换原生分发与推送。作为二期可选 |

**PWA 与未来原生不冲突**：所有功能都走 §3 的 REST API，原生 App 只是换一个 UI 客户端。

---

## 2. 信息架构（已实现）

```
登录页
  ├─ 服务端地址（自动预填当前域名）
  ├─ 方式一：邀请码注册（新成员，POST /v1/tokens）
  └─ 方式二：粘贴已有 Token（admin 发放 / /v1/tokens/self 加签）

主界面（底部 4 Tab）
  ⚙ 设置    生效配置列表（团队/个人来源与版本号标签）、编辑值、新增项；
            顶部「📱 连接手机」卡片（admin）：展示连接二维码、邀请码复制、多网卡地址候选切换
  ⬇ 插件    插件列表（版本/渠道/sha256/大小）、下载制品、admin 发布与删除
  🛡 管理    仅 admin：创建成员（Token 只显示一次）、审计日志
  👤 我的    身份信息、Token 列表与撤销、退出登录
登录页    服务端地址 + 邀请码/Token；「📷 扫码连接」按钮（HTTPS 下可应用内扫码）；
          支持 dsh 桌面端生成的二维码深链 /app#invite=… 自动预填
```

交互细节：
- **冲突处理**：编辑保存带 `base_version`，遇 409 弹确认框展示"服务器已被他人更新"，用户可选强制覆盖（LWW）或放弃——与桌面客户端同一语义。
- **值即 JSON**：输入框接受 JSON 或普通文本，与服务端 `value_json` 模型一致。
- 权限自适应：非 admin 隐藏"管理"Tab、团队设置选项与插件删除按钮（服务端仍兜底校验）。

## 3. API 映射（全部复用现有服务端，零后端新增）

| App 功能 | API |
|---|---|
| 邀请码登录 | `POST /v1/tokens` |
| 身份 / 会话校验 | `GET /v1/me`（401 即回登录页） |
| 设置列表（合并视图 + ETag） | `GET /v1/settings` |
| 编辑/新增设置（乐观并发） | `PUT /v1/settings/{scope}/{key}` |
| 插件列表 / 制品下载 | `GET /v1/plugins`、`GET /v1/plugins/{id}/{ver}/download` |
| 发布 / 删除插件（admin） | `POST /v1/plugins/{id}`、`DELETE /v1/plugins/{id}/{ver}` |
| 成员管理 / 审计 / Token 撤销 | `POST /v1/users`、`GET /v1/audit`、`DELETE /v1/tokens/{hash}` |

## 4. 手机如何连上（按推荐顺序）

0. **扫码连接（最省事，已实现）**：桌面浏览器打开 `/app` 并用 admin 登录 → 设置 Tab → 「📱 连接手机」→ 手机**系统相机**对准二维码 → 自动打开本页并填好服务端地址与邀请码 → 输入用户名 → 连接。二维码内容由服务端 `GET /v1/connect/qr` 生成（深链 `http(s)://<地址>/app#invite=<邀请码>`，segno 渲染 SVG）；多网卡机器会在卡片里列出全部候选地址，点选即切换二维码。应用内扫码按钮仅在 HTTPS（或 localhost）下可用——LAN HTTP 环境浏览器禁止网页调用摄像头，系统相机是唯一稳定通道。

1. **同一 Wi-Fi/局域网（当前运行模式）**：手机浏览器打开 `http://<服务机IP>:8020/app（8000/8010 已被本机 Django 开发占用，dsh 固定用 8020）`。Windows 首次启动 uvicorn 会弹防火墙授权，勾选"专用网络"允许。
2. **异地团队 → Tailscale**：服务机与手机都装 Tailscale，手机访问 `http://<tailscale-ip>:8020/app`。零公网暴露，最推荐。
3. **公网 + HTTPS**：用仓库里的 docker compose（Caddy 自动证书绑定 `DSH_SYNC_DOMAIN`）。**PWA 的"添加到主屏幕"与 Token 存储在 HTTPS 下体验最稳**，纯 HTTP 下 iOS Safari 会限制部分能力。

连接后：iOS Safari → 分享 → "添加到主屏幕"；Android Chrome → 菜单 → "添加到主屏幕"，之后从桌面图标全屏进入。

## 5. 安全设计

- Token 只存手机 `localStorage`，随请求 Bearer 头发送；401 自动清会话回登录页。
- "我的"Tab 可随时**远程撤销**任意设备 Token（丢手机立刻处置）。
- admin 创建成员的 Token 只显示一次，提示立即复制。
- 传输安全依赖网络形态（§4）：公网必须走 compose + Caddy 的 HTTPS；LAN 内网 HTTP 可接受（团队私有数据 + 可随时撤销的 Token）。
- **DeepSeek API Key 依然只在各设备本地**，App 与服务端都不存（见 ARCHITECTURE.md §7）。

## 6. 后续路线（按需做，不建议一次性）

| 优先级 | 能力 | 说明 |
|---|---|---|
| ✅ 已完成 | 扫码连接 | 服务端生成含地址+邀请码的二维码（`/v1/connect/qr`，segno SVG），PWA 设置 Tab「连接手机」卡片展示；登录页支持 `#invite=` 深链自动预填 + 应用内扫码（BarcodeDetector，需 HTTPS） |
| ✅ 已完成 | 安卓 APK | `android/` 原生 WebView 壳，`bash android/build.sh` 构建；`/apk` 免登录安装页 + 下载二维码。见 ARCHITECTURE.md §12 |
| P1 | Service Worker 离线缓存 | 断网时仍可查看上次拉到的设置/插件清单 |
| P2 | Capacitor 套壳 | 复用本 PWA 换原生分发，获得推送能力 |
| P2 | 插件发布审核流 | 发布走"待审核"状态，admin 在手机上批准 |
| P3 | 推送通知（插件更新/审计告警） | 需要原生或统一推送服务，PWA Web Push 在国内生态不可靠 |

## 7. 已实现与已验证

- ✅ `GET /app`：服务端自带单文件 PWA（`server/dsh_sync/static/mobile.html`，无外部依赖）
- ✅ 扫码连接：`connect.py`（内网地址探测，RFC1918 优先）+ `GET /v1/connect/info` / `GET /v1/connect/qr`（admin-only）+ 设置 Tab「连接手机」卡片 + 登录页深链预填/应用内扫码
- ✅ 手机视口（390×844）实测：Token 登录 → 新增团队设置（写入 PG 成功）→ 插件列表/下载/发布 → 管理页审计日志渲染；连接二维码卡片渲染、候选地址切换、`#invite=` 深链预填实测通过
- ✅ 截图：`dsh-app-settings.png`、`dsh-app-plugins.png`、`dsh-app-admin.png`、`dsh-app-connect-qr.png`、`dsh-app-connect-phone.png`

## 8. 运维坑（2026-09-10 实测踩到并修复）

### 8.1 pytest 会洗掉生产库（已修）

`tests/conftest.py` 原先默认 `DSH_TEST_DATABASE_URL=postgresql://dsh@127.0.0.1:15433/postgres`
—— 与 `server-worker.cmd` 的生产 DSN **完全同一库**，且每个用例调 `db.reset_schema()`
执行 `DROP SCHEMA public CASCADE`。**跑一次 pytest，生产数据全没。**

现在的行为：

- 默认测试库 = 生产实例的同名库加 `_test` 后缀（`postgres_test`），不存在则自动 `CREATE DATABASE`；
- 若 `DSH_TEST_DATABASE_URL` 指向生产库，**直接拒绝运行**（`pytest.exit`，退出码 4），不靠注释约定；
- 测试库独立，`reset_schema` 只影响它自己。

数据被洗后用 `python data/restore_state.py` 恢复（幂等）：重建 bootstrap admin token、
按磁盘上的制品重算 sha256 重建 demo 插件行、清理测试残留用户。

### 8.2 重复 worker 自旋刷日志（已修）

`server-worker.cmd` 有个 `:loop` + `timeout /t 3 /nobreak` 的自动重启循环。两个问题叠在一起：

1. **`timeout` 在无控制台的分离进程里不等待** —— 实测 `timeout /t 3` 约 1.2s 就返回，
   循环基本没有节流；
2. **没有单例守卫** —— 第二个 worker 启动 uvicorn 绑定失败、立即退出、马上重来，
   每次迭代写两行日志，实测 **~1760 行/秒**，足以吃满磁盘。

修复：worker 启动前用 `netstat` 检查 `192.168.5.2:8020` 是否已被监听，是则 sleep 20s 空转；
用 `Start-Sleep` 替代 `timeout`；连续 5 次退出后退避 60s；启动时轮转超过 5MB 的日志
（`server.log` → `server.1.log`）。

同时 `start-server.bat` 也加了同样的前置检查并拒绝重复启动。注意两处的匹配串都必须是
**`192.168.5.2:8020`** 而不是 `:8020` —— Django 开发栈占着 `127.0.0.1:8020`，
只匹配端口号会让 dsh 误判"已在运行"而永远不启动。

### 8.3 验收要点（真机复测用）

`dsh` 固定绑 LAN IP，**本机回环访问不到**（`127.0.0.1:8020` 永远是 Django）：

| 检查项 | 命令 | 期望 |
|---|---|---|
| 服务健康 | `curl http://192.168.5.2:8020/healthz` | `{"status":"ok",...}` |
| PWA 可达 | `curl -o /dev/null -w "%{http_code}" http://192.168.5.2:8020/app` | `200` |
| 连接信息 | `curl -H "Authorization: Bearer <admin-token>" .../v1/connect/info` | `base_urls` + `invite_code` |
| 二维码 | `.../v1/connect/qr?host=192.168.5.2` | 2069 字节 `image/svg+xml` |
| 日志不再暴走 | 隔 5s 对比 `logs/server.log` 大小 | 增长 ≈0 |
| 单一实例 | `netstat -ano \| findstr "192.168.5.2:8020"` | 只有 1 条 LISTENING |