足记 · 工作手册（精简版 v2.4）

用途：每次工作前读本手册恢复状态；严格按流程执行；用户可随时拿本文档让 AI 接续工作。
为什么必须读手册（甲方诊断，2026-09-08）：早期错误多、反复改，根因就两条——①规矩太松，手册写得不够清楚；②有手册长期不读，凭印象干活。为此已建成防错机制：执行前必读对应章节、新教训立即写回手册、检查经验库盖楼式防漏、发布门禁、命名规范定死。手册不是摆设：没读对应章节就不许开工。
项目名：足记（足球追踪网页）
在线地址：https://bxgj2030.top/（COS/CDN，2026-09-07起；surge.sh已废弃）
当前版本：v10.09
最后更新：2026-09-07（逐字逐句校订：统一积分榜数据源口径、场均高级数据主源改为StatMuse、球队数/部署平台/联赛数全部按现状更正）

0. 一分钟速览（恢复工作先看这里）

足记是什么：手机端看的静态足球网页。首页看赛程/积分榜/射手榜；31支俱乐部队+9支国家队专属球员页，看球员能力雷达、29项游戏能力、赛季真实数据。核心价值是"快速看懂、公正对比球员"，基础数据准确是生命线。

8支重点关注球队：阿森纳、曼城、利物浦、切尔西、皇马、巴萨、巴黎圣日耳曼、拜仁慕尼黑。DESC（比赛前瞻后顾）重点写这8支球队。

扩展球队：英超其余16队+欧冠一档二档其余球队+意甲/德甲/法甲/葡超代表球队，共31支俱乐部，维护名单+OVR+六维+场均数据。

9支国家队页：巴西、英格兰、西班牙、法国、德国、意大利、葡萄牙、荷兰、阿根廷（brazil/england/spain/france/germany/italy/portugal/netherlands/argentina）。国家队大名单未正式公布前只搭框架，公布后按名单做，与俱乐部数据相互独立。

项目架构（2026-09-07现状：数据与视图分离 + 公共模块抽取）：

• index.html — 首页（赛程+积分榜+射手榜，数据从data/*.js加载）
• *_players.html（40个=31俱乐部+9国家队）— 球员页，只负责渲染，不内嵌数据。通过<script src="data/players/xxx.js">加载对应球队数据。
• data/players/*.js（40个）— 球员数据源文件，每队一个文件，包含window.PLAYERS = [...]。改球员数据只改这里，不需要改HTML。
• data/css/common.css + data/js/ 下 9 个模块（utils/data_loader/render/render_detail/render_detail2/events/render_leagues/render_leagues2/main，F-01-06 20261009 拆分）— 公共样式和逻辑，球队页面共用
• manual.html — 本手册
• changelog.html — 更新日志
• deploy_site.sh — COS/CDN 部署脚本（--cos-only，硬门禁 HEAD==master + 版本/变更/内容/制品指纹留痕，2026-09-07 起主用；README 44 行有完整通道说明）
• backups/ — 部署自动备份目录（保留最近10个版本）
• .git — git版本控制（每次修改commit，出问题可回滚）

三条铁律：

1. 改球员数据 → 只改 data/players/对应球队.js，HTML不动
2. 改样式/逻辑 → 改对应HTML或common.js/common.css，数据文件不动
3. 任何部署 → 必须用 ./scripts_ops/deploy_site.sh --cos-only（硬门禁：本地 HEAD 必须=master，防旧工作区覆盖线上），自动上传+设置缓存头+制品指纹留痕（deployment_log.md），部署后浏览器抽验；新目录文件（如 data/js/i18n/zh.js）deploy 不传，需手动 put_object（ContentType=text/javascript + no-cache）

git版本控制：项目已初始化git，每次修改后commit，出问题可git reset --hard回滚。这是最基础的工程纪律，必须遵守。

1. 数据分级与锁定机制（2026-09-07球员分级已取消）

分级原则：按更新频率分层。锁定原则：低频数据确认后锁定，日常更新只能动第一级。重要变更：原A级/B级/C级/D级球员四级分级体系已于2026-09-07取消，所有球员一视同仁，详见1.5节。

第一级铁律

• ❌ 禁止只更1A不更1C（比分变了球员数据没变=进球一致性必挂）
• ❌ 禁止查不到就填0（查不到=换源，不是填0）
• ❌ 禁止按角色推断出场数（必须真实来源）
• ✅ 1A/1B/1C全部更新完、全部验算通过才能部署
• ✅ 更新顺序：先1A（比分/进球轴）→ 再1C（球员数据）→ 最后1B（积分榜/射手榜）

第二级：单个球员修正（不需要解锁）

• 触发：比赛数据中发现进球者/首发球员不在名单中（有明确比赛证据）
• 操作：直接添加/修正，记录到更新日志
• 典型：伊杜博（摩纳哥对巴黎进球但名单遗漏）、格拉利什（压哨租借埃弗顿）

1.5 球员数据统一维护（2026-09-07取消分级）

核心原则：取消A级/B级/C级/D级四级分级体系，所有球员一视同仁。per90统一=25-26上赛季基准（per90Season=2025-26）；26-27本赛季场均数据冬窗后统一更新（用户拍板，2026-09-08第22章定案，禁止赛季初小样本提前补），26-27只存seasonStats基础数（apps/goals/assists/cleanSheets）。关键认知：StatMuse数据源无反爬，球队级别页面一次返回整队数据，27队524人次约9分钟抓完，抓取成本极低，不需要通过分级来减轻维护工作量。

数据字段统一标准

场均数据更新口径（以2026-09-08第22章为准，取代此前所有版本）

• per90语义固定=25-26上赛季基准（per90Season=2025-26，两源皆无=置空不编）；26-27本赛季场均冬窗后统一更新（用户拍板），禁止赛季初小样本提前补；26-27只存seasonStats（apps/goals/assists/cleanSheets）
• 显示：详情页弹窗26-27列无数据显示"-"不fallback；per90字段一律不拿26-27冒充（规则见13.1b与第22章）
• 三集合认知：①名单有+StatMuse有=直接挂；②名单有+StatMuse无=本赛季还没出场，随赛季推进自然有，不是缺失不用补；③StatMuse有+名单无=新援未录名单，先补档案再挂

日常维护内容（不需要分级）

• 比赛结果更新（比分、进球时间、红黄牌、换人）
• 积分榜更新（直接抄现成榜单，不自己算，数据源见3.5.5）
• 射手榜更新（直接抄现成榜单，不自己算，数据源见3.5.5）
• 比赛前瞻/后顾DESC（纯手写，核心竞争力）
• 转会窗球员名单更新

1.6 最近重大变更记录（2026-09-06）

• 英格兰国旗修正：数据文件中217名英格兰球员国籍代码从"gb"（英国米字旗）修正为"gb-eng"（英格兰圣乔治十字旗）。同时修正player_common.js中getFlagUrl函数，去掉错误的gbMap映射（之前把gb-eng错误映射成gbeng导致404），flagcdn.com直接支持gb-eng/gb-wls/gb-sct/gb-nir格式。
• 37队名单双源交叉核实进行中：CEO和小老弟各用5个数据源（CEO：Transfermarkt/懂球帝/ESPN/WhoScored/球队官网；小老弟：FotMob/直播吧/SofaScore/FBref/联赛官网）独立抄录37支俱乐部球队名单，完成后交叉比对，不一致的再查，最终修正转会错误和离队球员残留。已发现差异：摩根·罗杰斯（维拉→切尔西）、卡塞米罗（曼联→迈阿密国际）、格拉利什（曼城→罗马）等。
• 取消球员分级体系（2026-09-07）：原A级/B级/C级/D级四级分级取消，所有球员一视同仁。原因：StatMuse数据源无反爬，球队级别页面一次返回整队数据，抓取成本极低，不需要通过分级减轻维护工作量。场均数据冬窗之后所有球员统一加26-27赛季数据，不分级。
• 24队国籍补全完成：小老弟完成24支非关注球队623名球员的国籍补全，100%覆盖，国籍格式为两位字母国家代码(ar/fr/gb/es等)。
• 24人29项补全：小老弟完成24名OVR≥85核心球员的FC27 29项详细能力值补全，包括B费、奥布拉克、若昂·内维斯、迈尼昂、科贝尔、于帕梅卡诺、迪巴拉、托纳利、皮克福德、扎卡等。B级球员从134人升至158人。
• 24队B级数据批量上线：小老弟从FCRatings.com批量抓取24支球队（英超16队+欧冠8队）共623名球员的名单+OVR+六维，全部fcVerified=true。PSV埃因霍温因FCRatings无页面暂缺，后基于Transfermarkt阵容补全（28人，六维为估算值，fcVerified=false）。
• 24队球员名字中文化：小老弟完成623名球员英文→中文译名替换，以中文足球圈常用译法为准。
• 巴西球员页俱乐部队标改为射手榜样式：左侧国旗去掉，右侧添加53x53px俱乐部队标（absolute定位+白色描边+阴影，与射手榜一致），名字下方显示俱乐部名称标签。
• 球员卡片去掉出场/进球/助攻数据：所有球员卡片不再显示赛季数据这一排，赛季数据以后专门换地方重新设计。
• 射手榜队标修复：射手榜俱乐部队标改为底部对齐，只超出上面3px，和巴西球员页队标效果统一。
• 首页布局修复：container padding恢复原24px，积分榜/射手榜恢复原样；比赛列表#list单独加32px右侧padding，避免被右侧22px导航栏遮挡。
• 自动化定时任务调整（2026-09-07）：原①巴西国家队大名单自动监控（每天8点检查CBF官网，发现新名单自动更新巴西页+补数据+部署）保留；②A级球员数据自动巡检补全（每周一10点）因球员分级取消而暂停，改为每周一足记数据更新（比赛结果+积分榜+射手榜+DESC）。

2. 例行更新总流程（用户说"更新"时按这个走）

核心原则：用户只说"更新"，AI自己判断该更什么、怎么更、验证完再部署。日常更新只动第一级。

标准步骤（每次必走，不能跳）

第1步：读手册 + 看锁定状态（30秒）

• 确认第二级、第三级处于锁定状态，本次只动第一级

第1.5步：变更检测（必须第一步执行）

• 工具：node zuji_tools/change_detect.js（自动检测最近3天已赛、未来3天未赛、desc质量，输出更新建议）
• 拉取最新比赛状态，和本地MATCHES对比：
  • 新结束的比赛 → 必须更新比分+进球轴+写总结
  • 3天内未赛比赛 → 检查伤停是否有新变化，有变化才更新前瞻
  • 超过3天的远期比赛 → 不更新前瞻（无变量）
  • 已赛比赛的desc → 只写一次，写完锁定，不重复更新
• ⚠️ API延迟：football-data API在比赛结束后30-90分钟才同步FINISHED状态。比赛刚结束2小时内如果API显示SCHEDULED，用懂球帝/直播吧战报交叉确认

第2步：更新1A首页比赛（比分→进球轴→desc）

• 已赛场次补录进球时间轴（≥2来源验证：懂球帝/直播吧）
• 多场新已赛比赛时，并行搜索，不要串行
• 写desc（见第5节规范）
• 验算：比分主客进球数=goals里h/a个数

第3步：更新1C球员赛季数据

• 更新频率（分级已取消，所有球员一视同仁）：8关注队每轮必更（约20分钟）；同联赛扩展队每周一次；其他联赛两周一次
• 主源：FotMob（数据最全，更新及时，2026-09-05验证曼城2场全对）
• 次源：联赛官网统计页（仅8关注队做交叉验证）
• FBref已降级为参考源：英超数据滞后（2026-09-07验证26-27赛季第3轮打完其联赛页仍全0），查不到就返回空，不能做主源
• 用data_model的loadTeam/saveTeam安全写入
• 验算：①全队进球之和=1A首页进球轴 ②门将零封≤出场数

第4步：更新1B联赛排名

• 直接抄现成榜单整体替换，不自己算（方法见3.5.5）。当前覆盖7个联赛：英超PL、西甲PD、德甲BL、法甲FL、意甲SA、葡超PO、欧冠CL
• 机器校验：用1A的MATCHES里关注队的已赛结果反算积分/进球，和抄来的榜单比对（仅核对关注队，不全量交叉）
• 欧冠未开赛时积分榜全0属正常，不要编数据

第5步：跑自动检查（必须全绿）

• node zuji_tools/check_all.js（结构+人数+进球一致性，0 ERROR才能继续）
• node zuji_tools/verify_data.js（首页数据五方校验）

第6步：部署

• ./scripts_ops/deploy_site.sh --cos-only（自动：上传全部HTML/数据文件到 COS/CDN+设置no-cache缓存头）
• 部署后必须用普通模式（非无痕）浏览器打开线上地址抽验改动点

第7步：更新状态表和日志

• 刷新手册顶部状态表
• 在changelog.html追加本次更新记录
• 给用户报结果：更了什么、验证结果、有没有待确认项

3. 数据源映射表（核心·以后直接照此查）

数据源沿革（避免再走弯路）：①场均高级数据早期用FootyStats（Cloudflare反爬、单球员页、临时工取数不一致），后改用FBref，2026-09-06起全面改用StatMuse（无反爬、球队页一次返回整队29+14项），FootyStats方案废弃但保留在3.5.1作历史参考；②积分榜/射手榜早期靠MATCHES自己算（慢、且MATCHES只有关注队不完整、乌龙球算错），后确立直接抄原则；③FBref的26-27英超数据严重滞后（第3轮打完联赛页仍全0），绝不能作为基础数据和积分榜主源，只用于场均高级数据的交叉验证。

场均数据（advanced/per90）字段映射表（2026-09-07更新主源）

说明（重要）：场均高级数据的主源已切换为 StatMuse（球队页一次返回整队、无反爬、Per90口径，抓取方法和字段对照见第12章）。下表是早期FootyStats/FBref时代的字段对照，仅在StatMuse缺某字段时用于补漏或交叉验证。FBref数据最全但有Cloudflare反爬、且英超更新滞后；FootyStats方案已废弃（见3.5.1）。

数据源使用优先级（2026-09-07修订）

1. StatMuse — 场均per90主数据源，球队页批量返回整队29项非门将+14项门将，无反爬、Node.js直连，详见第12章
2. FBref — 交叉验证源（xG/xA等最权威），但有Cloudflare反爬、英超更新滞后，只用于验证和StatMuse缺字段时补漏
3. FotMob — 基础数据（出场/进球/助攻）主源，补充射正、被犯规、触球等字段，中文界面好查
4. SofaScore — 补充传中、争顶成功率、创造绝佳机会等细分字段
5. Understat — 仅用于xG/xA验证，只覆盖五大联赛

按位置的关键字段速查

铁律

1. 查不到就换源，禁止填0、禁止估算、禁止按角色推断
2. 两源不一致时，第三源裁决，少数服从多数
3. 全部源不可用→保留上次值，更新日志标记，不编造
4. 分清两类数据的源：基础数据（出场/进球/助攻）主源FotMob，不用FBref（英超滞后）；场均per90主源StatMuse（第12章），FBref只做验证
5. 补数据前先做三个圆分类（第14章），禁止不分类就一个一个查

关键配置

• football-data API Key：your-api-key-here（积分榜/射手榜程序化备选，明文 Key 已清理，实际值见凭据台账）
• worker 部署通道（013 令）：Cloudflare Workers（Worker 名与账号见凭据台账）；部署=multipart PUT（metadata body_part=script + script 文件）；schedules 4 条 cron（boards 每日4档 / 每3h / seasonstats */3 / live */5）可单独 GET/PUT；凭证只从 docs/足记凭据台账.md 读取，不写明文
• 当前部署平台：腾讯云 COS+CDN（bxgj2030.top）：存储桶、登录账号、操作员等凭据见 docs/足记凭据台账.md（明文已清理，不贴手册）；网站地址 https://bxgj2030.top/
• 部署命令（当前主用）：./scripts_ops/deploy_site.sh --cos-only（自动上传全部文件并设置no-cache）
• Surge（已废弃，仅存档）：账号/密码/token 明文已清理（见凭据台账）；2026-09-06起因整个surge.sh平台在当前网络超时，已迁又拍云，不要再用
• 俱乐部队标：https://crests.football-data.org/{ID}.png（完整ID对照见11.5节）
• 国旗：https://flagcdn.com/w160/{code}.png。英国构成国特殊格式：英格兰=gb-eng、苏格兰=gb-sct、威尔士=gb-wls、北爱尔兰=gb-nir。禁止用gb表示英格兰球员（会显示英国米字旗）。

