# Live Capsule · 功能需求文档
版本：2026-11-17｜基于 followed-direct-preview 当前方案。
原型为本地固定数据。字段、服务端行为和缺失数据规则为建议；已识别偏差在各模块边界处理中标注。

## 1. Live Capsule
悬浮入口与最多三场快捷切赛

### 展示位置
- APP 内固定贴边悬浮；默认靠右。News、新闻详情、Leagues、比赛内页可展示；Matches、Favorites 两个底部主 Tab 不展示。
- 默认收起，只露出可识别的 LIVE 入口；关闭按钮附着在收起胶囊的右上角。内容滚动时保持固定位置，避让底部导航和安全区。

### 展示内容
- 收起态：直播动效、LIVE、匹配条件的进行中比赛数量。展开态：最多 **3 场**独立小胶囊，不使用整块弹窗。
- 每场顺序为 **主队队徽 → 比分 → 客队队徽 → 比赛分钟**。保留单场减号移除入口和 View more。
- 展开后原入口变为收起图标，不展示整体关闭按钮；收起后恢复 LIVE 入口和右上角关闭按钮。

### 取数
- 建议接口模型：Match.id、home/away.{id,name,crestUrl}、score.{home,away}、status、clock.{minute,addedMinute}、kickoffAt；用户保存 capsuleMatchIds、excludedMatchIds、mainMatchId。
- 数据和字段名为交付建议，尚未对接真实接口。Demo 为固定样例；真实比赛变化由实时数据源更新。

### 计算
- 按 matchId 去重，一场比赛即使同时命中两支关注球队也只计一次。LIVE 数量为满足展示规则的进行中比赛数，不等于展开的 3 场数量。
- 优先展示用户置顶的主要比赛；无主要比赛时展示最新开赛的比赛。相同开球时间建议按 matchId 稳定排序。
- 最多 3 场。单场移除后不在当前展开会话自动补入第四场，避免用户操作目标跳位。

### 交互
- 点击 LIVE 展开；点击收起图标、外部区域或滚动页面收起。收起不删除已加入比赛。
- 点击单场进入对应比赛内页；首次引导发生在进入内页之后。减号只移除胶囊快捷项，不取消比赛关注。
- View more 始终直接打开比赛列表，首次点击也不展示引导。

### 边界处理
- 没有符合条件的进行中比赛时不显示自动胶囊；新比赛符合条件后可重新出现。手动加入是否允许未开赛比赛：本期仅覆盖进行中比赛。
- 队徽缺失使用中性队徽占位并保留球队可访问名称；比分或分钟未知显示“—”，不伪造为 0。
- 待对齐：当前 Demo 以最近手动加入比赛优先于 pin；需求建议明确 pin 优先。LIVE 数与手动加入集合的统计口径也需实现时统一。

## 2. Live Matches
比赛列表、筛选、置顶与关注

### 展示位置
- 由展开胶囊下方 View more 打开；在当前页面上覆盖比赛列表弹窗，背景不可操作，关闭后回到原页面及原滚动位置。

### 展示内容
- 每次打开默认 **Following + General**。顶部范围：Following / Popular / All live；内容视图：General / Stats / Events。
- General：球队、队徽、比分、分钟、置顶图标和关注星标。Stats：角球、控球率、射门数、XG。Events：进球与红牌等事件，显示球员头像、队徽、分钟及事件图标。
- 事件数量多时横向滑动查看全部，不使用“+N”替代内容；比赛列表纵向滚动。各比赛卡片保持紧凑高度。

### 取数
- 范围来自用户关注 matchIds、热门球队配置、全部 live 比赛；热门球队名单由产品运营维护，不用 Demo 的固定样例作为正式名单。
- 技术统计字段建议：stats.home/away.{corners,possession,shots,xg}；事件字段：eventId、matchId、type、minute、addedMinute、playerName、playerPhoto、teamId、occurredAt。

### 计算
- 角球、射门按整数；控球率以百分数展示；XG 保留两位小数。这里使用数据源给出的值，不自行推算。
- 置顶项排在当前范围的首位；其他比赛顺序保持稳定。事件按发生时间排序，新增事件不抢占正在横滑的位置。

### 交互
- 右上角 pin 设置／取消主要关注比赛；设置后立即置顶，并同步胶囊主比赛。
- 星标取消关注后立即取消高亮，本次已打开列表仍保留该行；关闭后下次进入 Following 才移除。重新点亮星标立即恢复关注。
- 点击比赛信息行进入对应比赛内页；设置入口打开 Live capsule 设置，关闭设置后回到列表。切换范围时保留当前内容视图；重新打开列表恢复默认组合。

