hailin
ce9cc5b72e
## 后端 (backend/services/telemetry-service) ### 修复骨架中的关键缺陷 - 创建本地 JwtAuthGuard / AdminGuard，替换不存在的 @genex/common 包 - 修复 req.user.sub → req.user.id（与 JwtStrategy.validate() 返回值对齐） - 重写 Dockerfile，移除对不存在的 packages/common 目录的引用 - 更新 telemetry.module.ts，将 JwtAuthGuard / AdminGuard 注册为 providers - admin-telemetry.controller.ts 改用本地 AdminGuard（检查 role === 'admin'） ### 新增功能 - GET /api/v1/telemetry/config：公开配置下发接口 Flutter TelemetryConfig.syncFromRemote() 每小时拉取，返回全局开关、采样率、 心跳间隔等配置，所有字段支持环境变量覆盖（TELEMETRY_GLOBAL_ENABLED 等） - 设备字段（deviceBrand/deviceModel/deviceOs/appVersion/locale）提升为顶层列 BatchEventsDto / TelemetryEvent 实体 / recordEvents() 全链路补齐 原因：JSONB 内字段无法走 B-tree 索引，千万级数据分组查询需独立列 ### DB 迁移 - 050_add_device_fields_to_telemetry_events.sql：为已有 telemetry_events 表 新增 5 个设备字段列和 device_brand / app_version 索引 ### docker-compose 环境变量 - telemetry-service 新增 TELEMETRY_GLOBAL_ENABLED / SAMPLING_RATE / HEARTBEAT_INTERVAL / CONFIG_VERSION 环境变量，支持生产环境热调整 ## 前端 ### genex-mobile (Flutter 消费者端) - 复制 lib/core/telemetry/ 模块（11个文件）：TelemetryService、 HeartbeatService、SessionManager、TelemetryUploader、TelemetryStorage 等 - 修正 API 路径：presence/heartbeat → telemetry/heartbeat， analytics/events → telemetry/events - pubspec.yaml 新增依赖：uuid ^4.3.3、equatable ^2.0.5、device_info_plus ^10.1.0 - main.dart：initState 首帧回调初始化 TelemetryService（需 BuildContext 采集设备信息） 已登录时自动注入 accessToken - auth_service.dart：_setAuth() 登录成功后注入 userId + accessToken； _clearAuth() 退出时清除（同时覆盖 Token 过期自动清除场景） ### admin-app (Flutter 发行方控制台) - 复制 lib/core/telemetry/ 模块（同上） - pubspec.yaml 新增依赖：uuid、equatable、device_info_plus、shared_preferences - IssuerLoginPage：initState 首帧初始化 + 登录成功后注入 userId/token 使用 api.gogenex.cn（与 UpdateService 域名一致） - settings_page.dart：退出登录时调用 clearUserId() + clearAccessToken() ## 架构说明 - 在线人数：Redis Sorted Set (genex:presence:online)，心跳 60s/次，180s 窗口判定在线 - DAU：app_session_start 事件写入 telemetry_events，每天凌晨 1 点聚合到 daily_active_stats 表，同时每小时滚动更新当日 DAU - 设备字段采用 Amplitude 风格：前端本地队列存 properties 内， toServerJson() 上传时自动提升为顶层字段，后端写入独立索引列 - 心跳需要 JWT 认证（未登录用户自动跳过，不报错） - 遥测完全异步，任何失败只打 debug 日志，不影响主流程 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| backend | ||
| blockchain | ||
| deploy/nginx | ||
| docs | ||
| frontend | ||
| logo | ||
| scripts | ||
| .gitignore | ||
| README.md | ||
README.md
Global Coupon Exchange
Website: gogenex.com
Brand Naming Strategy
This project adopts a regional branding strategy, using different brand names for different markets while maintaining brand family consistency.
Brand Structure
| Market | Brand | Abbr | Description |
|---|---|---|---|
| Western (US/Europe) | Genex | GNX | Derived from Generation + Exchange, familiar Western naming style |
| Asian (including China) | Gensen / 券信 | GS | "Gensen" from Cantonese pronunciation of Chinese characters "券信" |
Unified Domain
- gogenex.com - Single global domain for all markets
- Subdomains or paths for regional content (e.g., gogenex.com/cn, gogenex.com/asia)
Naming Logic
Genex (Western Markets)
- Gen = Generation / Generic / Genesis
- ex = Exchange
- Natural pronunciation, similar to well-known Western brands like FedEx, Amex
- Professional, modern, and trustworthy fintech image
Gensen / 券信 (Asian Markets)
- 券 (Quan) = Coupon / Voucher
- 信 (Xin) = Trust / Credit
- Gensen = Romanization of Cantonese pronunciation "gyun seon"
- Use Chinese characters "券信" in Mainland China
- Use romanized "Gensen" in other Asian regions
- Two characters conveying core values: coupon trading + trust guarantee
Brand Consistency
Genex ←── "Gen-" prefix ──→ Gensen
↑ ↑
└─────── Same brand family ────┘
↓
券信 (Chinese localization)
- Genex and Gensen share the "Gen-" prefix, establishing brand family recognition
- Gensen directly transliterates to 券信, providing seamless connection
- Global users can recognize these as regional versions of the same platform
Usage Scenarios
| Scenario | Western Markets | Asian Markets (non-China) | China Market |
|---|---|---|---|
| Company Name | GoGenex Inc. | Gensen Asia Ltd. | 券信科技有限公司 |
| App Name | Genex | Gensen | 券信 |
| Domain | gogenex.com | gogenex.com/asia | gogenex.com/cn |
| Social Media | @gogenex | @gensen_official | @券信official |
Note on Company Structure:
- Inc. (Corporation) for Western markets: Better for VC funding, stock issuance, and potential IPO
- Ltd. (Limited) for Asian markets: Common structure in Asia-Pacific region
- Social media handles use variations to avoid conflicts with existing accounts
Legal & Operations
Due to varying financial regulations across countries, each regional brand will:
- Operate as an independent legal entity
- Comply with local regulatory requirements
- Share core technology platform and philosophy
- Establish brand association through parent company
Project Overview
Global Coupon Exchange (GCX) is a coupon asset trading platform designed to provide users with secure and convenient trading services for digital assets such as coupons, gift cards, and vouchers.
Core Features
- Coupon asset listing and trading
- Secure transaction matching mechanism
- Multi-currency settlement support
- User credit system
Tech Stack
TBD
Documentation
For detailed development documentation, please refer to the docs directory.
License
TBD