# iphonetodesk

**Repository Path**: a-liu232/iphonetodesk

## Basic Information

- **Project Name**: iphonetodesk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# iPhone To Desk

一个面向拍摄辅助场景的局域网实时取景工具。

它把手机浏览器里的摄像头画面实时传到 Pad 或另一台显示设备，在大屏上叠加姿势参考图、调整透明度，并从显示端远程触发拍照。当前形态是一个 WebRTC + 局域网部署的 MVP，目标是先验证核心拍摄流程，而不是先做原生 App。

## 产品概览

`iPhone To Desk` 解决的是“手机负责拍，平板负责看和引导”的问题。

典型使用场景：

- 自拍或他拍时，需要一张姿势参考图叠在实时画面上进行对位
- 手机架得较远，小屏幕难以看清构图，希望在更大的屏幕上查看
- 拍摄者希望在 Pad 上远程控制拍照，而不是来回走到手机前操作
- 希望快速验证产品体验，不依赖 App Store 上架或原生开发链路

## 核心能力

- 手机浏览器采集摄像头画面，并通过 WebRTC 实时推送到 Pad 端
- Pad 端显示实时画面，并叠加姿势参考图
- 姿势图可切换、可调透明度，可辅助对位
- Pad 端可控制镜像、旋转、网格和远程拍照
- 手机端接收远程拍照指令后，本地截帧并弹出保存界面
- 显示端和拍照端通过同一个 `roomId` 配对
- 服务端自动生成本地 HTTPS 证书，并提供 `/setup` 引导页

## 用户流程

### 1. 设备角色

- 手机端：打开浏览器相机页，负责采集和拍照保存
- Pad 端：打开引导界面，负责预览、姿势叠加和远程控制
- 局域网服务端：负责 HTTPS、信令中转、姿势数据和静态资源

### 2. 使用流程

1. 启动本地服务端，生成 HTTPS 证书并暴露 `/setup` 引导页
2. 手机端按引导页完成证书信任后，打开 `/iphone` 页面
3. Pad 端打开主界面，自动等待实时视频流
4. 选择姿势图并调整透明度，让参考图叠在实时画面上
5. 在 Pad 端点击拍照，手机端本地生成截图并保存

## 当前产品形态

这是一个为“拍摄辅助链路”而设计的 MVP，不是完整摄影工作流产品。

当前已经覆盖的关键体验：

- 实时取景
- 姿势参考图叠加
- 透明度调节
- 基础构图辅助
- 远程拍照

当前没有覆盖或仍然比较初级的部分：

- 云端相册、历史作品管理
- 多人协作或多机位调度
- 用户系统、任务系统、拍摄项目管理
- 完整的原生 App 体验
- 后台持续取流能力

## 技术方案

### 为什么先用 Web 方案

这个项目优先验证的是产品体验，而不是原生能力边界。

相比原生 App，当前 Web 方案的优势是：

- 手机上无需安装 App，浏览器即可进入
- 开发迭代更快，适合高频试错
- WebRTC 足以满足局域网低延迟视频传输
- Node.js 服务端就能同时承载信令、证书和静态资源

### 架构概览

- 手机端：`iphone-page/`
  负责摄像头访问、本地预览、WebRTC 发流、接收拍照指令
- Pad 端：`pad-app/`
  负责视频显示、姿势图叠加、透明度调节和控制栏交互
- 服务端：`server/`
  负责 HTTPS、Socket.IO 信令中转、姿势数据 API 和 `/setup` 页面

### 通信链路

- 视频流：手机端与 Pad 端通过 WebRTC P2P 直连
- 控制消息：通过 Socket.IO 中转 `offer / answer / ICE / capture`
- 静态资源：服务端提供姿势图片、Pad 页面和手机页面

## 功能边界与限制

使用前需要明确这几个现实约束：

- 设备必须在同一局域网内
- iPhone Safari 在非 `localhost` 下访问摄像头必须使用 HTTPS
- iPhone 首次使用时需要安装并信任本地证书
- 手机端浏览器不能长期切后台，否则系统会暂停摄像头
- 远程拍照保存发生在手机端，本项目当前不做服务端归档
- 局域网质量会直接影响 WebRTC 建联稳定性和延迟

## 适用设备与环境

- Node.js 18+
- 一台运行本地服务的电脑
- 一台手机
  推荐目标场景：iPhone Safari
  当前也可用 Android 浏览器调试手机页面
