# 铁律避坑规则（功能三：提炼账号设定）

> 本文件记录账号设定提炼（功能三）执行过程中踩过的坑和沉淀的解决方案，防止重复犯错。
> 与「账号数据分析执行避坑.md」（功能四）互为镜像，结构一致。

## 一、工具/工艺类

| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
|---|---------|------|---------|---------|
| 1 | PowerShell `ConvertTo-Json` 序列化大文本（人设卡全文约 1.5 万字符）后 `Invoke-RestMethod` POST 接口超时（120s 卡死，后台任务被终止） | PowerShell `ConvertTo-Json` 对大字符串序列化性能差，请求发送阶段卡住；最小 payload（几十字节）46ms 即成功，证明是**请求体大小**问题而非接口问题 | 接口调用改用 **Python 直连构造 JSON**（`urllib.request` + `json.dumps(ensure_ascii=False)`），绕开 PowerShell ConvertTo-Json；大文本一律走 Python，不用 PowerShell 序列化 | 已沉淀为本规则 |
| 2 | 写库后无法确认是否写入成功（后台任务消失、无输出） | 后台 job 被终止后状态丢失，接口又无查询列表端点 | 用**幂等重试**验证：同 payload 重复提交，返回 `analyses:0` 即证明已去重入库（脚本层自动去重）；POST 接口本身是最可靠的验证手段 | 已沉淀为本规则 |
| 3 | 人设卡写入数据库时误用测试 payload 探测接口，留下脏数据 | 先用最小 payload 测连通性，意外写入 1 条测试记录 | 探测接口连通性用 `GET`（如 `/mcn/api/account/videos?accountId=X`），**不用写接口探测**；若已写入测试数据，同账号+type 重复提交正式内容会覆盖（脚本层按 账号+类型 去重） | 已沉淀为本规则 |

## 二、数据质量类

| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
|---|---------|------|---------|---------|
| 4 | 平台返回的 analysis 为 6 字段简化格式（缺赛道/人设/框架/事件等核心维度） | 部分视频平台侧解析版本较旧，仅返回简化分析 | 以平台实际返回为准照实保存，在人设卡「设定分析说明」中标注该条深度弱于其他条；不得凭印象补造缺失维度；后续可用功能五单独重解析替换 | 已沉淀为设定分析说明规则 |
| 5 | 既有解析产物 detailId 与 aweme_id 不一致（如 26164 vs 7667477088350044069） | detailId 是业务解析 ID，aweme_id 是抖音视频 ID，两者本就不同 | 校验产物归属时用**标题匹配**而非 ID 匹配；detailId 不用于对照视频来源 | 已沉淀为校验规则 |

## 三、流程/规范类

| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
|---|---------|------|---------|---------|
| 6 | 本地接口（`/mcn/api/...`）调用规范未沉淀，每次现查 | 无统一接口调用规范文件 | 新建 `references/接口调用/本地接口调用规范.md`，记录接口基地址判定（`$env:DSH_WEB_URL` → 3080/3081 兜底）、接口清单、请求构造方式（Python 直连优先） | 已沉淀为本规则 |
| 7 | 生成人设卡前未先判定账号类型就套模板 | 账号类型判定是模板选择前置 | 严格执行 5.0 判定：从筛选出的 TOP 视频 analysis「人设」字段提取主角名称 → 全部不同=群像型 / 同一主角=固定主角+轮换搭档 / 全固定=单一达人型 | 已沉淀为人设卡生成方法 5.0 |
| 8 | 生成设定卡时机械套赛道标签配色，把「明快欢乐型亲子（俊希）」误配成「深焦糖深色系」 | 「温情/亲子/治愈」赛道标签**双义**（深沉催泪型 vs 明快欢乐型），未做调性二次判定就套下表默认深色 | 色系二选以账号实际内容调性（情绪锚点：明快/欢乐/爽文/暖心 → 浅色系；深沉/催泪/怀旧/悲情 → 深色系）为最终判据，赛道标签只作初筛；赛道含「治愈/亲子/温情」等暧昧词时**必须回读情绪锚点判定明快 vs 深沉** | 已沉淀为 06_生成账号设定卡片.md「调性优先于赛道标签」规则 |

---

## 快速参考：本地接口调用（功能三写库用）

> 接口基地址判定、接口清单、请求构造铁律，见 `references/接口调用/本地接口调用规范.md`。