# 比赛列表视图需求文档

版本：2026-11-10 · 范围：Live / Explore / Favorites > Matches。

依据：用户原始三张设计图、逐轮批注及当前确认 Demo。页面视觉与明确交互为已确认；本文建议字段/刷新/异常规则不代表既有 API 或已确认后台实现。

## 1. Live
按联赛分组的比赛列表；原页面高保真延续

### 展示位置
- 顶部保留 Live / Explore；搜索栏保留 By Competition、搜索、筛选及右侧红色视频按钮。
- 比赛视图设置放在头像左侧，不占用视频、搜索或筛选位置；底部 Matches 为选中态。

### 展示内容
- 保留日期、联赛标题、队徽、上下两行球队、GIF 标识、比分和铃铛。新增内容仅在单场比赛主体下方。
- 三种模式：Scores only、Scores + stats、Event timeline。数据模式同屏展示四项；事件模式为紧凑横向滑动条。
- 未赛赛事在原比分区域纵向显示主胜 / 平局 / 客胜三项指数；三种模式均显示。Demo 保留六场未赛样例。

### 取数
- 建议契约：match.id、status、kickoff_at、competition、home/away、score、media、favorite；统计、事件、指数按 match_id 关联。字段名称为建议，非已存在 API。
- 沿用现有列表的筛选、日期、联赛排序及视频权限逻辑；新增视图不改变列表结果集。

### 交互
- Live 与 Explore 可互切；切换只改变页面，不重置所选比赛视图。
- 铃铛操作同步 Favorites；数据和事件在列表内可查看，无需逐场进入比赛内页。

### 边界处理
- 长球队名保持单行省略，点击/辅助说明可读全名；多语言不依赖完整指标文字宽度。
- 空列表展示空态；接口失败保留最后成功列表并提供重试（实施建议）。原视频能力不属于本次迭代。

## 2. Explore
推荐赛事与联赛折叠列表；共用比赛视图

### 展示位置
- 按提供原图保留日期条、日历、You May Like 推荐区、联赛折叠列表和 All Competitions 区。
- 头像左侧使用与 Live 一致的设置入口。底部仍选中 Matches。

### 展示内容
- 推荐卡片保留原卡片结构；新增数据/事件区作用于下方展开的比赛列表，不额外塞入推荐卡片。
- Premier League 默认展开用于演示；其他联赛可折叠。每场使用与 Live 相同的比分、指数和扩展区域组件。
- 联赛数量必须来自实际筛选后的赛事数量；当前 Demo 数量与日期是视觉样例，不能作为生产数据。

### 取数
- 建议字段：date_key、recommendations[]、competition.id/name/logo、matches[]；联赛 count 由当前日期结果集产生。
- 同一 match_id 在三个页面使用同一比分、统计、事件和收藏状态。

### 计算
- 联赛数量 = 当前日期与筛选条件下，该联赛有效赛事数；不按当前是否展开计数。

### 交互
- 点击联赛标题或箭头展开/收起；点击设置切换模式后，展开状态保持。
- 推荐卡片沿用横向滑动，比赛事件条有独立横滑区域，不能相互联动滚动。

### 边界处理
- 无推荐内容时隐藏推荐区；无赛事的联赛按既有产品规则处理（需对齐原规则）。
- 原图中的 Seeaie A、All Copmetitions 拼写在 Demo 中保留；正式上线文案是否修正需确认，不将其固化为接口字段。

## 3. Favorites
Matches 收藏列表；按日期与联赛组织

### 展示位置
- 标题 Favorites 居中；保留 News / Matches / Teams / Leagues / Player 分类，Matches 选中。
- 底部 Favorites 高亮。比赛视图设置仍在头像左侧；其他收藏分类不在本次功能范围。

### 展示内容
- 按原图还原日期分组、联赛标题、比赛行和黄色已收藏铃铛。
- 收藏比赛同样支持仅比分、四项数据与事件时间轴；未赛比分区始终显示三项指数。
- 模式切换不改变收藏数量、日期归属或排序。Demo 中补充未赛样例用于检查指数表现。

### 取数
- 建议字段：favorite.match_ids、match.kickoff_at、competition.id；以用户收藏结果为准，去重键为 match_id。
- 日期分组建议按用户所选时区对 kickoff_at 转换后的自然日；跨日、夏令时和排序需与既有收藏页统一。

### 交互
- 底部 Matches / Favorites 互切；Live、Explore 收藏或取消后，Favorites 即时同步。
- Favorites 中取消收藏后移除该场；如果日期或联赛分组变空，同时移除空标题。
- 设置是跨三个比赛列表共享的偏好；搜索只过滤结果，不修改收藏状态。