3.5 数据获取SOP（详细操作步骤，照着做就行，别走弯路）

核心原则：所有数据获取方法必须写死，包括用什么工具、什么数据源、URL格式、提取步骤、反爬应对、常见错误。这样不管是AI自己更新，还是别人接手，都能照着做，不用重新摸索。工具优先级：webfetch > Playwright/Puppeteer > curl。webfetch能自动处理反爬和JS渲染，是首选；curl大概率被拦截，不要用。

3.5.1 场均数据（advanced）获取方法 — ⚠️已废弃，保留作历史参考（主源改用StatMuse，见第12章）

⚠️ 本节为2026-09-06之前的FootyStats旧方案，已废弃。当时结论"不要用StatMuse"是错误的——后来验证StatMuse用Node.js https.get可直连、无反爬、球队页一次返回整队数据，已成为场均per90的主源（第12章）。本节仅在StatMuse确实缺某小众字段时作补漏参考，不要再按本节批量抓数据。

（旧）数据源：FootyStats（https://footystats.org）。旧方案曾认为FBref被Cloudflare拦截、StatMuse缺字段——这些结论已被第12章的StatMuse实践推翻。

工具优先级：

1. webfetch（首选）— 自动处理反爬和JS渲染，直接返回页面纯文本，30秒搞定一个球员，不会被拦截
2. Playwright/Puppeteer有头浏览器（备选）— webfetch不可用时用，每个页面等待3-4秒让JS渲染完成
3. curl（禁止）— 大概率被Cloudflare拦截返回403，不要浪费时间

FootyStats球员页面URL格式：

• 国家路径：英文小写，必须匹配球员国籍。英格兰=england，苏格兰=scotland，威尔士=wales，北爱尔兰=northern-ireland，爱尔兰=republic-of-ireland（注意不是ireland），美国=usa（注意不是united-states），法国=france，德国=germany，西班牙=spain，意大利=italy，葡萄牙=portugal，巴西=brazil，阿根廷=argentina，挪威=norway，埃及=egypt
• 球员slug：英文名全小写，空格替换为连字符-，特殊字符转换（Đ/đ→d, ø→o, é/è/ê→e, á/à/ã→a, ç→c, ü→u）
• 示例：布卡约·萨卡（英格兰）= https://footystats.org/players/england/bukayo-saka
• 重要：国家路径必须匹配球员国籍，用错会被重定向到列表页，返回空数据。不确定国籍时先查球员国籍再构建URL。

11个字段的准确label和所在区块（一个字都不能错）：

注意：前10个字段从FootyStats获取，第11个字段（ballRecoveries夺回球权）FootyStats没有，需要用general_search搜索FBref球探报告页面提取。搜索关键词格式：{球员英文名} Ball Recoveries per 90 2024-25 Premier League FBref。

提取步骤（webfetch方式，推荐）：

1. 用webfetch访问球员页面URL，获取页面纯文本
2. 按区块分割文本：找到"Attacking"、"Defending"、"Passing"三个关键词的位置
3. 在Attacking区块内搜索6个进攻字段的label，取Per 90列的值（第3个数值）
4. 在Defending区块内搜索tackles和interceptions，取Per 90列的值
5. 在Passing区块内搜索Pass Completion Rate，取Total列的百分比值，去掉%号
6. 所有数值保留两位小数

提取步骤（Playwright方式，备选）：

1. 用page.goto()访问球员页面，waitUntil: 'networkidle'
2. 用page.waitForFunction()等待页面包含"Shots Taken"关键词（必须等JS渲染完成，不要用固定等待时间）
3. 用page.evaluate(() => document.body.innerText)获取页面纯文本
4. 后续步骤同webfetch方式

反爬应对方法（用Playwright时必须看）：

• 每个球员页面之间等待3-4秒，不要连续快速请求
• 每批最多处理10名球员，每批之间休息5分钟
• 遇到Cloudflare"Just a moment..."挑战页时，先导航回球队页面重置状态，等待30秒后再继续
• 被拦截的球员在后续批次中重试，不要直接放弃
• 连续访问20-30个页面后，Cloudflare拦截率会上升到30-40%，这是正常现象，分批处理+重试即可

常见错误和解决方法（之前临时工犯过的，必须避免）：

守门员数据说明：守门员的进攻字段（shots、shotsOnTarget、xG、dribbles）为0是正常的，但keyPasses、tackles、interceptions、passAccuracy应该有值。如果守门员的所有字段（包括passAccuracy）都是0，需要重新核实，可能是抓取失败。

3.5.1.1 标准提取脚本（必须用这个，禁止自己写提取逻辑）

铁律：所有场均数据提取必须使用标准脚本 extract_footystats.js，禁止自己写正则或提取逻辑。之前两个临时工取出不同的数据（Worker 1 tackles=0.51，DuMate tackles=1.50），就是因为各自写提取逻辑，一个取错了列，一个取对了。用标准脚本可以保证任何人跑出来的结果完全一致。

脚本位置：项目根目录 extract_footystats.js，每个任务包都会附带这个文件。

使用步骤：

1. 用 webfetch 访问球员页面，把返回的内容保存到文件（如 saka.md）
2. 运行：node extract_footystats.js saka.md
3. 脚本输出 JSON 格式的10个字段数据（FootyStats可提取的，不含ballRecoveries），直接复制到数据文件中
4. ballRecoveries（夺回球权）需要单独用general_search搜索FBref提取

脚本输出示例：

联赛: Premier League

{
  "shots": 2.87,
  "shotsOnTarget": 1.09,
  "xG": 0.4,
  "keyPasses": 2.59,
  "xA": 0.29,
  "dribbles": 1.86,
  "tackles": 1.5,
  "interceptions": 0.65,
  "passAccuracy": 77.25,
  "aerialDuelsWon": 1.2
}

✅ 10个字段全部提取成功

脚本处理的特殊情况：

• Shots On Target：Total列是"27/ 71"（带分数），脚本自动提取Per 90列的纯数字
• Pass Completion Rate：Per 90列显示N/A，脚本自动取Total列的百分比值，去掉%号
• Per 90为N/A的字段：自动设为0（如前锋的某些防守字段）
• 多比赛标签页：脚本自动取第一个联赛数据区块（Premier League/La Liga/Bundesliga等），不会取到杯赛或欧冠数据

如果脚本报错：

• 说明页面结构变了，或者webfetch返回的内容不完整
• 不要自己改脚本，报告给CEO，由CEO统一更新脚本
• 可以尝试重新用webfetch获取页面内容，确保完整

批量处理方法：

1. 用webfetch并行获取多个球员页面（每批5-10个），保存为单独的文件
2. 写一个简单的循环脚本，逐个调用 extract_footystats.js 提取数据
3. 把提取结果汇总到球队的advanced.js文件中
4. 每批之间间隔3-5秒，避免触发反爬

3.5.1.2 各位置核心字段要求（2026-09-06确定）

原则：每个位置有不同的核心字段要求，核心字段必须100%补全，次要字段尽量补全（容错率80%）。核心字段全有 + 次要字段达标 = 该球员数据达标。

注意：夺回球权（ballRecoveries）是后腰和中后卫的核心字段，但FootyStats没有此字段，必须用general_search搜索FBref提取。这是数据补全中最耗时的部分。

3.5.1.3 大规模补全任务的临时工分工机制（2026-09-06建立）

背景：2026-09-06统计发现756名球员中有503人场均数据不达标，需要大规模补全。单个AI处理503人耗时太长，建立6人并行分工机制。

分工方法：

1. 把503名未达标球员按顺序平均分成6份，每份约84人
2. 每份打包成一个独立的任务包（zip），包含：任务说明书、球员名单CSV、标准提取脚本
3. 每个任务包分配给一个临时工（数据协作伙伴），并行处理
4. 临时工完成后，把结果文件（JS格式）发回，由CEO统一合并校验

任务包内容：

• task_instructions.txt — 任务说明书（中文，详细操作指南，含如何搜索英文名、如何构建URL、标准提取脚本使用方法、查不到数据的处理方式、回复要求）
• player_list.csv — 球员名单（84人，含球队、中文名、国籍、位置、缺哪些核心字段、缺哪些次要字段、现有字段数）
• extract_footystats.js — 标准提取脚本（v4，支持10个FootyStats字段）

任务说明书必须包含的内容：

1. 任务背景和目标
2. 11个字段说明（10个FootyStats + 1个FBref）
3. 各位置核心字段要求
4. 如何从中文名搜索英文名（因为数据库中只有中文名）
5. 如何构建FootyStats URL（国籍路径 + 球员slug）
6. 标准提取脚本使用方法
7. ballRecoveries（夺回球权）的FBref搜索提取方法
8. 数据格式要求（JS格式，window.ADVANCED_DATA）
9. 查不到数据的处理方式（留空不填0，标注原因）
10. 回复要求（完成情况总结、交付文件、遇到的问题）
11. 遇到困难怎么解决
12. 实在解决不了怎么回复

文件名规范：

• 任务包zip文件名用中文（如"1号任务包.zip"），方便甲方识别
• zip内部文件名用英文（如task_instructions.txt），避免手机解压乱码
• 多个任务包打包成一个大zip（如"6个任务包打包.zip"），甲方只需要下载一个文件

合并校验流程：

