Sidney Zhang
b8bd749f43
为 build_studio_urls.py 添加指标和维度的可配置支持，包括： - 新增 metrics.json 和 dimensions.json 映射文件加载 - 支持中文/英文别名映射及指标代码透传 - 列别名扩展以识别"指标"和"维度"列 - 空值时自动回退到 CONFIG 默认值
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
# 常见问题排查
|
||
|
||
脚本的错误分三类，先分清类型再定位：
|
||
|
||
- **提示（stderr，不中断）**：未识别的列、未找到国家映射文件等，仅警告。
|
||
- **致命错误（退出码 1）**：输入文件不存在、格式不支持、缺必要列。
|
||
- **失败行（退出码 2）**：个别需求行生成失败，成功行仍会写出；stderr 逐行打印「第N行 …：原因」。
|
||
|
||
## 输入相关
|
||
|
||
### 输入文件不存在
|
||
- 原因：`-i` 路径错误，或文件名大小写/中文名不符。
|
||
- 解决：确认路径存在；PowerShell 中路径含空格时用引号包裹。
|
||
|
||
### 不支持的输入格式
|
||
- 原因：扩展名不是 `.csv` / `.xlsx` / `.xls`。
|
||
- 解决：另存为支持格式后再跑。
|
||
|
||
### 输入缺少必要列
|
||
- 原因：清单中没有「所有者ID」或「数据周期」（或其别名）。
|
||
- 解决：补齐列；列名支持别名，见 input-guide.md 第 2 节。
|
||
|
||
### 未识别的列（提示）
|
||
- 原因：列名不在别名表。
|
||
- 解决：不影响生成；如需在输出中回显，改用别名表中列名。
|
||
|
||
## 行级失败（第 N 行）
|
||
|
||
### 缺少所有者ID
|
||
- 原因：该行 `owner_id` 为空。
|
||
- 解决：补充所有者ID。
|
||
|
||
### 缺少实体ID
|
||
- 原因：实体类型不是所有者（如群组/频道/节目）且 `entity_id` 为空。
|
||
- 解决：补充实体ID；若确为所有者整体场景，把实体类型改为「所有者/账号」并留空实体ID。
|
||
|
||
### 无法解析数据周期
|
||
- 原因：日期不符合 `yyyy.m.d-yyyy.m.d`（或 `~`/`～` 分隔）的写法。
|
||
- 解决：按 input-guide.md 第 3 节修正。
|
||
|
||
### 未识别的国家
|
||
- 原因：中文国家名不在 `countries.json`，也不是两位 ISO 代码。
|
||
- 解决：改用两位 ISO 代码，或向 `countries.json` 追加映射。
|
||
|
||
### 未识别的实体类型
|
||
- 原因：`entity_type` 不在映射表。
|
||
- 解决：使用 群组/所有者/频道/节目 或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO。
|
||
|
||
### 未识别的指标
|
||
- 原因：`指标` 列的值不在 `metrics.json` 映射里，也不是已知指标代码。
|
||
- 解决：改用 `metrics.json` 中的中文/英文名或已知指标代码（如 `SUBSCRIBERS_NET_CHANGE`），或向 `scripts/metrics.json` 追加映射；留空该列则走 `CONFIG` 默认。
|
||
|
||
### 未识别的维度
|
||
- 原因：`维度` 列的值不在 `dimensions.json` 映射里，也不是已知维度代码。
|
||
- 解决：改用 `dimensions.json` 中的中文名或已知维度代码（如 `VIDEO`），或向 `scripts/dimensions.json` 追加映射；留空该列则走 `CONFIG` 默认。
|
||
|
||
## 输出问题
|
||
|
||
### 输出行数 < 输入行数
|
||
- 原因：存在失败行（退出码 2）。
|
||
- 解决：查看 stderr 失败列表，逐条修复后重跑。
|
||
|
||
### 输出为空 / Excel 打开乱码
|
||
- 原因：成功记录为 0；或查看方式不对。
|
||
- 解决：确认输入有合法行；脚本以 UTF-8-SIG 写出，Excel 可直接打开正常显示。
|
||
|
||
### 找不到输出文件
|
||
- 原因：未指定 `-o`，默认输出在**输入文件同目录** `studio_urls_output.csv`。
|
||
- 解决：显式用 `-o` 指定输出路径。
|
||
|
||
## 编码相关
|
||
|
||
- CSV 输入乱码/解析异常：脚本先按 UTF-8-SIG 读，失败回退 GBK；仍异常时，把文件另存为 UTF-8 或 GBK 后重试。
|
||
- `countries.json` 建议 UTF-8；脚本按 UTF-8-SIG 读取，带 BOM 无影响。
|
||
|
||
## 改了固定参数不生效
|
||
|
||
- 原因：粒度、维度、`t_metrics` 等固定参数集中在脚本顶部 `CONFIG`，改后需重跑脚本才会生效。
|
||
- 提示：改 `CONFIG` 只影响 URL 参数，不需要改需求清单；若想按行选主指标，改用需求清单的 `指标` 列（无需改 `CONFIG`）。
|