### 边界处理
- Following 为空展示“No followed matches”；Popular / All live 的空态分别描述当前范围，不统一写成关注为空。
- 事件为空展示“No events yet”；缺少某项统计显示“—”；头像缺失使用占位头像。
- 待对齐：Demo 的 followingSessionIds 有缓存；正式实现应在每次重新打开 Following 时建立新快照，保证取消关注后下次进入不再出现。

## 3. Match Centre
比赛内页与胶囊收藏开关

### 展示位置
- 比赛列表行、小胶囊等正常入口均进入同一比赛内页设计。顶部比赛名称右侧 panel 图标为“加入／移出胶囊”，不是打开全部比赛的按钮。

### 展示内容
- 按照已确认参考图呈现：深色比分头部、队徽和比分、Overview 标签、Highlights、Momentum、Scoring chances、统计、Timeline、新闻、H2H、排名和比赛信息。
- 顶部胶囊按钮高亮表示当前比赛已加入胶囊；未加入时不高亮。可访问名称明确为 Add this match to live capsule / Remove this match from live capsule。

### 取数
- 从所点击的 matchId 获取整场详情及胶囊收藏状态；详情数据与小胶囊的 matchId、球队、比分、分钟必须一致。
- 胶囊收藏独立于比赛关注：移出胶囊不改变 Following 星标，取消比赛关注也不能隐式修改另一套状态，除非有明确产品规则。

### 交互
- 正常点击顶部图标：立即加入／移出当前比赛并更新高亮，不打开列表，也不反复展示引导。
- 仅首次使用或胶囊提醒已关闭时，点击该图标先打开引导设置；用户确认后将当前比赛加入胶囊。取消引导留在比赛内页，不执行收藏变更。
- 从胶囊切赛时直接替换当前详情，返回仍回到最初来源页面；不要在多个比赛详情之间形成冗长返回链。

### 边界处理
- 加入状态需持久化，刷新或重新打开 APP 后恢复；单场移除与功能整体关闭区分保存。
- Demo 的下方详情模块、球员和图表含静态示例，不代表当前队伍的真实比赛数据。开发验收要求所有模块绑定同一 matchId，不能沿用示例跨队数据。
- 视频仅展示示意静帧；评论、阵容等标签在 Demo 中为模块跳转，完整业务不属于本次胶囊迭代范围。

## 4. First-use Guide
先进入比赛，再说明胶囊功能

### 展示位置
- 首次从小胶囊进入比赛：**先打开对应比赛内页，再在内页上弹出设置引导**。背景必须是刚点击的比赛，不能停留在原 News 页面。
- View more 仅打开列表，不触发也不消耗首次引导。顶部收藏开关首次使用／提醒关闭后的再次使用可触发引导。

### 展示内容
- 标题“Keep your matches within reach”；说明浏览其他页面时查看比分，点击胶囊快速切回比赛。
- 提供真实样式的两步图示：News 旁浮动比分 → Tap → Match centre。图示是功能说明，不表现为实时比分或可点击比赛。
- 展示范围二选一；自动出现规则默认“Followed teams are live”；只提供永久确认 Always enable，不提供 Just this time。

### 取数
- 建议状态：onboardingCompleted、capsuleEnabled、sessionHidden、pendingAction.{type,matchId}。首次资格按账号保存，未登录时本机保存。
- 引导使用独立 draft，编辑选项不立即改动已保存设置。确认时一次性提交并标记引导完成。

### 交互
- 首次点击小胶囊 → 进入详情 → 展示引导 → Always enable 保存 → 关闭引导并留在该详情。
- 顶部开关触发引导 → Always enable 保存 → 当前比赛加入胶囊并高亮；返回／关闭弹窗不保存草稿。
- 已完成且提醒开启时不再重复引导；仅未确认关闭引导，不视为完成。关闭胶囊提醒后再从顶部开启时重新询问。

### 边界处理
- 首次引导不因刷新原型而自动出现：必须满足触发行为。文档左侧已预置“引导打开”状态用于评审，不能作为产品自动弹出规则。
- “重置首次体验”和“恢复胶囊”是原 Demo 的演示工具，不进入正式产品界面。
- 默认 Never 或无展示范围时不得以 Always enable 确认为开启；设置页中仍可保存 Never 作为永久关闭规则。

## 5. Capsule Settings
展示范围与自动出现规则

### 展示位置
- 比赛列表右上角设置入口；首次引导复用同一配置内容。设置关闭后返回来源页面或列表。

### 展示内容
- 展示范围为互斥单选：**In app only**（仅 APP 内）或 **In & outside app**（APP 内外）；不存在“只在 APP 外”选项。默认仅 APP 内。
- 自动出现规则互斥单选：Never / Followed teams are live / Popular teams are live / Any match is live。首次默认关注球队有比赛。
- 设置永久生效，Done 保存。移除 Ask before closing 设置行；关闭时的 Don’t ask again 保留在关闭确认弹窗。