1. 收到6个临时工的交付文件后，逐个检查JSON语法是否正确
2. 检查每个球员的核心字段是否全有
3. 检查数据是否合理（如OVR范围、数值是否异常）
4. 合并到主数据库的data/players/*.js文件中
5. 运行全量校验脚本validate_all.js，确保0错误
6. 部署上线

历史教训：

• 2026-09-06第一次打包时，球员名单CSV中的英文名和FootyStats URL都是错的（因为数据库中只有中文名，生成CSV时用了中文名），导致临时工无法直接使用。修复方法：在任务说明书中详细说明如何从中文名搜索英文名并构建URL。
• 2026-09-06第一次打包时，标准提取脚本只有9个字段，缺少aerialDuelsWon（争顶成功）。修复方法：更新脚本到v4，支持10个FootyStats字段。
• 2026-09-06第一次打包时，zip文件名用中文，内部文件名也用中文，导致手机解压乱码。修复方法：zip文件名用中文，内部文件名用英文。

3.5.2 OVR和六维数据获取方法

数据源：FCRatings.com（https://fcratings.com）。这是FC27官方评分的数据源，全队列表页可以批量提取，不需要逐个球员页搜索。

工具：webfetch（首选）或Playwright（备选）。FCRatings反爬不严格，curl也可能能用，但推荐webfetch。

球队页面URL格式：

• 示例：阿森纳 = https://fcratings.com/teams/arsenal，曼城 = https://fcratings.com/teams/manchester-city，皇马 = https://fcratings.com/teams/real-madrid
• 球队slug一般是球队英文名小写，空格用连字符

提取内容：球队列表页直接显示25人左右的OVR和六维（PAC/SHO/PAS/DRI/DEF/PHY），不需要进入球员个人页。

注意事项：

• 新升班马球员、新转会球员数据更新滞后约1-2周，FCRatings可能没有
• 有29项detailed数据的球员，OVR和六维以detailed数据自带的为准，禁止修改
• 六维数据必须同步更新fc和abilities两个字段，保持一致
• 所有数据变动加lastUpdated时间戳

3.5.3 29项detailed数据获取方法

数据源：FCRatings.com球员个人页。

球员个人页URL格式：

• 示例：萨卡 = https://fcratings.com/players/bukayo-saka，哈兰德 = https://fcratings.com/players/erling-haaland
• slug规则同FootyStats

注意事项：

• 29项数据是FC27游戏内的详细能力值，一年更新一次（赛季初），维护成本低
• 一旦录入不再修改，是最高权威数据
• 部分球员FCRatings可能没有个人页（如帕利尼亚、约翰尼·卡多索），需要从Sofifa或EA官方库补，或者确认不在FC27数据库里
• slug可能有错，如cardoso实际是johnny-cardoso，需要多试几种拼法

3.5.4 名单和号码获取方法

数据源优先级：

1. 俱乐部官网（最高权威）— 官方名单和号码最准确
2. ESPN squad页面（次选）— 更新及时，号码准确
3. 懂球帝转会新闻（验证）— 转会窗期间用于确认转会
4. Transfermarkt（参考）— 号码更新有时滞后于官方官宣，而且被AWS WAF拦截，curl访问不了

注意事项：

• 所有阵容页都滞后，转会窗期间必须用转会新闻+官网双源验证
• 重要转会必须双源确认，不能单信一个网站（之前格拉利什转会罗马就是单源出错）
• 转会更新时必须同时处理转出球员，不能只加不删（之前巴黎巴尔科拉错误残留就是只加不删）
• 批量抓取后必须抽样校验，不能直接入库（之前罗马14人批量错误就是没校验）

3.5.5 积分榜和射手榜获取方法（2026-09-07更新为7联赛）

重要规则（2026-09-06确立，2026-09-07强化）：积分榜和射手榜直接抄现成榜单，不要自己根据MATCHES比赛结果算。原因：MATCHES只有8支关注队的比赛，算出来不完整、容易错（乌龙球也算不明白），而且要翻所有比赛，很慢。抄不算，是铁律。

当前覆盖7个联赛：英超PL、西甲PD、德甲BL、法甲FL、意甲SA、葡超PO、欧冠CL。standings.js/scorers.js都按这7个key维护。

数据源（直接抄网页榜单）：

• 积分榜：球迷屋（已知：英超 https://m.qiumiwu.com/league/yingchao/standings 、西甲 https://m.qiumiwu.com/league/xijia/standings ；其余联赛在球迷屋站内搜"联赛名+积分榜"，不硬编URL）；备选联赛官网/直播吧/懂球帝
• 射手榜：新浪体育（已知：英超 https://sports.sina.com.cn/g/pl/table.html 、西甲 https://sports.sina.com.cn/g/laliga/table.html ；其余同理站内搜）；备选直播吧/懂球帝射手榜
• 程序化备选：football-data API（key见3章关键配置），可直接拉结构化积分榜/射手榜，适合批量；免费额度有限，超限就改抄网页

抄取字段：积分榜=排名/场次/胜/平/负/进球gf/失球ga/净胜球gd/积分pts（对应standings.js字段）；射手榜=排名/球员name/球队team/进球goals/助攻assists/出场played。

注意事项：

• 球队/球员名称必须用中文，和现有数据文件里的中文名完全一致（如"纽卡斯尔联""托特纳姆热刺"）
• 欧冠未开赛时积分榜全0、射手榜为空数组属正常，不要编数据，开赛了再抄
• 抄完只用8支关注队的已赛结果反算核对（不全量交叉，那是画蛇添足），关注队对得上就过
• 不要用FBref抄英超积分榜：其26-27英超数据严重滞后（第3轮打完仍全0）

3.5.6 比赛结果和赛程获取方法

数据源：

• 比赛结果：联赛官网（英超官网、西甲官网等），次选懂球帝/直播吧
• 赛程：联赛官网，次选懂球帝

注意事项：

• 比赛列表必须确保45天以内的已公布比赛都在列表里，每次更新时检查
• 比赛时间必须注意时区转换，英超/西甲比赛时间是当地时间，要转换成北京时间（之前拜仁比赛时间写错就是时区没转换）
• 乌龙球必须记在对方球员名下，不能记在进球球员名下（之前乌龙球处理标准不统一）
• 比赛结果更新后，必须同步更新球员赛季数据（出场/进球/助攻），不能只更比分不更球员数据

3.5.7 desc（前瞻/后顾）获取和写作方法

核心原则（2026-09-06确立）：禁止凭印象写任何事实性信息，必须先搜2-3个媒体报道融合提炼。AI训练数据有截止日期，2026年的转会、伤停、主帅信息可能不知道，凭印象写必然出错。

后顾（赛后总结）写作规范：

• 只写：战术转折、争议判罚、轮换深意、状态信号、里程碑
• 不写：按时间顺序的进球过程（"第X分钟XX传球XX射门破门"这种流水账）
• 三次更新机制：赛后1小时（快速版）、赛后6-12小时（博主观点出来后）、赛后24-48小时（深度分析出来后）

前瞻（赛前预告）写作规范：

• 只写：比赛重要性、近期状态、战术对位、教练信号、赛程因素、8支关注队核心主力伤病（必须说明战术影响）
• 不写：边缘球员伤病、长期伤号（米利唐、罗德里戈这种伤了大半年的场场提）、流水账伤病名单、非关注队伤病
• 三次更新机制：新增比赛时（基础版）、赛前2-3天（博主前瞻出来后）、赛前12-24小时（首发预测出来后）

搜索关键词格式：

• 后顾："主队 比分 客队 赛后战报 YYYY年M月D日 联赛名"
• 前瞻："主队 vs 客队 赛前前瞻 比赛分析 YYYY年M月D日"

4. 质量门禁与检查机制

核心原则：靠工具不靠自觉。更新了哪一级数据，就跑哪一级的检查；全部通过才能部署。

检查工具

两道闸（务必分清）

• 结构闸 = check_all/validate_data/verify_data：查格式、枚举、内禀一致性。查不出"数字真不真"
• 事实闸 = 双源交叉验证：专门抓"数字和现实不符"。每次更新第一级数据必须对源双核，不能只看结构闸全绿就发布

回归测试（按变更类型触发）

拟人视觉检查 v4（2026-09-08确立，人眼级全面检查）

为什么必须做：代码断言查不出"人眼一看就错"的问题——文字重叠、队名被时间盖住、百分比溢出框体、队徽国旗空白、颜色错配。用户原话："你不是定位代码，你是检查的方法。如果真的是人看，一眼就看出来了。"检查必须像人眼一样看渲染后的画面（滚动着看，每一寸），而非只做代码断言。

工具：visual_check.py（Playwright渲染+几何检测+截图存证）

• 运行：cd match-tracker && python3 visual_check.py（本地服务 python3 -m http.server 8123 需先启动）
• 检测5类：①文本截断(scrollWidth>clientWidth) ②文字重叠(absolute元素相交>30%) ③破图(img naturalWidth=0) ④超出视口 ⑤超出父容器
• v4关键升级：滚动全页遍历（每560px一检，合并去重）——首屏之外的问题（如滚动后出现的卡片重叠）也必须抓到
• 误报过滤：fixed/sticky顶栏属正常遮挡层不报；宽度<10px装饰条不报
• 部署门禁：视觉检查必须0条才允许部署（与结构闸并列，是人眼闸）

本日修复沉淀（2026-09-08，全部经visual_check验证0条）

新增静态资源铁律（2026-09-08教训：data/img未同步导致线上404）

• 新增任何静态资源目录（图片/字体等），必须同步加进 sync_to_deploy.sh 的 FILES 和 cp 段，否则部署脚本不传、线上404
• 部署后必须 curl 线上资源验证（https://bxgj2030.top/ 本机https直连不通，用http验证）

球员归属强制校验机制（2026-09-06确立，解决AI印象与现实差距问题）

核心问题：AI训练数据有截止日期，2026年转会/主帅信息可能不知道，凭印象写导致事实错误。已犯错误：格拉利什（曼城→罗马）、恩佐（切尔西→利物浦？）、达尼洛（尤文→弗拉门戈，2025年1月就走了）、姆巴佩（巴黎→皇马）、卡塞米罗（曼联→迈阿密国际）等。AI的印象改不了，只能用方法弥补。

铁律（违反等于事故）

• 任何涉及球员归属、转会、名单、主帅的操作，必须先查我们自己的数据库，绝对不能凭印象。
• 我们的数据库（网站上的球员页面）是唯一的事实来源——因为已经核对过名单，是最新的。
• 数据库里没有的球员/球队，才去查外部数据源（Transfermarkt、懂球帝、直播吧等），不能凭印象。
• 外部数据源查到的信息与数据库不一致时，先更新数据库，再操作，不能直接用外部信息覆盖。

操作前检查清单（每次必走，不能跳）

转会确认名单（持续更新，操作前先扫一眼）

以下球员已确认转会，绝对不能再按原球队写：

注意：这个名单只是"已确认的重大转会"，不是全部。操作前还是必须查数据库确认，不能只看这个名单。

违规事故记录

• 2026-09-06 达尼洛事故：审计小老弟交付包时，看到juventus.js里有达尼洛，没有先查我们的数据库（尤文不在我们系统，达尼洛2025年1月已转会弗拉门戈），就把"达尼洛在FC27里存不存在"列进问题清单问小老弟，浪费时间。根因：没有执行"审计交付包前先过滤不存在的球队"规则。
• 2026-09-03 格拉利什事故：数据源更新滞后，格拉利什转会罗马后未及时更新名单，球员所属球队错误。根因：转会期没有双源验证。

5. desc前瞻与后顾规范（核心竞争力）

定位：观赛指南+看点提炼，不是流水账（用户会看集锦，过程不重复）。

写作铁律（2026-09-06确立）

• 禁止凭印象写任何事实性信息——球员归属、主帅、伤缺、数据，全部必须从媒体报道核实，不能凭AI记忆（AI训练数据有截止日期，2026年转会/主帅可能不知道）
• 先搜媒体报道，再融合提炼——每场比赛找2-3个媒体（直播吧、懂球帝、虎扑、The Athletic、BBC等）的赛后回顾/赛前前瞻，交叉验证后提取关键信息
• 只写有来源的内容——不确定的宁可不写，不能编造，不能用"疑似"、"可能"糊弄
• 先查自己的名单——写desc前先查data/*.js确认球员归属、号码、位置，不凭印象判断

已赛写后顾（补盲区）

只写时间轴和集锦看不到的东西：

• 战术转折/位置调整
• 争议瞬间（VAR/红牌/误判）
• 轮换深意
• 状态起伏信号
• 非常规进球亮点（连过数人/绝杀等）
• 伤退/复出、新援首秀/里程碑

常规进球不写（进球只进goals时间轴，集锦能看到）。

未赛写前瞻（提醒下一场看什么）

前瞻应该写什么（按优先级）

1. 比赛重要性/背景：联赛位置影响、德比战、教练压力、杯赛晋级意义
2. 近期状态走势：最近几场结果、主客场表现、进球失球趋势
3. 战术对位：预期阵型、关键球员对位、比赛风格碰撞（控球vs反击、高压vs低位）
4. 核心伤病影响：只提8支关注队的核心主力，且必须说明战术影响（如"萨利巴缺阵→后防出球和制空下降"）
5. 教练信号：赛前发布会透露的轮换、战术调整暗示
6. 赛程因素：是否有欧战分心、舟车劳顿、连续客场
7. 巴西球员相关变量（如有）

前瞻绝对不写什么

• ❌ 边缘球员、轮换球员的伤病（一个都不认识的，伤不伤不影响比赛走势）
• ❌ 长期伤号（米利唐、罗德里戈这种伤了大半年早就知道复出不了的，不用每场都提，只在他复出或有新进展时提）
• ❌ 流水账式伤病名单罗列（"A伤了、B伤了、C停赛"这种没有分析的罗列）
• ❌ 非关注队的伤病（除非直接影响和我们关注队的比赛，且是核心球员）
• ❌ 已经确定没有悬念的信息（"双方都希望拿3分"这种废话）
• ❌ 战绩流水账（"近5场3胜2平"这种没有分析的罗列）

伤病信息的正确写法

不是"谁受伤了"，而是"这个球员受伤对战术有什么影响"。

• 只提8支关注队的核心主力（首发级别的）
• 必须说明战术影响："德利赫特缺阵→中卫正面防守和制空能力下降，后场出球选择减少"
• 替补能替代的不用提（"替补前锋伤了"这种不影响）
• 长期伤号不用每场提，只在复出或有新进展时提
• 非关注队的伤病：除非是核心球员且直接影响和我们关注队的比赛，否则不提

核心原则：前瞻是"提醒下一场看什么"，不是"伤病名单播报"。读者想看的是这场比赛有什么看点、什么变量可能决定比赛，不是谁谁谁又伤了。

三次更新机制（2026-09-06确立，基于媒体发布时间规律）

后顾三次更新

前瞻三次更新

前瞻段落骨架（2026-09-09 V8修订：90字压缩版）

每篇desc ≤90字，六要素压缩在一段内，不强制分段，信息密度优先：

① 看点钩子：这场为什么值得看，一句话具体信息（"曼城若再平分差拉到5分"），禁"巅峰对决""焦点之战"。

② 背景数字：联赛位置/排名/分差/晋级意义，必须带数字。

③ 状态信号：最近走势一个趋势（连续不胜/主场强/进多丢多），不罗列战绩。

④ 战术对位：预期阵型/关键对位/风格碰撞一句话。

⑤ 伤停变量：只核心主力+影响，不列名单。

⑥ 信息量收尾：一个悬念或具体看点，禁"拭目以待"。字数硬上限90字，超了砍废话保事实。

AI味打散准则（2026-09-08新增，用户：一眼看穿AI文章已成公害）

禁用的AI腔（出现即返工）：①排比/对仗句（"不仅是实力的较量，更是意志的比拼"）；②总分总结构、每段首句都是主题句；③"值得注意的是""不可否认""综上所述""让我们拭目以待"；④三个一组过度工整的并列；⑤空泛形容词（精彩绝伦/荡气回肠/技惊四座）；⑥每篇固定"北京时间X月X日"开头；⑦完美总结式收尾（把全文复述一遍）。

人味写法（强制）：①写具体（第几分钟、谁、什么数据、什么细节），具体本身就没AI味；②用引语（主帅发布会原话、球员赛后采访）；③换视角（站在主队球迷/客队/中立角度看同一件事）；④口语化连接（"有意思的是""但问题在于""说到底"）；⑤留白不把话说满（"这可能是""关键看"）；⑥长短句交替、短句收尾；⑦允许带一点点立场和情绪，不装客观播音腔。

写作流程（每篇必走）：先搜2-3个媒体来源→提取事实与引语→按六段骨架填内容→自查AI腔清单→交给用户审。初稿只写骨架+事实，不追求一次成型；用户的修改意见是训练信号，每轮意见沉淀回本节。

巴西101分原则

同等内容给巴西考察球员多一分关注，不贴显性标签：

• 稳定主力（维尼修斯/拉菲尼亚/加布里埃尔/阿利松/马尔基尼奥斯）只在有变量时提
• 位置不稳的（吉马良斯/罗德里戈/若昂·佩德罗/马丁内利等）盯首发
• 边缘伤病（恩德里克/米利唐/埃斯特旺）进名单都值得提

防重复机制

• 每场比赛desc带descUpdated时间戳
• 距上次更新<6小时且数据源无变化 → 跳过不写
• 三次更新按时间点触发，每次更新必须有新内容来源，不能重复第一次的内容
• 已赛desc写完第三次后锁定，不重复更新

前瞻时效性强制规则（2026-09-08，治"初版躺平"）

• 每次执行更新时必须扫描全部未赛比赛：赛前≤24h的比赛必须已是最终版（第三次前瞻），赛前2-3天的必须已是第二版；否则标记"待更新"并立即补写，不得带病发布
• desc必带 descUpdated 时间戳；无descUpdated=未走三次更新流程=不允许上线
• 教训实例：2026-09-09凌晨欧冠波尔图vs曼城/皇马vs国米，文章停在"英超首轮"时代（内容写曼城首轮逆转），实际曼城已3连胜——初版写完无人跟进

口水话黑名单（2026-09-08，出现即删）

• ❌ "客场挑战""主场作战""主场战斗力强""客场远征""气氛热烈"
• ❌ "争取XX连胜/拿下XX"式口号开头
• ❌ "以XX著称"无具体数据支撑的空泛描述（"以防守反击著称"→改为"防守反击+定位球，场均解围超30次"）
• ✅ 每个判断必须带具体事实：数字、球员名、事件、历史战绩

伤停重复上报规则（2026-09-08）

• 上一场已报过的伤停，若无新进展（复出/加重/新伤），本场不再提（实例：奥赖利英超赛前热身伤，欧冠前瞻又报一遍=重复）
• 只报绝对主力（首发级别），替补/轮换/边缘球员伤病一律不写
• 转会/首秀/里程碑等焦点事件必写（实例：恩佐转会曼城并已融入，欧冠前瞻只字未提=严重遗漏）

6. 首页更新SOP

MATCHES字段

{team:"阿森纳", comp:"英超 第2轮", date:"2026-08-30 23:30",
 home:"阿斯顿维拉", away:"阿森纳",
 score:"", ended:false, goals:[["59'","萨卡","a"]],
 homeRank:5, awayRank:1, desc:"..."}

• goals格式：["分钟","进球者","h/a","点"/"乌"(可选)]
• h=主队进球靠左，a=客队靠右
• 乌龙球记录标准（重要）：side字段永远表示"进球算在哪边/显示在哪侧"，和普通进球完全一致。乌龙球只用第4字段"乌"标记，进球者名字写实际进乌龙的球员。
  • 主队球员进乌龙 → 算客队进球 → side="a"（显示在客队侧）
  • 客队球员进乌龙 → 算主队进球 → side="h"（显示在主队侧）
  • 示例：切尔西球员佩德罗进乌龙 → ["63'","佩德罗","a","乌"]（算布莱顿进球）
• 乌龙球不算射手榜进球（进球者不计入个人进球数）
• 法甲比赛不显示排名（leagueKey逻辑已处理）

比赛列表45天检查更新机制（2026-09-06确立）

• 触发条件：每次用户说"更新"、"例行更新"、"读手册更新"时，必须执行此检查
• 检查标准：确保未来45天内的已公布比赛（8支关注队+欧冠一档二档球队）全部在列表中
• 检查步骤：
  1. 提取当前列表中最晚的比赛日期
  2. 如果最晚日期距今天不足45天，搜索赛程补全到45天
  3. 检查未来45天内已公布的关注队比赛是否都在列表中，遗漏的新增
  4. 新增比赛时同时写第一次前瞻（初步前瞻：比赛性质、排名背景、大致看点）
• 赛程来源：联赛官网（英超/西甲/德甲/法甲）+ 欧冠官网 + 懂球帝/直播吧赛程页，双源验证
• 当前状态：2026-09-06检查，列表覆盖到2026-10-21，正好45天，符合要求

积分榜/射手榜更新规则（2026-09-06确立，重要）

• 主数据源：球迷屋（英超 https://m.qiumiwu.com/league/yingchao/standings、西甲 https://m.qiumiwu.com/league/xijia/standings，其余联赛站内搜）
• 备用数据源：新浪体育 https://sports.sina.com.cn/g/pl/table.html、7M体育、联赛官网；程序化可用football-data API
• 覆盖联赛：英超PL/西甲PD/德甲BL/法甲FL/意甲SA/葡超PO/欧冠CL，共7个（2026-09-07起，之前"删除德甲法甲"的说法已作废）
• 更新时机：每次例行更新时，同步抄取最新的积分榜和射手榜，整体替换STANDINGS和SCORERS
• 抄取内容：完整积分榜（排名、场次、胜平负、进球失球、净胜球、积分）+ 前20名射手榜（球员、球队、进球数、助攻数、出场数）
• 验证方式：抄取后与备用数据源交叉验证，关键球队（前8名+8支关注队）的积分和排名必须一致；只用关注队MATCHES反算核对，不全量交叉
• 注意事项：
  • 球队名称必须用中文，和现有数据库中的球队名称一致
  • 射手榜中如果有新球员（不在现有数据库中），只记录进球数，不需要新增球员数据
  • 抄取后更新last updated时间戳
  • 欧冠未开赛时全0/空数组属正常，不要编数据；不要用FBref抄英超（滞后）

比赛卡片六联赛配色（注意：这是首页比赛卡片的色条，不是积分榜；积分榜7联赛统一用teal渐变背景）

注：意甲SA、葡超PO目前只进积分榜/射手榜（7联赛），比赛卡片暂未设专属色，若后续这两个联赛出现比赛卡片再补色，不影响积分榜显示。

7. 部署SOP（2026-09-06架构重构后）

项目架构（数据与视图分离）

• HTML页面（40个*_players.html=31俱乐部+9国家队，另加index.html + manual.html + changelog.html）：只负责渲染，不内嵌数据
• 球员数据文件（data/players/*.js，40个=31俱乐部+9国家队）：每队一个JS文件，包含window.PLAYERS = [...]球员数据
• 公共模块（data/css/common.css + data/js/common.js）：40个球队页面共用的样式和逻辑，改一处全生效，改完必须全量回归
• 比赛数据文件（data/matches.js）：比赛数据，包含window.MATCHES = [...]（2026-09-06分离）
• 积分榜数据文件（data/standings.js）：英超+西甲+德甲+法甲+意甲+葡超+欧冠共7联赛，window.STANDINGS = {...}（2026-09-07扩展）
• 射手榜数据文件（data/scorers.js）：英超+西甲+德甲+法甲+意甲+葡超+欧冠共7联赛（欧冠开赛前为空数组），window.SCORERS = {...}（2026-09-07扩展）
• HTML通过<script src="data/players/arsenal.js"></script>加载对应球队数据
• index.html通过<script src="data/matches.js"></script>等加载比赛/积分榜/射手榜数据
• 修改球员数据：只改data/players/对应球队.js，不需要改HTML
• 修改比赛/积分榜/射手榜：只改data/matches.js / data/standings.js / data/scorers.js，不需要改HTML
• 修改样式/逻辑：改对应HTML，数据文件不动

git版本控制（必须遵守）

• 项目已初始化git仓库，所有文件纳入版本控制
• 每次修改前：git status确认当前状态
• 每次修改后部署前：git add -A && git commit -m "描述修改内容"
• 出问题回滚：git log查看历史，git reset --hard <commit_id>回滚到任意版本
• 部署脚本会自动git commit，但手动修改后也应该主动commit

标准部署流程（COS/CDN，2026-09-07起）

• 命令：./scripts_ops/deploy_site.sh --cos-only
• 自动完成：上传所有HTML和数据文件到COS 存储桶（桶名见凭据台账，明文已清理）
• 部署平台：腾讯云 COS+CDN（bxgj2030.top），存储桶match-tracker，国内加速
• 网站地址：https://bxgj2030.top/
• COS 账号：见凭据台账（明文已清理）
• 操作员：见凭据台账（明文已清理，密码见部署脚本）
• 部署脚本：deploy_site.sh（用腾讯云 COS 官方 SDK，自动识别Content-Type，设置no-cache）
• 部署后必须浏览器开线上地址抽验改动点

浏览器缓存问题解决（重要！2026-09-07更新）

• 问题：又拍云CDN默认缓存8天，用户手机端普通模式看到的是旧版本，只有无痕模式正常。2026-09-07师姐TASK-003成果因JS引用无版本参数导致全炸。
• 强制要求（任何人做功能改造必须遵守）：
  1. 所有JS引用必须加版本参数，格式<script src="data/players/arsenal.js?v=YYYYMMDDHHMM"></script>
  2. 所有HTML文件必须设置 Cache-Control: no-cache, no-store, must-revalidate + Pragma: no-cache + Expires: 0
  3. 批量修改脚本必须包含这两步，不能只改功能忘了缓存
  4. 给协作方（师姐/临时工）的任务说明里必须明确写这两条要求
• 版本号规则：每次部署更新版本号，格式为YYYYMMDDHHMM（年月日时分），如202609071430
• 更新范围：40个球队页面（31俱乐部+9国家队）+ index.html + manual.html的所有JS引用（matches.js、standings.js、scorers.js、common.js、players/*.js）
• 部署脚本：deploy_upyun_sdk.py必须自动给HTML文件设置no-cache头
• 用户端：如果还是看到旧版本，让用户强制刷新（下拉刷新）或清缓存，之后就正常了
• 验证：部署后必须用普通模式（非无痕）打开线上地址抽验，确认是最新版本

历史部署平台（已废弃）

• surge.sh：match-tracker-2026.surge.sh，2026-09-06因当前网络环境无法访问（整个surge.sh平台超时）废弃
• 腾讯云COS：brazil2030-1477241622.cos-website.ap-chengdu.myqcloud.com，2026-09-06因手机浏览器触发下载而非渲染废弃
• Gitee Pages：官方已下线，无法使用
• Vercel/Netlify/Cloudflare Pages：注册失败（邮箱限制/人机验证/403）

数据备份与恢复

• 每次部署自动备份到backups/目录，保留最近10个版本
• 恢复：从backups/对应时间戳目录复制文件覆盖，然后重新部署
• git回滚：git log --oneline查看历史，git reset --hard <commit_id>回滚
• 双重保险：备份目录 + git版本控制，任何误操作都可恢复

版本号规则

• 纯数据更新（比分/积分/球员赛季数据）不升版本
• UI/功能/结构改动才小步递增（v10.05→v10.06）
• 版本号同时更新两处：<title>标签 + 积分榜header的.version-num

8. UI已锁定设计（没要求别改坏）

• 已赛卡片堆叠折叠62px（露队标/比分/联赛标），点开看goals+desc；未赛默认展开可收起
• 顶部球队按钮真实队标圆形，"全部"用FIFA双足球
• 预约按钮只在未赛展开时显示、生成ICS
• 手机返回键拦截：积分/射手页返回先回首页
• 积分榜：关注队队名金色高亮
• 射手榜：巴西球员金色高亮（br:1）
• 球员弹窗：雷达180×180；有detailed显示29项双列，无则降级6维
• desc故意不折叠（用户明确要求）

9. 待办事项（按优先级，2026-09-06更新）

执行规则：做完一项划掉一项，绝对不重复列已完成事项；每次更新手册前先核对本清单。

P0 最高优先级（本周内完成）

• ✅ 合并新临时工交付的worker1四队数据：曼联、热刺、纽卡、布莱顿四队场均数据合并到主数据库（2026-09-06完成，合并275人）
• ✅ 补7个URL错误球员数据：杜库雷、平诺克、阿耶尔、安德森、博格尔、博尔瑙、内茨——worker3说查不到，实际是URL构建错误，已确认有数据并补全（2026-09-06完成）
• ✅ 全量数据校验：全部合并后跑一次全量校验（JSON语法、数据类型、字段完整性、异常值）（2026-09-06完成，0错误1警告）

P1 中优先级（本周内完成）

• ✅ 比赛数据分离：把index.html里的60场MATCHES抽成独立 data/matches.js，HTML只负责渲染（2026-09-06完成）
• ✅ 积分榜/射手榜数据分离：把index.html里的积分榜、射手榜抽成独立 data/standings.js 和 data/scorers.js（2026-09-06完成，同时修复deploy.sh的desc检测脚本）
• ✅ 更新标准提取脚本：支持webfetch返回的"压缩内联文本"格式（如Shots Taken321.4768），升级到v4，支持10个FootyStats字段（含aerialDuelsWon）（2026-09-06完成）
• ✅ 苏格兰/威尔士/北爱尔兰球员国籍代码核实修正：已修改13个知名国脚（苏格兰4、威尔士7、北爱尔兰2），剩余约200人以后再做（2026-09-06部分完成）

P2 低优先级（2-4周内完成）

• ✅ 代码模块化（公共JS/CSS抽出来）：40个球队页面（31俱乐部+9国家队）+首页全部模块化，抽取common.css(13.8KB)+common.js(40.8KB)，球队页面从55KB→6KB减少82%（2026-09-07完成，婉师姐）
• ⬜ 增量校验/增量部署优化：只校验修改过的文件，只上传修改过的文件，不做全量校验/全量部署（预计1-2小时）
• ⬜ 移动端适配优化：优化手机端显示效果（预计2-4小时）
• ✅ 26-27赛季场均数据+双赛季同屏：26-27已于2026-09-07抓取上线，详情页26-27与25-26同格双值显示（2026-09-07晚改版完成，规则见13.1b），所有球员一视同仁不分级。场均数据不需要每轮更新，低频刷新即可
• ⏸️ 欧冠数据分离：联赛数据和欧冠数据分开存储，球员详情页支持切换显示联赛/欧冠数据（等欧冠有3-4轮数据后做，预计4-6小时）
• ⏸️ 2人pending六维跟进：道曼（阿森纳OVR68 RW）、纳撒尼尔·布朗（拜仁OVR81 LB），等FCRatings更新

P3 很低优先级（有空再弄）

• ⬜ 全量CI/CD管道：提交代码自动校验+自动部署，不用手动跑deploy_site.sh（预计4小时）
• ⬜ 球员头像补全：给没有头像的球员补头像

已完成（不再重复列）

• ✅ 8支关注队OVR/六维全量校准（193人191 verified，2人pending：道曼/纳撒尼尔·布朗）
• ✅ 24队B级数据批量上线（623人全部fcVerified=true，名字已中文化，国籍已补全）
• ✅ PSV埃因霍温数据补全（28人，六维为估算值fcVerified=false）
• ✅ 24支新球队球员页创建+部署
• ✅ 球员详情页三级颜色区分+展开全部（🔴核心/🔵位置相关/⚪其他，8个位置各有默认显示方案，2026-09-07完成，婉师姐）
• ✅ 取消球员分级体系（2026-09-07，原A级/B级/C级/D级取消，所有球员一视同仁）
• ✅ 增量更新diff机制（tools/backup_data.js + tools/diff_update.js）
• ✅ 每周一数据更新定时任务（比赛结果+积分榜+射手榜+DESC，每周一10点）
• ✅ 球员数据分离（30个独立data/players/*.js文件，HTML只负责渲染）
• ✅ 比赛数据分离（60场比赛→data/matches.js，2026-09-06）
• ✅ 积分榜/射手榜数据分离（→data/standings.js + data/scorers.js，2026-09-06）
• ✅ 巴西国家队动态聚合（从30个俱乐部文件动态筛选巴西国籍球员）
• ✅ 积分榜/射手榜改为抄数据源（球迷屋/新浪体育，不再自己算）
• ✅ 比分直接抄（不再根据进球列表算，乌龙球不会算错）
• ✅ deploy.sh自动化检查（7项检查：JSON校验、数据文件校验、HTML引用校验、版本号校验、desc流水账检测、changelog更新检测、手册章节检查）
• ✅ 场均数据3×3网格显示（球员详情页，按进攻→组织→防守顺序排列）
• ✅ 标准提取脚本v4（支持Markdown/纯文本/压缩内联三种格式，10个FootyStats字段）
• ✅ 29项detailed数据补全（151人）
• ✅ 6支空数据球队删除（monaco、napoli、rb_leipzig、real_sociedad、stuttgart、villarreal）
• ✅ 英国球员国籍代码修正（13个知名国脚：苏格兰4、威尔士7、北爱尔兰2）

已否决不再做

• ❌ DESC半自动化生成器——DESC是本版本最亮眼的地方，纯手写保证质量，搞成半自动化就变成流水账了（2026-09-06甲方明确否决）
• 半自动/云端定时更新、ICS默认闹钟、近态色点、卡片水印、自画人形logo
• AI生成完整射手榜图、Score90风格、form guide、最近赛果列、排名聚合视图

10. 已知坑与教训

1. 所有阵容页都滞后：Transfermarkt、Premier League官网、SPORT.es等6个网站验证滞后（格拉利什9/1租借埃弗顿，这些网站9/4还挂着他）。名单必须用转会新闻+俱乐部官网双源
2. FBref查不到就返回0、且英超更新极慢：曼联8/30比赛到9/4还查不到；2026-09-07验证，26-27英超第3轮（9/6）全部打完，FBref联赛页积分榜仍全0、球队页阿森纳只显示1轮。基础数据（出场/进球/助攻）主源用FotMob，积分榜/射手榜直接抄不用FBref，场均per90主源用StatMuse，FBref只做xG/xA验证
3. 转会窗截止日租借最容易漏：永久转会有官方公告不容易漏，租借（尤其是压哨）最容易漏。关窗后48小时内专门排查
4. 批量抓取后必须抽样校验：罗马14人批量错误事件教训——批量抓取后不能直接入库，必须抽样校验
5. 数据写入前必须加合法性校验：FBref返回0值事件教训——0值、空值、明显超出范围的数据禁止直接写入
6. 转会更新必须同时处理转出球员：巴黎巴尔科拉错误残留事件教训——不能只加不删
7. 变更检测必须第一步执行：不管检测到什么其他问题，都先把变更检测走完，再去处理其他问题
8. API延迟：football-data API在比赛结束后30-90分钟才同步FINISHED状态，刚结束的比赛用懂球帝/直播吧交叉确认
9. 比分不能靠进球列表算：之前比分根据进球列表计算，结果乌龙球算不明白（乌龙球算在对方头上，不是自己进的）。比分必须直接从联赛官网抄，不能根据进球列表算。进球列表只用来展示，不参与比分计算。乌龙球在进球列表里单独标注（"乌"），不影响比分。
10. 积分榜/射手榜不能靠算：之前根据比赛结果算积分榜和射手榜，需要找所有比赛，很慢，而且MATCHES只包含部分比赛（主要是8支关注队），算出来的积分榜不完整、容易出错。积分榜/射手榜必须直接抄数据源（球迷屋/新浪体育），不能自己算。
11. 画蛇添足的计算要删掉：积分交叉验证（validate_standings.js）是画蛇添足——积分榜是抄来的，抄来的就是对的，不需要和比赛结果交叉验证，而且验证还需要找所有比赛，很慢。抄来的数据不需要验证，直接用
    批量抓取先抽查解析正确性再全量：2026-09-09血泪——parse_table 用"排名后600字符切段"解析，跨行截断导致名字/值错位（"2025-26"/"0"/"2,141"等变成key），A组23队+seasonStats74队全部作废重抓。正确姿势：按 <tr> 逐行解析，NAME列固定第3列、指标值第4列，名字去尾部缩写（X. Y. 段），先抽查1队确认再全量。。

手册版本：v2.3 精简版（2026-09-07 逐字逐句校订）
v2.3本次校订：①在线地址/部署平台由surge.sh全面改为又拍云（deploy_upyun_sdk.py）；②球队规模统一为31俱乐部+9国家队共40个球员页/数据文件；③数据源口径统一——积分榜/射手榜一律"直接抄现成榜单不自己算"（主源球迷屋/新浪/联赛官网，football-data API作程序化备选，禁用FBref抄英超），场均per90主源由FBref/FootyStats改为StatMuse（第12章），FootyStats旧方案3.5.1标废弃；④联赛数统一为7个（PL/PD/BL/FL/SA/PO/CL），删除"法甲德甲已删除"的错误说法；⑤StatMuse实际成果更正为26队737人、29项非门将+14项门将；⑥备份云端改为又拍云。
v2.2历史：从约19000字精简，删除历史试错记录、重复验证过程、已完成待办；保留执行规则、数据源映射、检查清单、更新流程。
完整历史记录：见 changelog.html

1.7 备份与diff机制（2026-09-05建立，2026-09-06升级全量备份）

目的：本地+云端双备份，每次数据更新留痕，出问题能精准定位到某次更新、某个字段，方便回滚和排查。避免出现云端数据丢失、本地无备份的情况。

双备份架构：

• 云端：又拍云存储桶 match-tracker 部署的网站文件（全量，地址 http://match-tracker.test.upcdn.net/）
• 本地：工作目录项目文件 + backups/ 目录的历史备份

工具位置：

• tools/backup_full.js — 全量备份工具（备份整个网站，打包tar.gz，推荐每次部署前使用）
• tools/backup_data.js — 数据备份工具（仅备份data目录）
• tools/diff_update.js — 数据对比工具
• tools/check_dates.js — 比赛日期检查工具（每次部署前必须运行，检查日期异常）

使用流程（每次更新/部署必走）：

1. 部署前全量备份：node tools/backup_full.js — 备份整个deploy_temp目录（含index.html、js、css、data、手册等全部89个文件），打包成tar.gz到backup/，自动清理30天以上旧备份
2. 更新前数据备份：node tools/backup_data.js — 备份当前data目录到backup/时间戳/
3. 更新数据：修改data/*.js文件
4. 更新后对比：node tools/diff_update.js backup/时间戳 deploy_temp/data — 生成HTML变更报告到diff_reports/目录
5. 查看报告：打开diff_reports/diff_时间戳.html，确认变更内容符合预期
6. 部署前日期检查：node tools/check_dates.js — 扫描所有比赛日期，发现异常立即报警（未赛比赛日期已过去/已赛比赛日期在未来），有错误必须修正后才能部署
7. 部署：确认无误后部署上线（云端同步更新）

全量备份说明：

• 备份范围：整个deploy_temp目录（index.html、js/、css/、data/、changelog.html、manual.html等全部文件）
• 备份格式：tar.gz压缩包，按时间戳命名（full_backup_YYYY-MM-DDTHH-MM-SS.tar.gz）
• 备份大小：约0.17MB（89个文件）
• 保留期限：30天，超过自动清理
• 恢复方法：解压tar.gz，用其中的deploy_temp目录覆盖当前目录即可

报告内容：

• 新增球员、删除球员、修改球员数量统计
• 每个修改球员的具体字段变更（旧值→新值）
• 按球队分类，颜色标注（新增=绿、删除=红、修改=橙）

注意事项：

• 每次部署前必须先运行全量备份 + 日期检查，禁止不备份、不检查直接部署
• 每次更新数据必须先备份再对比，禁止直接修改不备份
• diff报告发现异常变更（如批量球员被删除、OVR大幅波动）必须暂停部署，排查原因
• 日期检查发现异常（未赛比赛日期已过去/已赛比赛日期在未来）必须修正后才能部署
• 录入比赛日期时必须注意时区换算（德甲/西甲/法甲=北京时间+6小时夏令时），双源验证（联赛官网+懂球帝/直播吧）
• 备份保留30天，超过自动清理
• 云端又拍云和本地backups目录形成双保险，任一丢失可从另一处恢复

11. 球队页面咪咕风格改造规范（2026-09-07 确定）

11.1 整体设计

• 参考咪咕视频APP球队页面设计，Header照抄咪咕风格
• 核心数据栏显示6项：进球、失球、助攻、红牌、黄牌、场均控球率
• Tab切换：阵容 / 赛程
• 球员列表按OVR降序排列（不按位置分组）

11.2 Header规范

• 队标：72px×72px，使用football-data.org真实队标（https://crests.football-data.org/{id}.png）
• 队名：26px，中文队名
• 英文名：14px，英文队名
• 主场：12px，主场球场名
• 右侧排名：36px数字 + 12px"XX排名"标签
• 胜平负：24px数字 + 12px"胜/平/负"标签
• 背景色：球队主题色（如阿森纳=红色、巴萨=红蓝渐变）

11.3 核心数据栏规范

• 6项数据横向排列，每项包含：数字（24px）+ 标签（12px）+ 排名（10px红色标签）
• 数据来源：积分榜（进球、失球、排名、胜平负）+ StatMuse（助攻、红牌、黄牌、控球率）
• 排名显示格式："排名第X"
• 暂无数据显示"-"

11.4 联赛映射表

11.5 队标ID对照表（football-data.org）

• 阿森纳=57, 曼城=65, 利物浦=64, 切尔西=61, 热刺=73, 曼联=66
• 纽卡=67, 维拉=58, 布莱顿=397, 水晶宫=354, 布伦特福德=402, 埃弗顿=62
• 诺丁汉森林=351, 富勒姆=63, 伯恩茅斯=352, 桑德兰=361, 利兹=341, 伊普斯维奇=349
• 考文垂=353, 赫尔城=356
• 巴萨=81, 皇马=86, 马竞=78, 贝蒂斯=90
• 拜仁=5, 多特=4, 巴黎=524, 国米=108, 罗马=100, 波尔图=503

11.6 必须保留的元素

• id="playerCount"：必须保留（可以隐藏），否则JS会报错导致球员列表不渲染
• const PLAYERS：球员数据JS文件变量名必须是大写PLAYERS
• JS版本参数：所有JS引用必须加?v=YYYYMMDDHHMM版本参数，解决浏览器缓存问题

12. StatMuse 批量数据抓取方法（2026-09-06 新增）

12.1 数据源

网站：StatMuse.com

特点：自然语言查询，返回结构化JSON数据嵌入HTML中。支持批量获取球队所有球员的多项统计数据。

12.2 URL格式（关键！）

https://www.statmuse.com/fc/ask/most-{统计类型}-{球队slug}-player-{赛季}-season

示例：

• 阿森纳2025-26赛季夺回球权：https://www.statmuse.com/fc/ask/most-possession-won-arsenal-player-2025-26-season
• 皇马2026-27赛季预期进球：https://www.statmuse.com/fc/ask/most-expected-goals-real-madrid-player-2026-27-season

12.3 可抓取的统计数据（早期验证12项，全量已达29项非门将+14项门将）

说明：下表是2026-09-06最早验证可行的12项；2026-09-06晚已由协作方全量抓取，实际每个球员拿到 29项非门将数据 + 14项门将专属数据（Per90口径），成果存于 statmuse_full_data.json（26队/737人，0失败）。完整字段以该文件和下表字段对照为准，下表URL关键词仍然适用。

12.4 球队slug对照表

12.5 抓取方法（Node.js脚本）

关键脚本：batch_all_stats.js（项目根目录）

步骤：

1. 用Node.js的https模块直接请求URL（不需要浏览器，不需要webfetch）
2. 设置User-Agent为Chrome浏览器
3. HTML中的数据是JSON格式，用"编码，需要先替换为普通引号
4. 用正则匹配每个球员的数据块（从"NAME":[0,{"value":[0,"开始）
5. 提取字段值："字段名":[0,{"value":[0,值],"display":[0,"显示值"]}
6. 计算Per 90：值 / (出场时间 / 90)
7. 合并到数据库的advanced对象中

注意事项：

• 每次请求间隔200-500ms，避免被封IP
• 字段名容易搞错（关键传球是PASS-KEY不是KP，过人是DRIB不是DRB，争顶成功是AER-W不是ADW）
• 只更新缺失或为0的字段，不覆盖已有数据
• 球员名字匹配用模糊匹配（去重音、小写、姓氏匹配）

12.6 赛季支持

• 2025-26赛季：✅ 已全量抓取，26队737名球员、0失败（statmuse_full_data.json）
• 2026-27赛季：seasonStats基础数随赛季更新；per90场均冬窗后统一更新（2026-09-08第22章定案，方法见12.8/12.9）
• 历史赛季：✅ 支持，StatMuse有2014-15赛季以来的数据（跨队转会球员可查其上赛季所在队，见第14章）

⚠️ 字段命名铁律（2026-09-07 血的教训）：预期进球/预期助攻在不同批次脚本里出现过两套写法——全拼 expectedGoals/expectedAssists 和短名 xG/xA，而渲染层（ADV_POSITION_CONFIG、ADV_FIELD_LABELS、双排对齐）只认短名。曾导致 387 人次的 xG/xA 格子空白。规定：所有新抓取、新合并、派给协作方的数据，per90 一律用短名 xG/xA，禁止再写全拼。common.js 已加 normalizeAdv() 在渲染前兜底转换（短名优先、转后删全拼、用副本不污染原数据），但数据层仍必须统一，不能依赖兜底。同理字段单位、口径以第12章对照表为准，不得自造别名。

12.7 与其他数据源对比

12.8 26-27更新流程（2026-09-07跑通，照此走）

1. node fetch_2026_27.js 抓27队全部（约9分钟，可加队slug参数单队重抓），产出 statmuse_2026_27_raw.json
2. node build_map_fingerprint.js 用25-26数值指纹反推重建英文→中文映射 name_map_auto.json（见12.9）
3. node match_2026_27.js 三级匹配（auto本队/transferred转会/miss无名单），产出 match_report.json + need_review.json
4. node merge_2026_27.js 把auto+transferred写入球员文件（旧值备份到per90_2526）
5. miss的人走第14章三集合判断，真·新援打包补录（参考TASK-013）
6. 统一刷新所有HTML的common.js/css版本号 ?v= 后，python3 deploy_2026_27.py 精准部署

12.9 26-27抓取的4个必踩坑 + 指纹反推映射法（2026-09-07血泪，务必照做）

URL模板：https://www.statmuse.com/fc/ask/{urlSlug}-{teamSlug}-player-2026-27-season，Node https.get直连，UA必须用Chrome120桌面UA。

• 坑1·HTML转义：返回体里是 " 和 &，解析前必须 .replace(/"/g,'"').replace(/&/g,'&')，否则会把有效slug误判成422/0块（探测脚本漏这步白忙一场）
• 坑2·多赛事拆分：同一球员返回多条，第一条带MIN且MIN>0的是赛季汇总，后面MIN=undefined的是联赛杯/欧战分条；只取汇总条（现有"minutes>0才收"天然过滤），并排除 name==='Total' 汇总行
• 坑3·MIN千分位：分钟数可能是"3,330"带逗号，必须 .replace(/,/g,'') 否则parseFloat得3
• 坑4·门将扑救率源字段坏掉：NPSH几乎全0，改用标准公式 savePercentage = SV/(SV+GC)×100；门将走综合页 most-save-pct，一个URL返回SV/GC/CS/SV-PK/ERR-SH/ERR-G/OG/RC全部字段（符合"开一个网页把该抄的一起抄"）。传球成功率=passes/passAttempts×100；playerRating是场均评分直接保留2位、不做per90

指纹反推映射法（解决"英文→中文匹配率低"的关键，比人工建name_map高效得多）：25-26全量数据(statmuse_full_data.json，英文名+per90数值)与现有球员文件(中文名+相同per90数值)，用 ballRecoveries/keyPasses/tackles/dribbles/interceptions/aerialDuelsWon/crosses/clearances 这8个命名一致字段拼数值指纹，至少3个字段全等即判定同一人，自动重建英文→中文映射。25-26实测737人指纹配对536人(72.7%)，叠加旧表后26-27自动匹配率从21.9%→78.1%。

译名全称/简称坑：name_map里常是全称"哈里·凯恩"，球员文件里是简称"凯恩"，精确相等会误判缺失。匹配函数要做 cnCore（取"·"后部分）+ 双向包含匹配，多人同时命中才标歧义人工确认（match_2026_27.js 的 findInRoster 已实现）。

13. 球员详情页场均数据显示规则（2026-09-06 确定）

13.1 整体设计

• 总共约25项非门将数据 + 14项门将数据，全部抓回来存在数据库
• 详情页默认只显示该位置相关的8项左右
• 点击「展开全部」可以查看所有数据
• 三种颜色区分：
  • 🔴 核心数据（必须有的）— 红色/橙色高亮
  • 🔵 位置相关数据 — 浅蓝色背景
  • ⚪ 其他数据 — 默认灰色

13.1b 双赛季同屏显示（2026-09-07 确定，最高优先级；2026-09-07晚改版为同格双值）

• 球员列表页：只显示26-27本赛季（出场/进球/助攻三个基础数），不做双赛季。
• 球员详情页进阶数据：26-27本赛季和25-26上赛季同一个字段的两个数值放在同一个格子里，禁止Tab切换、禁止上下两排。
  • 格子结构：label在上 → 本赛季值（26-27，彩色）居中 → 上赛季值（25-26，浅灰色）在下
  • 配色：核心字段橙块/位置相关字段浅蓝块/其他字段灰块，上赛季值统一浅灰（#bbb），一眼区分新旧
  • 顶部图例：● 26-27本赛季 / ● 25-26上赛季
  • 本赛季无数据（如只打了3轮某些字段为0或缺值）显示「-」虚线占位，不报错
• 逐格对齐（关键）：同一字段永远在同一格内上下对比，两季字段并集按 core→pos→全局顺序ADV_FIELD_ORDER 排序。实现：openPlayerModal 先算 alignedKeys，renderSeasonBlock(curData, oldData, positionShort, alignedKeys, curOnlyKeys) 按统一序列渲染（旧版renderSeasonBlock(data,pos,type,title,alignedKeys,curOnlyKeys)上下两排签名已废弃）。
• 字段三分类：
  • ① 同格双值显示（技术能力指标，跨季对比有价值）：进球/射门/射正/xG/助攻/过人/错失良机、关键传球/xA/传球/传球成功率/长传/直塞/传中/触球/评分、抢断/拦截/夺回球权/争顶/解围/封堵/犯规；门将：扑救/扑救率/失球/零封/扑点
  • ② 只在26-27本赛季显示（偶发/纪律数据，per90近0、对比无意义）：黄牌、红牌、乌龙球、失误致进球、失误致射门（ADV_CURRENT_ONLY）
  • ③ 不放进数据格：minutes出场分钟，只用于样本判断（<90分钟触发提示）
• 数据字段：p.per90=26-27、p.per90_2526=25-26，两个字段都保留，渲染时都读，严禁用新赛季覆盖旧赛季。

⚠️ 血的教训（2026-09-07）：甲方早已明确「场均数据冬窗后才碰26-27、半年更一次」，但当时只被授权做列表页三个基础数，却擅自把全队per90从25-26整体覆盖成才打3轮的26-27并上线，属于越权。铁律：更改per90赛季口径、整批覆盖数据前，必须得到甲方明确授权；讨论方案阶段不得擅自上线。本次最终决策是不回滚、改为双赛季同屏保留。

13.2 各位置默认显示方案

中锋 ST/CF（默认8项）

• 🔴 核心：射门、xG、射正
• 🔵 位置相关：进球、过人、争顶成功、错失良机、越位
• 展开看：助攻、关键传球、传球成功率、直塞球

注意：过人是现代全能中锋（罗纳尔多、亨利、哈兰德、伊萨克）的核心武器之一，必须放在位置相关，不能放展开看。

边锋 LW/RW/LM/RM（默认8项）

• 🔴 核心：射门、xG、过人
• 🔵 位置相关：射正、关键传球、xA、传中、错失良机
• 展开看：助攻、抢断、越位

前腰 CAM/AM（默认8项）

• 🔴 核心：关键传球、xA、射门
• 🔵 位置相关：过人、xG、射正、传球成功率、错失良机
• 展开看：抢断、助攻、直塞球

中前卫 CM（默认8项）

• 🔴 核心：关键传球、抢断、传球成功率
• 🔵 位置相关：传球次数、夺回球权、xA、射门、拦截
• 展开看：过人、犯规、长传

后腰 CDM/DM（默认8项）

• 🔴 核心：抢断、拦截、夺回球权
• 🔵 位置相关：传球成功率、传球次数、犯规、关键传球、解围
• 展开看：射门、xA、长传

边后卫 LB/RB（默认8项）

• 🔴 核心：抢断、关键传球、拦截
• 🔵 位置相关：传中、过人、夺回球权、助攻、解围
• 展开看：射门、xG、xA

中后卫 CB（默认8项）

• 🔴 核心：抢断、拦截、争顶成功、夺回球权
• 🔵 位置相关：解围、封堵、传球成功率、犯规
• 展开看：进球、助攻、长传、黄牌

注意：解围是中后卫四大核心维度之一（Gradient Sports数据确认），必须放在位置相关。

门将 GK（默认8项）

• 🔴 核心：扑救、扑救成功率、零封
• 🔵 位置相关：失球、扑救点球、失误导致射门、胜平负、出击
• 展开看：犯规、黄牌、红牌

13.3 实现时间

等临时工全量数据（statmuse_full_data.json）抓回来后，合并到数据库，然后按照本规则实现详情页的颜色区分和展开功能。

14. 三个圆分类法（补数据前必须先做，2026-09-07 血的教训）

14.1 什么是三个圆分类法

在补全球员缺失数据之前，必须先做三个圆分类，把缺失球员按数据可得性分成五类，然后再派任务。不能盲目地一个一个查，否则会浪费大量时间和人力。

三个圆的定义：

• 大圆：数据源网站（如StatMuse）整个网站覆盖的所有球队和联赛
• 小圆：你之前已经抓过的数据范围（如statmuse_full_data.json里只有26支球队）
• 球员圆：当前缺失数据的球员名单

14.2 为什么必须先做（血的教训）

2026-09-07的教训：之前补全88名缺失球员时，没有先做三个圆分类，直接派任务让师姐一个一个查，导致：

• 师姐白做了很多工作（有些球员明明在小圆里，直接从已有数据拿就行，她却重新去网上抓）
• 一轮一轮地补，像"拿着瓢舀鱼一样一瓢一瓢的舀"，效率极低
• 用户暴怒："你在这每一轮你像那个拿着瓢舀鱼一样一瓢一瓢的舀，你要舀到什么时候？"

正确做法：先花10分钟做三个圆分类，把88人分成五类，然后按分类派任务，一次性做完，不用一轮一轮补。

14.3 五类分类标准

14.4 操作步骤（补数据前必须按此走）

1. 第一步：明确小圆范围 — 列出你之前已经抓过哪些球队的数据（如statmuse_full_data.json里有26队）
2. 第二步：明确大圆范围 — 数据源网站（如StatMuse）覆盖哪些联赛哪些球队（可以测试几个典型球队确认）
3. 第三步：列出缺失球员名单 — 从数据文件中筛选出per90为null的球员
4. 第四步：逐个分类 — 基于足球知识，判断每个缺失球员25-26赛季在哪队，然后按五类分类
   • 已知在小圆里的 → 第一类
   • 已知在大圆但不在小圆里的 → 第二类
   • 已知不在大圆里的 → 第三类
   • 替补门将/青年球员 → 第四类
   • 不确定的 → 第五类
5. 第五步：按分类派任务 — 不要混在一起派，按分类分别处理：
   • 第一类：直接从已有数据拿，必须找到（重点检查名字匹配）
   • 第二类：列出需要重新抓的球队，一次抓整队数据
   • 第三类：换其他数据源或确认没有后撇开
   • 第四类：直接撇开，不用管
   • 第五类：先查25-26赛季在哪队，查清楚后再分类

14.5 实际案例（2026-09-07，88人补全）

小圆：statmuse_full_data.json里的26支球队

大圆：StatMuse网站覆盖的所有球队（五大联赛+其他联赛）

球员圆：88名缺失per90数据的球员

分类结果：

效果：分类后，16人直接从已有数据拿（零成本），25人直接撇开（不用管），只剩下10人需要重新抓球队数据+35人需要先查，工作量减少了一半以上，而且不用一轮一轮补。

14.6 注意事项

• 名字匹配是第一类的重灾区：很多球员明明在小圆里，但因为英文名翻译不一致（如"德扬·库卢塞夫斯基"vs"Dejan Kulusevski"）没匹配上，必须仔细核对
• 同名不同人要排除：如曼城的"安德森"名字太普通，一定要精确匹配，不要配错人
• 抓球队数据要一次抓整队：不要一个球员一个球员抓，打开一个球队页面，整队所有球员的该项数据都有了，一起抄下来
• 替补门将直接撇开：不要浪费时间去查替补门将有没有数据，肯定没有
• 分类要写进任务说明：派任务时，把分类结果写清楚，让执行者按分类处理，不要让他自己重新分类

14.7 2026夏窗关键离队记录（2026-09-09登记）

• 莱万多夫斯基：2026-06 合同到期离开巴塞罗那，2026-07 官宣加盟 MLS 芝加哥火焰（SPORT/Fabrizio Romano 确认）。barcelona.js 无此人=正确，非缺失；项目未覆盖 MLS 球队页，不建新页。
• 萨拉赫：2026 夏合同到期离开利物浦，自由转会土超特拉布宗体育（2026-09 初官宣）。liverpool.js 无此人=正确，非缺失；项目未覆盖土超球队页，不建新页。

第15章 师姐协作与新球队合并（2026-09-07）

15.1 协作机制（用户定的规矩）

• 师姐（wan）是临时帮手：与草包同为豆包AI，能力相同，仅临时协助。分工：草包做决策+顺手的小事，繁杂的事打包给师姐。用户只在中间传话，草包负责给师姐派任务
• 文件命名：草包发caobao_前缀，师姐发wan_前缀，都放又拍云collab/目录。用户只传"发布了"，双方各自去collab/取最新zip
• 师姐交付物不能整包覆盖：师姐的common.js是旧版（无renderTeamHeader/同格双值），直接覆盖会丢失草包的新功能。必须提取有价值内容（新球队HTML数据、数据文件），升级结构后合并，禁止覆盖公共JS/CSS
• 派任务粒度（2026-09-07用户强调）：给师姐派任务不用像给临时工那样写细——师姐与草包同为豆包AI能力相同，只需发任务包+关键方法要点（如已验证的URL模板），她不懂会主动问。写太细反而浪费时间。此条区别于对临时工的详细任务书要求

15.2 新球队合并流程（2026-09-07已验证）

• 来源：师姐新球队包（wan_新球队建设与新援补录），含23个新球队HTML+48个数据JS+61队index
• ⚠️ 合并前必查师姐数据文件是否带per90_2526（2026-09-07教训）：师姐的旧队更新文件（如man_city.js）不带per90_2526，直接覆盖会丢失git里已有的25-26旧数据（41队丢失）。合并前必须：grep -c "per90_2526" 师姐文件；合并后必须全量检查grep -L "per90_2526" data/players/*.js，缺的从git旧提交恢复（git show 3a98bea:data/players/{slug}.js 提取per90_2526按name合并，不覆盖per90）
• ⚠️ 师姐数据可能错位（2026-09-07教训）：师姐把AC米兰25人名单写进了inter.js，ac_milan.js只有6人。合并后必须抽查豪门队名单是否与球队对应（git旧版名单为基准对照），发现错位按git正确名单重建+按name合并师姐的per90
• 合并步骤：
  1. 复制48个数据文件到 data/players/（覆盖同名+新增，保留per90+per90_2526双字段——师姐数据格式兼容）
  2. 复制23个新HTML，批量升级Header：h1旧结构→<div class="team-header" id="teamHeader"></div>（用正则替换）
  3. 刷版本号：common.css/js?v=统一为最新版本号
  4. 修复师姐HTML重复count：师姐的HTML里count div重复（替换时保留原count又加新的），需去重。注意：Python str.replace会替换所有匹配项，两个相同count会被一起删掉，必须用count=1参数或先加回再验证
  5. TEAM_MAP补新队：cn/en/stadium/lg/crest五字段全填。联赛键必须与standings.js一致（PL/PD/BL/FL/SA/PO/CL），从积分榜按lg+中文名取排名
  6. index.html用师姐的61队版（她加了新队入口），验证引用的data文件都存在
  7. 全部验证后同步deploy_site并部署 COS/CDN
• 验证清单：①所有页面id="playerCount"恰好1个 ②所有页面common.js版本号一致 ③新队页面Header渲染（队徽+中英文名+主场+排名+胜平负） ④详情弹窗正常 ⑤node语法校验common.js ⑥线上curl确认
• 容错设计：team_summary_stats.json（助攻/红牌/黄牌/控球率）只有26旧队，新队这四项显示"-"不报错，进球/失球从standings.js正常取

15.3 当前网站状态（2026-09-07）

• 线上地址：https://bxgj2030.top/（COS 桶名见凭据台账，明文已清理）
• 球队规模：61队（39旧+22新），62个球员数据文件，134个上传文件全部成功
• 待办：22支新队的team_summary_stats数据（助攻/红牌/黄牌/控球率）待师姐补；新队球员的详情页双赛季数据视数据源情况
• TASK-016管道已合入（2026-09-07晚）：StatMuse一键更新管道（run_update.js），一条命令跑完抓取→映射→匹配→合并→校验，内置红线自查6项，每周更新从多步手工变成一条命令
• TASK-017 Tab已合入（2026-09-07晚）：球员页新增阵容/赛程Tab切换，62页已批量套用，版本号统一202609072300，已部署线上

第16章 合并校验关卡与协作红线（2026-09-07新增，防覆盖事故）

背景：2026-09-07合并师姐"新球队建设"包时发生覆盖事故——师姐旧队更新文件不带per90_2526导致41队25-26数据丢失；师姐基于旧底版common.js导致27队sm字段为空；师姐HTML退回旧h1导致Header消失。全部是"合并时没自动关卡"造成的。

16.1 合并校验关卡（合并任何交付包前后必跑）

• 脚本：项目根目录 validate_merge.py
• 用法：python3 validate_merge.py（查当前状态全绿）或 python3 validate_merge.py <交付zip>（合并前查交付包）
• 检查项：
  1. 数据文件62个语法+window.PLAYERS存在
  2. per90_2526双字段覆盖率（国家队9/英冠3/葡超1/新队3/ac_milan允许缺，其余必须双字段）
  3. common.js语法+6个关键函数（renderTeamHeader/renderSeasonBlock/openPlayerModal/loadTeamStats/goTo/goBack）
  4. TEAM_MAP的sm字段（除国家队9个外不得为空）
  5. 球员页HTML全部含id="teamHeader"与id="playerCount"，版本号统一
  6. index.html含goTo/render/renderStandings/renderScorers/switchTab+三个数据引用
  7. team_summary_stats.json≥53队+关键队key
  8. 交付包专项预警：common.js的sm为空、球员页缺teamHeader、数据文件缺per90_2526（警告不阻断，需人工确认）
• 退出码：0=全绿可合并部署；1=有错误禁止合并

16.2 协作红线（已发师姐，collab/caobao_协作规范_合并红线）

1. 数据文件永远带per90_2526：师姐更新旧队数据只改per90，保留per90_2526；新队可无
2. common.js必须带全TEAM_MAP的sm字段：sm为空说明底版旧，先要最新底版
3. 球员页HTML禁止退回旧h1：必须保留<div class="team-header" id="teamHeader">；缺则只提取JS/CSS不采用HTML
4. 合并前先跑校验关卡：validate_merge.py <zip> 全绿才合并
5. 版本号统一：common.css/js?v=同一版本号

16.3 合并流程总纲（防覆盖五步）

1. 备份+git提交当前状态（形成可回滚点）
2. 跑validate_merge.py <交付zip>，有警告先看：sm空→补sm；缺teamHeader→不采用其HTML；缺2526→确认是否旧队更新（是→禁止整包覆盖）
3. 提取式合并：只提取师姐要更新的部分（per90数据/新增函数/新增队），不整文件覆盖。旧队数据文件用"按名字合并per90"脚本，保留per90_2526
4. 合并后跑validate_merge.py全绿
5. 同步deploy_site+部署 COS/CDN+git提交

16.4 项目基建清单（师姐上帝视角误判的纠正）

• git版本管理：已有（项目根目录git仓库，每日提交，覆盖事故可回滚——2026-09-07恢复41队2526数据即靠git历史3a98bea）
• 数据管道：StatMuse手动+脚本混合（手册12章抓取方法；每周更新为手动流程，师姐建议脚本化待评估）
• 部署：deploy_site.sh一键部署（134文件0失败）
• 站点监控：暂无（师姐P0建议，待定）
• 字段口径：assistsPer90等字段名与实际口径可能不一致（师姐指出assistsPer90存的是总数），需逐步核对，渲染时标注口径

第17章 协作行业标准与项目落地规范（2026-09-08新增，多人协作章程）

背景：团队从2人（草包+婉师姐）扩展为多人（+临时工+外部评审），用户要求"按行业标准来办"。本章用六项行业公认标准逐条核对现有做法：GitHub Flow（Git工作流）、Conventional Commits（提交规范）、SemVer（语义化版本）、Code Review（代码评审）、CI/CD（发布流程）、RACI（权责矩阵）+ 异步协作最佳实践。核对结论：对的坚持、错的改正、缺的补上。

17.1 六项标准核对总表

17.2 沟通机制（坚持+补漏）

• 唯一异步通道：collab目录（又拍云/collab/）。所有任务包、交付包、回复、通知都走collab，用户居中传话"发布了"只是通知信号，不承载内容。
• 正式回复格式（坚持）：致：XXX / 回复编号：CEO-日期-序号 / 日期 / 正文 / 落款CEO草包。对同意项说明理由，对否决项说明原因（尊重对方建议）。
• 回复时限（补）：交付后24小时内验收回复；任务领取后24小时内开工，48小时内首次交付或说明进度。
• 命名规范（改，统一）：从2026-09-08起，collab新文件一律按：
  <角色>_<类型>_<主题>_<日期>.ext
  角色：caobao（草包）、wan（师姐）、tmp（临时工）、ext（外部评审）
  类型：task（任务包）、delivery（交付包）、reply（回复）、note（规范/通知）、data（数据文件）
  示例：caobao_task_TASK020_xxx_2026-09-08.zip、wan_delivery_TASK020_xxx_2026-09-08.zip、caobao_reply_验收TASK020_2026-09-08.txt
  历史文件保持原样（已成档案），新规范从现在执行。

17.3 Git提交信息规范（改）

行业标准：Conventional Commits（Angular/Vue/React等主流项目采用）。

落地格式（简化版）：

feat(球员页): 新增阵容/赛程Tab切换
fix(首页): 修复手机返回空白(bfcache)
docs(手册): 第17章协作标准
chore(部署): 部署v2300
data(球员): 补全曼城25-26场均数据

• type：feat(功能)/fix(修复)/docs(文档)/data(数据)/chore(部署杂务)
• scope：受影响模块（首页/球员页/手册/数据/部署）
• 历史提交不动，从现在起新提交用此格式

17.4 版本号双轨制（改）

• 部署版本号（保留时间戳）：v=20260908XX。用途：浏览器缓存刷新参数（query string）。这是静态网站的实际需求，保留。
• 产品语义版本（新增SemVer）：vMAJOR.MINOR.PATCH。用途：对外发布里程碑标记。
  • 主版本MAJOR：不兼容重大变更（如页面架构重构、数据格式变更）
  • 次版本MINOR：新增功能（如Tab、AC米兰入口）
  • 修订PATCH：bug修复（如手机返回空白）
  当前为 v1.4.0（1.0初始、1.1前端优化、1.2核心数据栏、1.3赛程Tab+AC米兰入口+未赛收起）
• 记录位置：changelog.html每次发布更新SemVer版本号+改动摘要。

17.5 RACI权责矩阵（正式化）

A=最终负责(唯一) R=执行 C=咨询 I=知情。核心：用户是唯一A（最终拍板）；草包是部署/验收的A+R；师姐是功能执行的R；临时工是数据执行的R；外部评审只做C（提供意见不决策）。

17.6 发布流程与回滚预案（补全）

标准发布流程（每步必须）：

1. 合并前：跑 validate_merge.py <交付zip> 全绿（否则退回）
2. 合并后：跑 validate_merge.py 全绿
3. 同步deploy_site → 部署 COS/CDN（记录文件数/失败数）
4. 线上验证（chromium无头抽查关键页面）
5. git提交（Conventional Commits格式）
6. changelog.html更新SemVer版本号

回滚预案（三件事写死）：

• 触发条件：部署后发现数据丢失/页面崩溃/功能回退（validate_merge.py报错）；用户反馈严重异常且确认是新版引入
• 操作步骤：①git log找上一个正常提交 → ②git checkout <上版> -- 受影响文件（或git revert）→ ③重跑validate_merge.py → ④重新部署 COS/CDN → ⑤线上验证
• 执行人：草包（CEO）唯一，无需等确认（用户已授权"你定"）

17.7 交付自查清单（补，发给所有协作方）

任何交付包必须随附交付说明，包含以下五段（缺一段验收时退回补交）：

【TASK-XXX 交付说明】
一、改动内容：改了哪些文件、各改了什么（逐条）
二、验证结果：怎么验证的、测了什么、结果如何（写明浏览器/尺寸）
三、自查清单：
  [ ] 数据文件带per90_2526（旧队更新时）
  [ ] common.js含全部关键函数+sm字段非空
  [ ] HTML含id="teamHeader"（球员页）
  [ ] 版本号统一
  [ ] 语法检查通过（node --check / chromium实测）
四、待确认问题：需要草包侧决策/确认的事项
五、数据说明：数据来源、口径、与上次的差异

17.8 基线制度（治本：彻底解决"协作方基于旧底版交付"）

事故复盘（2026-09-08）：师姐TASK-017/016/019b三次交付均基于旧底版（缺goTo/缺Tab/sm空），草包每次"提取式打补丁"重复劳动。更深层：TASK-017合并时用 git stash push 备份，把含Tab的common.js存进stash后工作区被重置，导致Tab版本从未进入git历史、从未上线——备份用git commit，绝不用git stash（commit可追溯，stash会吞修改）。

行业标准对应：GitHub Flow的"单一事实来源+开工前拉最新+CI自动拦截"。落地为基线制度：

1. 发任务包必带基线：草包发任务包时，包内附 baseline/ 目录（最新common.js/index.html/模板）+ BASELINE.json（版本号+文件SHA256+关键函数指纹），用 python3 make_baseline.py 生成。协作方必须基于包内baseline修改，禁止用自己本地旧版。
2. 交付必随附BASELINE.json：从基线复制不改动。合并前 validate_merge.py <zip> 自动对比：交付的common.js/index.html若缺基线关键函数（renderTeamHeader/renderSeasonBlock/openPlayerModal/loadTeamStats/goTo/goBack/initViewTabs/renderSchedule等）→ 硬错误退回，机器拦截，不靠人工发现。
3. 关键函数指纹清单（BASELINE.json维护）：common.js 8项（含Tab），index.html 5项。任何交付缺一项即判"基于旧底版"。
4. 交付包文件名规范：<角色>_<类型>_<主题>_<日期>.ext（caobao_task_/wan_delivery_/caobao_reply_/caobao_note_）。

使用流程：

# 草包发任务前
python3 make_baseline.py                    # 生成基线(版本+指纹)
zip 任务包.zip 任务说明.txt baseline/ 相关文件  # baseline内含BASELINE.json

# 合并交付包前（必须）
python3 validate_merge.py 交付包.zip         # 【7】基线一致性检查自动拦截旧底版

17.9 授权边界与直接发布规则（2026-09-08，分工细化）

分工原则：草包负责决策/商量/大环境（统筹+验收+部署），师姐负责小检查/小改动执行。用户可直接向师姐派小任务。

A类（师姐可直接发布）——小改动：

• 单/少量数据文件补全（≤3个数据文件）
• 纯数据文件（data/players/*.js）更新
• 发布前：python3 validate_merge.py 全绿；发布用 deploy_single.py（只传指定文件，内置禁止名单）；发布后通知草包（改了什么+文件列表）

B类（禁止直接发布，必须发草包验收合并）：

• common.js / common.css / index.html（公共文件，影响全局）
• 跨多文件结构性改动（Tab/Header/新功能/批量套用）
• 批量数据更新（>3文件）；新球队/新页面创建
• deploy_single.py 内置禁止名单（common.js/common.css/index.html/*_players.html），尝试直接发布会被拒绝

工具包：deploy_single.py（单文件发布，含Content-Type映射+禁止名单）、validate_merge.py、make_baseline.py、BASELINE.json 已打包发师姐（collab/caobao_task_工作包_授权边界与直接发布）。

回滚责任仍在草包：师姐直接发布出错→草包用git/旧版回滚，不影响B类流程。

17.10 发布/回滚命令固化（2026-09-08，一条命令完成标准发布）

问题：此前"手动校验→手动部署→手动记版本"，环节多易漏（曾发生没校验就发布、Tab版本被stash吞）。行业标准：发布流程固化成可执行命令，校验内嵌，不通过自动停止。

标准发布（一条命令）：

python3 release.py "改动摘要"           # 默认PATCH（bug修复）
python3 release.py "改动摘要" --minor   # MINOR（新功能）
python3 release.py "改动摘要" --major   # MAJOR（不兼容变更）

自动完成4步：①validate_merge.py全绿（红字禁止继续）②部署 COS/CDN ③git commit+打SemVer tag ④changelog.html记录。任何一步失败即停止，不产生半成品。

一键回滚（执行人：草包唯一）：

python3 rollback.py            # 回滚到上一个tag
python3 rollback.py v1.4.0     # 回滚到指定版本
python3 rollback.py <commit>   # 回滚到指定提交

自动完成：checkout目标版本→校验全绿→部署。未提交的新工作不受影响。

SemVer规则（已通过release.py强制）：MAJOR=不兼容变更 / MINOR=新功能 / PATCH=bug修复。当前 v1.4.0。每次发布自动打tag+更新changelog，版本永远可追溯。

回滚预案三件事（17.6已定义，现在可执行）：触发条件=validate报错/线上异常；操作=python3 rollback.py；执行人=草包。

17.12 产品测试流程（2026-09-08，QA角色正式上岗）

铁律：写代码的人不测自己的代码。用户已明确不再当第一道测试（此前一直是用户发现错误，成本极高）。

测试三级流程：

1. 草包自查（发布前必做）：validate_merge.py全绿 + chromium headless抽查关键页（首页/球员页/Tab/手机宽度）+ 数据文件与页面引用核对。自查不过不发布。
2. 师姐QA测试（TASK-020起）：按测试清单逐项实测（首页8项/球员页9项/国家队/数据一致性，共20项），问题分级P0致命/P1严重/P2轻微，P0/P1不修复不许报通过。报告五段式（环境/总览/问题清单含复现步骤/通过项/建议）。
3. 用户终验：只看最终成果，按验收清单划勾。用户发现问题→退回草包+师姐，查流程哪一环漏了（自查还是QA），不重复修。

RACI更新：师姐兼任QA（R：功能执行+测试执行），草包（A：验收/部署），用户（A：唯一拍板/终验）。

责任链：用户发现错误时，先查"自查漏了还是QA漏了"，写进对应环节的检查清单，不允许同一类错误第二次到用户手里。

17.13 批量改动防呆（2026-09-08，颜色事故教训）

事故：TASK-017批量套用阿森纳模板生成62页，--team-color变量未按队替换，30个豪门页全变阿森纳红。代码检查（validate/chromium抓DOM）全部通过，因为代码结构没问题——只有人眼能发现"颜色不对"。

教训：

1. 批量套用模板后，必须抽≥5队肉眼验证变量值确实不同（不是只看代码）
2. 凡含"按队不同"的变量（颜色/队名/队标/数据），批量后必须逐队diff检查变量值
3. 测试清单增加"人眼视角"项：每个球队页颜色/Header/队标是否跟队走
4. 用户是最终验收人：用户报的视觉问题优先于所有代码级检查

批量后必查命令：

# 检查是否全站同一个颜色（应多色）
grep -l -- "--team-color: *#C41E3A" *_players.html | wc -l   # 应远小于页面总数
grep -o -- "--team-color: *[^;]*" *_players.html | sort | uniq -c  # 看颜色分布

17.14 AI视觉质检（2026-09-08，产品检测员升级）

为什么升级：用户指出"代码层面检查看不到颜色不对/元素挤压/超出边界/图标不显示"——TASK-020测试（Playwright抓DOM+查函数）通过了所有代码检查，但30个球队页全是阿森纳红色，代码检查完全没发现。行业标准：视觉回归测试+Vision Model QA（截图→AI看图→结构化断言），代码断言测不了"样子对不对"。

检测员职责：像用户一样打开网站、用眼睛看、逐寸逐按钮检查（手机375px为主+桌面1440px）。每页从上到下逐区域看图，每个按钮真的点。

逐寸检查清单（每页通用）：颜色跟队走 / 队标图标无裂图 / 无挤压重叠错位 / 无溢出被切 / 间距一致 / 文字可读（深底浅字）/ 空态区分"无数据正常"与"应该有没有"。球员页：Header→数据栏6项→Tab→列表→详情弹窗（三色规则/双赛季同格/✕能关/返回）。

视觉基线（草包侧）：

python3 /tmp/visual_shot.py          # Playwright全站截图(线上URL,手机+桌面,等networkidle)
python3 visual_diff.py                # 改版后对比基线,列出视觉变化页,AI分类(有意/无意)

基线目录 /home/user/deploy_site_shots/{mobile,desktop}/（68页×2尺寸）。改版后diff >0.5%像素即需人工/AI确认变化是否有意。

铁律：检测结论必须"人眼看着对"，不许"代码看起来对"。用户报的视觉问题优先于所有代码级检查。

第18章 AI全盘战略（2026-09-08，白皮书v1.0）

一句话：足记不只是"网站+AI工具"，而是让AI成为产品的心脏——数据活、质检AI首检、保护物理级、错误自动吸收、内容人机分层、体验拟人化、协作规则化。

七大系统：①数据神经系统（Schema+来源标注+交叉验证+异常检测）②质检免疫系统（L1机器→L2视觉→L3探索→L4师姐→L5用户）③安全防护（部署前快照+指纹校验+自动回滚+凭证管理+恢复演练）④自我进化（错误→代码级防再犯规则，不靠记性）⑤内容引擎（DESC护城河+AI周边素材/速览/故事）⑥体验系统（拟人化走查/个性化/仪式感/语音/问答）⑦协作操作系统（任务自动路由+决策自动化）。

铁律：每个教训必须变成"机器拦"，不是"人记"；重复决策自动化，人只管例外；检测结论必须"人眼看着对"。

完整版：docs/AI战略白皮书_v1_2026-09-08.md（collab: caobao_note_AI战略白皮书_v1_全盘AI规划_2026-09-08.md）

17.15 部署防呆三铁律（2026-09-08，血的教训）

教训一：rsync污染——`rsync -a --delete ./ /home/user/deploy_site/` 把项目根的 node_modules/task*/worker*/zip/py 全部同步进部署目录，线上被传了1588个文件（原本只有134个）。铁律：deploy_site 只能由部署脚本（deploy_site.sh）维护，禁止rsync整个项目根；往部署目录同步必须用白名单式复制（只拷 *.html + data/）。

