# 07 - 遥测 (Telemetry) 与移动端版本管理开发指南

> 参考项目: rwadurian/backend/services/presence-service + admin-service
> 目标: 为 Genex 券金融平台增加 **用户遥测分析** 和 **移动端 OTA 版本管理** 能力

---

## 一、功能概览

### 1.1 遥测系统 (Telemetry)

| 能力 | 说明 |
|------|------|
| 心跳检测 | 客户端定时上报心跳，服务端通过 Redis Sorted Set 实时计算在线用户数 |
| 事件采集 | 批量上报客户端事件（会话开始、页面浏览、操作行为等），写入 PostgreSQL |
| DAU 统计 | 基于 `app_session_start` 事件按 userId/installId 去重，支持省市维度 |
| 在线快照 | 每分钟记录在线用户数快照，支持 1m/5m/1h 区间聚合查询 |
| Prometheus | 暴露 `/metrics` 端点供 Grafana 抓取（心跳数、事件数、在线人数、DAU） |

### 1.2 版本管理 (App Version / OTA Update)

| 能力 | 说明 |
|------|------|
| 版本 CRUD | 管理员创建/编辑/删除/启禁用版本记录 |
| APK/IPA 上传 | 上传安装包，自动解析 versionCode/versionName/minSdkVersion |
| 强制更新 | `isForceUpdate` 标志，客户端据此决定是否阻断使用 |
| 检查更新 API | 移动端调用，返回是否有更新、下载地址、SHA256 校验 |
| 断点续传下载 | HTTP Range 206 支持，大文件友好 |
| 文件完整性 | SHA256 哈希校验，防篡改 |

---

## 二、Genex 项目适配方案

### 2.1 架构决策

参考 rwadurian 项目的独立服务架构，Genex 同样采用独立微服务方案：

| 功能 | 归属服务 | 端口 | 理由 |
|------|---------|------|------|
| **遥测 (Telemetry)** | **telemetry-service** | :3011 | 独立微服务，专注心跳检测、事件采集、DAU 统计、Prometheus 指标 |
| **版本管理 (App Version)** | **admin-service** | :3012 | 独立微服务，专注 APK/IPA 管理、OTA 更新、MinIO 文件存储 |

### 2.2 与参考项目的差异

| 维度 | rwadurian | Genex |
|------|-----------|-------|
| ORM | Prisma | TypeORM (与现有一致) |
| 架构 | 独立服务 + CQRS | **独立服务 + DDD 四层架构** |
| 文件存储 | 本地 `./uploads` | **MinIO** (已有基础设施) |
| 事件总线 | Kafka | **Kafka** (KRaft 模式) |
| 缓存 | Redis | **Redis** (已有) |
| APK 解析 | adbkit-apkreader | 同方案 |
| IPA 解析 | unzipper + bplist-parser | 同方案 |
| Prometheus | prom-client | 同方案 |
| 在线检测窗口 | 180s (3 min) | 180s |
| DAU 计算 | 每天凌晨 1:00 + 每小时滚动 | 同方案 |
| 下载端点 | Express 流式 | NestJS StreamableFile + Range |

### 2.3 数据库表 (新增 4 张)

#### `telemetry_events` — 事件日志 (append-only)

```sql
CREATE TABLE IF NOT EXISTS telemetry_events (
    id BIGSERIAL PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    install_id VARCHAR(128) NOT NULL,
    event_name VARCHAR(64) NOT NULL,
    event_time TIMESTAMPTZ NOT NULL,
    properties JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_telemetry_events_time ON telemetry_events(event_time);
CREATE INDEX idx_telemetry_events_name_time ON telemetry_events(event_name, event_time);
CREATE INDEX idx_telemetry_events_user ON telemetry_events(user_id);
```

#### `daily_active_stats` — DAU 日统计

```sql
CREATE TABLE IF NOT EXISTS daily_active_stats (
    day DATE PRIMARY KEY,
    dau_count INT NOT NULL DEFAULT 0,
    dau_by_platform JSONB DEFAULT '{}',
    dau_by_region JSONB DEFAULT '{}',
    calculated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    version INT NOT NULL DEFAULT 1
);
```

