# 应用发版操作手册

> 本文档描述美家卡智影桌面应用的完整发版流程。
> 采用 Tauri 官方 updater 插件 + FastAPI 动态更新 JSON + 七牛云存储方案。

---

## 前置条件

### 1. 签名密钥（已生成，只需确认存在）

```bash
ls ~/.tauri/meijiaka.key ~/.tauri/meijiaka.key.pub
```

- 私钥 `~/.tauri/meijiaka.key`：构建时用于签名，**不要泄露**
- 公钥内容：已写入 `tauri-app/src-tauri/tauri.conf.json` 的 `plugins.updater.pubkey`

### 2. 七牛云环境变量（复用素材上传配置）

```bash
# python-api/.env
QINIU_ACCESS_KEY=xxx
QINIU_SECRET_KEY=xxx
QINIU_VIDEO_BUCKET=media-liche
QINIU_VIDEO_DOMAIN=media.liche.cn
```

### 3. 后端已部署

```bash
# 测试环境
cd python-api
docker compose -f docker-compose.test.yml up -d --build

# 验证
curl https://dev.tapi.meijiaka.cn/api/v1/system/health
```

> 数据库表会在 Docker 启动时自动创建（`alembic upgrade head` 已内置于容器启动命令），无需手动执行迁移。

---

## 发版流程

### 步骤 1：修改版本号

三个文件版本号必须完全一致：

```bash
cd tauri-app

# 1. package.json
npm version 1.6.0 --no-git-tag-version

# 2. Cargo.toml
# 手动修改：src-tauri/Cargo.toml → version = "1.6.0"

# 3. tauri.conf.json
# 手动修改：src-tauri/tauri.conf.json → "version": "1.6.0"
```

### 步骤 2：构建

```bash
cd tauri-app
export TAURI_SIGNING_PRIVATE_KEY="$HOME/.tauri/meijiaka.key"
npm run tauri build
```

构建产物（含签名文件）位于 `src-tauri/target/release/bundle/`：

| 平台 | 安装包 | 签名文件 |
|------|--------|----------|
| macOS | `macos/*.app.tar.gz` | `.app.tar.gz.sig` |
| Windows | `nsis/*-setup.exe` | `.exe.sig` |
| Linux | `appimage/*.AppImage` | `.AppImage.sig` |

> **注意**：不同平台的构建产物和签名文件是 Tauri 自动生成的。若只发 macOS 版本，只需上传 macOS 的包即可；Windows/Linux 用户不会收到更新提示。

### 步骤 3：发布

```bash
cd python-api

python scripts/publish_release.py \
  --version 1.6.0 \
  --notes "修复视频导出崩溃\n优化启动速度" \
  --bundle-dir ../tauri-app/src-tauri/target/release/bundle
```

脚本执行逻辑：

1. 扫描 `bundle/` 目录，匹配 `.sig` 文件和对应的安装包
2. 上传安装包到七牛云 `media-liche` bucket 的 `releases/{version}/` 路径
3. 读取 `.sig` 文件内容（Ed25519 签名）
4. 调用后端 API `POST /api/v1/update/releases`，将版本信息写入数据库

> 若后端在本地 Docker（端口 8081），加 `--api-url http://localhost:8081`

---

## 验证发版

### API 验证

```bash
curl "https://dev.tapi.meijiaka.cn/api/v1/update/check?version=1.5.15&target=darwin&arch=aarch64"
```

正常返回示例：

```json
{
  "version": "1.6.0",
  "notes": "修复视频导出崩溃\n优化启动速度",
  "pub_date": "2026-05-15T10:00:00+00:00",
  "mandatory": false,
  "platforms": {
    "darwin-aarch64": {
      "url": "https://media.liche.cn/releases/1.6.0/xxx.app.tar.gz",
      "signature": "-----BEGIN SIGNATURE-----\nxxx\n-----END SIGNATURE-----"
    }
  }
}
```

### 客户端验证

1. 启动桌面应用，3 秒后自动检查更新
2. 若当前版本低于数据库最新版本，弹出更新对话框
3. 或在**设置 → 系统更新**中手动点击"检查更新"

---

## 回滚操作

若发出去的版本有问题，删除版本记录即可：

```bash
# 测试/本地环境
docker exec meijiaka-zy-api psql $DATABASE_URL \
  -c "DELETE FROM app_releases WHERE version = '1.6.0';"

# 或进入服务器直接执行
psql $DATABASE_URL -c "DELETE FROM app_releases WHERE version = '1.6.0';"
```

用户下次检查更新时会自动拿到上一个版本。

---

## 跨平台说明

| 平台 | 安装包格式 | 安装行为 | 是否需要重启 |
|------|-----------|---------|------------|
| macOS | `.app.tar.gz` | 解压替换 `.app` bundle | 是 |
| Windows | `.exe` / `.msi` | 运行安装程序替换 | 是（安装程序强制退出应用）|
| Linux | `.AppImage` | 替换可执行文件 | 是 |

Tauri updater 插件已内置跨平台安装逻辑，前端代码无需区分平台。

---

## 文件清单

| 文件 | 作用 |
|------|------|
| `~/.tauri/meijiaka.key` | 私钥（签名用，勿泄露） |
| `tauri-app/src-tauri/tauri.conf.json` | updater 配置：公钥 + endpoint URL |
| `python-api/scripts/publish_release.py` | 发版脚本（扫描 .sig → 上传七牛云 → 写数据库） |
| `python-api/app/api/v1/update.py` | 后端更新检查 API |
| `python-api/app/models/update.py` | 数据库模型（`mjk_app_releases` / `mjk_app_release_packages`） |
