游戏内悬浮球产品文档

依据：产品需求基线 v0.35 · 2026-09-15。状态：方案评审稿（原型同步状态见各端说明）。

v0.35 新手奖励资格补充

仅两种情况提供一次新手奖励信号：VIB 未登录且游戏账户未检测到信号使用记录；或 VIB 已登录且未与任何游戏网站产生关联。其他情况不新增新手奖励，已有发放记录继续去重。已登录后只检查当前网站未关联是不够的，须检查全部网站。交互原型已同步新手资格、首次关联前判定、登录保留已发信号、发放去重及当前标签页刷新恢复。已登录新手暂按免费演示，正式计费待确认。

使用信号前点数不足界面（2026-09-15 补充）

已同步文档与原型：右侧选择“使用前 · VIB 点数不足” → 点击球 → 首次剧本结束 → 查看不足页。仅告知点数不足，不展示点数明细；保留购买、重新检查、返回游戏操作。模拟购买成功后恢复选择游戏；确认游戏才扣点。验证见 check-floating-points.cjs，截图见 qa/points-before-*.png。满屏限制可通过“满屏限制 · 新手已使用／新手已过期”直接查看；过期暂立即限制，模拟重开恢复，v0.35 起刷新恢复当前标签页状态。此补充不代表其余 v0.34 待同步行为已实现。

v0.34 规则补充与实现边界

需求已更新：游戏 PWA 内先登录游戏、再在悬浮窗登录 VIB 时首次关联；有效期仅从具体游戏信号生成后开始，倒计时由游戏接口提供，无退点；新手过期也触发遮罩、重启恢复；切号清空所有信号。支付失败或取消即放弃，不提供历史单续付，待到账沿用当前版本；VIP 生命周期依据第三方，项目不提供续费退款操作。

本次同步需求文档。以下原型说明保留 v0.33 演示情况；满屏限制已补充直接演示入口及过期触发，实际持久化恢复仍待实现，不能作为 v0.34 已实现的证据。注册赠点仍为演示值。

本次方案调整与原型状态

产品方案与游戏内悬浮球交互原型已同步 v0.33。默认从新手体验开始，右侧评审面板可切换登录、关联冲突、点数不足及进程情境。所有账户、支付、奖励与游戏行为均为本地模拟。

设计与开发衔接

• 普通浮窗仍在球旁展开、可收起；强制登录遮罩覆盖整个游戏，是独立的阻断状态。
• 假设用户是已进入 AI 版游戏、尚无 VIB 账户的新手，以及切换游戏账号的回访用户。这是定性流程推演，不是真实用户研究。
• 新手的关键理解点是：安装／注册 VIB 后仍须返回悬浮球登录；点数不足的关键理解点是：确认具体游戏前补足点数。相关操作和错误提示需在手机首屏清晰可见。
• 奖励来源已确认：新手金额在 MVP 代码写死，正常信号金额由管理后台配置。剧本首次以游戏进程为边界，独立 VIB PWA 重启不重置。后台奖励范围内具体取值、游戏进程识别与跨页状态、换账号清空全部信号已确认，服务端对接仍需细化。
• 原型演示值：新手奖励 R$ 50、正常奖励 R$ 90（后台配置结果样例）、建议下注 R$ 10、正常扣点 16、注册赠点 100、剧本 2.4 秒和下注倒计时 60 秒。新手使用后 5 秒遮罩为已确认业务时长。
• 游戏进程重开使用评审按钮模拟，保留当前页内的新手使用和奖励记录；v0.35 起当前标签页刷新会恢复状态，点击评审场景才重置。若新手已使用且未登录，模拟重开游戏后立即恢复遮罩为防绕过的原型假设，v0.34 已确认必须恢复，实际持久化尚待实现。
• 登录未关联游戏账户时模拟建立关联；登录保留已发新手信号并归并发放记录，不重复发放；当前新手信号完成后可模拟条件奖励。关联时点已确认，实际接口写入仍待对接。
• 真实登录、账户校验、扣点、游戏下注事件和进程识别尚需接入验证。
• 验收清单见 5.3.1；验证脚本为 check-v33.cjs，截图位于 qa/v33-*.png。正式服务与真实游戏进程识别不属于静态原型验证范围。