教训二：清理白名单——线上清理垃圾文件时，白名单漏了 `*_players.html`，62个球员页被误删（幸好本地完整，重部署恢复）。铁律：线上删除前必须列出完整白名单（*_players.html + index/manual/changelog + data/ + collab/），先dry-run打印清单确认再删。

教训三：又拍云SDK目录判断——getlist 返回 type='F' 是文件夹（不是'folder'），删目录要先递归删内容再删目录。写清理脚本时先验证 type 取值。

正确部署流程：改文件（项目根）→ validate_merge.py 全绿 → 用 deploy_site.sh（只认 deploy_site）→ curl 抽查线上 200 → visual_shot.py --new + visual_diff.py 看变化分类 → git commit。

本章一句话总结：协作的行业标准核心是"异步文档化沟通 + 一事一A + 校验关卡 + 可回滚"——我们已有骨架（collab/validate/每日git），补上命名统一、提交规范、SemVer、回滚预案、自查清单五块，即可按行业标准运转，多人加入不乱套。

第19章 检查体系升级：验收标准清单+错误自动吸收（2026-09-08新增，血的教训）

触发背景：用户连续报出射手榜无国旗、按钮无描边、球衣配色丢失、列表卡片无赛季数据——这些我设的检查全没拦住。根因分析：

