# 球队与球员能力值需求规格 版本：2026-11-02；依据：飞书《AiScore_足球新增数据P0》1.3、1.5、2.1，以及本次页面批注。 ## 实现范围与证据边界 Demo 默认定位概况能力模块；文档另提供球员详情和分享样图预览；正式接口、GK 样例、系统分享属于文档定义/待接入范围。其他资料区域保留原截图。 ## Team Ability 球队概况 · 完整 Key players 下方常驻展示 ### 展示位置 - 本 APP：General 页，完整 Key players 卡片之后、Key Transfer 之前插入 Team Ability。 ### 展示内容 - 展示 Team Ability 标题、综合能力值、六维雷达图及轴外“名称＋评分”。综合能力值直接展示数据源数值。 - 从最上方开始顺时针固定顺序：进攻 Attacking → 组织 Build-up → 防守 Defending → 转换 Transition → 定位球 Set Pieces → 体系 Tactical System。 - 雷达图正下方展示球队强弱项，依次为强 Strong、较强 Relatively Strong、弱 Weak、较弱 Relatively Weak；每组一行，左侧为彩色图标与类别名，右侧最多 2 个能力标签。 ### 取数 - 来源：GET /api/v5/football/team/ability/list。results 为球队记录数组，以 id 匹配当前球队；comprehensive 是综合能力值，ability 是六维数据。综合能力值取当前球队记录的 comprehensive。 - ability 的单项按字段说明解析为 [特点 ID, 特点数值, 默认 0]，按 ID 31–36 映射轴位，不直接使用接口数组顺序。 - 服务端首次按 id 拉取全量，随后按 time 增量获取变化；数据源建议同步频次为 1 分钟/次。 - 强弱项读取数据源分类及评分：Strong、Relatively Strong 类别分别取评分最高的前 2 项；Weak、Relatively Weak 类别分别取评分最低的前 2 项。标签使用对应能力小项名称。 - Demo 综合能力值 92 及强弱项评分为演示数据；正式接入时替换为当前球队的数据源记录。 ### 计算 - 正六边形等角六轴；中心 0、外层 100，点位半径 = 评分 / 100 × 最大半径；连成闭合多边形，保留网格线。 - 综合能力值直接取数据源 comprehensive，不进行等级映射或前端加权计算。 - Strong、Relatively Strong 各自按评分降序排列后取前 2 项；Weak、Relatively Weak 各自按评分升序排列后取前 2 项。不足 2 项时展示全部有效项；相同评分保留数据源顺序。 - 评分颜色：0–59 红、60–79 黄、80–89 绿、90–100 蓝；综合能力值与六维评分色签使用相同规则。 ### 交互 - 模块随资料页滚动，正常文档流占位。能力项未定义点击动作。 ### 边界处理 - 无数据：数据源未返回当前球队的能力数据，或能力数据为空时，隐藏整个 Team Ability 模块，包括标题、综合能力值、雷达图和强弱项；不保留空卡片或空白占位，下方 Key Transfer 自然上移。 - 六维中至少 3 个有评分才展示能力模块，少于 3 个隐藏整个模块。0 是有效分数，不能按空值处理。 - 单个维度缺失时保留名称，评分显示“-”，该轴按 0 绘制；不能把缺失评分文字改成 0。 - 某类别没有有效小项则隐藏该行；四个类别均没有有效小项时隐藏整个强弱项区域。 ## Player Ability 球员概况 · 替换整个 Playing style 模块 ### 展示位置 - 本 APP：General 页，以 Player Ability 能力区完整替换 Playing style 标题、说明和图表；上接 Career、下接 Position。原截图其他区域保持原样。 ### 展示内容 - 本 APP 模块标题改为 Player Ability（源文档为 Player Traits），标题右侧展示综合分；雷达图按原 UI 蓝色填充、细网格、圆点及轴外分数标签制作。 - 非 GK 顺时针：速度 Speed、射门 Shooting、传球 Passing、盘带 Dribbling、防守 Defending、身体 Physical；最上方为速度 Speed。GK 顺时针：弹跳 Jumping、飞身扑救 Diving、手接球 Handling、门球 Kicking、站位 Positioning、反应 Reflexes；最上方为弹跳 Jumping。Demo 雷达图使用英文名称，需求说明保留中英文对照。 ### 取数 - 综合分读取 results.comprehensive；六维读取 results.ability；能力小项读取 results.ability_detail；分享更新时间读取 results.updated_at。 - 依据球员主位置判断类型：主位置等于 GK 时使用门将维度与分组；其他位置使用非门将配置，不能仅按球员名称或任一兼任位置判断。 - 维度根据供应商类型枚举映射固定轴位；原文可读正文给出了维度名称与顺序，未确认完整球员维度 ID 对照，联调前补齐映射表。Demo 使用源 UI 示例 90、93、78、82、45、88，综合分 91。 ### 计算 - 六轴中心 0、外缘 100，按分数线性定位，绘制网格与闭合轮廓。综合分直接展示接口值，不用六维平均或权重计算。 - 正常评分范围 0–100；原文统一色阶为 0–59 红、60–79 黄、80–89 绿、90–100 蓝。 - 视觉冲突：源球员 UI 为 90+ 红、80–89 橙、60–79 黄、0–59 绿，与文字规则相反。本次高保真 Demo 保留源 UI 颜色；生产实现按原文字规则，若要沿用图中色彩，需同步修改统一色阶需求。 ### 边界处理 - 无数据：数据源未返回当前球员的能力数据，或能力数据为空时，隐藏整个 Player Ability 模块，包括标题、综合能力值和雷达图；不保留空卡片或空白占位，下方 Position 自然上移。 - 6 个维度至少 3 项有评分时显示 Player Ability；少于 3 项隐藏整个模块。测试至少覆盖 0、2、3、6 项有效值。 - results.comprehensive 缺失时只隐藏综合分，不能虚构默认分或影响满足条件的雷达图。 - 单轴缺失仍显示维度名，分数显示“-”，图中点位按 0 绘制；有效分数 0 仍显示 0 并计入有效项数量。 ## Player Ability 能力值详情 · 原文 1.5 的独立页面与小项数据 ### 展示位置 - 源 APP 顶部顺序：Overview、Matches、Statistics、能力值、Career、Honor；能力值位于 Statistics 后、Career 前。 - 本次概况 Demo 保留原有导航截图并移除“更多”入口；详情作为需求文档中的独立评审预览保留。正式 APP 新增导航入口时按现有导航结构落位。 ### 展示内容 - 能力页依次为综合能力卡片、能力小项卡片。综合能力卡片复用综合分、类型分支和雷达逻辑，右上角展示“分享”。 - 小项采用分组标题＋两列条目；每项名称在左、评分在右，下方为评分进度条。列表按源枚举次序排列，不按分数重排。 - 非 GK：进攻 6 → 技术 9 → 身体 11 → 战术 5 → 防守 7。GK：守门 21 → 移动 22 → 技术 9 → 身体 11 → 战术 5。 ### 取数 - 分组 ID 位于 results.ability_detail[n][0]；只展示对应球员类型的目标分组。 - 进攻 6 小项顺序：1 传中、2 终结、3 头球精度、4 短传、5 凌空抽射。技术 9：1 带球、2 弧线、3 任意球精度、4 长传、5 控球。 - 身体 11：1 射门力量、2 弹跳、3 体力、4 力量、5 远射。战术 5：1 侵略性、2 拦截、3 站位、4 传球视野、5 点球、6 沉着。 - 防守 7：1 防守意识、2 抢断、3 铲球。守门 21：1 飞身扑救、2 手接球、3 门球、4 门将站位、5 门将反应。移动 22：1 加速、2 速度、3 敏捷、4 反应、5 平衡。 - 以上小项顺序来自原文枚举截图；小项记录内分值所在下标应按实际供应商接口结构解析，本文不假定未给出的数组层级。 ### 计算 - 进度条长度 = 小项评分 / 100 × 条长；0 分条长为 0，但仍显示名称和 0。 - 综合分、维度分、小项分与进度条使用同一套生产色阶：0–59 红、60–79 黄、80–89 绿、90–100 蓝；视觉示例与文字冲突说明同上。 ### 交互 - 存在有效能力小项才显示能力值 Tab；从顶部 Tab 进入当前球员能力页，顶部标记当前选中项。本次已取消概况“更多”入口。 - 文档提供独立详情预览，可返回概况并自动定位到能力模块；使用静态示例小项，不代表真实球员最新数据。 ### 边界处理 - 目标分组不存在或其小项列表为空时，隐藏整个分组及标题；缺失小项不展示，不保留空进度条。 - 全部能力小项无有效数值时隐藏整个能力值 Tab。不能用综合分存在作为能力值 Tab 的显示条件。 - 六维不足 3 项但小项有效时，Tab 仍满足显示条件；综合能力雷达区沿用概况隐藏规则，小项继续展示。此组合需在正式接入时验收。 ## Ability Sharing 分享规则 · 原文流程与当前 Demo 的边界 ### 展示位置 - 入口仅位于球员能力值页综合能力卡片右上角。概况页不展示“更多”或分享入口。 ### 展示内容 - 分享载荷为 1 句文本＋1 张图。源文案：Watch free sports live streaming on AiScore App.；迁移到你的 APP 时沿用你 APP 现有分享文案及品牌配置。 - 图片包含 Logo、App 名称、球员头像/姓名、球队队徽、国家队或俱乐部名称，以及固定顺序的 位置 · 身价 · 年龄 · 身高。基础信息取资料页头部同源数据。 - 继续展示综合分、六维雷达图和能力小项；底部为 Updated YYYY/MM/DD。文档左侧为飞书原始分享样图，不是本 APP 已接入的分享服务。 ### 取数 - 分享时使用当前球员的同一份能力数据快照，避免图中的综合分、雷达与列表来自不同更新时间。基础信息复用资料页，时间取 results.updated_at。 - 原文未规定时间戳单位和时区，需与接口约定后格式化为 YYYY/MM/DD，不直接显示本地生成图片的日期。 ### 交互 - 正式流程：点击分享 → 生成当前数据的分享图（loading）→ 生成成功 → 拉起系统分享面板，附带文本与图片。 - Demo 的详情页分享按钮打开原文分享样图供评审，并明确标记为示例预览；未伪装系统分享或真实数据生成完成。 ### 边界处理 - 任一基础信息缺失时不展示该项，并清理多余分隔点；updated_at 为空时隐藏整行更新时间。图内六维及小项缺失规则与能力页一致。 - 原文未定义生成失败、重复点击、系统取消的细节。接入建议：生成期间防重复提交；失败恢复按钮并允许重试；用户取消分享返回详情页。此为补充建议，待开发接入时确认。 ## 验收用例 - 球队：Key players 最后一行完整；Team Ability 紧随其后；Key Transfer 无遮挡、无人工留白。 - 球员：Playing style 整块消失；Career → Player Ability → Position 顺序正确，图片正常解码。 - 数据门槛：有效维度数 2 时隐藏、3 时展示；有效 0 不当作缺失；空维度显示“-”而不是 0。 - 颜色边界：59/60、79/80、89/90 分分别命中正确生产色阶；不要将源球员样图配色误当生产配置。 - 小项：按球员类型过滤分组；空组消失；列表固定枚举排序；强弱选项分别取最大/最小 2 项。 - 入口：有小项无综合分仍可进入详情；无小项有六维时只显示概况；分享时间缺失时不产生虚构日期。 - 未决项：球队小项具体字段结构、球员六维枚举 ID、时间戳单位/时区及同分排序约定需在联调前补齐。