> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked.

# Fonrey 客户端发布管理技术方案

**版本**: 1.0  
**项目**: Fonrey 房产经纪管理系统  
**技术栈**: Django 4.x + HTMX + PostgreSQL 16（public schema）+ Redis + Celery + Electron + electron-updater + Cloudflare R2/CDN  
**关联 PRD**: `PRD/发布管理/客户端发布管理模块PRD.md`（v1.2）  
**关联数据模型**: `DATA_MODEL/DATA_MODEL_PUBLIC.md`（`client_releases` / `client_heartbeats`）  
**关联枚举字典**: `DATA_MODEL/ENUMS.md`（含中文显示标签）  
**关联契约规范**: `TECH_STACK/API_CONTRACT.md`  
**最后更新**: 2026-04-30

---

## 变更历史

| 日期 | 变更人 | 变更内容 |
|---|---|---|
| 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |

## 一、文档定位与边界

本文件定义客户端发布管理模块（`apps/release`）的实现口径：

1. Electron 客户端壳应用与运行时安全边界
2. EV 代码签名与构建发布链路
3. Heartbeat 上报与版本分布统计方案
4. 自动升级、强制升级与失败回退策略
5. 客户端下载完整性校验（SHA256）
6. R2 版本资产管理（对象键、状态流转、回滚）
7. 公司下载站点（官网）分发方案
8. 便携版（Portable ZIP）落地方案

> 本文件不重复 DDL。表结构与索引以 `DATA_MODEL_PUBLIC.md` 为唯一权威。

---

## 二、范围定义（以 PRD v1.2 为准）

### 2.1 P0 必须覆盖

- Windows 客户端（win32）下载安装与登录使用
- 平台运营后台版本管理（草稿/发布/下线、普通/强制）
- 自动更新（启动 + 每 4 小时检测）
- SHA256 完整性校验（EXE/ZIP）
- Heartbeat（启动时上报）与版本分布/租户活跃统计
- 官方下载页（公司站点）
- 便携版 ZIP（可选上传、受控分发）

### 2.2 非目标（本期不做）

- macOS / Linux 客户端
- 移动端 App
- 客户端离线模式
- 客户端反逆向加固（v2）

---

## 三、模块架构边界

### 3.1 模块职责（`apps/release`）

- 管理端：客户端版本元数据管理、发布状态流转、回滚
- 公共接口：客户端更新检测、下载引导、Heartbeat 上报
- 统计接口：版本分布、租户活跃数、历史装机总数
- 资产管理：R2 对象键规范、发布包引用与审计

### 3.2 分层与鉴权

| 子能力 | Schema | 鉴权 | 说明 |
|---|---|---|---|
| 版本管理后台 API | public | Platform Admin 必须认证 | 跨租户统一运营能力 |
| 更新检测 API | public | 公开（客户端调用） | 仅返回当前发布版本，不暴露草稿/下线版本 |
| Heartbeat API | public | 已登录客户端会话或签名设备票据 | 防伪造上报、防刷统计 |
| 统计 API | public | Platform Admin 必须认证 | 提供 Story 5 所需聚合指标 |

### 3.3 外部依赖

| 依赖 | 用途 |
|---|---|
| Electron + electron-updater | 客户端壳应用、更新下载与安装 |
| electron-builder | 打包 NSIS EXE + Portable ZIP |
| EV 代码签名证书 | Windows SmartScreen 信任 |
| Cloudflare R2 + CDN | 发布包存储与分发 |
| Celery | 异步计算 checksum / 文件扫描 / 可选预热 |

---

## 四、API 设计原则

1. **路径以 PRD 为准**：统一使用 `/api/release/...` 命名空间。  
2. **只允许单一生效版本**：同 `platform + arch` 仅 1 条 `published`。  
3. **公开接口最小暴露**：客户端仅获取更新必要字段，不返回后台内部字段。  
4. **统计可信优先**：Heartbeat 仅“启动上报”，按 `(tenant_id, device_id)` Upsert。  
5. **完整性优先于安装**：校验失败禁止安装，保留当前版本可用。  
6. **强制更新可控**：`release_type=force` + `min_required_version` 双保险。

---

## 五、端点清单（核心）

### 5.1 页面路由（平台运营后台）

| 路径 | 方法 | 鉴权 | 说明 |
|---|---|---|---|
| `/platform/release/updates/` | GET | Platform Admin | 版本列表页 |
| `/platform/release/updates/new/` | GET | Platform Admin | 新建版本页 |
| `/platform/release/updates/{id}/edit/` | GET | Platform Admin | 编辑版本页 |
| `/platform/release/metrics/` | GET | Platform Admin | 版本分布与租户活跃榜 |

### 5.2 JSON API（对齐 PRD + 数据模型）