根因一：视觉diff只做"变化检测"，不做"对错检测"——visual_diff 对比的是基线截图；基线=TASK-021修复后状态，基线里就没有国旗/描边/卡片数据，diff自然报"无变化"。基线固化错误=错误永远发现不了。

根因二：检查清单只查负面现象，不查正面验收——旧清单查"裂图/溢出/重叠"，不查"射手榜必须有国旗、按钮必须有描边"这类产品定义。

根因三：产品定义散在聊天里，没固化——用户确认过的规则（球衣配色、双赛季同格、8色、列表页三数据）没变成可逐条勾选的机器清单。

升级方案（L3对错检测层）：新增《产品验收标准清单》PRODUCT_ACCEPTANCE.md（collab: caobao_note_产品验收标准清单_2026-09-08.md），A-F六类条目全部固化用户确认过的产品定义。规则：

① 每次全站测试必须逐条对照该清单；② 清单比视觉diff权威，"看起来没坏"不算过，清单条目不满足=问题；③ 基线≠权威，清单=权威，基线缺项要补基线；④ 错误自动吸收：每次用户报错→先问"这为什么没拦住"→升级清单/检查工具→再改bug，不许先修后忘；⑤ 发现清单没覆盖的新产品定义→立即补清单。

检查体系四层（升级后）：L1代码校验（validate_merge.py）→ L2视觉diff（visual_diff.py，变化检测）→ L3产品定义对照（PRODUCT_ACCEPTANCE.md，对错检测） → L4人眼（师姐TASK-026全量130页次）+ L5用户终验。

