# VTY 品牌域名防护 · 技术开发清单

| 字段 | 内容 |
|------|------|
| 文档类型 | **技术开发清单**（研发 / 测试联调） |
| 文档版本 | **v1.0** |
| 修订日期 | 2026-09-02 |
| 对应产品 PRD | [PRD.html](../PRD.html) v1.2 |
| 范围 | 品牌域名 · PC / H5（不含 App、分享域名） |

> **说明：** 本清单从产品 PRD 拆解 **研发必做项**，供排期与联调勾选。判定细节（阈值、特征库）由技术自定，但 **产品表现** 须与 PRD 一致。

---

# 一、风控判定（不下发主站列表）

落地域进入后、**返回动态域名之前**，须完成以下判定。**任一命中 → 不调用 / 不返回动态域名接口**，前端展示 **空页（E1）** 或对应全屏（E6）。

## T-1 异常 IP / 设备判定 ⭐ P0

| 项 | 要求 |
|----|------|
| **后台配置** | 运营/风控在后台维护 **IP 黑名单**、**设备黑名单**（支持增删、批量导入、生效时间） |
| **接口** | 落地域服务提供 **查询接口**（或内网 RPC），返回当前生效黑名单 / 命中结果；支持缓存与失效刷新 |
| **采集维度** | ① **当前请求 IP**（含 X-Forwarded-For 规范） ② **当前设备标识**（浏览器指纹 / deviceId，H5·PC 同一套生成规则） |
| **匹配逻辑** | 请求 IP ∈ IP 黑名单 **或** 设备 ID ∈ 设备黑名单 → **判定异常** |
| **关于「登录用户」** | 品牌链进入时 **通常尚未登录**。判定以 **当前访问 IP + 当前设备指纹** 为准。若需关联账号维度，可将 **账号历史登录 IP/设备** 作为黑名单数据源之一，由后台配置，**不强制** |
| **命中后** | **拒绝下发** 动态域名；HTTP 可返回空 body / 特定 code；前端 **空页**，无文案 |
| **产品映射** | R-L1 · R-L2 · E1 · B3 |

**建议接口形态（示例，字段技术自定）：**

```text
POST /api/landing/risk-check
Request : { ip, deviceId, fingerprint, brand, ua, ... }
Response: { pass: false, reason: "IP_BLACKLIST" | "DEVICE_BLACKLIST" | ... }
          pass=true 时才允许下一步拉取动态域
```

---

## T-2 脚本 / 爬虫 / 自动化判定 ⭐ P0

| 项 | 要求 |
|----|------|
| **目标** | 识别 **脚本、Headless、自动化工具、爬虫** 等非正常人工浏览器访问 |
| **判定时机** | 与 T-1 同属风控链路，在 **获取动态域名之前** |
| **命中后** | **直接拒绝** 获取动态域名（与 T-1 相同：**空页 E1**，不下发列表） |
| **手段（技术自选）** | UA 规则、Headless 特征、行为挑战、TLS/Canvas/WebDriver 检测、请求频率特征等 |
| **产品映射** | R-L1 · §3.3.1 脚本进入 · B4 |

> 产品要求：**是脚本/爬虫即拒绝**，不要求对用户解释原因。

---

## T-3 刷机 / Root 环境判定 P0

| 项 | 要求 |
|----|------|
| **范围** |  primarily **H5**；PC 可按 UA/环境可选扩展 |
| **判定标准** | 技术补充（越狱、Root、模拟器、调试环境等特征库） |
| **命中后** | 同 T-1/T-2：**拒绝动态域名 + 空页** |
| **产品映射** | §3.3.1 刷机设备 · B4 |

---

## T-4 访问频率限制 P1

| 项 | 要求 |
|----|------|
| **规则** | 同一 IP 或 deviceId 在滑动窗口内超过阈值 → 拦截 |
| **命中后** | **不下发** 动态域名；前端 **全屏 E6**「访问过于频繁」（**非空页**） |
| **配置** | 阈值、窗口时长可后台或配置中心调整 |
| **产品映射** | R-L7 · E6 · B6 |

---

# 二、动态主站域名下发

## T-5 加密动态域名接口 ⭐ P0

| 项 | 要求 |
|----|------|
| **前置条件** | **仅** 在 T-1～T-4 风控 **全部通过** 后才可调用 |
| **返回内容** | 加密的主站域名列表，**最多 3 条**，**有序** |
| **加密** | 算法与密钥管理技术自定；须防明文嗅探、重放（建议 nonce + 短 TTL） |
| **域名来源** | 对接现有 **主站域名池**；与 App/分享链路网关 **隔离配置** 亦可，但池内主站需可用 |
| **失败** | 接口异常 → 前端 E5 全屏「加载失败」 |
| **产品映射** | R-L3 · R-L6 |

**建议接口形态：**

```text
POST /api/landing/domains
Request : { deviceId, brand, token from risk-check, ... }
Response: { encrypted: "...", ttl: 300, count: 3 }
          风控未通过 → 403 / pass=false，body 不含域名
```

---

## T-6 拒绝策略统一网关 P0

| 项 | 要求 |
|----|------|
| **原则** | 风控失败 **不得** 在任何响应中泄露 `play-*.com` 明文 |
| **服务端** | 统一风控中间层：未 pass 则 **domains 接口直接拒绝** |
| **客户端** | 收到 reject 后不尝试解密、不探活，直接渲染 **空页或 E6** |
| **产品映射** | R-L2 · R-L6 · §8.3 |