| 端点 | 方法 | 说明 |
|---|---|---|
| `/api/release/updates/latest/` | GET | 客户端检查最新版本（公开） |
| `/api/release/updates/` | GET | 管理端查询版本列表 |
| `/api/release/updates/` | POST | 管理端创建版本（草稿/发布） |
| `/api/release/updates/{id}/` | PATCH | 修改状态、版本类型、日志 |
| `/api/release/updates/{id}/rollback/` | POST | 回滚至历史版本（原子切换 published） |
| `/api/release/heartbeats/` | POST | 客户端启动上报（Upsert） |
| `/api/release/metrics/version-distribution/` | GET | 版本活跃分布 |
| `/api/release/metrics/tenant-installs/` | GET | 指定租户活跃安装数 + 历史装机数 |
| `/api/release/metrics/tenant-leaderboard/` | GET | 全平台租户活跃榜 |

> 说明：`heartbeats/metrics` 为实现 Story 5 与 `DATA_MODEL_PUBLIC` 聚合查询所需端点，归属同一模块。

---

## 六、关键 API 规范（请求/响应）

### 6.1 更新检测

`GET /api/release/updates/latest/?platform=win32&arch=x64&current_version=1.2.0`

响应（有更新）：

```json
{
  "has_update": true,
  "latest_version": "1.3.0",
  "force_update": false,
  "min_required_version": "1.0.0",
  "download_url": "https://download.fonrey.com/releases/system/v1.3.0/fonrey-setup-1.3.0-win.exe",
  "portable_url": "https://download.fonrey.com/releases/system/v1.3.0/fonrey-portable-1.3.0-win.zip",
  "checksum_sha256": "<exe_sha256>",
  "portable_checksum_sha256": "<zip_sha256>",
  "file_size_bytes": 157286400,
  "release_notes": "## v1.3.0\n- ...",
  "release_date": "2026-05-01"
}
```

### 6.2 Heartbeat 上报

`POST /api/release/heartbeats/`

```json
{
  "device_id": "9e6de37b-8c49-4f9b-af47-52f4e5b8b7f2",
  "client_version": "1.3.0",
  "platform": "win32",
  "arch": "x64",
  "os_version": "Windows 11 23H2"
}
```

处理要求：
- 服务端从登录上下文解析 `tenant_id`、`user_id`
- 使用 `INSERT ... ON CONFLICT (tenant_id, device_id) DO UPDATE`
- 更新 `last_seen_at` 与 `launch_count = launch_count + 1`

### 6.3 版本发布（管理端）

`POST /api/release/updates/`

```json
{
  "version": "1.3.0",
  "platform": "win32",
  "arch": "x64",
  "release_type": "normal",
  "min_required_version": "1.0.0",
  "download_url": "https://download.fonrey.com/releases/system/v1.3.0/fonrey-setup-1.3.0-win.exe",
  "portable_url": "https://download.fonrey.com/releases/system/v1.3.0/fonrey-portable-1.3.0-win.zip",
  "checksum_sha256": "<exe_sha256>",
  "portable_checksum_sha256": "<zip_sha256>",
  "release_notes": "## v1.3.0\n- ...",
  "status": "published"
}
```

---

## 七、HTMX 交互约定（平台运营后台）

- 列表筛选（状态/版本号）使用 HTMX 局刷表格区域
- 发布/下线/回滚操作使用确认弹窗 + 局部刷新
- 成功：`HX-Trigger: toast-success`
- 失败：`HX-Trigger: toast-error`（同时返回标准错误码）

模板建议：
- `templates/release/updates_list.html`
- `templates/release/fragments/updates_table.html`
- `templates/release/fragments/version_distribution_chart.html`
- `templates/release/fragments/tenant_leaderboard_table.html`

---

## 八、权限与数据范围

### 8.1 最小权限矩阵

| 能力 | permission_code |
|---|---|
| 客户端版本列表查看 | `platform.release.view.allow` |
| 创建/编辑发布版本 | `platform.release.edit.allow` |
| 发布/下线/回滚 | `platform.release.publish.allow` |
| 版本分布与租户统计查看 | `platform.release.metrics.view.allow` |

### 8.2 范围规则

- 所有管理能力仅 Platform Admin 可访问
- Tenant Admin / Agent 不可访问平台发布后台
- 数据物理存储在 public schema，逻辑上属于平台级共享数据

---

## 九、异步任务与缓存策略

### 9.1 异步任务

| 任务 | 触发时机 | 说明 |
|---|---|---|
| `release_compute_checksum_task` | 文件上传后 | 计算 EXE/ZIP SHA256 并回填 |
| `release_publish_cdn_warmup_task` | 版本发布后 | 可选，预热热点下载节点 |
| `release_scan_artifact_task` | 文件上传后 | 可选，执行恶意文件扫描与审计 |

### 9.2 Redis Key 建议