铁律：用户报的每个错，第一反应必须是"升级检查体系"，第二才是改bug。改完bug必须把该错误写进验收清单，否则下次还是漏。

第20章 行业标准落地：Design Tokens + 视觉回归基线管理（2026-09-08新增，查标准抄来的）

来源：不探索，查行业标准（Design Tokens 2014年Salesforce提出，全球设计系统标配；视觉回归测试为前端CI标准）。用户原话："肯定有行业标准，你去抄嘛，探索个毛线"。

Design Tokens铁律：所有主题色走 var(--team-color)/var(--team-watermark-color)，禁止裸写死（裸写死=违反单一事实来源，改一处坏一处）。三层：primitives(基础色值)→semantic(--team-color语义层)→component(组件层)。合规检查工具：python3 check_hardcoded_colors.py .（部署/测试前必跑，全库裸写死=0才放行）。

本次实战抓到的两个真bug：①62页详情弹窗评分均值ratingAvg裸写死color:#C41E3A（阿森纳模板残留24处）→已改var(--team-color)；②球衣渐变第二段裸写死#EF0107：linear-gradient(180deg, var(--team-watermark-color,#EF0107) 0%, #EF0107 100%)——球衣"上半段跟队色、下半段永远阿森纳红"（皇马白球衣变白→红渐变）→已改双token。这两个都是"画好了又变"的代码级真凶。

