# 运球爬行 ## 概述使用真正的浏览器自动化和 playwright-core 从（具有 Cloudflare 保护的 SPA）提取俱乐部和固定装置数据。两阶段工作流程：提取（原始 API 数据）→ 转换（经过验证、合并的数据）。 **目的**：抓取 dribl.com 以维护 Williamstown SC 网站的最新俱乐部和赛程数据。 ## 架构 **数据流：** dribl API → data/external/fixtures/{team}/ (raw) → 转换 → data/matches/ (validated) dribl API→数据/外部/俱乐部/（原始）→转换→数据/俱乐部/（已验证） **两阶段模式：** 1. **提取**：Playwright拦截API请求，保存原始JSON 2. **转换**：读取原始数据，用Zod验证，转换，去重，保存 **关键技术：** * playwright-core（真正的Chrome浏览器） * Zod验证模式 * 带有 tsx 运行器的 TypeScript ## 俱乐部提取 **参考**：`bin/crawlClubs.ts` **图案：** // 启动浏览器 const 浏览器 = 等待 chromium.launch({ 无头：假，频道：“铬” }); // 自定义用户代理（绕过检测） const context = 等待 browser.newContext({ userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...', 视口：{宽度：1280，高度：720} }); // 拦截API请求 const [clubsResponse] = 等待 Promise.all([ page.waitForResponse((response) => response.url().startsWith(clubsApiUrl) && response.ok(), { 超时：60_000 }), page.goto(url, { waitUntil: 'domcontentloaded' }) ]); // 验证并保存 const rawData = 等待clubsResponse.json(); const 已验证 = externalApiResponseSchema.parse(rawData); writeFileSync(outputPath, JSON.stringify(validated, null, '\t') + '\n'); **API端点：** * URL：`https://mc-api.dribl.com/api/list/clubs?disable_paging=true` * 响应：带有俱乐部对象“data”数组的 JSON * 验证：`externalApiResponseSchema` (src/types/matches.ts) **输出：** * 路径：`data/external/clubs/clubs.json` * 格式：包含所有俱乐部的单个 JSON 文件 **CLI 参数：** * `--url ` （可选，默认为标准灯具页面） ## 赛程提取 **模式（在 bin/crawlFixtures.ts 中实现）：** **步骤：** 1. 导航至 2. 等待 SPA 加载 (`waitUntil: 'domcontentloaded'`) 3. 应用过滤器（必需）： * 季节（例如“2025”） * 竞赛（例如“FFV”） * 联赛（例如“state-league-2-men-s-north-west”） 4.拦截`/api/fixtures`响应 5. 处理分页： * 检测 DOM 中的“加载更多”按钮 * 单击按钮加载下一个块 * 等待新的API响应 * 重复直到没有更多数据 6. 将每个块保存为 `chunk-{index}.json` **API端点：** * URL：`https://mc-api.dribl.com/api/fixtures` * 查询参数：赛季、比赛、联赛（来自过滤器） * 响应：带有“data”数组、“links”（下一个/上一个）、“meta”（光标）的 JSON * 验证：`externalFixturesApiResponseSchema` **输出：** * 路径：`data/external/fixtures/{team}/chunk-0.json`、`chunk-1.json`等 * 格式：多个 JSON 文件（每个“加载更多”点击一个） * 命名：`chunk-{index}.json`，其中索引从 0 开始 **CLI 参数：** * `--team `（必需）- 输出文件夹的团队 slug（例如，“state-league-2-men-s-north-west”） * `--league `（必需）- 用于过滤的联盟 slug（例如，“State League 2 Men's - North-West”） * `--season `（可选，默认为当前年份） * `--competition ` （可选，默认为 FFV） ## 俱乐部转型 **参考**：`bin/syncClubs.ts` **图案：** // 加载外部数据 const externalResponse = loadExternalData(); // 来自数据/外部/俱乐部/ const 已验证 = externalApiResponseSchema.parse(externalResponse); // 转换为内部格式 const apiClubs = externalResponse.data.map((externalClub) =>transformExternalClub(externalClub)); // 加载现有的俱乐部常量现有文件 = loadExistingClubs(); // 来自数据/俱乐部/ // 合并（通过externalId去重） const ClubsMap = new Map<字符串, Club>(); for (现有俱乐部的 const 俱乐部) { clubsMap.set(club.externalId, 俱乐部); } for (apiClubs 的 const apiClub) { clubsMap.set(apiClub.externalId, apiClub); // 更新或添加 } // 按名称排序 const mergedClubs = Array.from(clubsMap.values()).sort((a, b) => a.name.localeCompare(b.name)); // 保存 writeFileSync(CLUBS_FILE_PATH, JSON.stringify({ Clubs: mergedClubs }, null, '\t')); **转换服务** : `src/lib/clubService.ts` * `transformExternalClub()`: 将外部俱乐部格式转换为内部格式 * 映射字段：id→externalId、attributes.name→name/displayName等 * 规范化地址（组合address_line_1 + address_line_2） * 映射社交数组（名称→平台，值→url） * 使用“clubSchema”验证输出 **输出：** * 路径：`data/clubs/clubs.json` * 格式：`{ 俱乐部: 俱乐部[] }` ## 赛程改造 **参考**：`bin/syncFixtures.ts` **图案：** // 读取所有块文件 const teamDir = path.join(EXTERNAL_DIR, team); const 文件=等待 fs.readdir(teamDir); const chunkFiles = files.filter((f) => f.match(/^chunk-\d+\.json$/)).sort(); // 自然数排序 // 加载并验证每个块 const 响应：ExternalFixturesApiResponse[] = []； for (chunkFiles 的常量文件) { const content = wait fs.readFile(path.join(teamDir, file), 'utf-8'); const 已验证 = externalFixturesApiResponseSchema.parse(JSON.parse(content)); 响应.push（已验证）； } // 变换所有灯具 const allFixtures = []; for（响应的常量响应）{ for (response.data 的 const externalFixture) { const 固定装置=transformExternalFixture(externalFixture); allFixtures.push(fixture); } } // 去重（按轮 + homeTeamId +awayTeamId） const saw = new Set<字符串>(); const 去重 = allFixtures.filter((f) => { const key = `${f.round}-${f.homeTeamId}-${f.awayTeamId}`; if (seen.has(key)) 返回 false；看到.add(key); 返回真； }); // 按轮数排序，然后按日期排序 const Sorted = deduplicated.sort((a, b) => { if (a.round !== b.round) return a.round - b.round; 返回 a.date.localeCompare(b.date); }); // 计算元数据 const TotalRounds = Math.max(...sorted.map((f) => f.round), 0); // 保存 const 夹具数据 = { 竞赛：“FFV”，季节: 2025, 总夹具：排序的长度，总回合数, 赛程：已排序 }; writeFileSync(outputPath, JSON.stringify(fixtureData, null, '\t')); **转换服务**：`src/lib/matches/fixtureTransformService.ts` * `transformExternalFixture()`: 将外部夹具格式转换为内部格式 * 解析轮数（例如，“R1”→ 1） * 格式化日期/时间/日期字符串（ISO 日期、24 小时时间、工作日名称） * 将地面名称+字段名称组合起来作为地址 * 通过匹配球队名称/徽标查找俱乐部外部 ID * 使用“fixtureSchema”验证输出 **输出：** * 路径：`data/matches/{team}.json` * 格式: `{ 比赛, 赛季, 总赛程, 总轮数, 赛程: 赛程[] }` **CLI 参数：** * `--team `（必需）- 要同步的团队 slug（例如，“state-league-2-men-s-north-west”） ## 验证模式 **参考**：`src/types/matches.ts` **外部模式（API 响应）：** * `externalApiResponseSchema`：俱乐部 API 响应 * `externalClubSchema`：单个俱乐部对象 * `externalFixturesApiResponseSchema`：Fixtures API 响应 * `externalFixtureSchema`：单个夹具对象 **内部模式（转换后的数据）：** * `clubSchema`: 单一俱乐部 * `clubsSchema`：俱乐部文件 (`{clubs: Club[] }`) * `fixtureSchema`: 单个灯具 * `fixtureDataSchema`：赛程文件（`{比赛，赛季，totalFixtures，totalRounds，赛程}`） **模式**：始终在边界处验证（API→外部模式，转换→内部模式） ## CI 集成 **参考**：`.github/workflows/crawl-clubs.yml` **Linux 设置（GitHub 操作）：** - 名称：安装 Chrome 运行： npx playwright install --with-deps chrome - 名称：爬行俱乐部运行： npm runcrawl:clubs:ci -- ${{inputs.url && format('--url "{0}"',inputs.url) || '' }} **要点：** * 在 Linux 上为无头 Chrome 使用 `xvfb-run` 前缀（例如，`xvfb-run npm runcrawl:clubs`） * 使用 `--with-deps` 标志安装以获取系统依赖项 * 设置适当的暂停（俱乐部 5 分钟，比赛可能需要更多） * 上传数据文件的工件 **Package.json 脚本模式：** { "crawl:clubs": "tsx bin/crawlClubs.ts", "crawl:clubs:ci": "xvfb-run tsx bin/crawlClubs.ts", "sync:clubs": "tsx bin/syncClubs.ts", "sync:fixtures": "tsx bin/syncFixtures.ts" } ## 最佳实践 **记录：** * 为了清晰起见，使用表情符号记录： * ✓ / ✅ - 成功 * ❌ - 错误 * 📂 - 文件操作 * 🔄 - 处理/转换 * 大型操作的日志计数和进度 **错误处理：** * 在顶层尝试/捕获 * 对 ZodError 的特殊处理（打印问题） * 失败时退出并返回代码 1 * 在finally块中关闭浏览器 **文件操作：** * 在写入之前始终使用 `mkdirSync(path, { recursive: true })` * 使用制表符格式化 JSON：`JSON.stringify(data, null, '\t')` * 在文件末尾添加换行符：`content + '\n'` * 使用 `resolve(__dirname, '../relative/path')` 的绝对路径 **数据分离：** * 将原始外部数据保存在`data/external/`中（gitignored） * 将转换后的数据保存在“data/”中（已提交） * 切勿直接提交外部 API 响应 **验证：** * 收到API数据后立即验证 * 在写入转换后的数据之前进行验证 * 使用带有文件路径的描述性错误消息 **CLI 参数：** * 使用 Commander 库进行一致的 CLI 解析 * 使用 `.option()` 或 `.requiredOption()` 定义选项 * 为可选参数提供默认值 * Commander 自动生成帮助文本并验证所需的参数 ## 常见模式 **读取块：** const 文件 =等待 fs.readdir(dir); const 块 = 文件 .filter((f) => f.match(/^chunk-\d+\.json$/)) .sort((a, b) => { const numA = parseInt(a.match(/\d+/)?.[0] || '0', 10); const numB = parseInt(b.match(/\d+/)?.[0] || '0', 10); 返回 numA - numB； }); **重复数据删除：** const saw = new Set<字符串>(); const unique = items.filter((item) => { const key =computeKey(item); if (seen.has(key)) 返回 false；看到.add(key); 返回真； }); **与现有合并：** const map = new Map<字符串, T>(); existing.forEach((item) => map.set(item.id, item)); 传入.forEach((item) => map.set(item.id, item)); // 更新或添加 const merged = Array.from(map.values()); **浏览器清理：** 让浏览器：浏览器|不明确的; 尝试{ 浏览器=等待 chromium.launch(...); // 工作 }最后{ 如果（浏览器）等待 browser.close(); }

运球爬行

包含技能