txagent-y/txagent-y

Fork 0

远舟 17abe4b1a9 docs(api): 补充埋点初始化与设备参数说明

2026-05-11 18:46:30 +08:00

11 KiB

Raw Blame History

API-11 系统配置（CONFIG）

共 5 个接口：CONFIG-01~05

系统配置（config）

CONFIG-01 获取全局配置

项目	说明
接口路径	GET /client/api/v1/config
接口用途	获取平台全局配置（App启动时调用）
权限要求	公开
涉及表	platform_config, announcement, payment_channel

接口逻辑：

读 platform_config 表获取各项配置（签到/首充/分成/版本、自定义标签长度等）。其中 revenueShare 读取实际结算使用的无代聊分成配置：优先读取 revenue_share.without_agent.platform_percent / revenue_share.without_agent.creator_percent，缺失时兼容旧键 revenue.platform_rate / revenue.creator_rate
读 announcement 表获取最新公告（status=1，最新一条）
读 recharge_tier 表获取可用支付通道信息
组装返回

请求参数： 无

响应数据：

字段	类型	说明
checkin	object	签到配置
checkin.enabled	number	签到是否开启：0关 1开
checkin.dailyReward	number	每日签到奖励（糖心币）
checkin.weekBonus	number	连续7天奖励（糖心币）
firstRecharge	object	首充配置
firstRecharge.enabled	number	首充奖励是否开启：0关 1开
firstRecharge.bonusPercent	number	首充额外赠送比例（%）
firstRecharge.bonusAmount	number	首充额外固定赠送币数
revenueShare	object	分润配置
revenueShare.platformRate	number	平台抽成比例（%）；来自 `revenue_share.without_agent.platform_percent`
revenueShare.creatorRate	number	创作者分成比例（%）；来自 `revenue_share.without_agent.creator_percent`
coinsPerYuan	number	人民币兑糖心币比例，表示 `1 元 = N 币`
customTagMaxNameLength	number	自定义标签名称最大字符数；读取 `platform_config.content.tag.max_name_length`，默认 10，有效范围 1~32，配置缺失或非法时返回 10
paymentChannels	array	全局支付通道兼容信息（前端充值主联调以 `COIN-02` 的 `tiers[].paymentChannels` 为准）
paymentChannels[].name	string	通道名称
paymentChannels[].type	string	通道类型
paymentChannels[].enabled	number	是否启用：0关 1开
announcement	object/null	最新公告（无公告为null）
announcement.title	string	公告标题
announcement.content	string	公告内容
announcement.publishedAt	timestamp	发布时间
appVersion	object	App版本信息
appVersion.latestVersion	string	最新版本号
appVersion.minVersion	string	最低支持版本
appVersion.forceUpdate	number	是否强制更新：0否 1是

CONFIG-02 获取可用域名列表

项目	说明
接口路径	GET /client/api/v1/config/domains
接口用途	App 获取当前可用 API/CDN 域名，用于容灾切换
权限要求	公开
涉及表	platform_domain

接口逻辑：

查询 platform_domain（is_active=1，deleted_at 为空）（读）
按 type 分组，每组按 priority 升序排序
建议边缘 CDN 缓存 60s 以提升可用性

请求参数： 无

响应数据：

字段	类型	说明
api	array	API 域名列表（按优先级，首个为主用）
api[].host	string	域名（不含 scheme），如 `api.txfans.com`
api[].priority	number	优先级，数字越小越优先
cdn	array	静态资源/媒体 CDN 域名列表
cdn[].host	string	CDN 域名
cdn[].priority	number	优先级
ttl	number	客户端本地缓存秒数（默认 300）

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "api": [
      { "host": "api.txfans.com", "priority": 1 },
      { "host": "api-bak1.txfans.com", "priority": 2 }
    ],
    "cdn": [
      { "host": "cdn.txfans.com", "priority": 1 }
    ],
    "ttl": 300
  }
}

说明：本接口与 CONFIG-01 拆开是为了保持轻量、可独立 CDN 缓存，避免 CONFIG-01 大体积响应或上游表故障影响域名容灾能力。

CONFIG-03 获取城市列表

项目	说明
接口路径	GET /client/api/v1/config/cities
接口用途	获取发布内容/筛选场景使用的热门城市与省级地区列表
权限要求	公开
涉及表	platform_config

接口逻辑：

查询 platform_config 表，读取 config_key=location.city_index 的配置（读）
将配置值按 JSON 解析为 hotCities 与 provinces 两个数组
过滤 code 或 name 为空的脏数据项
若配置不存在或值为空，返回空数组
若配置 JSON 非法，返回业务错误，提示城市配置格式错误

请求参数： 无

响应数据：