#### `online_snapshots` — 在线快照

```sql
CREATE TABLE IF NOT EXISTS online_snapshots (
    id BIGSERIAL PRIMARY KEY,
    ts TIMESTAMPTZ NOT NULL UNIQUE,
    online_count INT NOT NULL DEFAULT 0,
    window_seconds INT NOT NULL DEFAULT 180
);
CREATE INDEX idx_online_snapshots_ts ON online_snapshots(ts DESC);
```

#### `app_versions` — 应用版本

```sql
CREATE TABLE IF NOT EXISTS app_versions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    platform VARCHAR(10) NOT NULL CHECK (platform IN ('ANDROID', 'IOS')),
    version_code INT NOT NULL,
    version_name VARCHAR(32) NOT NULL,
    build_number VARCHAR(64) NOT NULL,
    download_url TEXT NOT NULL,
    file_size BIGINT NOT NULL DEFAULT 0,
    file_sha256 VARCHAR(64) NOT NULL,
    min_os_version VARCHAR(16),
    changelog TEXT NOT NULL DEFAULT '',
    is_force_update BOOLEAN NOT NULL DEFAULT FALSE,
    is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
    release_date TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by UUID,
    updated_by UUID
);
CREATE INDEX idx_app_versions_platform ON app_versions(platform, is_enabled);
CREATE INDEX idx_app_versions_code ON app_versions(platform, version_code DESC);
```

### 2.4 Redis 数据结构

| Key | 类型 | 用途 |
|-----|------|------|
| `genex:presence:online` | Sorted Set | member=userId, score=heartbeat Unix时间戳 |
| `genex:dau:{YYYY-MM-DD}` | HyperLogLog | 实时近似 DAU（userId/installId） |
| `genex:dau:{YYYY-MM-DD}:ttl` | - | 自动过期 48h |

### 2.5 Kafka Topics (新增)

| Topic | 生产者 | 消费者 | 用途 |
|-------|--------|--------|------|
| `telemetry.session.started` | user-service | notification-service | 会话开始事件 |
| `telemetry.heartbeat` | user-service | - | 心跳事件（可选） |

### 2.6 MinIO Bucket

| Bucket | 用途 |
|--------|------|
| `app-releases` | 存放 APK/IPA 安装包 |

---

## 三、API 设计

### 3.1 遥测 API

```
POST /api/v1/telemetry/events          — 批量上报事件 (无需认证，支持匿名)
POST /api/v1/telemetry/heartbeat       — 心跳上报 (需认证)
GET  /api/v1/telemetry/online-count    — 当前在线人数 (需认证)
GET  /api/v1/telemetry/online-history  — 在线历史趋势 (需认证)

# Admin (遥测分析 — 独立路径避免与 issuer 的 analytics 冲突)
GET  /api/v1/admin/telemetry/dau       — DAU 统计查询
GET  /api/v1/admin/telemetry/events    — 事件列表查询
GET  /api/v1/admin/telemetry/realtime  — 实时数据面板
```

### 3.2 版本管理 API

```
# 移动端 (无需/轻认证)
GET  /api/v1/app/version/check         — 检查更新
GET  /api/v1/app/version/download/:id  — 下载安装包 (支持断点续传)

# Admin
GET    /api/v1/admin/versions          — 版本列表
GET    /api/v1/admin/versions/:id      — 版本详情
POST   /api/v1/admin/versions          — 创建版本 (手动填写)
POST   /api/v1/admin/versions/upload   — 上传 APK/IPA 自动创建
POST   /api/v1/admin/versions/parse    — 解析安装包 (不保存)
PUT    /api/v1/admin/versions/:id      — 更新版本信息
PATCH  /api/v1/admin/versions/:id/toggle — 启用/禁用
DELETE /api/v1/admin/versions/:id      — 删除版本
```

### 3.3 检查更新响应示例