对应需求原文

以下摘录保留原章节编号和已确认／待明确口径；若存在历史表述冲突，以 v0.35 新手资格及当前 MVP 范围为准。

1. 产品定位

New VIB 是基于 VIB 2.0 衍生的产品，暂称 VIB AI。用户通过嵌入 AI 版博彩游戏中的悬浮机器人获取信号，通过独立的 PWA 完成 VIB 注册、账户管理、发现更多支持的游戏及充点。

产品设想结合用户游戏行为采集游戏数据，提供信号，先展示多款可选游戏，用户选择后获得指定游戏、建议下注金额及倒计时，并自行在游戏中下注。提高胜率、极大概率赢得本局以及“AI 破解”属于用户提出的目标效果，当前没有提供验证证据，本文件不将其记为已实现能力或保证收益承诺。

2. 文档约定

• 已确认：用户直接提出或明确纠正的需求。
• 待明确：当前描述尚未给出具体规则，不默认已有结论。
• 建议：用于后续设计或验证的候选方案，不代表已批准范围。

本文件区分业务版本与文档版本：MVP 是首个产品交付范围；“后续版本”尚未指定正式版本号或交付时间。

3. 产品组成与术语

全局终端与安装约束（最新确认）：

• VIB 用户产品仅面向移动端用户；PWA 与游戏内机器人均按移动端使用场景定义，桌面用户端不纳入当前范围。
• VIB PWA 自身仍需先安装，再按第 5.4 节完成 Splash 和注册／登录；未安装时全屏安装引导，不展示首页及底部导航。
• v0.32 悬浮球例外（已确认）：下载 AI 版游戏平台后即可看到悬浮球。游戏账户已登录、未登录悬浮球 VIB 且游戏账户未检测到信号使用记录的新手，可在安装／注册 VIB 前体验新手信号。使用完成 5 秒后出现不可关闭的全游戏遮罩，提供下载 VIB PWA 或登录 VIB 两个入口；在悬浮球内成功登录前不解除。
• 本次明确替代旧“所有操作前先安装”的悬浮球规则；游戏内只提供 VIB 登录，注册在 VIB PWA 完成。新手信号不预扣，也不抵扣注册／登录后赠送的点数。
• 管理后台是否也限定移动端、是否也必须安装 PWA，尚未明确；本次用户群体约束不自动推导后台操作终端。
• 支持的移动操作系统及浏览器、安装状态检测和无法检测时的处理仍需开发评估。

一个 VIB 账户可关联多个不同网站，也可关联同一网站的多个账户；一个游戏账户只能关联一个 VIB 账户；新手奖励仅按第 5.2 节两种资格提供一次，已登录 VIB 且曾关联任意游戏网站的用户不因新增网站或账户再次获得。合作网站为 JS 接入和配置记录的单位，网站内可包含多款供信号选择的具体游戏；现有后台“游戏名称”等字段与网站的映射需按此区分。游戏内不提供 VIB 注册，不把游戏注册当作 VIB 注册。

5.1 游戏内悬浮机器人

v0.32（2026-09-15，已确认）：以下为当前 MVP 方案，替代旧安装前置、新手预扣及每次使用信号执行剧本的规则。交互原型已同步 v0.33，使用本地状态模拟登录、奖励、扣点与游戏进程。

5.1.1 接入方式与基本交互