字段	类型	说明
hotCities	array	热门城市列表
hotCities[].code	string	城市行政区划代码（GB/T 2260），如 `110100`
hotCities[].name	string	城市名称，如 `北京`
provinces	array	省级地区列表
provinces[].code	string	省级行政区划代码（GB/T 2260），如 `110000`
provinces[].name	string	省级地区名称，如 `北京市`、`浙江省`

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "hotCities": [
      { "code": "110100", "name": "北京" },
      { "code": "310100", "name": "上海" },
      { "code": "440100", "name": "广州" },
      { "code": "440300", "name": "深圳" },
      { "code": "330100", "name": "杭州" },
      { "code": "320100", "name": "南京" },
      { "code": "320500", "name": "苏州" },
      { "code": "120100", "name": "天津" },
      { "code": "420100", "name": "武汉" },
      { "code": "430100", "name": "长沙" },
      { "code": "500100", "name": "重庆" },
      { "code": "510100", "name": "成都" }
    ],
    "provinces": [
      { "code": "110000", "name": "北京市" },
      { "code": "120000", "name": "天津市" },
      { "code": "130000", "name": "河北省" },
      { "code": "140000", "name": "山西省" },
      { "code": "150000", "name": "内蒙古自治区" },
      { "code": "210000", "name": "辽宁省" },
      { "code": "220000", "name": "吉林省" },
      { "code": "230000", "name": "黑龙江省" },
      { "code": "310000", "name": "上海市" },
      { "code": "320000", "name": "江苏省" },
      { "code": "330000", "name": "浙江省" },
      { "code": "340000", "name": "安徽省" },
      { "code": "350000", "name": "福建省" },
      { "code": "360000", "name": "江西省" },
      { "code": "370000", "name": "山东省" },
      { "code": "410000", "name": "河南省" },
      { "code": "420000", "name": "湖北省" },
      { "code": "430000", "name": "湖南省" },
      { "code": "440000", "name": "广东省" },
      { "code": "450000", "name": "广西壮族自治区" },
      { "code": "460000", "name": "海南省" },
      { "code": "500000", "name": "重庆市" },
      { "code": "510000", "name": "四川省" },
      { "code": "520000", "name": "贵州省" },
      { "code": "530000", "name": "云南省" },
      { "code": "540000", "name": "西藏自治区" },
      { "code": "610000", "name": "陕西省" },
      { "code": "620000", "name": "甘肃省" },
      { "code": "630000", "name": "青海省" },
      { "code": "640000", "name": "宁夏回族自治区" },
      { "code": "650000", "name": "新疆维吾尔自治区" },
      { "code": "710000", "name": "台湾省" },
      { "code": "810000", "name": "香港特别行政区" },
      { "code": "820000", "name": "澳门特别行政区" }
    ]
  }
}

CONFIG-04 获取落地页配置

项目	说明
接口路径	GET /client/api/v1/landing/config
接口用途	H5 落地页获取下载、联系、安装失败教程链接
权限要求	公开
涉及表	platform_config

接口逻辑：

查询 platform_config 表，读取 group_name=landing 相关配置
返回 iOS 下载、Android 下载、商务合作 TG、联系我们 TG、安装失败教程链接
H5 前端根据 User-Agent 自行判断当前设备并选择对应下载链接

请求参数： 无

响应数据：

字段	类型	说明
iosDownloadUrl	string	iOS 下载链接
androidDownloadUrl	string	Android 下载链接
businessTgUrl	string	商务合作 Telegram 链接
contactTgUrl	string	联系我们 Telegram 链接
installTutorialUrl	string	安装失败「点我查看教程」链接

业务规则：

后端只返回运营后台配置的链接，不做设备判断
前端/H5 根据 User-Agent 判断 iOS / Android 后，自行使用 iosDownloadUrl 或 androidDownloadUrl
后端不返回 fallbackDownloadUrl
未配置的字段返回空字符串

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "iosDownloadUrl": "https://apps.apple.com/app/id123",
    "androidDownloadUrl": "https://cdn.example.com/app.apk",
    "businessTgUrl": "https://t.me/business",
    "contactTgUrl": "https://t.me/contact",
    "installTutorialUrl": "https://h5.example.com/install-help"
  }
}

CONFIG-05 获取 Analytics SDK 初始化配置

项目	说明
接口路径	GET /client/api/v1/analytics/config
接口用途	客户端初始化 Analytics SDK 时获取 `appId` 与 `encryptedConfig`
权限要求	公开
涉及服务	数据中心 `GET /sdk/getAvailableDomainList`

接口逻辑：

服务启动时立即向数据中心拉取一次密文配置，并在后台按固定周期刷新
上游地址按环境区分：
- 测试环境：https://dcapi.dc-dev.cc/sdk/getAvailableDomainList
- 正式环境：https://api.dc-server.cc/sdk/getAvailableDomainList
上游响应要求：
- HTTP 2xx
- code = 0
- data 为非空字符串
上游 data 视为不透明密文，后端只做“拉取 -> 缓存 -> 转发”，不解密、不修改
拉取成功则刷新缓存；拉取失败但本地/Redis 仍有历史缓存时继续返回旧值
若首次拉取失败且无任何缓存，则向客户端返回明确错误，不返回空字符串

请求参数： 无

响应数据：

字段	类型	说明
appId	string	业务端配置的应用 ID，客户端初始化 SDK 时直接透传
encryptedConfig	string	数据中心返回的密文配置，客户端原样交给 SDK
updatedAt	number	最近一次成功刷新缓存的 Unix 时间戳（秒）

缓存规则：

拉取周期默认 10 分钟
Redis TTL 默认 30 分钟
后端不解析 encryptedConfig 内容，也不从中提取上报域名或白名单
客户端拿到 encryptedConfig 后直接传给 SDK，由 SDK 内部完成解密与使用

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "appId": "17",
    "encryptedConfig": "vIF30KjWHGsB7vng776ZGLt5qvb3lswIjEf1I0fHkOTZhRSBZ8ugR+NT7kMl8CFbD...",
    "updatedAt": 1710000000
  }
}

11 KiB Raw Blame History Unescape Escape

API-11 系统配置（CONFIG）

系统配置（config）

CONFIG-01 获取全局配置

CONFIG-02 获取可用域名列表

CONFIG-03 获取城市列表

CONFIG-04 获取落地页配置

CONFIG-05 获取 Analytics SDK 初始化配置

11 KiB

Raw Blame History