视觉回归基线管理（行业标准）：①基线快照必须进git版本控制（禁只存本地目录）；②只有"有意的、用户/设计批准的"UI变化才更新基线；③基线来自"确认正确的需求"，不来自"当前现状"——现状拍照=固化错误；④基线生成环境=测试环境（测线上URL，禁止测本地臆想版）；⑤差异=回归缺陷，先审后更新。

组件集中原则：同样的样式（弹窗rating/卡片/Header）必须集中在common.css，禁止逐页复制62份——复制62份=改1处要改62处，漏1个就"变了"（62页#f8f8f8/#888/#333同类样式逐页复制，待收敛）。

第21章 发布门禁（release_gate.py，2026-09-08新增，行业CI/CD适配静态站实际）

行业标准：CI/CD流水线在合并前自动跑测试门禁。我们无CI服务器（静态站+又拍云+师姐协作），适配为本地发布门禁脚本：python3 release_gate.py，5关全绿才允许合并/部署。

五关：①validate_merge全绿（数据+代码+基线7关）②Design Tokens合规（check_hardcoded_colors全绿）③页面结构完整（62页teamHeader/ts-goals/common.js/goBack）④数据一致（62文件≥15人+seasonStats存在）⑤git工作区干净。

红灯=预期拦截也记录：门4红灯≠禁止前进，是"待办清单"（如seasonStats=TASK-024进行中），部署前确认红灯项有明确负责人在做即可。

