timeline-desktop/README.md

# Timeline 桌面客户端

> 记录生活中的每一个精彩时刻 - 桌面端应用

## 📖 项目简介

Timeline 桌面客户端是基于 Electron 构建的跨平台桌面应用，支持 Windows、macOS 和 Linux 系统。提供完整的离线支持、自动更新、系统托盘等功能。

## 🛠️ 技术栈

| 技术 | 版本 | 说明 |
|-----|------|------|
| Electron | 28.x | 跨平台桌面应用框架 |
| Electron Vite | 2.x | Electron 构建工具 |
| TypeScript | 5.x | 类型安全 |
| Electron Builder | 24.x | 打包与分发 |
| Electron Updater | 6.x | 自动更新 |

## 📁 项目结构

```
timeline-desktop/
├── src/
│   ├── main/                    # 主进程代码
│   │   ├── main.ts              # 主进程入口
│   │   └── preload.ts           # Preload 脚本
│   └── renderer/                # 渲染进程（可选）
├── build/                       # 构建资源
│   ├── icon.ico                 # Windows 图标
│   ├── icon.icns                # macOS 图标
│   └── icon.png                 # Linux 图标
├── release/                     # 打包输出目录
├── package.json
├── electron.vite.config.ts      # Vite 配置
└── tsconfig.json
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.x
- npm >= 9.x 或 pnpm >= 8.x

### 安装依赖

```bash
# 使用 npm
npm install

# 或使用 pnpm
pnpm install
```

### 开发模式

```bash
# 启动开发服务器
npm run dev
```

开发模式下，应用会自动加载 `http://localhost:8080`（Web 前端开发服务器）。

### 构建打包

```bash
# 构建所有平台
npm run build
npm run dist

# 仅构建 Windows
npm run dist:win

# 仅构建 macOS
npm run dist:mac

# 仅构建 Linux
npm run dist:linux
```

## 📦 打包输出

打包完成后，安装包位于 `release/` 目录：

```
release/
├── win-unpacked/               # Windows 免安装版
├── Timeline Setup 1.0.0.exe    # Windows 安装包
├── Timeline-1.0.0.dmg          # macOS 安装包
├── Timeline-1.0.0.AppImage     # Linux AppImage
└── timeline-desktop_1.0.0_amd64.deb  # Linux DEB 包
```

## ⚙️ 配置说明

### 应用配置 (package.json)

```json
{
  "build": {
    "appId": "com.timeline.desktop",
    "productName": "Timeline",
    "directories": {
      "output": "release"
    },
    "win": {
      "icon": "build/icon.ico",
      "target": ["nsis"]
    },
    "mac": {
      "icon": "build/icon.icns",
      "target": ["dmg", "zip"]
    },
    "linux": {
      "icon": "build/icon.png",
      "target": ["AppImage", "deb"]
    }
  }
}
```

### 环境变量

| 变量名 | 说明 | 默认值 |
|-------|------|-------|
| NODE_ENV | 运行环境 | development |
| API_URL | API 地址 | https://api.timeline.com |

## 🔄 自动更新

### 配置自动更新

1. 在 `package.json` 中配置发布地址：

```json
{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "your-github-username",
      "repo": "timeline-desktop"
    }
  }
}
```

2. 在 GitHub 创建 Release 并上传安装包

3. 应用启动时会自动检查更新

### 更新流程

```
应用启动 → 检查更新 → 发现新版本 → 提示用户 → 下载更新 → 安装更新
```

## 🔌 IPC 通信 API

### 渲染进程可用 API

```typescript
// 获取应用版本
const version = await window.electronAPI.getVersion();

// 获取操作系统平台
const platform = await window.electronAPI.getPlatform();

// 检查更新
const updateInfo = await window.electronAPI.checkUpdate();

// 下载更新
await window.electronAPI.downloadUpdate();

// 安装更新
await window.electronAPI.installUpdate();

// 打开外部链接
await window.electronAPI.openExternal('https://timeline.com');

// 监听更新事件
window.electronAPI.onUpdateAvailable((info) => {
  console.log('发现新版本:', info.version);
});

window.electronAPI.onUpdateDownloaded((info) => {
  console.log('更新已下载:', info.version);
});
```

## 🖥️ 功能特性

### 系统托盘

- 最小化到托盘
- 托盘菜单快捷操作
- 点击托盘图标显示窗口

### 应用菜单

- 文件操作
- 编辑功能（撤销/重做/复制/粘贴）
- 视图控制（缩放/全屏）
- 帮助链接

### 安全特性

- Context Isolation 启用
- Node Integration 禁用
- 安全的 Preload 脚本

## 🔐 签名与公证

### Windows 代码签名

```bash
# 设置环境变量
set CSC_LINK=path/to/certificate.pfx
set CSC_KEY_PASSWORD=your-password

# 打包时自动签名
npm run dist:win
```

### macOS 公证

```bash
# 设置环境变量
set APPLE_ID=your-apple-id
set APPLE_ID_PASSWORD=app-specific-password
set APPLE_TEAM_ID=your-team-id

# 打包并公证
npm run dist:mac
```

## 📋 后续拓展计划

### 短期计划 (1-2 个月)

| 功能 | 描述 | 优先级 |
|-----|------|-------|
| 离线模式 | 支持离线浏览和编辑 | P0 |
| 本地存储 | 数据本地缓存 | P0 |
| 快捷键 | 全局快捷键支持 | P1 |
| 多窗口 | 支持多窗口操作 | P1 |
| 深色模式 | 跟随系统深色模式 | P2 |

### 中期计划 (3-6 个月)

| 功能 | 描述 | 优先级 |
|-----|------|-------|
| 批量导入 | 批量导入本地照片/视频 | P1 |
| 本地备份 | 数据本地备份与恢复 | P1 |
| 剪贴板监听 | 自动识别剪贴板图片 | P2 |
| 文件拖放 | 拖放文件快速上传 | P2 |
| 系统通知 | 原生系统通知 | P2 |

### 长期计划 (6-12 个月)

| 功能 | 描述 | 优先级 |
|-----|------|-------|
| 插件系统 | 支持第三方插件 | P2 |
| 主题定制 | 自定义主题和样式 | P3 |
| 多语言 | 国际化支持 | P3 |
| 云同步 | 数据云同步 | P3 |

## 🐛 常见问题

### Q: 开发模式下白屏？

检查 Web 前端开发服务器是否启动：

```bash
cd ../timeline-frontend
pnpm dev
```

### Q: 打包后应用无法启动？

检查 `main.ts` 中的资源路径是否正确：

```typescript
// 生产环境应使用打包后的路径
mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));
```

### Q: 自动更新不生效？

1. 检查 `publish` 配置是否正确
2. 确保 GitHub Release 已发布
3. 检查网络连接

## 📞 技术支持

- 问题反馈: https://github.com/timeline/timeline-desktop/issues
- 文档地址: https://docs.timeline.com/desktop

## 📄 许可证

MIT License