• 悬浮球通过后台提供的 JS 接入合作游戏网站；下载 AI 版游戏平台并进入游戏后即可看到，无需先登录游戏或安装 VIB。
• 用户可以拖动悬浮球，不能关闭悬浮球。是否响应点击由游戏登录、VIB 登录及账号关联状态决定。
• 消息气泡在球旁，靠左向右展示、靠右向左展示；普通操作浮窗在球旁展开并随拖动移动，可收起，浮窗外游戏区域可操作。
• 例外：新手信号使用后的强制登录遮罩覆盖整个游戏界面，不能按普通浮窗规则收起，详见 5.1.3。
• 游戏内只提供 VIB 登录，注册跳转 VIB PWA。PWA 内安装、Splash、注册／登录沿用 5.4 节。
• 原型免填账号密码登录仅为历史演示方式，不代表生产认证要求。

5.1.2 登录与关联状态

游戏登录门槛与关联冲突优先于剧本和信号流程。“首次点击”定义见 5.1.6，不等于首次获得新手权益。

5.1.3 新手体验与 5 秒强制登录遮罩

1. 用户已下载 AI 版游戏平台、登录游戏账户，未在悬浮球中登录 VIB，且游戏账户未检测到信号使用记录；按 5.2 节新手资格与发放记录去重。
2. 悬浮球显示 1 个未读角标。首次点击打开浮窗，自动开始剧本；结束后告知有一个信号待使用。
3. 点击“使用信号”展示多款游戏；确认选择一款后关闭浮窗，自动跳转指定游戏搜索结果，用户手动进入游戏。
4. 显示建议下注金额及倒计时。在指定游戏、倒计时内按建议金额下注，标记新手信号已使用。此新手体验不扣点，不生成待扣债务。
5. 从“新手信号使用完成”事件起延迟 5 秒，用户仍未在悬浮球内登录 VIB 时，自动显示覆盖整个游戏界面的遮罩；无需再次点击球。不是从选择游戏、点击使用或奖励结算时起算。
6. 遮罩提供“下载 VIB PWA”和“登录 VIB 账号”。没有关闭、稍后或跳过入口，点击空白、返回普通浮窗或收起操作不能解除遮罩，底层游戏不可操作。
7. 下载路径引导安装 VIB PWA，在 PWA 完成注册后返回游戏，在遮罩提供的悬浮球登录流程内登录 VIB。仅下载、安装、注册或在 PWA 登录，均不等于已在悬浮球登录，不能解除游戏遮罩。
8. 悬浮球内登录成功后解除遮罩，用户可继续游戏；后续信号须通过账号关联校验，按正常规则获取和使用。登录失败保留遮罩及重试入口；关联冲突仍按 5.1.2 禁止分析和获取信号。
9. 如在 5 秒内已完成悬浮球 VIB 登录，不再显示过时的登录遮罩。关闭普通浮窗不取消该计时。

原型评审入口（本次补充）：右侧“满屏限制 · 新手已使用”和“满屏限制 · 新手已过期”直接展示全游戏限制。正常使用路径仍在匹配下注完成后延迟 5 秒；过期路径暂按立即显示实现（演示假设，业务延迟待确认）。两种限制均可演示下载返回、登录失败重试、成功解锁和模拟重开恢复。满屏指手机中的完整游戏区域。v0.35 起当前标签页刷新恢复演示状态，点击评审场景重置；真实进程持久化尚未接入。

遮罩文案提案：标题“登录 VIB 后继续游戏”；说明“请下载 VIB PWA 完成注册，再返回这里登录；已有账号可直接登录。”两个操作首屏可见；登录表单和错误提示位于遮罩内，输入失败后可重试。该文字为设计提案，固定账号冲突文案按用户原文执行。

v0.34 已确认：新手信号未使用而过期也触发强制登录遮罩；重启游戏后仍恢复遮罩，不能通过重启绕过。使用完成后继续沿用 5 秒延迟；过期触发是否也延迟 5 秒尚未说明。持久化、剩余计时恢复及游戏退出登录的技术处理由研发细化。

5.1.4 点数不足与正常信号流程