17.16 流水线缓冲规则（2026-09-08用户提议后固化）

问题：旧流程"师姐做A→交付→草包验证合并(15-20分钟)→师姐干等→发结果→做B"串行阻塞，师姐交付后空转，任务排队积压（025/026曾长期排队），全量覆盖推进慢。

规则（流水线缓冲，参考生产管理）：①师姐手上常备≥2个任务（交付前就已拿到下一个）；②交付-验证异步化：她交付→立即做手上下一个，草包异步验证→验证结果发collab→她有错才修，不阻塞主流水；③草包验证必须脚本化提速（发布门禁+自动抽查），目标10分钟内闭环；④任务包一次多批派发（如027+025+026一起排队），师姐按编号顺序执行；⑤版本基线：她每次交付前确认基于线上最新版（TASK-022教训：测旧版=白测）。

19.7 数据合理性验证（2026-09-08新增，红牌数据事故后固化）

事故：皇马红牌显示1.75/7张，西甲官网实际=0张（4轮黄牌8、红牌0）；切尔西2.67/8张同样离谱。StatMuse球队红牌字段不可靠，已全库置空（77处），待英超/西甲官方源逐队核实后补，宁缺毋滥。

铁律：①任何per90类数据入库前做合理性检查：红牌per90>0.5、单场>2张、出场数>赛程轮次×2 等必须人工核实；②新数据源首次使用前，用已知球队（如皇马红牌=0）交叉验证；③per90字段语义固定=25-26上赛季数据，26-27本赛季场均冬窗后统一补充，禁止拿旧数据冒充新赛季（弹窗26-27列无数据显示"-"，不fallback）。

第22章 数据治理：per90统一基准（2026-09-08新增，赛季混合事故后固化）

事故：TASK-025扫描发现per90字段赛季混合无标记——同一队内拉亚per90.minutes=270（26-27的3场）与萨利巴=2614（25-26整季）并存，数据语义被破坏。根因：per90曾在多轮任务中被部分覆盖（StatMuse 26-27赛季初数据混入25-26基准）。

治理方案（已执行，TASK-025B）：①per90统一=25-26上赛季基准（数据源：statmuse_full_data.json 26队全量英文名匹配530人 + per90_2526备份412人，两源皆无=置空不编818人）；②per90Season字段全库统一标"2025-26"（杜绝无标记混放）；③26-27本赛季场均冬窗后统一更新（用户拍板，禁止赛季初小样本提前补——已证实1分钟传360球伪值）；④零分母治理：minutes缺失/0带场均值的置空；⑤门将字段单独核查补齐。

新铁律：①per90语义固定=25-26上赛季，26-27数据只存seasonStats（apps/goals/assists/cleanSheets），冬窗后整体换新；②任何per90改动必须同步per90Season标记；③字段短名铁律（手册12.6）：expectedGoals/expectedAssists全拼一律xG/xA（全库654处已清零）；④从StatMuse全量复制数据时禁止带"门将模板值"（arsenal 3人advanced曾整段被拉亚模板覆盖，已用全量正确值修复）；⑤新数据入库先做跨源交叉验证（19.7）。

第23章 检查体系2.0：拟人检查+行业标准（2026-09-08新增，用户灵魂拷问"你到底检查了没有"后固化）

背景：用户连问"AI检查到底行不行""你是不是没好好检查"，并用两张截图证明代码级检查抓不到的视觉问题（拜仁队名时间黏连/巴黎时间缺前缀/利物浦队徽爆框/国旗缺失）。结论：代码检查（L1-L3）拦数据与结构，拦不住"人眼级排版与交互"。

拟人检查三查法（《视觉检查操作方法》collab存档）：①截图查：手机414+桌面1280双宽度chromium headless真渲染截图（不受缓存干扰）；②DOM查：getComputedStyle查主题色/球衣渐变真实样式（截图看不出的用这个）；③交互查：JS真点每个可点元素（切Tab/开弹窗/验证跳转目标）。

检查经验库（盖楼式防漏，docs/检查经验库_人眼发现.md）：每次用户/拟人发现漏网问题→立即追加为"必查项"→下次检查必须验证。覆盖面只增不减，历史漏网（球衣染错色/全队变红/按钮无描边/弹窗同值冒充/长队名黏连/队徽爆框/国旗缺失/按钮行为不对…）全部进库。

行业标准融入（ISTQB/黑盒测试查证）：①四级测试：组件（JSON合法）→集成（页面↔数据）→系统（师姐全站测试）→验收（用户终验）；②用例设计四法：场景法（用户主流程走通）、边界值（0出场/末位排名/空数据/超长队名/OVR极值）、错误猜测法（=检查经验库）、回归（改动后全站复测）；③兼容性：手机375+桌面1280必测；④缺陷管理：一事一报/客观描述/跟踪到底。

铁律：检查动作全部脚本化/清单化可分配，草包不闷头全看——归纳方法→派师姐执行→草包验收，效率2/3师姐、1/3草包。

23.1 检测能力矩阵（2026-09-08，甲方验收标尺：看检测能力不看网站样子）

甲方定调：验收标准=工具能不能自己发现所有问题并修复，而非产品形态。检测能力分四层，逐层加厚：

L1数据层（全量）：JSON合法/字段口径/缺失/零分母/赛季混合——validate_merge.py+自动化断言。盲区：值本身对错（需官方源人工核实，如红牌）。

L2结构层（全量）：页面完整性/引用残留/链接/硬编码颜色——断言脚本+check_hardcoded_colors.py。盲区：排版视觉。

L3视觉层（人眼级）：破图/溢出/颜色/间距/遮挡——Playwright手机414+桌面1280双宽度截图+DOM复核。盲区：截图看不出但人眼难受的细节。

L4交互层（全量）：每个按钮真点/Tab/弹窗/跳转——JS交互自动化。盲区：设计合理性判断（需甲方球商）。

漏检进化机制（盖楼式，已生效）：每次甲方/拟人发现漏网→根因分析（为什么没查到）→补进检查经验库必查项→下次必查。覆盖面只增不减，检测能力随轮次加厚。

效率目标：问题从发现到修复上线闭环≤2小时；执行完工作立即巡检，不等定时。

17.17 collab自动巡检+休眠唤醒协议（2026-09-08新增，去人工信使）

问题：草包与师姐经又拍云collab异步交换文件，无通知机制，此前全靠用户传话"发布了"，用户被迫当人肉信使。

双向自动轮询（已上线）：草包侧定时任务「collab交付自动巡检」（每30分钟）：跑 poll_collab.py 查collab新 wan_delivery_* → 自动下载→验证→合并→门禁→部署→git→汇报。师姐侧同构（每30分钟查 caobao_task_* 自动开工）。补充（2026-09-08脱手测试）：草包每次执行完工作（发任务包/部署/改数据/更新手册）后，立即手动跑一次 poll_collab.py 检查师姐新交付，不等30分钟定时；师姐同理（每次交付完立即查新任务）。目标是全自动闭环、用户完全脱手。

休眠/唤醒协议：①用户1小时无交流=离线：巡检触发时读 /tmp/collab_inbox/active.txt 时间戳（草包每回复更新），超3600秒→停本任务+传 caobao_note_休眠 通知→师姐见文件自停；②用户回来发消息=自动唤醒：恢复任务+传 caobao_note_唤醒 通知→师姐自恢复；③消耗优化：活跃期30分钟、休眠期零消耗，用户手动通知两边兜底。

铁律：草包每轮回复顺手更新active.txt（收到用户消息的第一时间写当前时间戳，不攒不拖）；休眠/唤醒通知文件命名 caobao_note_休眠_日期.txt / caobao_note_唤醒_日期.txt，师姐轮询按优先级处理（休眠>唤醒>任务包>说明）。
防御式判定（2026-09-08教训修正）：active.txt 缺失或读取失败 → 一律视为用户活跃，禁止判离线。休眠的唯一依据是「文件存在且确实超过3600秒」。宁可多跑一次巡检，绝不因文件缺失误休眠——用户全程在聊天却被判定离线导致师姐休眠，就是这个漏洞（15:15误休眠事故）。巡检任务query已同步此逻辑。

17.18 协作文件命名规范（2026-09-08定死，唯一版本，无变体）

历史教训：师姐交付曾用 wan_delivery_* / wan_TASK026_截图* / 交付N_* 三种风格顺手命名，导致巡检脚本两次漏检。现定死四类命名，所有协作方必须严格使用，禁止任何变体：

① 师姐交付：wan_delivery_任务号_内容简述_日期.zip（示例 wan_delivery_TASK026FIX_图标与返回按钮修复_2026-09-08.zip）——内容简述用"修复/数据/报告"等词，中间产物截图单独打 wan_delivery_任务号_截图_日期.zip。

② 草包派任务：caobao_task_任务号_内容简述_日期.zip。

③ 草包通知/决策：caobao_note_类型_日期.txt（类型=休眠/唤醒/决策/说明）。

④ 禁止：不带delivery/task/note前缀的裸命名（如"交付1"）、中文无后缀（交付3_TASK017）、时间戳缺失。

商业化方向已交底（2026-09-08）：项目已进入商业化准备阶段，026终测通过后输出《商业化就绪度清单》。

背景：出场/进球/助攻/零封为一级数据，每周必刷。2026-09-09 教训：串行抓取会卡死（48队×2页串行+超时挂起，15队后停摆），必须用并发。

12.10.1 URL（关键！一页拿全）

• most-appearances 一页同时含 M(出场)/G(进球)/A(助攻)/MIN(分钟)/START(首发)，不需要分别抓 apps/goals/assists 三页：https://www.statmuse.com/fc/ask/most-appearances-{teamSlug}-player-2026-27-season
• 门将零封走 most-save-pct 页（CS/SV/GC 同页返回），savePct=SV/(SV+GC)×100（坑4）
• 注意：most-apps 是 422 死路，出场必须用 most-appearances（most-appearances / most-games-played 均可，实测 200）

12.10.2 速度（实测）

• 并发8路：第一波 appearances 48队约11秒；第二波 save-pct 48队约48秒；48队全量约60秒
• 每周刷新直接用 t042/work/fetch_ss_fast.py（并发版），禁止串行/禁止一次只抓一页

12.10.3 解析四坑（同12.9，务必照做）

• 坑1 HTML转义：" 和 & 先反转义再解析
• 坑2 多赛事拆分：只取 MIN>0 的赛季汇总条，排除 name==='Total'
• 坑3 MIN千分位：去逗号再 parseFloat
• 坑4 门将公式：NPSH全0，用 savePct=SV/(SV+GC)×100

12.10.4 匹配写回（关键：号码桥用 26-27 名册）

• 25-26 名册号码大量过期（夏窗后新援号码对不上，2026-09-09 实测匹配率极低），必须抓 26-27 名册：URL https://www.statmuse.com/fc/ask/{teamSlug}-players-2026-27-season（同源、一页整队名单，号码→英文名）
• 链路：球员号码 → 2627名册(号码→英文名) → raw(英文名→M/G/A) → 写回；name_map 有则优先（中文→英文直配，含 cnCore 简称匹配）
• 只补空不覆盖（已有 seasonStats 不动）；node --check 全 PASS 才部署
• 合并脚本：t042/work/merge_ss_2627.py

12.10.5 源覆盖边界

• StatMuse 26-27 无数据队（422/0人）：fenerbahce/sporting_cp/coventry/hull/ipswich 等 → 走 FotMob 球队页补（手册3.5 主源：基础数据主源 FotMob）
• 没出场的替补/新援/第三门将无 26-27 数据属正常（赛季才3轮），随赛季推进自然有，不要填0/编数据