```json
{
  "code": 0,
  "data": {
    "needUpdate": true,
    "forceUpdate": true,
    "version": "2.1.0",
    "versionCode": 210,
    "downloadUrl": "https://minio.gogenex.com/app-releases/ANDROID-2.1.0.apk",
    "fileSize": 52428800,
    "fileSizeFriendly": "50.0 MB",
    "sha256": "a1b2c3d4e5f6...",
    "updateLog": "1. 新增券转让功能\n2. 修复钱包余额显示\n3. 性能优化",
    "releaseDate": "2026-02-12T10:00:00Z"
  }
}
```

### 3.4 强制更新决策流程

```
客户端 → GET /app/version/check?platform=android&current_version_code=200
                    ↓
服务端: 查找该平台最新 enabled 版本
                    ↓
          ┌── 无更新版本 → { needUpdate: false }
          │
          └── 有更新版本 (latestCode > currentCode)
                    ↓
              isForceUpdate && isEnabled?
              ├── YES → { needUpdate: true, forceUpdate: true, ... }
              └── NO  → { needUpdate: true, forceUpdate: false, ... }
                    ↓
客户端:
  forceUpdate=true  → 弹窗阻断，只能更新
  forceUpdate=false → 提示可选更新
```

---

## 四、实现文件清单

### 4.1 遥测服务 (telemetry-service :3011)

```
services/telemetry-service/src/
├── domain/
│   ├── entities/
│   │   ├── telemetry-event.entity.ts       # 事件日志实体
│   │   ├── online-snapshot.entity.ts       # 在线快照实体
│   │   └── daily-active-stats.entity.ts    # DAU 统计实体
│   ├── value-objects/
│   │   ├── event-name.vo.ts                # 事件名值对象
│   │   ├── install-id.vo.ts                # 安装ID值对象
│   │   └── time-window.vo.ts               # 时间窗口值对象
│   └── events/
│       ├── session-started.event.ts        # 会话开始领域事件
│       └── heartbeat-received.event.ts     # 心跳接收领域事件
├── application/services/
│   ├── telemetry.service.ts                # 事件采集 + 心跳 + DAU
│   └── telemetry-scheduler.service.ts      # 定时任务 (快照/DAU/清理)
├── infrastructure/
│   ├── redis/
│   │   └── presence-redis.service.ts       # Redis 在线检测操作
│   ├── kafka/
│   │   └── telemetry-producer.service.ts   # Kafka 事件发布
│   └── metrics/
│       └── telemetry-metrics.service.ts    # Prometheus 指标
└── interface/http/
    ├── controllers/
    │   ├── telemetry.controller.ts         # 遥测 API (心跳/事件/在线)
    │   ├── admin-telemetry.controller.ts   # Admin 遥测分析 API
    │   ├── metrics.controller.ts           # GET /metrics (Prometheus)
    │   └── health.controller.ts            # 健康检查
    └── dto/
        ├── batch-events.dto.ts
        ├── heartbeat.dto.ts
        └── query-dau.dto.ts
```

### 4.2 版本管理服务 (admin-service :3012)

```
services/admin-service/src/
├── domain/
│   ├── entities/
│   │   └── app-version.entity.ts           # 版本实体 + Platform 枚举
│   └── value-objects/
│       ├── version-code.vo.ts              # 版本号值对象
│       ├── version-name.vo.ts              # 版本名值对象
│       ├── file-sha256.vo.ts               # 文件哈希值对象
│       └── download-url.vo.ts              # 下载链接值对象
├── application/services/
│   ├── app-version.service.ts              # 版本 CRUD + 检查更新
│   └── file-storage.service.ts             # MinIO 文件上传/下载
├── infrastructure/
│   └── parsers/
│       └── package-parser.service.ts       # APK/IPA 解析
└── interface/http/
    ├── controllers/
    │   ├── app-version.controller.ts       # 移动端检查更新 + 下载 (无认证)
    │   ├── admin-version.controller.ts     # Admin 版本 CRUD (JWT+ADMIN)
    │   └── health.controller.ts            # 健康检查
    └── dto/
        ├── check-update.dto.ts
        ├── create-version.dto.ts
        └── upload-version.dto.ts
```