---

# 三、落地页前端（PC / H5）

## T-7 落地页壳与品牌参数 P0

| 项 | 要求 |
|----|------|
| **部署域** | 落地中间域（如 `entry.vty.net`） |
| **301 参数** | 解析 `from=winbet` 等品牌来源，上报风控/统计 |
| **页面内容** | **不得** 含投注、钱包、完整首页；仅 Loading / 空页 / 错误态 |
| **产品映射** | R-B1～R-B4 · 注意事项 §5 |

---

## T-8 设备指纹采集 P0

| 项 | 要求 |
|----|------|
| **PC / H5** | 统一生成 **deviceId / fingerprint**，写入风控请求 |
| **持久化** | localStorage / cookie（策略技术定），供频率限制与黑名单匹配 |
| **隐私** | 不上送 unnecessary PII；日志脱敏 |

---

## T-9 探活与进站 P0

| 项 | 要求 |
|----|------|
| **解密** | 客户端解密 T-5 返回列表 |
| **顺序** | 严格 **1 → 2 → 3** 探活 |
| **成功** | 第一条可用 → `location` 跳转主站 |
| **切换** | 前序超时 → Toast「正在切换备用线路…」再试下一条 |
| **全失败** | E4 全屏，可重试（重新走 risk + domains + 探活） |
| **地址栏** | 探活完成前保持 **落地域** |
| **产品映射** | R-L4 · R-L5 · E3 · E4 · B5 · B7 |

---

## T-10 异常 UI 分级 P0

| 场景 | UI | 禁止 |
|------|-----|------|
| 风控命中（T-1/T-2/T-3） | **空页** E1 | 全屏报错、暴露主站域 |
| 频率限制 T-4 | 全屏 E6 | 空页 |
| 接口失败 | 全屏 E5 | 展示域名池 |
| 探活全失败 | 全屏 E4 | 跳主站 |
| **文案** | zh-CN 默认；vi-VN 同 key | 「刷机」「脚本」「黑名单」等 |

---

# 四、后台与运维

## T-11 黑名单管理后台 P0

| 项 | 要求 |
|----|------|
| **功能** | IP 黑名单、设备黑名单 CRUD、导入导出、操作审计 |
| **联动** | 变更后 **≤N 分钟** 内落地服务生效（推/拉模式技术定） |
| **角色** | 运营/风控维护；研发提供 API |

---

## T-12 主站域名池对接 P0

| 项 | 要求 |
|----|------|
| **能力** | 按品牌/区域返回最多 3 条 **当前可用** 主站 |
| **探活** | 服务端预筛 or 客户端探活（产品要求客户端探活） |
| **与现网** | 进站后切换逻辑 **不改**，仅保证 brand 链能带入正确首站 |

---

## T-13 运维 301（协同项） P0

| 项 | 负责 | 要求 |
|----|------|------|
| 品牌域 301 | **运维** | 任意路径 → 落地域，**禁止** 直连 play-*.com |
| 落地域 URL | **研发提供** | 规范、参数、多品牌映射表 |

---

# 五、安全与观测

## T-14 传输与存储 P1

| 项 | 要求 |
|----|------|
| HTTPS | 品牌 / 落地 / 主站全链路 |
| 域名列表 | 传输加密；客户端内存持有，不落盘明文 |
| 日志 | 记录 pass/fail reason；**不对用户展示**；主站域名日志脱敏 |

---

## T-15 监控与 KPI P1

| 项 | 要求 |
|----|------|
| 指标 | 品牌链成功率、风控拦截率（分 reason）、探活成功率、301 可用率 |
| 告警 | 主站池全不可用、domains 接口错误率飙升 |
| 对齐 KPI | PRD D1～D3（≥88% 进入率等） |

---

# 六、明确不做

| 项 | 说明 |
|----|------|
| App 动态域名 | 现网不变 |
| 分享域名链路 | 现网不变 |
| 落地域业务页 | 禁止 |

---

# 七、研发排期建议（参考）

| 阶段 | 内容 | 依赖 |
|------|------|------|
| **Phase 1** | T-1 黑名单接口 + T-11 后台 + T-7 空页/Loading | 运维 301 规范 T-13 |
| **Phase 2** | T-2 脚本爬虫 + T-3 刷机 + T-4 频率 | Phase 1 |
| **Phase 3** | T-5 加密下发 + T-9 探活进站 + T-10 全屏态 | Phase 2 |
| **Phase 4** | T-14/T-15 安全观测 + 联调 B1～B8 | 全流程 |

---

# 八、联调验收（对照产品 PRD 第九章）

| # | 开发项 | 验收 |
|---|--------|------|
| 1 | T-1 IP/设备黑名单 | B3 空页 |
| 2 | T-2/T-3 脚本/刷机 | B4 空页 |
| 3 | T-4 频率限制 | B6 全屏 E6 |
| 4 | T-5 + T-9 正常链路 | B1/B2 进站 |
| 5 | T-9 探活全失败 | B5 全屏 E4 |
| 6 | T-6 不泄露主站域 | B5 + §8.3 |
| 7 | T-10 文案 | B8 中越 |

---

**文档结束 · 技术开发清单 v1.0**