| Key | TTL | 说明 |
|---|---|---|
| `release:latest:{platform}:{arch}` | 60s | 最新发布版本缓存 |
| `release:metrics:version_distribution` | 60s | 版本分布聚合缓存 |
| `release:metrics:tenant:{tenant_id}` | 60s | 单租户安装/活跃统计缓存 |
| `release:download:ratelimit:{ip}` | 60s | 下载链接接口限流 |

---

## 十、性能与可靠性约束

- 更新检测接口：`p95 < 120ms`（缓存命中）
- Heartbeat 写入：`p95 < 80ms`
- 版本列表页：`p95 < 200ms`
- 发布状态切换使用事务，保证“下线旧版 + 发布新版”原子完成
- 任意更新失败不影响当前版本继续运行（可恢复原则）

---

## 十一、安全与合规

1. Electron 必须启用：`contextIsolation=true`、`nodeIntegration=false`、`sandbox=true`。  
2. 更新包仅允许 HTTPS 下载；域名白名单固定为 `download.fonrey.com`。  
3. EV 证书私钥仅在 CI 密钥库中可用，禁止落盘到开发机。  
4. 校验值由服务端生成并签名传输（至少 TLS + 服务端可信源）。  
5. Heartbeat 接口必须防重放/防刷（鉴权 + 频控 + 审计）。  
6. 管理端操作（发布、回滚、下线）全部记录审计日志。

---

## 十二、错误码建议

| code | HTTP | 中文含义 |
|---|---|---|
| `RELEASE_VERSION_INVALID` | 400 | 版本号不符合 SemVer |
| `RELEASE_PUBLISHED_CONFLICT` | 409 | 当前平台架构已存在发布版本 |
| `RELEASE_ARTIFACT_NOT_FOUND` | 404 | 发布包不存在或不可访问 |
| `RELEASE_CHECKSUM_MISMATCH` | 400 | 安装包完整性校验失败 |
| `RELEASE_HEARTBEAT_INVALID` | 400 | 心跳参数非法 |
| `RELEASE_PERMISSION_DENIED` | 403 | 权限不足 |
| `RELEASE_RATE_LIMITED` | 429 | 请求过于频繁 |

---

## 十三、测试映射（P0）

| Story | 测试关注点 |
|---|---|
| Story 1 下载安装 | 官网下载链接可用、签名有效、安装步骤 ≤3、首次启动直达登录 |
| Story 2 客户端使用 | Chromium 内核能力、HTMX/Alpine/Tailwind 渲染一致性、文件上传下载 |
| Story 3 自动升级 | 启动 + 4h 检测、普通更新/强制更新分支、失败可恢复 |
| Story 4 发布管理 | 版本创建/发布/下线/回滚、唯一 published 约束 |
| Story 5 版本分布 | Heartbeat Upsert、活跃统计（24h）、租户活跃榜排序 |

测试文件建议：`tests/integration/release/test_us_release.py`

---

## 十四、落地顺序建议

1. `apps/release` 模型/服务/API 基础骨架（先打通 `/api/release/updates/latest/`）
2. 平台运营后台版本管理页（列表 + 新建 + 发布/下线）
3. Electron 壳应用最小可运行版本（加载 Web + 标题版本）
4. 自动更新链路（electron-updater + 后端 latest API）
5. Heartbeat 上报 + 统计 API + 后台图表
6. 官网下载页上线（公司域名）
7. 便携版 ZIP 与企业无安装权限场景验收

---

## 十五、文档同步规则

- PRD 发布管理模块变更：同步本文件
- `client_releases/client_heartbeats` 字段变更：同步 `DATA_MODEL_PUBLIC.md`
- 枚举值变更：同步 `DATA_MODEL/ENUMS.md`（含中文标签）
- API 包络/错误契约变更：同步 `TECH_STACK/API_CONTRACT.md`
- 若将来新增独立测试用例文档：同步 `TECH_STACK/测试规范.md` 与测试用例注册表

---

## 附：你关注的 8 个专题落地结论

1. **Electron 方案**：采用 Electron + electron-updater，客户端坚持“壳应用”原则。  
2. **EV 证书方案**：CI 自动签名，证书私钥仅在密钥管理系统。  
3. **Heartbeat 方案**：仅启动上报，`(tenant_id, device_id)` Upsert，支撑活跃与版本分布。  
4. **自动升级方案**：启动 + 每 4h 轮询，普通/强制双模式，失败可恢复。  
5. **完整性验证**：下载后先 SHA256 校验，再安装；失败禁止覆盖当前版本。  
6. **R2 版本管理**：`releases/system/v{version}/...` 路径规范，发布状态驱动可见性。  
7. **公司网站下载**：`download.fonrey.com` 静态下载页 + 版本信息 + 更新日志。  
8. **便携版实现**：electron-builder 输出 ZIP，首次运行写入用户目录配置，不修改系统级安装。