• 无信号时，浮窗提示没有可用信号；信号获取仍依据已确认奖励条件。MVP 气泡包含点数不足、游戏余额不足及活动等场景；事件管理和消息配置不属于 MVP 后台。
• 有信号时，首次有效点击按 5.1.6 执行剧本；剧本结束展示信号状态。此后同一游戏进程会话内点击“使用信号”直接展示可选游戏，不重复剧本。
• 扣点位置：用户确认选择某一款具体游戏时。确认界面展示该游戏所需点数和当前 VIB 点数；校验足额并扣点成功后，再推进跳转和下注引导。匹配下注仅标记使用完成，不再次扣点；奖励结算不作为扣点触发事件。
• 使用信号前的点数不足界面（本次补充）：游戏与 VIB 均已登录、无关联冲突、有普通待用信号且点数不足时，点击悬浮球，在本进程首次剧本结束后展示独立的“VIB 点数不足”球旁浮窗；再次打开直接显示，不重复剧本。新手免费体验不进入此状态，无信号仍显示无信号页面。
• 界面仅提示“VIB 点数不足”及补足点数后继续，可保留待用信号数；不显示当前点数、需要消耗的点数或差额。主操作“去 VIB 购买点数”新页打开点数购买页，次操作“重新检查点数”“返回游戏”，不提供“查看可选游戏”入口。所需点数依据当前信号奖励及 20% 扣点规则计算；原型正常信号为 16 点，不使用固定 20 点阈值。所需点数仅用于内部校验，在选定游戏后的确认页展示。
• 不足时不扣点、不消耗信号、不产生具体游戏信号或启动倒计时；返回游戏仅收起浮窗，不强制离开游戏。购买取消、失败或尚未到账时保持不足状态。补足后恢复选择游戏入口，不自动扣点或使用信号；如已选定游戏，则保留游戏并恢复确认按钮，主动确认时再次校验。静态原型以评审面板“模拟购买成功”更新点数，未接入跨页支付与余额服务。
• 点数不足提示位置：放在选定游戏的确认区域，不能等用户进游戏、按建议下注后才提示。文案：“VIB 点数不足，还差 X 点。尚未扣点或使用信号。”提供“去 VIB 购买点数”，跳转 VIB 点数购买页；不足时不完成该游戏的扣点确认，不消耗信号、不开始该次下注引导。
• 球旁可同步展示点数不足气泡与状态样式，辅助提示不替代选定游戏时的余额校验。VIB 点数与游戏账户余额分开表达。
• 购买后返回应刷新余额，由用户再次确认选择，不能因打开购买页而视为购买成功或自动扣点。
• 重复点击／请求重试不能重复扣点。扣点失败不显示成功；扣点成功后不存在退点逻辑，过期、放弃、跳转失败或切号均不退点。

5.1.5 账户关联与切换

• 一个 VIB 账户可关联多个游戏账户（包括同网站多个账户），一个游戏账户只能关联一个 VIB 账户。游戏账户身份需结合网站标识区分，不能仅凭跨网站可能重复的游戏 ID 关联。
• 检测到当前游戏账户已关联其他 VIB 时，机器人气泡准确显示：“当前游戏账户已与其他VIBAI账户关联”。停止分析和获取信号，不覆盖原关联，也不能使用其他账户遗留信号。
• 切换游戏账户会清空所有信号，不以悬浮球是否登录 VIB 为前提；重新校验新游戏账户的关联状态，旧账户待下注指引和异步返回不得继续作用于新账户。
• 切号清空全部信号后，切回旧账户不恢复被清空的信号；已扣点不退。清空信号不等于删除历史使用与财务记录。
• 关联发生在游戏 PWA：用户先登录游戏账户，再在悬浮窗成功登录 VIB，首次产生关联。已有相同关联直接沿用，已有其他 VIB 关联不覆盖。解除／更换关联能力未定义。切号不重置游戏进程内的剧本首次标记。

5.1.6 剧本触发、收起与会话定义