### 边界处理
- 无收藏时显示引导前往比赛列表的空态；取消收藏请求失败时恢复原状态并提示（实施建议）。
- 本 Demo 的其他收藏分类是演示空态，并非本次要新增的业务页面。

## 4. View Settings
一个小入口；不新增视图切换 Tab

### 展示位置
- Live、Explore、Favorites 的头像左侧使用同一图标入口；设置浮层锚定顶部右侧。

### 展示内容
- 首次进入时视图设置入口显示红点，包括默认 Scores only 状态；首次打开设置即消除并记忆，Live / Explore / Favorites 共用已读状态。切换模式不重新点亮；Demo 恢复初始状态重新显示。
- 浮层仅保留三项：Scores only、Scores + stats、Event timeline；选中项有单选反馈。
- 不增加底部图例、帮助段落或另一排模式 Tab。

### 取数
- 建议字段：preferences.match_list_view，枚举 scores / stats / timeline；持久化方式待确认。
- 当前 Demo 使用本地状态；生产是否跨设备同步、登录前后如何合并需产品确认。

### 交互
- 点击选项立即生效并关闭；点击关闭、浮层外区域或 Escape 关闭。关闭后焦点返回入口。
- 切换模式保留当前页面、筛选和联赛折叠状态；事件详情关闭后保留该场事件条的滚动位置。

### 边界处理
- 已确认：首次进入默认 Scores only（仅比分）；恢复初始状态也回到仅比分。用户主动切换后保留其选择。
- 未知偏好值回退 scores（实施建议）；键盘可操作，屏幕阅读器能读出入口、选项及选中态。

## 5. Match Statistics
四项同时展示；图标适配多语言

### 展示位置
- 单场比赛原主体下方；左右留白相同、整体居中，四等分排列；不扩成横向表格。
- 当前设计参考：统计条约 46px 高、左右各 12px 留白；320–375px 宽屏保持一行四项。

### 展示内容
- 固定顺序：角球、控球率、射门、预期进球。每项均按主队 – 客队显示，不能按大小交换。
- 角球用旗帜图标；控球率用占比图标；射门用球鞋射门图标；预期进球直接用大写 XG。
- 角球、射门显示非负整数；控球率显示整数及 %；xG 固定两位小数。真实 0 必须显示 0 / 0% / 0.00。

### 取数
- 建议字段：stats.home/away.corners、possession_pct、shots_total、xg，外加 updated_at、period_scope、coverage。
- 射门口径为总射门，不等于射正；xG 使用供应商累计值。角球总数仍展示，即使时间轴排除角球事件。

### 计算
- 前端仅做格式化：整数 round(value)，xG round(value,2)；不自行生成或估算缺失值。
- 控球率以供应商百分比为准，不用两队值重新归一化；若供应商给出 0–1 比例，由适配层转换为百分数。
- 统计期间必须一致；建议使用当前比赛累计常规时间，是否包含加时由供应商与产品确认，点球大战不混入常规射门/xG。

### 交互
- 点击图标或 XG 显示对应指标解释；关闭后回到原列表。按钮无须显示完整英文指标名，但无障碍名称需保留名称与双方数值。

### 边界处理
- 单侧缺失只显示该侧 —；保留另一侧真实值。四项全缺失仍保留四项结构及 —，禁止补零。
- 未赛不显示统计条；比赛取消、延期、腰斩和完赛的统计展示策略由现有 status 映射决定，需联调确认。
- 接收非数字、负值或超范围控球率时按缺失处理并记录异常（实施建议）。

## 6. Event Timeline & Pre-match Odds
紧凑事件条与所有未赛通用的指数规则

### 展示位置
- 时间轴放在比赛主体下方；条内左对齐，不因事件少而居中。多事件仅横滑查看，不显示 +N、Earlier 或额外“更多”入口。
- 指数放在未赛比赛的原比分列，主胜 / 平局 / 客胜从上到下排列；不能放到统计条内。

### 展示内容
- 事件仅进球、黄牌、红牌；排除角球和换人。每项包括球员头像、姓氏、所属球队徽标、事件图标及分钟。
- 头像在左、姓名与分钟在右；参考约 50px 高的紧凑区域。按时间从早到晚保留全部符合条件的事件。
- 指数统一灰色、两位小数；无数据显示 —。三种模式与三个页面采用相同规则。

### 取数
- 建议事件字段：id、match_id、type、period、minute、added_minute、sequence、team_id、player.id/display_name/short_name/avatar、updated_at、is_cancelled。
- 建议指数字段：market_type=1X2、home/draw/away、provider_id、updated_at。必须使用同一供应商、同一市场和同一快照，不能混拼。

### 计算
- 事件先按允许类型过滤、按 event.id 去重，再按 period、minute、added_minute、sequence 升序；补时格式如 45+2′。
- 指数采用十进制格式保留两位小数；Demo 为静态样例，不计算胜率、不提供真实预测。