### 取数
- 建议配置字段：placement=inside|both、autoShowMode=never|followed|popular|all、followedTeamIds、popularTeamIds、updatedAt。
- Following 比赛关注列表和 followedTeamIds 不是相同概念：自动规则使用球队关注关系，比赛列表使用比赛关注关系。

### 计算
- Never：自动展示关闭；followed：进行中比赛任一方在 followedTeamIds；popular：任一方在 popularTeamIds；all：所有进行中比赛。
- 匹配集合按 matchId 去重。仅有未开赛、已结束或无可用 live 数据时，不计入自动出现的 LIVE 数量。

### 交互
- 选择范围和规则只修改草稿，点击 Done / Always enable 后才持久保存；返回或关闭放弃本次修改。
- 选择 APP 内外也保留 APP 内展示；设置页再次进入恢复已保存值，不能每次覆盖为默认值。

### 边界处理
- APP 外展示在此 Demo 中**仅为配置模拟**，未实现系统悬浮窗、授权或后台更新。正式方案需按 iOS / Android 能力单独评审后确定样式与权限流程。
- 建议权限失败时保留 APP 内可用并解释外部展示未启用，不得把“选中了 APP 内外”当成系统授权成功。
- 建议真实端优先账号持久化，断网允许本地暂存并重试同步；最终接口和刷新频率由技术评审确定。

## 6. Close & Restore
收起、单场移除、整体关闭分开处理

### 展示位置
- 仅收起胶囊右上角提供整体关闭 ×。展开时不提供整体关闭按钮；每场的减号与入口收起箭头各自保留。

### 展示内容
- 关闭确认提供 Hide for now、Turn off live capsule、Don’t ask again 和 Cancel。
- Hide for now 表示本次 APP 会话隐藏；Turn off live capsule 表示永久关闭，直至主动重新开启。不与引导设置的永久保存混淆。

### 取数
- 建议分别保存 sessionHidden、capsuleEnabled、rememberCloseChoice=none|session|off、capsuleMatchIds、excludedMatchIds。
- rememberCloseChoice 仅决定是否重复询问以及重复哪种关闭动作，不改变单场收藏。

### 交互
- 点击 × → 若未记住选择则显示关闭确认；确认 Hide for now 后本次隐藏，确认 Turn off 后整体关闭。
- 勾选 Don’t ask again 后记住本次选择；后续 × 直接执行对应动作。Cancel 或遮罩取消不改变状态。
- 收起箭头只隐藏展开列表；减号只移除该场；顶部收藏图标加入／移出当前比赛；四类操作不得互相替代。
- 提醒关闭后，顶部图标可重新打开引导，保存后恢复功能并加入当前比赛。

### 边界处理
- 待实现：Demo 用本地状态持久保存 orbHidden，没有真实“新 APP 会话”生命周期；Hide for now 的下次启动恢复需要原生端补齐。
- 关闭全部后，收藏比赛记录仍保留；重新开启时只恢复仍符合条件的进行中比赛。
- 文档内每个原型是独立评审副本，刷新恢复初始示例；原 Demo 的持久保存与演示重置逻辑保持不变。
## 验收场景

1. 首次点击小胶囊：先出现所选比赛内页，再显示带功能图示的设置引导；取消后仍留在该详情页。
2. 首次点击 View more：直接显示 Following + General，不显示引导；后续首次点击小胶囊仍可触发引导。
3. 完成引导后：正常收藏／取消收藏只改变当前比赛的胶囊状态与高亮；功能关闭后再次点击才重新询问。
4. 展开：最多三场独立胶囊，原入口变为收起图标，整体关闭按钮不存在；收起：LIVE 入口和右上角关闭按钮恢复。
5. 点击外部区域或滚动内容：胶囊收起，页面不跳回顶部。
6. 取消比赛关注：星标立即取消，本次列表保留，下次重新打开 Following 不显示。
7. 选择 In & outside app 后仅该选项选中；保存后恢复时仍为该值，APP 内功能保持开启。
8. 引导只有永久开启按钮；设置取消不保存；已完成后不重复展示。
9. 单场移除不改变比赛关注；整体关闭不清空胶囊收藏。
10. 真实端缺失数据不得显示为 0；结束比赛和无匹配比赛按模块规则退出自动显示集合。

## 待评审及开发对齐

- 正式热门球队配置、进行中状态集合、开赛时间排序、pin 与最近手动加入优先级。
- 关注列表重开快照、会话生命周期、实时刷新策略和账号同步。
- APP 外展示的系统能力、权限、样式、后台更新与降级方案。当前交付没有验证原生能力。
- Demo 内图表、球员、事件和视频均为示例，禁止直接当成对应比赛的生产内容。
