@ (#111)

docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
2026-07-03 15:00:37 +08:00
parent ee132aa93b
commit a563c1ca4b
102 changed files with 2418 additions and 217 deletions
@@ -0,0 +1,100 @@
+# 邀请绑定（bind + landing-track）
+
+> 所属:Invite 组（前缀 `/api/v1/invite`） | 鉴权:bind 需 Bearer / landing-track 无需鉴权 | [← 返回 API 索引](../README.md)
+
+---
+
+## POST /bind — 绑定邀请人
+
+把当前登录用户（被邀请人）绑定到某邀请码。支持三种归因路径：clipboard（首启读剪贴板）、manual（手动输入邀请码）、fingerprint（指纹兜底反查）。绑定成功双方各发 1 万金币。
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `invite_code` | string \| null | ❌ | 邀请码；走指纹兜底时为空 |
+| `channel` | string | ✅ | 归因来源：`clipboard` / `manual` / `fingerprint` |
+| `fingerprint` | object \| null | ❌ | 指纹兜底时必传 |
+| `fingerprint.screen` | string | - | 屏幕分辨率（如 `1080x2400`） |
+| `fingerprint.device_model` | string | - | 设备型号（如 `24115RA8EC`） |
+
+Mock 入参（clipboard 归因）:
+```json
+{
+  "invite_code": "A3F8K2",
+  "channel": "clipboard",
+  "fingerprint": null
+}
+```
+
+Mock 入参（指纹兜底）:
+```json
+{
+  "invite_code": null,
+  "channel": "fingerprint",
+  "fingerprint": {
+    "screen": "1080x2400",
+    "device_model": "24115RA8EC"
+  }
+}
+```
+
+### 出参
+
+响应 `200`:`BindInviteOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `status` | string | `success` / `already_bound` / `invalid_code` / `self_invite` / `not_eligible` / `fp_not_found` |
+| `coins_awarded` | int | 本次给当前用户（被邀请人）发的金币 |
+| `message` | string | 给前端直接展示的文案 |
+
+Mock 出参:
+```json
+{
+  "status": "success",
+  "coins_awarded": 10000,
+  "message": "邀请绑定成功"
+}
+```
+
+---
+
+## POST /landing-track — 落地页指纹采集
+
+B 浏览器打开 `dl.html?ref=xxx` 时上报指纹（剪贴板归因失败时兜底）。**无需鉴权**（浏览器没 token）。
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `ref` | string | ✅（4-16 位） | 邀请码（落地页 `?ref=`） |
+| `screen` | string | ❌ | 屏幕分辨率（如 `1080x2400`） |
+
+Mock 入参:
+```json
+{
+  "ref": "A3F8K2",
+  "screen": "1080x2400"
+}
+```
+
+### 出参
+
+响应 `200`:`LandingTrackOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `status` | string | `ok` / `invalid_code` / `no_ip` |
+
+Mock 出参:
+```json
+{"status": "ok"}
+```
+
+---
+
+## 说明
+- `bind`: 绑定只在注册后首次有效（`not_eligible` = 已过新人期），自邀屏蔽
+- `landing-track`: IP/UA 服务端从 HTTP 头自动拿，JS 无需上报
+- 指纹反查窗口期由 `INVITE_FP_WINDOW_DAYS` 控制