### 交互
- 事件区域支持触摸横滑和鼠标拖动；拖动结束不误触详情。竖向浏览列表与横滑事件可共存。
- 点击单个事件进入列表内的事件详情底部面板；关闭保留原列表位置与事件横滑偏移。
- 列表更新期间不自动抢回滚动位置；新事件追加，撤销事件移除（实施建议）。

### 边界处理
- 事件数据成功返回且过滤后无进球/黄牌/红牌时展示 No events yet；加载中/失败不算空事件；缺头像用统一头像占位，缺球员用球队信息代替，不伪造姓名；长姓氏省略但详情可读全名。
- 第二黄转红、乌龙球、VAR 撤销的供应商编码须建立映射；所属队徽表示事件球员所属队，不能简单按受益球队代替。
- 未赛缺一项指数只替换该项；开赛后改为比分，禁止继续显示旧赛前指数。指数源、刷新时点、暂停市场显示规则待确认。

## 联调与验收清单

- [ ] 三个页面共用视图偏好；无额外模式 Tab；设置不覆盖视频入口。
- [ ] 三模式 × 三页面的未赛比分列都显示三项指数；开赛转比分。
- [ ] 四统计顺序固定；主客不交换；球鞋射门 / XG 正确；缺失与真实零区分。
- [ ] 事件仅进球/黄/红；按时间排序；头像与队徽归属正确；无换人、角球或 +N 入口。
- [ ] 少事件左对齐；多事件横滑；拖动不误触；详情关闭保持滚动偏移。
- [ ] 收藏联动，取消后空分组移除；搜索不改变收藏数据。
- [ ] 长队名/姓氏、320px 屏宽、控球率 100%、xG 缺失、补时、同分钟事件均无布局溢出。
- [ ] 供应商更正/事件撤销/状态变更按 match_id 和 event.id 更新，不重复追加。
- [ ] 实际工程验收须覆盖加载、重试、断网恢复与后台切前台；本 Demo 未连接生产接口。

## 建议数据契约与刷新（后台行为，原型不模拟）

- Match：id:string；status:scheduled/live/finished/postponed/cancelled/abandoned；kickoff_at:ISO8601 UTC；home/away:{id,name,short_name,logo}；score:{home,away}。
- Statistics：每场、每侧四个 nullable number 字段；corners/shots_total 为整数，possession_pct 为 0–100，xg 为非负数；携带 coverage、period_scope 与 updated_at。
- Event：稳定 id 与 sequence；数值分钟和补时独立，不能用展示字符串排序；允许 supplier type 映射与撤销标记。
- Odds：market_type、同源三项 nullable decimal、provider_id、updated_at；不得从不同供应商取最优值拼接。
- 建议复用既有比赛列表批量加载/实时通道，避免逐场打开详情接口；切换模式仅加载所需统计或事件。
- 优先复用现有推送更新；若仅支持轮询，由客户端/服务端共同确定间隔，本文不指定虚构 SLA。可见列表更新优先，退出页面停止订阅；返回前台补齐最新快照。
- 建议使用 updated_at 或版本号丢弃旧响应；首次缺数据展示 —，刷新失败保留最后成功值并标明更新时间/异常，不显示伪造的零。

## 待确认事项

1. 偏好是否跨设备、跨账号同步（首次默认已确认为 Scores only）。
2. 统计供应商、字段映射、常规时间/加时口径；xG 覆盖范围。
3. 1X2 指数供应商、刷新频率、市场暂停/过期判断与状态切换时间点。
4. 赛事状态枚举、VAR/乌龙球/第二黄转红映射、收藏日期时区与排序。
5. 保持现有产品规则的细节：筛选、视频、推荐排序及无赛事联赛处理。
6. Explore 原图英文拼写修正；完成比赛是否继续显示统计/事件。

## 原型与生产边界

- 原型内为静态演示球队、统计、指数、事件和示意球员头像；截图日期不代表实时赛程。
- 本次文档保留既有列表交互；其他收藏分类、新闻和联赛首页、视频播放不在实现范围。
- 原型中部分推荐/日期/联赛数量为视觉样例；正式上线须按真实结果集生成。
- 演示采用本地共享状态，不验证登录、服务端收藏同步、数据刷新或错误恢复；以上在实际工程中单独验收。


### 事件空态图示（2026-11-17）

![事件空态](assets/empty-events.png)

- 保留原比赛行；下方浅灰区域左右各 12px 留白，约 48px 高，圆角 7px；11px 灰色文字左对齐。
- 不显示头像、事件图标或更多入口；空态不响应点击。长译文换行并增高。
- 仅在请求成功且过滤后无支持事件时展示；加载中、失败、未覆盖数据不使用 No events yet。
- 图示比分与分钟为演示样例。
