feat(scripts): 支持动态指标和维度参数配置

为 build_studio_urls.py 添加指标和维度的可配置支持,包括:
- 新增 metrics.json 和 dimensions.json 映射文件加载
- 支持中文/英文别名映射及指标代码透传
- 列别名扩展以识别"指标"和"维度"列
- 空值时自动回退到 CONFIG 默认值
This commit is contained in:
2026-08-24 15:28:48 +08:00
parent ba00651fa9
commit b8bd749f43
16 changed files with 996 additions and 36 deletions

View File

@@ -22,6 +22,8 @@ description: "根据需求清单CSV/Excel批量生成 YouTube Studio 内
- **数据周期Period**`yyyy.mm.dd-yyyy.mm.dd``yyyy.m.d-yyyy.m.d` 的日期区间,起始日与结束日均包含。
- **日界线Day Boundary**:周期中日期对应的 Unix 毫秒,采用「锚点 2026-06-15 = 1781506800000 + 整日偏移」计算,不做时区换算。
- **国家筛选Country Filter**`ur_dimensions=COUNTRY` + `ur_values`;多国以 `'``%27`)包裹、`|``%7C`)连接;国家用 ISO 3166-1 alpha-2 代码。
- **指标Metric**报表主指标URL 中的 `metric` 参数;每行可选(`指标` 列),中文名/英文名写在同目录 `metrics.json` 里映射到内部代码,留空走 `CONFIG` 默认。选中后排序字段 `o_column` 一并跟随。
- **维度Dimension**报表细分维度URL 中的 `dimension` 参数;每行可选(`维度` 列),中文名写在同目录 `dimensions.json` 里映射到内部代码,留空走 `CONFIG` 默认。
## 工作流
@@ -44,6 +46,8 @@ description: "根据需求清单CSV/Excel批量生成 YouTube Studio 内
| 实体ID | 视类型 | 群组/频道/节目必填所有者场景可留空回退用所有者ID |
| 数据周期 | 是 | 见领域词汇「数据周期」 |
| 国家 | 可空 | 一个或多个,中文名或两位 ISO 代码 |
| 指标 | 可默认 | 主指标(`metric` 参数);中文名/英文名或已知指标代码;留空走 CONFIG 默认 |
| 维度 | 可默认 | 细分维度(`dimension` 参数);中文名或已知维度代码;留空走 CONFIG 默认 |
完成标准:对每一条需求,上表要素已确定,或明确「留空走默认」。
@@ -68,17 +72,22 @@ uv run python scripts\build_studio_urls.py -i <输入文件> [-o <输出csv>]
### 5. 校验输出并处理失败行
- 检查输出列所有者名称、所有者ID、实体类型、实体名称、实体ID、数据周期、国家、国家代码、开始时间戳、结束时间戳、URL。
- 抽查 URL 是否包含正确的 `entity_type` / `entity_id` / `time_period` / `ur_values`(国家筛选)。
- 检查输出列所有者名称、所有者ID、实体类型、实体名称、实体ID、数据周期、国家、国家代码、指标、指标代码、维度、维度代码、开始时间戳、结束时间戳、URL。
- 抽查 URL 是否包含正确的 `entity_type` / `entity_id` / `time_period` / `ur_values`(国家筛选)`metric`(指标)、`dimension`(维度)
- 有失败行时脚本以退出码 2 结束,并在 stderr 逐行打印「第N行 …:原因」;逐条按 [references/troubleshooting.md](references/troubleshooting.md) 修复后重跑。
完成标准:所有需求行均生成 URL或失败行已定位原因并修复。
## 固定参数CONFIG
metric / granularity / dimension / t_metrics / o_column / o_direction / explore_type / comparison_type 等固定参数集中在脚本顶部 `CONFIG` 一处维护。**修改固定参数只需改 `CONFIG`(单点维护)**,不要逐行携带到需求清单中。
granularity / dimension / t_metrics / o_direction / explore_type / comparison_type 等固定参数集中在脚本顶部 `CONFIG` 一处维护。**修改这些固定参数只需改 `CONFIG`(单点维护)**,不要逐行携带到需求清单中。
`metric`(主指标)**可按行选择**:在需求清单加一列 `指标`(别名 `主指标` / `数据指标` / `metric`),填中文名/英文名(`metrics.json` 映射)或已知指标代码均可;留空则回退 `CONFIG["metric"]`,选中时 `o_column`(排序字段)一并跟随。
`dimension`(细分维度)**同样可按行选择**:在需求清单加一列 `维度`(别名 `细分维度` / `dimension`),填中文名(`dimensions.json` 映射)或已知维度代码均可;留空则回退 `CONFIG["dimension"]`
## 参考
- [需求输入制作指南](references/input-guide.md):列名别名、日期/国家/实体类型写法、完整示例、制作核对清单。
- [常见问题排查](references/troubleshooting.md):按 现象 → 原因 → 解决 逐条排查。
- [映射文件维护指南](references/maintenance-guide.md)`countries.json` / `metrics.json` / `dimensions.json` 三个映射文件的来源、结构与新增/更新条目方法。