### 4.3 数据库迁移

```
migrations/
├── 032_create_telemetry_events.sql
├── 033_create_daily_active_stats.sql
├── 034_create_online_snapshots.sql
└── 035_create_app_versions.sql
```

### 4.4 Kong 路由

```yaml
# telemetry-service (:3011)
- name: telemetry-service
  url: http://telemetry-service:3011
  routes:
    - name: telemetry-routes
      paths: [/api/v1/telemetry]
    - name: admin-telemetry-routes
      paths: [/api/v1/admin/telemetry]

# admin-service (:3012)
- name: admin-service
  url: http://admin-service:3012
  routes:
    - name: app-version-routes
      paths: [/api/v1/app/version]
    - name: admin-version-routes
      paths: [/api/v1/admin/versions]
```

### 4.5 Docker Compose 服务

```yaml
telemetry-service:
  build: ./services/telemetry-service
  ports: ["3011:3011"]
  depends_on: [postgres, redis, kafka]

admin-service:
  build: ./services/admin-service
  ports: ["3012:3012"]
  depends_on: [postgres, minio]
```

---

## 五、关键实现要点

### 5.1 心跳在线检测

- 客户端每 60s 发送心跳
- 服务端用 Redis `ZADD genex:presence:online userId timestamp`
- 在线判定窗口: 180s (3 分钟内有心跳即在线)
- 在线人数: `ZCOUNT genex:presence:online (now-180) +inf`
- 每小时清理 24 小时前的过期数据: `ZREMRANGEBYSCORE`

### 5.2 DAU 计算策略

- **实时近似**: Redis HyperLogLog `PFADD genex:dau:2026-02-12 userId`
- **精确计算**: 每天凌晨 1:00 从 `telemetry_events` 查询 `app_session_start`
- **去重优先级**: userId > installId
- **地理维度**: 从 event properties 中提取 province/city

### 5.3 文件存储 (MinIO)

- Bucket: `app-releases`
- 对象命名: `{platform}/{versionName}/{timestamp}-{random}.{ext}`
- 预签名 URL: 下载时生成 24h 有效的签名链接
- SHA256: 上传时计算，存入 `app_versions.file_sha256`

### 5.4 APK/IPA 解析

- **Android**: `adbkit-apkreader` 读取 AndroidManifest.xml
  - 提取: packageName, versionCode, versionName, minSdkVersion
- **iOS**: `unzipper` 解压 → `bplist-parser` 读取 Info.plist
  - 提取: CFBundleIdentifier, CFBundleVersion, CFBundleShortVersionString, MinimumOSVersion

### 5.5 断点续传

- 响应头: `Accept-Ranges: bytes`
- 请求头: `Range: bytes=1048576-`
- 状态码: 206 Partial Content
- 流式读取: `fs.createReadStream(path, { start, end })`

---

## 六、与现有系统集成

### 6.1 Admin-web 管理面板

admin-web 已有 Dashboard 页面，新增:
- **遥测面板**: DAU 趋势图、在线用户数、事件分析
- **版本管理页**: 版本列表、上传、强制更新开关

### 6.2 genex-mobile / miniapp

Flutter/Taro 客户端需要:
- 启动时发送 `app_session_start` 事件
- 定时心跳 (60s)
- 启动时调用检查更新 API
- 根据 `forceUpdate` 决定是否阻断

### 6.3 notification-service

消费 `telemetry.session.started` 事件:
- 新用户首次登录 → 发送欢迎通知
- 用户回归 (>7 天未登录) → 发送召回通知

---

## 七、Prometheus 指标

| 指标名 | 类型 | 标签 | 说明 |
|--------|------|------|------|
| `genex_online_users` | Gauge | - | 当前在线用户数 |
| `genex_dau` | Gauge | date | 每日活跃用户数 |
| `genex_heartbeat_total` | Counter | app_version | 心跳总数 |
| `genex_events_total` | Counter | event_name | 事件总数 |
| `genex_event_batch_duration` | Histogram | - | 批量事件处理耗时 |