docs(api): document promotion tracking stats
This commit is contained in:
parent
7f8958d41b
commit
4d313490fe
@ -495,7 +495,7 @@
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 接口路径 | GET/PUT `/admin/api/v1/config/system` |
|
||||
| 接口用途 | 配置 Android / iOS 侧 App API 域名列表、默认头像/昵称库、人民币兑糖心币比例、推广工具短链域名 |
|
||||
| 接口用途 | 配置 Android / iOS 侧 App API 域名列表、默认头像/昵称库、人民币兑糖心币比例、推广工具短链域名、推广落地页基准 URL |
|
||||
| 权限要求 | 超级管理员 |
|
||||
| 涉及表 | platform_config, admin_operation_log |
|
||||
|
||||
@ -509,7 +509,7 @@
|
||||
**PUT** — 更新系统配置：
|
||||
1. 校验管理员权限（permission_key: `config:manage`）
|
||||
2. 查询 `platform_config` 读取现有值（读）
|
||||
3. 对 `appApiAndroid`、`appApiIos` 做分号列表标准化，对 `defaultNicknamePool` 做按行去重标准化，对 `coinsPerYuan` 做正整数且可与 `100 分` 精确换算校验，对 `shortLinkDomainUrl` 做完整 URL 校验并去除尾部 `/`，按配置键写回 `platform_config`（写）
|
||||
3. 对 `appApiAndroid`、`appApiIos` 做分号列表标准化，对 `defaultNicknamePool` 做按行去重标准化，对 `coinsPerYuan` 做正整数且可与 `100 分` 精确换算校验，对 `shortLinkDomainUrl`、`promotionLandingBaseUrl` 做完整 URL 校验并去除尾部 `/`，按配置键写回 `platform_config`（写）
|
||||
4. 写入 `admin_operation_log`（action: `update_system_config`）（写）
|
||||
|
||||
**业务规则：**
|
||||
@ -521,6 +521,7 @@
|
||||
- `defaultNicknamePool`
|
||||
- `coinsPerYuan`
|
||||
- `shortLinkDomainUrl`
|
||||
- `promotionLandingBaseUrl`
|
||||
2. 所有字段都支持部分更新，未传字段保持原值
|
||||
3. 传空字符串表示清空对应配置
|
||||
4. 输入值按分号分隔多个域名，后端会自动：
|
||||
@ -534,6 +535,7 @@
|
||||
- `defaultNicknamePool` -> `app.default_nickname_pool`
|
||||
- `coinsPerYuan` -> `coin.rate_coins_per_yuan`
|
||||
- `shortLinkDomainUrl` -> `promotion.short_link_domain_url`
|
||||
- `promotionLandingBaseUrl` -> `promotion.landing_base_url`
|
||||
- `group_name = system`
|
||||
- `config_type = string/int`
|
||||
6. 旧的通用 KV 接口 `/admin/api/v1/configs` 不作为此页面的对接入口
|
||||
@ -549,6 +551,7 @@
|
||||
| defaultNicknamePool | string[] | 默认昵称库，一行一个昵称 |
|
||||
| coinsPerYuan | number | 人民币兑糖心币比例，表示 `1 元 = N 币` |
|
||||
| shortLinkDomainUrl | string | 推广工具短链域名完整 URL，例如 `https://txin.me` |
|
||||
| promotionLandingBaseUrl | string | 推广工具短链点击后的临时承接页基准 URL，例如 `https://h5.txagent.cc` |
|
||||
|
||||
**PUT 请求参数（Body）：**
|
||||
|
||||
@ -560,6 +563,7 @@
|
||||
| defaultNicknamePool | string[] | 否 | 默认昵称库 |
|
||||
| coinsPerYuan | number | 否 | 人民币兑糖心币比例，表示 `1 元 = N 币` |
|
||||
| shortLinkDomainUrl | string | 否 | 推广工具短链域名完整 URL；传空字符串表示清空 |
|
||||
| promotionLandingBaseUrl | string | 否 | 推广工具短链点击后的临时承接页基准 URL；传空字符串表示清空 |
|
||||
|
||||
**PUT 响应数据：**
|
||||
|
||||
@ -571,6 +575,7 @@
|
||||
| defaultNicknamePool | string[] | 默认昵称库 |
|
||||
| coinsPerYuan | number | 人民币兑糖心币比例 |
|
||||
| shortLinkDomainUrl | string | 标准化后的推广工具短链域名完整 URL |
|
||||
| promotionLandingBaseUrl | string | 标准化后的推广工具短链临时承接页基准 URL |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -607,7 +607,7 @@
|
||||
| shortLink.shortUrl | string | 拼接后的推广短链；未配置短链域名时为空字符串 |
|
||||
|
||||
> 说明：
|
||||
> - 本期只补“配置 + 查询”能力，不包含短链跳转入口、绿色落地页、二维码图片接口和真实点击归因。
|
||||
> - 短链路径段固定使用不可变 `username`。
|
||||
> - 前端应使用后端返回的 `shortLink.shortUrl`，不要硬编码 `txin.me`。
|
||||
|
||||
---
|
||||
@ -619,11 +619,14 @@
|
||||
| 接口路径 | GET /client/api/v1/creator/promotion/stats |
|
||||
| 接口用途 | 获取创作者推广工具页所需的引流统计数据 |
|
||||
| 权限要求 | 创作者 |
|
||||
| 涉及表 | user |
|
||||
| 涉及表 | user, creator_promotion_click, creator_promotion_attribution, creator_promotion_conversion, creator_promotion_daily_stats |
|
||||
|
||||
**接口逻辑：**
|
||||
1. 校验当前登录用户为创作者（`user.role=2`）
|
||||
2. 本期不读取点击归因表和落地页统计，直接返回稳定字段占位值 `0`
|
||||
2. 读取 `creator_promotion_daily_stats` 聚合统计（读）
|
||||
3. 统计累计点击 `totalClicks`、今日点击 `todayClicks`（读）
|
||||
4. 读取 `creator_promotion_click` 的累计唯一访客数作为转化率分母（读）
|
||||
5. 按 `累计首充转化数 / 累计唯一访客数 * 100` 计算 `conversionRate`
|
||||
|
||||
**请求参数：** 无
|
||||
|
||||
@ -631,13 +634,50 @@
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| totalClicks | number | 累计点击数；本期固定返回 `0` |
|
||||
| todayClicks | number | 今日点击数；本期固定返回 `0` |
|
||||
| conversionRate | number | 转化率；本期固定返回 `0` |
|
||||
| totalClicks | number | 累计点击数 |
|
||||
| todayClicks | number | 今日点击数（`Asia/Singapore` 自然日） |
|
||||
| conversionRate | number | 转化率，口径：点击转首充；分母为累计唯一访客数 |
|
||||
|
||||
> 说明：
|
||||
> - 本期只稳定统计字段，不接真实点击/转化埋点。
|
||||
> - 转化率后续口径预留为“点击转首充”，当前统一返回 `0`。
|
||||
> - 点击事件由推广短链入口写入 `creator_promotion_click`。
|
||||
> - 归因窗口为 7 天。
|
||||
> - 首充成功且命中有效归因时，写入 `creator_promotion_conversion`。
|
||||
> - 无点击数据时三项都返回 `0`。
|
||||
|
||||
---
|
||||
|
||||
#### CREATOR-10C 推广短链入口（公开）
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 接口路径 | GET /:username |
|
||||
| 接口用途 | 承接推广短链访问、记录点击、建立匿名访客标识，并临时跳转到 H5 创作者页 |
|
||||
| 权限要求 | 无 |
|
||||
| 涉及表 | user, platform_config, creator_promotion_click, creator_promotion_attribution |
|
||||
|
||||
**接口逻辑：**
|
||||
1. 根据路径中的 `username` 查询创作者；未命中或目标不是创作者返回 `404`
|
||||
2. 读取 `platform_config["promotion.landing_base_url"]` 作为临时承接页基准 URL（读）
|
||||
3. 读取或生成 `visitor_key`，通过短链域名 cookie 持久化 7 天
|
||||
4. 写入 `creator_promotion_click` 一条点击明细（写）
|
||||
5. 若请求带有效登录态，则立即把本次点击绑定到当前用户的推广归因（写）
|
||||
6. `302` 跳转到临时 H5 创作者页：`{promotionLandingBaseUrl}/creator/{creatorId}`
|
||||
|
||||
**路径参数：**
|
||||
|
||||
| 字段 | 类型 | 必选 | 说明 |
|
||||
|------|------|------|------|
|
||||
| username | string | 是 | 创作者不可变用户名，用作短链路径段 |
|
||||
|
||||
**返回行为：**
|
||||
- 成功：`302 Found`
|
||||
- 创作者不存在：`404 Not Found`
|
||||
- 未配置 `promotionLandingBaseUrl`：`503 Service Unavailable`
|
||||
|
||||
> 说明：
|
||||
> - 本期不做 Universal Link / App Link。
|
||||
> - 在绿色落地页上线前，短链先跳现有 H5 创作者主页作为临时承接页。
|
||||
> - 访客唯一性优先以短链域名 cookie `visitor_key` 识别；后续登录/注册/充值链路会结合 `IP + User-Agent` 做 7 天内的弱归因补绑。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -137,6 +137,7 @@
|
||||
- CREATOR-10 创作者数据总览 — `GET /client/api/v1/creator/dashboard`
|
||||
- CREATOR-10A 获取推广短链信息 — `GET /client/api/v1/creator/promotion`
|
||||
- CREATOR-10B 获取推广引流统计 — `GET /client/api/v1/creator/promotion/stats`
|
||||
- CREATOR-10C 推广短链入口（公开） — `GET /:username`
|
||||
- CREATOR-11 搜索粉丝（@ 选择器） — `GET /client/api/v1/creator/fans/search`
|
||||
- CREATOR-12 移除粉丝 — `DELETE /client/api/v1/creator/fans/:fanId`
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user