hailin
8d2fd3335a
feat(telemetry): add presence-service + Flutter telemetry module
...
## Backend — packages/services/presence-service (新微服务)
完整的 DDD + Clean Architecture 实现，移植自 RWADurian presence-service，
针对 IT0 架构做了以下适配：
### 核心功能
- 心跳接口: POST /api/v1/presence/heartbeat（JWT 验证，60s 间隔）
→ Redis Sorted Set `presence:online_users` 记录在线时间戳
→ 默认 5 分钟窗口判断在线（PRESENCE_WINDOW_SECONDS=300）
- 事件上报: POST /api/v1/analytics/events（批量，最多 50 条）
→ 写入 presence_event_log 表 + 更新 presence_device_profile
→ Redis HyperLogLog `presence:dau:{date}` 实时 DAU 估算
- 查询接口（需 AdminGuard）:
- GET /api/v1/analytics/online-count — 实时在线人数
- GET /api/v1/analytics/online-history — 历史在线快照
- GET /api/v1/analytics/dau — DAU 统计
### IT0 适配要点
- JWT payload: `sub` = UUID userId（非 RWADurian 的 userSerialNum）
→ JwtAuthGuard: request.user = { userId: payload.sub, roles, tenantId }
- AdminGuard: 改为检查 `roles.includes('admin')`（非 type==='admin'）
- 移除 Kafka EventPublisherService（IT0 无 Kafka）
- 移除 Prometheus MetricsService（IT0 无 Prometheus）
- 表前缀改为 `presence_`（避免与其他服务冲突）
- userId 字段 VarChar(36)（UUID 格式，非原来的 VarChar(20)）
- Redis DB=10 隔离（独立 key 空间）
### 数据库表（public schema）
- presence_event_log — 事件流水（append-only）
- presence_device_profile — 设备快照（upsert，每台设备一行）
- presence_daily_active_users — DAU 日统计
- presence_online_snapshots — 在线人数每分钟快照
### 定时任务（@nestjs/schedule）
- 每分钟: 采集在线人数快照 → presence_online_snapshots
- 每天 01:05 (UTC+8): 计算前一天 DAU → presence_daily_active_users
---
## Flutter — it0_app/lib/core/telemetry (新模块)
### 文件结构
- telemetry_service.dart — 单例入口，统筹所有组件
- models/telemetry_event.dart — 事件模型，toServerJson() 将设备字段提升为顶层列
- models/device_context.dart — 设备上下文（Android/iOS 信息）
- models/telemetry_config.dart — 远程配置（采样率/开关，支持远端同步）
- collectors/device_info_collector.dart — 采集 device_info_plus 设备信息
- storage/telemetry_storage.dart — SharedPreferences 队列（最多 500 条）
- uploader/telemetry_uploader.dart — 批量上传到 /api/v1/analytics/events
- session/session_manager.dart — WidgetsBindingObserver 监听前后台切换
- session/session_events.dart — 会话事件常量
- presence/heartbeat_service.dart — 定时心跳 POST /api/v1/presence/heartbeat
- presence/presence_config.dart — 心跳配置（间隔/requiresAuth）
- telemetry.dart — barrel 导出
### 集成点
- app_router.dart _tryRestore(): TelemetryService().initialize() 在 auth 之前
- auth_provider.dart login/loginWithOtp: setUserId + setAccessToken + resumeAfterLogin
- auth_provider.dart tryRestoreSession: 恢复 userId + accessToken
- auth_provider.dart logout: pauseForLogout + clearUserId + clearAccessToken
### 新增依赖
- device_info_plus: ^10.1.0
- equatable: ^2.0.5
---
## 基础设施
### Dockerfile.service
- 在 builder 和 production 阶段均添加 presence-service/package.json 的 COPY
### docker-compose.yml
- 新增 presence-service 容器（端口 3011/13011）
- DATABASE_URL: postgresql://... (Prisma 所需连接串格式)
- REDIS_HOST/PORT/DB: 10（presence 独立 Redis DB）
- APP_PORT=3011, JWT_SECRET, PRESENCE_WINDOW_SECONDS=300
- api-gateway depends_on 新增 presence-service
### kong.yml (dbless 声明式)
- 新增 presence-service 服务（http://presence-service:3011）
- presence-routes: /api/v1/presence
- analytics-routes: /api/v1/analytics
- 对整个 presence-service 启用 JWT 插件（Kong 层鉴权）
### DB 迁移
- packages/shared/database/src/migrations/010-create-presence-tables.sql
— 4 张 presence_ 前缀表 + 完整索引（IF NOT EXISTS 幂等）
- run-migrations.ts: runSharedSchema() 中新增执行 010-create-presence-tables.sql
---
## 部署步骤（服务器）
1. git pull
2. 执行 presence 表迁移（首次）:
docker exec it0-postgres psql -U it0 -d it0 \
-f /path/to/010-create-presence-tables.sql
或通过 migration runner:
cd /home/ceshi/it0 && node packages/shared/database/dist/run-migrations.js
3. 重建并启动 presence-service:
docker compose build presence-service api-gateway
docker compose up -d presence-service api-gateway
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-07 17:44:01 -08:00
hailin