- 一台 Pad 或另一台可显示页面的设备
  开发态可直接打开 Pad Web 页面

## 项目结构

```text
iphonetodesk/
├── server/                 # HTTPS + Socket.IO + poses API
├── iphone-page/            # 手机相机页面
├── pad-app/                # Pad 端 Vue 应用
├── docs/                   # 方案与架构文档
└── scripts/                # 辅助脚本
```

更细一点的职责划分：

- `server/index.js`
  提供 HTTPS 服务、证书分发、`/setup`、Socket.IO 和姿势数据接口
- `iphone-page/webrtc.js`
  手机端取流、建联、重连、缩放控制
- `iphone-page/capture.js`
  手机端远程拍照与保存交互
- `pad-app/src/components/VideoStream.vue`
  实时画面与姿势图叠加区域
- `pad-app/src/components/ControlBar.vue`
  透明度、镜像、旋转、网格、拍照操作
- `pad-app/src/composables/useWebRTC.js`
  Pad 端 WebRTC 接收逻辑

## 运行方式

### 方式一：一键启动本地模式

适合当前主流程联调，也是最推荐的启动方式。

Windows：

```bash
start.bat --mode local shoot-101
```

macOS / Linux：

```bash
./start.sh --mode local shoot-101
```

启动后脚本会自动：

- 安装 `server/` 和 `pad-app/` 依赖
- 构建显示端静态资源
- 启动 Node.js 统一服务
- 输出同一个 `roomId` 下的接入页、显示端和拍照端链接

### 方式二：一键启动云端模式

适合你后面把项目迁到云服务器时使用。

Windows：

```bash
start.bat --mode cloud shoot-101
```

macOS / Linux：

```bash
./start.sh --mode cloud shoot-101
```

云端模式会额外读取：

- `server/.env.cloud`
- `server/.env.cloud.local`

### 方式三：开发态分别启动

如果你需要单独调前端或调试服务端，也可以分开启动：

```bash
cd server
npm install
npm run start:local

cd ../pad-app
npm install
npm run dev
```

其中：

- 接入页：`http://你的局域网IP:3001/setup`
- 正式显示端：`https://你的局域网IP:3000/?roomId=你的房间号`
- 拍照端：`https://你的局域网IP:3000/iphone?roomId=你的房间号`
- 前端开发页：`http://你的局域网IP:5173/?roomId=你的房间号`

## 姿势资源管理

姿势图资源放在 `server/public/poses/`。

姿势数据由 `server/poses.json` 描述，例如：

```json
{
  "id": 7,
  "name": "自定义姿势",
  "description": "描述说明",
  "image": "/poses/custom.jpg",
  "category": "站姿"
}
```

Pad 端读取 `image` 字段后，会把它作为叠加层放到实时画面上。

## 常见问题

### 手机打不开摄像头

- 确认访问的是 `https://.../iphone`
- iPhone 场景下确认已安装并信任 `ca.pem`
- 确认浏览器已授予摄像头权限

### Pad 端只看到占位态，收不到视频

- 确认手机端页面已经显示本地预览
- 确认两端在同一局域网
- 确认服务端 3000 端口可访问
- 检查是否被路由器 AP 隔离影响

### 远程拍照可以触发，但实时视频不稳定

- 说明控制链路正常，重点排查 WebRTC 建联和局域网质量
- 优先看日志中的“已向显示端发送 offer”“已发送 answer”“已收到远端视频流”

### 手机切到后台后画面中断

- 这是移动浏览器和系统限制，不是业务层逻辑错误
- 当前产品假设手机端始终保持前台和常亮

## 文档索引

- [当前实现方案](docs/当前实现方案.md)
- [技术架构](docs/技术架构.md)
- [环境变量与启动模式](server/环境与启动模式.md)
- [实现方案（初版）](docs/实现方案(初版).md)
- [初版方案问题点](docs/初版方案问题点.md)

## 项目定位总结

这不是一个“启动命令集合”，而是一个围绕拍摄辅助体验构建的产品原型。

它的核心价值不在于“把手机视频传到平板”这件事本身，而在于把以下几个动作连成一个完整闭环：

- 手机负责拍
- 大屏负责看
- 姿势图负责引导
- Pad 负责控制
- 手机负责最终保存

README 应该帮助读者先理解这个闭环，再决定是否继续看部署细节。当前版本已经按这个方向重构。