• “首次”指从未打开过游戏，或用户杀掉游戏进程后再次打开，在该次游戏进程会话内首次有效点击悬浮机器人。
• 首次有效点击即打开界面并自动走剧本；游戏未登录、需先登录原关联 VIB 或关联冲突时，先执行对应门槛，不能绕过校验开始分析。
• 同一游戏进程会话内，后续获取、使用信号均不再走剧本；不能按信号数量或点击次数重复执行。重启后剧本可再次触发，但不重置新手奖励领取／使用记录，不重复送新手信号。
• 剧本运行时可关闭普通浮窗，剧本继续执行。随时重新打开看到当前进度；已经结束时显示结束后的信号状态，不从头播放。
• 悬浮球在剧本期间显示心电图效果；收起不清除运行状态。剧本内容、时长、是否可主动跳过仍待明确，展示不代表实际分析效果验证。
• v0.33 进程定义（已确认）：剧本只在游戏内悬浮窗执行，因此此处进程明确指游戏进程，不是独立 VIB PWA 的进程。仅关闭或重开 VIB PWA 不重置游戏内剧本的首次标记。游戏进程内收起浮窗、切换游戏账户不重置该标记；JS 对游戏进程生命周期的识别及跨搜索结果页状态保持仍需开发实现，不能将组件挂载、页面刷新或切到后台直接等同杀掉游戏进程。

5.1.7 视觉与交互交付要求

• 普通球旁浮窗保留拖动跟随、左右避让和收起能力；新手强制登录遮罩为独立的全游戏状态。
• 正常有信号展示角标；新手入口明确显示 1 个未读角标。一般角标按全部可用还是未读计数、已读清除规则待明确。
• 产生信号并明确使用哪款游戏后开始计算有效期；倒计时由游戏相关接口提供。建议下注金额与倒计时在球旁展示，倒计时相对球水平居中并随拖动定位，靠底边向上避让。
• 球体保留剧本、点数不足、游戏余额不足的文字／图标区分；不能只靠颜色区分状态。
• 购买点数、订阅跳转 VIB PWA；游戏内不完成支付。移动端长文案和键盘弹起时仍需可见当前操作，遮罩内管理焦点、阻断底层点击，错误提示可感知。

5.2 首次赠送信号

已确认：

1. 首次赠送面向下载 AI 版游戏的新用户，不以新注册 VIB 账户作为发放依据。
2. 符合资格的 AI 版游戏新用户可按 5.1.3 先体验再安装／注册 VIB。MVP 新手信号赠送数量及奖励金额均在代码中写死，不提供后台配置；本次入口呈现 1 个未读角标、1 个待使用信号，正式奖励金额未提供。
3. 信号出现后展示多款游戏供用户选择，选定后提供建议下注金额及倒计时。用户在倒计时结束前进入指定游戏并按建议金额下注，即完成信号使用。未按建议金额下注或玩其他游戏视为未使用；倒计时结束即信号过期。对应内容来源待定，目标游戏与下注金额的后台配置能力仍不纳入 MVP。
4. 注册 VIB 不额外重复赠送新手信号。有效期仅在产生信号并明确使用哪款游戏后开始，时长由游戏相关接口提供；倒计时内未使用即过期，视为放弃新手奖励信号。不再适用生成后 30 天有效期。
5. 新手信号使用完成 5 秒后，未登录悬浮球 VIB 的用户进入不可关闭的登录遮罩；未使用而过期也触发遮罩，重启后仍恢复。过期触发延迟尚未说明。新手体验不预扣、不抵扣赠点。

新手奖励资格（v0.35，2026-09-15 已确认）：

只有以下两种情况提供一次新手奖励信号：

