@ (#111)
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
This commit was merged in pull request #111.
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
# GET /api/v1/platform/ad-config — 客户端广告配置
|
||||
|
||||
> 所属:Platform 组（前缀 `/api/v1/platform`） | 鉴权:无 | [← 返回 API 索引](../README.md)
|
||||
|
||||
客户端启动 / 每场广告前拉取，缓存后用：穿山甲 `app_id` + 各位 ID + 各场景开关。不含验签密钥（密钥只在后端验 S2S 回调用）。
|
||||
|
||||
## 入参
|
||||
|
||||
无。
|
||||
|
||||
## 出参
|
||||
|
||||
响应 `200`:`AdConfigPublicOut`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `app_id` | string | 穿山甲应用 ID（改了需冷启才生效，SDK init 一次性读） |
|
||||
| `reward_code_id` | string | 福利页激励视频位 |
|
||||
| `compare_draw_code_id` | string | 比价 Draw 代码位 |
|
||||
| `coupon_draw_code_id` | string | 领券 Draw 代码位（与比价共用同一位，靠 `feed_scene` 区分收益） |
|
||||
| `reward_enabled` | bool | 福利激励视频开关 |
|
||||
| `compare_ad_enabled` | bool | 比价广告开关 |
|
||||
| `coupon_ad_enabled` | bool | 领券广告开关 |
|
||||
| `withdrawal_ad_enabled` | bool | 提现激励视频开关（关 = 客户端直接放行提现） |
|
||||
|
||||
Mock 出参:
|
||||
```json
|
||||
{
|
||||
"app_id": "5123456",
|
||||
"reward_code_id": "104001",
|
||||
"compare_draw_code_id": "104002",
|
||||
"coupon_draw_code_id": "104002",
|
||||
"reward_enabled": true,
|
||||
"compare_ad_enabled": true,
|
||||
"coupon_ad_enabled": true,
|
||||
"withdrawal_ad_enabled": false
|
||||
}
|
||||
```
|
||||
|
||||
## 说明
|
||||
- 空库回退默认值（= 客户端内置值，维持现状）
|
||||
- 不含验签密钥（`m-key`），安全边界
|
||||
- `coupon_draw_code_id` 与 `compare_draw_code_id` 通常同值，客户端按场景调不同端点区分
|
||||
@@ -0,0 +1,39 @@
|
||||
# GET /api/v1/platform/app-version — 最新 App 版本
|
||||
|
||||
> 所属:Platform 组（前缀 `/api/v1/platform`） | 鉴权:无 | [← 返回 API 索引](../README.md)
|
||||
|
||||
客户端启动 / 手动检查更新时拉取。用 `latest_version_code` 与本机 `versionCode` 比；未配置（返回默认 0）时客户端视为已是最新。
|
||||
|
||||
## 入参
|
||||
|
||||
无。
|
||||
|
||||
## 出参
|
||||
|
||||
响应 `200`:`AppVersionOut`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `latest_version_code` | int | 最新版 versionCode；0 = 未配置（无更新） |
|
||||
| `latest_version_name` | string | 展示用版本号（如 `0.1.4`） |
|
||||
| `apk_url` | string | 下载链接（发车产出的永久版本化链接） |
|
||||
| `update_note` | string | 更新说明，弹窗展示（如「修复了部分机型闪退问题」） |
|
||||
| `min_supported_version_code` | int | 本机低于此版本 = 强制更新；0 = 不强更（全可选） |
|
||||
| `apk_size_bytes` | int | 包大小（字节），展示「约 x MB」 |
|
||||
|
||||
Mock 出参:
|
||||
```json
|
||||
{
|
||||
"latest_version_code": 42,
|
||||
"latest_version_name": "0.1.5",
|
||||
"apk_url": "https://cdn.shaguabijia.com/releases/app-v0.1.5.apk",
|
||||
"update_note": "1. 修复了部分机型闪退问题\n2. 优化了比价速度\n3. 新增省钱大作战功能",
|
||||
"min_supported_version_code": 35,
|
||||
"apk_size_bytes": 18350080
|
||||
}
|
||||
```
|
||||
|
||||
## 说明
|
||||
- 不鉴权（版本信息非敏感，检查更新可能在登录前）
|
||||
- `latest_version_code = 0` → 无更新，客户端无需提示
|
||||
- `min_supported_version_code > 本机 versionCode` → 强制更新弹窗（不可跳过）
|
||||
@@ -0,0 +1,28 @@
|
||||
# GET /api/v1/platform/flags — 客户端 Feature Flags
|
||||
|
||||
> 所属:Platform 组（前缀 `/api/v1/platform`） | 鉴权:无 | [← 返回 API 索引](../README.md)
|
||||
|
||||
客户端拉取运营开关并缓存（app 启动 / 每场比价开始时刷新）。不鉴权：开关非敏感，且比价无障碍服务取值时未必有登录态。值来自 `app_config`（admin 可改），空库回退默认。
|
||||
|
||||
## 入参
|
||||
|
||||
无。
|
||||
|
||||
## 出参
|
||||
|
||||
响应 `200`:`AppFlagsOut`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `comparing_ad_enabled` | bool | 比价/领券期是否展示信息流广告（远程 kill-switch） |
|
||||
|
||||
Mock 出参:
|
||||
```json
|
||||
{
|
||||
"comparing_ad_enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
## 说明
|
||||
- 客户端拉取后本地缓存，避免每次请求
|
||||
- 空库回退默认值（false）
|
||||
@@ -0,0 +1,28 @@
|
||||
# GET /api/v1/platform/stats — 首页三统计(全平台门面数字)
|
||||
|
||||
> 所属:Platform 组（前缀 `/api/v1/platform`） | 鉴权:**无**（登录前首页也要展示） | [← 返回 API 索引](../README.md)
|
||||
|
||||
客户端首页顶部「帮助用户 / 完成比价 / 累计节省」三个平台级数字。每个指标的展示模式由运营后台配（见 [admin-dashboard-display](./admin-dashboard-display.md)），本接口只返回算好的结果值。
|
||||
|
||||
## 入参
|
||||
无。
|
||||
|
||||
## 出参
|
||||
响应 `200`:`PlatformStatsOut`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `help_users` | int | 帮助用户（人） |
|
||||
| `total_compares` | int | 完成比价（次） |
|
||||
| `total_saved_cents` | int | 累计节省（**分**），客户端 ÷100 显示「元」 |
|
||||
|
||||
## 说明
|
||||
三指标各自独立选模式,且**统一「定时刷新」**:客户端看到的展示值只在「更新时间(按更新间隔)」对齐的北京钟点(`anchor + k*间隔`)刷新一次,平时不变。每次刷新按模式算新值:
|
||||
- **real**:重新快照查库,再与保底值取大。`help_users`=有过 `status='success'` 比价记录的去重用户数;`total_compares`=成功比价记录数;`total_saved_cents`=成功记录 `saved_amount_cents` 求和(**只计 `0<saved≤300 元` 的条目**,剔除 bug 异常大值);最终展示 = `max(真实值, 运营配的 real_offset 保底值)`。
|
||||
- **manual**:取运营当前手填的固定值(改值到下个更新钟点生效)。
|
||||
- **random**:在上次展示值上按方式增长——`mult` ×一个 [1.0,1.5] 随机倍率 / `add` +一个 [下限,上限] 随机绝对增量(跨几个钟点走几次)。
|
||||
- **只增不减**:默认门面数字不回退(real/manual 新值低于当前则保持),除非运营开「允许下降」。
|
||||
|
||||
计算逻辑见 `app/repositories/ops_stat.py`,模型见 `app/models/ops_stat_config.py`(表 [ops_stat_config](../database/ops_stat_config.md))。
|
||||
|
||||
上线初始播种为 manual + 客户端原写死门面值(12847 / 86532 / 37621.40 元),保证前后展示一致。
|
||||
Reference in New Issue
Block a user