feat(scripts): 添加批量生成 YouTube Studio 内容管理器 URL 的脚本

2026-08-21 18:21:03 +08:00
commit c1b39e9466
29 changed files with 4020 additions and 0 deletions
--- a/tests/test_build_studio_urls.py
+++ b/tests/test_build_studio_urls.py
@@ -0,0 +1,400 @@
+# -*- coding: utf-8 -*-
+"""build_studio_urls.py 单元测试。
+
+覆盖纯逻辑函数（不落盘、不起子进程）：
+  ts()               日期 -> 日界线毫秒（锚点 + 整日偏移）
+  parse_period()     数据周期解析（多种写法、含首尾日）
+  normalize_columns() 输入列名别名映射
+  load_country_map() 国家映射加载
+  parse_countries()  国家列解析（中文名/ISO 码/多分隔符）
+  resolve_entity_type() 实体类型解析
+  build_url()        URL 拼接（参数完整性、编码、缺字段错误）
+
+CLI 端到端流程见 test_build_studio_urls_cli.py。
+"""
+
+import math
+
+import pandas as pd
+import pytest
+
+from conftest import COUNTRIES_JSON
+
+# 文档化锚点：2026-06-15 = 1781506800000（见 docs/adr/0001，脚本内 ANCHOR_MS）
+ANCHOR_MS = 1781506800000
+MS_PER_DAY = 86400000
+
+
+# ---------------------------------------------------------------------------
+# ts：日界线毫秒
+# ---------------------------------------------------------------------------
+class TestTs:
+    def test_anchor_date(self, url_builder):
+        assert url_builder.ts(2026, 6, 15) == ANCHOR_MS
+
+    def test_next_day(self, url_builder):
+        assert url_builder.ts(2026, 6, 16) == ANCHOR_MS + MS_PER_DAY
+
+    def test_prev_day(self, url_builder):
+        assert url_builder.ts(2026, 6, 14) == ANCHOR_MS - MS_PER_DAY
+
+    def test_month_boundary(self, url_builder):
+        assert url_builder.ts(2026, 7, 1) == url_builder.ts(2026, 6, 30) + MS_PER_DAY
+
+    def test_year_boundary(self, url_builder):
+        assert url_builder.ts(2027, 1, 1) == url_builder.ts(2026, 12, 31) + MS_PER_DAY
+
+    def test_anchor_matches_module_constant(self, url_builder):
+        assert url_builder.ts(2026, 6, 15) == url_builder.ANCHOR_MS
+
+
+# ---------------------------------------------------------------------------
+# parse_period：数据周期
+# ---------------------------------------------------------------------------
+class TestParsePeriod:
+    def test_standard_dot_format(self, url_builder):
+        start, end = url_builder.parse_period("2026.07.01-2026.08.01")
+        assert start == url_builder.ts(2026, 7, 1)
+        assert end == url_builder.ts(2026, 8, 1) + MS_PER_DAY  # 结束日包含
+
+    def test_single_digit_month_day(self, url_builder):
+        assert url_builder.parse_period("2026.7.1-2026.8.1") == \
+            url_builder.parse_period("2026.07.01-2026.08.01")
+
+    def test_dash_date_with_tilde(self, url_builder):
+        start, end = url_builder.parse_period("2026-07-01~2026-08-01")
+        assert start == url_builder.ts(2026, 7, 1)
+        assert end == url_builder.ts(2026, 8, 1) + MS_PER_DAY
+
+    def test_full_width_tilde(self, url_builder):
+        start, _ = url_builder.parse_period("2026.07.01～2026.08.01")
+        assert start == url_builder.ts(2026, 7, 1)
+
+    def test_spaces_around_separator(self, url_builder):
+        start, _ = url_builder.parse_period("2026.07.01 - 2026.08.01")
+        assert start == url_builder.ts(2026, 7, 1)
+
+    def test_same_day_period(self, url_builder):
+        start, end = url_builder.parse_period("2026.07.01-2026.07.01")
+        assert start == url_builder.ts(2026, 7, 1)
+        assert end == start + MS_PER_DAY  # 单日区间跨度正好一天
+
+    def test_end_date_inclusive(self, url_builder):
+        """结束日包含在范围内：time_period 结束值 = 结束日次日日界线。"""
+        _, end = url_builder.parse_period("2026.07.01-2026.07.31")
+        assert end == url_builder.ts(2026, 8, 1)
+
+    @pytest.mark.parametrize("bad", [
+        "",                     # 空
+        "2026.07.01",           # 只有起始日
+        "20260701-20260801",    # 无分隔符
+        "abc-def",              # 非日期
+        "2026.07-2026.08",      # 缺日
+        "2026.07.01 至 2026.08.01",  # 不支持的连接词
+    ])
+    def test_invalid_format_raises(self, url_builder, bad):
+        with pytest.raises(ValueError):
+            url_builder.parse_period(bad)
+
+    def test_invalid_month_raises(self, url_builder):
+        with pytest.raises(ValueError):
+            url_builder.parse_period("2026.13.01-2026.08.01")
+
+
+# ---------------------------------------------------------------------------
+# normalize_columns：列名别名映射
+# ---------------------------------------------------------------------------
+class TestNormalizeColumns:
+    def test_chinese_aliases(self, url_builder):
+        df = pd.DataFrame(columns=["所有者名称", "所有者ID", "群组名称", "群组ID",
+                                   "实体类型", "数据周期", "国家"])
+        mapping, unknown = url_builder.normalize_columns(df)
+        assert mapping == {
+            "owner_name": "所有者名称", "owner_id": "所有者ID",
+            "entity_name": "群组名称", "entity_id": "群组ID",
+            "entity_type": "实体类型", "period": "数据周期", "countries": "国家",
+        }
+        assert unknown == []
+
+    def test_english_aliases(self, url_builder):
+        df = pd.DataFrame(columns=["owner_name", "owner_id", "group_name", "group_id",
+                                   "entity_type", "period", "country"])
+        mapping, unknown = url_builder.normalize_columns(df)
+        assert mapping == {
+            "owner_name": "owner_name", "owner_id": "owner_id",
+            "entity_name": "group_name", "entity_id": "group_id",
+            "entity_type": "entity_type", "period": "period", "countries": "country",
+        }
+        assert unknown == []
+
+    def test_short_aliases(self, url_builder):
+        """所有者ID 的超短别名 o、实体ID 的别名 id。"""
+        df = pd.DataFrame(columns=["o", "id", "period"])
+        mapping, _ = url_builder.normalize_columns(df)
+        assert mapping["owner_id"] == "o"
+        assert mapping["entity_id"] == "id"
+
+    def test_column_name_normalized_before_lookup(self, url_builder):
+        """列名先去空白、转小写再匹配：' Owner_ID ' 可识别。"""
+        df = pd.DataFrame(columns=[" Owner_ID ", "Period"])
+        mapping, _ = url_builder.normalize_columns(df)
+        assert mapping["owner_id"] == " Owner_ID "
+        assert mapping["period"] == "Period"
+
+    def test_unknown_columns_reported(self, url_builder):
+        df = pd.DataFrame(columns=["所有者ID", "数据周期", "备注", "extra"])
+        mapping, unknown = url_builder.normalize_columns(df)
+        assert "owner_id" in mapping and "period" in mapping
+        assert unknown == ["备注", "extra"]
+
+    def test_country_slash_alias(self, url_builder):
+        df = pd.DataFrame(columns=["国家/地区"])
+        mapping, _ = url_builder.normalize_columns(df)
+        assert mapping["countries"] == "国家/地区"
+
+
+# ---------------------------------------------------------------------------
+# load_country_map：国家映射
+# ---------------------------------------------------------------------------
+class TestLoadCountryMap:
+    def test_missing_file_returns_empty_and_warns(self, url_builder, tmp_path, capsys):
+        path = tmp_path / "not_exists.json"
+        assert url_builder.load_country_map(str(path)) == {}
+        assert "未找到国家映射文件" in capsys.readouterr().err
+
+    def test_bom_file_loads(self, url_builder, tmp_path):
+        """utf-8-sig（Excel 另存带 BOM）可正常加载。"""
+        p = tmp_path / "c.json"
+        p.write_bytes('{"美国": "us"}'.encode("utf-8-sig"))
+        assert url_builder.load_country_map(str(p)) == {"美国": "US"}
+
+    def test_values_trimmed_and_uppercased(self, url_builder, tmp_path):
+        p = tmp_path / "c.json"
+        p.write_text('{ "美国" : " us " , "日本" : "jp" }', encoding="utf-8")
+        assert url_builder.load_country_map(str(p)) == {"美国": "US", "日本": "JP"}
+
+    def test_real_countries_json(self, real_countries):
+        assert real_countries["美国"] == "US"
+        assert real_countries["日本"] == "JP"
+        assert real_countries["中国台湾"] == "TW"
+        assert real_countries["香港"] == "HK"
+        # 真实映射规模足够覆盖常用地区
+        assert len(real_countries) > 80
+
+
+# ---------------------------------------------------------------------------
+# parse_countries：国家列解析
+# ---------------------------------------------------------------------------
+class TestParseCountries:
+    def test_none_returns_empty(self, url_builder):
+        assert url_builder.parse_countries(None, {}) == []
+
+    def test_nan_returns_empty(self, url_builder):
+        assert url_builder.parse_countries(float("nan"), {}) == []
+
+    def test_empty_string_returns_empty(self, url_builder):
+        assert url_builder.parse_countries("", {}) == []
+
+    def test_single_iso_code(self, url_builder):
+        assert url_builder.parse_countries("US", {}) == ["US"]
+
+    def test_lowercase_iso_uppercased(self, url_builder):
+        assert url_builder.parse_countries("us", {}) == ["US"]
+
+    def test_chinese_name_mapped(self, url_builder):
+        assert url_builder.parse_countries("美国", {"美国": "US"}) == ["US"]
+
+    @pytest.mark.parametrize("sep", [",", "，", "、", ";", "；", " ", "|"])
+    def test_multiple_separators(self, url_builder, sep):
+        text = sep.join(["美国", "日本"])
+        assert url_builder.parse_countries(text, {"美国": "US", "日本": "JP"}) == ["US", "JP"]
+
+    def test_mixed_code_and_chinese(self, url_builder):
+        assert url_builder.parse_countries("US,日本", {"日本": "JP"}) == ["US", "JP"]
+
+    def test_quotes_stripped(self, url_builder):
+        assert url_builder.parse_countries("'US' \"JP\"", {}) == ["US", "JP"]
+
+    def test_unknown_name_raises(self, url_builder):
+        with pytest.raises(ValueError, match="未识别的国家"):
+            url_builder.parse_countries("亚特兰蒂斯", {"美国": "US"})
+
+    def test_chinese_name_without_map_raises(self, url_builder):
+        with pytest.raises(ValueError, match="未识别的国家"):
+            url_builder.parse_countries("美国", {})
+
+    def test_real_map_common_countries(self, url_builder, real_countries):
+        assert url_builder.parse_countries("美国,日本,英国", real_countries) == ["US", "JP", "GB"]
+        assert url_builder.parse_countries("中国台湾、香港", real_countries) == ["TW", "HK"]
+
+
+# ---------------------------------------------------------------------------
+# resolve_entity_type：实体类型
+# ---------------------------------------------------------------------------
+class TestResolveEntityType:
+    @pytest.mark.parametrize("text,expected", [
+        ("群组", "GROUP"), ("GROUP", "GROUP"),
+        ("所有者", "CONTENT_OWNER"), ("账号", "CONTENT_OWNER"), ("CONTENT_OWNER", "CONTENT_OWNER"),
+        ("频道", "CHANNEL"), ("CHANNEL", "CHANNEL"),
+        ("节目", "VIDEO"), ("视频", "VIDEO"), ("VIDEO", "VIDEO"),
+    ])
+    def test_known_types(self, url_builder, text, expected):
+        assert url_builder.resolve_entity_type(text) == expected
+
+    @pytest.mark.parametrize("empty", ["", None, float("nan")])
+    def test_empty_defaults_to_group(self, url_builder, empty):
+        assert url_builder.resolve_entity_type(empty) == "GROUP"
+
+    def test_whitespace_only_defaults_to_group(self, url_builder):
+        assert url_builder.resolve_entity_type("   ") == "GROUP"
+
+    def test_unknown_raises(self, url_builder):
+        with pytest.raises(ValueError, match="未识别的实体类型"):
+            url_builder.resolve_entity_type("星球")
+
+
+# ---------------------------------------------------------------------------
+# build_url：URL 拼接
+# ---------------------------------------------------------------------------
+def make_row(**overrides):
+    row = {
+        "owner_name": "示例所有者",
+        "owner_id": "MC123",
+        "entity_name": "示例群组",
+        "entity_id": "NCy9C2QPQ1E",
+        "entity_type": "",
+        "period": "2026.07.01-2026.08.01",
+        "countries": "",
+    }
+    row.update(overrides)
+    return row
+
+
+class TestBuildUrl:
+    def test_full_url_exact(self, url_builder):
+        """完整 URL 精确匹配（含参数顺序与编码）。"""
+        row = make_row(countries="美国,日本")
+        url, status, msg = url_builder.build_url(row, {"美国": "US", "日本": "JP"})
+        assert (status, msg) == ("ok", "")
+
+        c = url_builder.CONFIG
+        start = url_builder.ts(2026, 7, 1)
+        end = url_builder.ts(2026, 8, 1) + MS_PER_DAY
+        expected = (
+            "https://studio.youtube.com/owner/MC123/analytics/tab-overview/period-default/explore"
+            f"?o=MC123&entity_type=GROUP&entity_id=NCy9C2QPQ1E"
+            f"&ur_dimensions=COUNTRY&ur_values=%27US%27%7C%27JP%27"
+            f"&ur_inclusive_starts=&ur_exclusive_ends="
+            f"&time_period={start}%2C{end}"
+            f"&explore_type={c['explore_type']}&metric={c['metric']}&granularity={c['granularity']}"
+            + "".join(f"&t_metrics={m}" for m in c["t_metrics"])
+            + f"&dimension={c['dimension']}&o_column={c['o_column']}"
+              f"&o_direction={c['o_direction']}&comparison_type={c['comparison_type']}"
+        )
+        assert url == expected
+
+    def test_url_parts(self, url_builder):
+        url, status, _ = url_builder.build_url(make_row(countries="US"), {})
+        assert status == "ok"
+        assert url.startswith(
+            "https://studio.youtube.com/owner/MC123/analytics/tab-overview/period-default/explore?")
+        assert "o=MC123" in url
+        assert "entity_type=GROUP" in url          # 空实体类型默认 GROUP
+        assert "entity_id=NCy9C2QPQ1E" in url
+        assert "ur_dimensions=COUNTRY" in url
+        assert "ur_values=%27US%27" in url          # 单国同样用 %27 包裹
+        assert "granularity=DAY" in url
+        assert "dimension=USER" in url
+        assert "o_direction=ANALYTICS_ORDER_DIRECTION_DESC" in url
+
+    def test_time_period_values(self, url_builder):
+        url, _, _ = url_builder.build_url(make_row(), {})
+        start = url_builder.ts(2026, 7, 1)
+        end = url_builder.ts(2026, 8, 1) + MS_PER_DAY
+        assert "time_period=%d%%2C%d" % (start, end) in url  # 逗号编码为 %2C
+
+    def test_t_metrics_repeat_per_config(self, url_builder):
+        url, _, _ = url_builder.build_url(make_row(), {})
+        assert url.count("t_metrics=") == len(url_builder.CONFIG["t_metrics"])
+        for m in url_builder.CONFIG["t_metrics"]:
+            assert "t_metrics=%s" % m in url
+
+    def test_no_country_omits_country_params(self, url_builder):
+        url, _, _ = url_builder.build_url(make_row(), {})
+        assert "ur_dimensions" not in url
+        assert "ur_values" not in url
+        assert "ur_inclusive_starts" not in url
+
+    def test_entity_type_channel(self, url_builder):
+        url, _, _ = url_builder.build_url(
+            make_row(entity_type="频道", entity_id="UCxyz"), {})
+        assert "entity_type=CHANNEL" in url
+        assert "entity_id=UCxyz" in url
+
+    def test_content_owner_falls_back_to_owner_id(self, url_builder):
+        """所有者整体场景：实体ID留空时回退用所有者ID。"""
+        row = make_row(entity_type="CONTENT_OWNER", entity_id="")
+        url, status, msg = url_builder.build_url(row, {})
+        assert (status, msg) == ("ok", "")
+        assert "entity_type=CONTENT_OWNER" in url
+        assert "entity_id=MC123" in url
+
+    def test_missing_owner_id(self, url_builder):
+        url, status, msg = url_builder.build_url(make_row(owner_id=""), {})
+        assert url is None
+        assert status == "error"
+        assert msg == "缺少所有者ID"
+
+    def test_missing_entity_id_for_group(self, url_builder):
+        url, status, msg = url_builder.build_url(make_row(entity_id=""), {})
+        assert url is None
+        assert status == "error"
+        assert msg == "缺少实体ID"
+
+    def test_missing_entity_id_for_channel(self, url_builder):
+        url, status, msg = url_builder.build_url(
+            make_row(entity_type="频道", entity_id=""), {})
+        assert url is None
+        assert status == "error"
+        assert msg == "缺少实体ID"
+
+    def test_missing_period(self, url_builder):
+        url, status, msg = url_builder.build_url(make_row(period=""), {})
+        assert url is None
+        assert status == "error"
+        assert msg == "缺少数据周期"
+
+    def test_bad_period_raises_value_error(self, url_builder):
+        with pytest.raises(ValueError):
+            url_builder.build_url(make_row(period="not-a-period"), {})
+
+    def test_unknown_country_raises_value_error(self, url_builder):
+        with pytest.raises(ValueError, match="未识别的国家"):
+            url_builder.build_url(make_row(countries="火星"), {"美国": "US"})
+
+    def test_unknown_entity_type_raises_value_error(self, url_builder):
+        with pytest.raises(ValueError, match="未识别的实体类型"):
+            url_builder.build_url(make_row(entity_type="星球"), {})
+
+    def test_owner_id_checked_before_entity(self, url_builder):
+        """所有者ID 缺失时报错优先于实体ID。"""
+        _, status, msg = url_builder.build_url(make_row(owner_id="", entity_id=""), {})
+        assert (status, msg) == ("error", "缺少所有者ID")
+
+
+# ---------------------------------------------------------------------------
+# 其他：nan 判断辅助行为（build_url 入参可能来自 pandas）
+# ---------------------------------------------------------------------------
+class TestNanHandling:
+    def test_period_nan_string_is_error(self, url_builder):
+        """main() 会把 NaN 转 ''，这里验证空串路径报「缺少数据周期」。"""
+        _, status, msg = url_builder.build_url(make_row(period=""), {})
+        assert msg == "缺少数据周期"
+
+    def test_parse_countries_nan(self, url_builder):
+        assert url_builder.parse_countries(float("nan"), {}) == []
+
+    def test_plain_float_treated_as_text(self, url_builder):
+        """普通 float（如 3.14）不是 NaN：走字符串解析分支，非两位代码则报未识别。"""
+        with pytest.raises(ValueError, match="未识别的国家"):
+            url_builder.parse_countries(3.14, {})