• 两条资格按 VIB 登录状态分别判断；是否注册过 VIB 不单独构成资格。
• 未登录分支检查游戏账户的信号使用记录，不再以游戏账户是否关联过 VIB 作为新手判定依据。
• 已登录分支检查该 VIB 账户全部游戏网站的关联情况；仅“当前网站未关联”不满足条件。已关联其他网站后再进入新网站，不再次获得新手奖励。
• “一次”沿用奖励发放记录去重：已有待使用新手信号时不重复生成；刷新、重开或注册不重发；过期仍按放弃处理。以上是发放资格，不撤回已经发放的信号。
• 游戏登录门槛及关联冲突阻断继续适用。游戏平台需记录信号使用、奖励发放及 VIB 关联信息，具体字段和跨端身份归并由研发细化。
• 待细化：首次双登录会建立关联，资格校验与首次关联写入的执行顺序需保证第二种情况可达；未登录体验转为登录时的发放记录归并方式需明确，不能将两种入口直接实现为各送一次。

一个 VIB 账户可关联多个网站、同网站多个账户；关联能力不代表每个网站各有一次新手权益。条件奖励仍按其独立规则发放。

有效期（v0.34）：仅在产生信号并明确使用哪款游戏后开始，倒计时由游戏相关接口提供；到期未使用即过期。取消原 30 天有效期及双重期限规则。

5.3 主要用户流程

1. 下载 AI 版游戏平台 → 进入游戏看到悬浮球。游戏未登录时提示先登录游戏，点击球无事件。
2. 游戏已登录、游戏账户未检测到信号使用记录、悬浮球 VIB 未登录的新手 → 1 个未读角标 → 首次点击自动剧本 → 1 个待使用信号。
3. 使用新手信号 → 选择具体游戏 → 跳转搜索结果 → 手动进入 → 倒计时内匹配下注 → 标记已使用；该体验不扣点。
4. 使用完成 5 秒后仍未登录悬浮球 VIB → 全游戏强制登录遮罩 → 下载 VIB PWA 并注册，或选择已有 VIB 账号登录。
5. 在悬浮球内登录成功 → 解除遮罩、继续游戏；通过关联校验后可使用后续获得的信号。同一游戏进程会话不再走剧本。
6. 普通信号 → 点击使用 → 展示多款游戏 → 确认某款时校验并扣除 VIB 点数 → 扣点成功再跳转及展示下注引导。点数不足在确认处提示去 VIB 购买点数。

使用、扣点及奖励结算是三个不同事件：

有效期（v0.34）：产生信号并明确具体游戏后，按游戏相关接口提供的倒计时计算有效期；到期未使用即过期，新手同时触发登录遮罩。金额不匹配或其他游戏下注不算使用。信号可累计，切换游戏账户清空所有信号，无退点逻辑。一次下注能否匹配多份信号仍待明确。

v0.33 奖励金额来源与扣点（已确认）：

普通信号扣点数 = ceil（（该信号奖励金额 − 下注金额）× 0.20），ceil 为向上取整。确认界面展示确定的奖励金额、下注金额、应扣点数及当前点数，余额校验通过并扣点成功后再推进流程；不等待游戏下注后的实际结算金额才扣点。游戏侧实际结算金额独立记录。

当前后台沿用最后一次充值金额百分比上下限配置，先按配置确定该信号的具体奖励金额，再用于确认游戏时的扣点；范围内具体取值算法及金额精度仍待细化。该技术细则不改变“正常信号奖励来源为后台配置”的已确认结论，不新增固定金额配置方式。

新手赠点规则：本次新手体验不扣点，不生成预扣记录，注册／登录赠送点数到账后不抵扣本次新手消耗。注册赠点权益保留，数量及是否存在独立登录赠点规则未明确；不推导成每次登录都赠点。历史“注册赠点先抵扣、不足扣到 0”规则取消。此前“已登录用户使用新手信号按公式实际扣点”的特殊分支是否也统一免费需进一步明确，不沿用该旧描述作为本次未登录新手体验的计费依据。

实施前待明确：后台配置范围内金额取值算法、非正差额处理、点数换算、倒计时接口字段与异常处理、换游戏及错误下注后的重试规则。已确认扣点成功后不退点，切号清空全部信号。

5.3.1 本轮验收清单

以上为产品验收标准；v0.33 静态原型验证对应模拟交互，详见 prototype/check-v33.cjs。真实服务接入与游戏进程识别仍需独立验证。