运营投放数据看板（ops-data-dashboard）

把一份「账户级投放明细」Excel，转换成运营组长日常用的多 Tab 数据追踪看板，并部署到固定链接。看板内嵌全部数据，无需后端；支持历史快照回看与跟进标注。

1. 适用场景

每个工作日拿到新的投放明细 Excel，刷新看板到固定链接。
需要从历史日期回看当时完整的看板数据（停投/掉量/新增等）。
组长对账户做跟进，打勾 / 写备注，且标注要按日期隔离、不被后续更新覆盖。
其他小组复用：换数据源表头、换运营名单、换主色调、换业务口径阈值。

2. 首次使用（必做）

当 scripts/config.json 不存在（或 group_name 为空）时，先用 AskUserQuestion 向使用者询问两项，不要直接跑脚本：

组的名字（用于看板标题，例如「腰客孵化组」「华东投放一组」）。
面板主色调（hex 色值，例如 #3182ce；可给几个预设色板让用户选）。

拿到后，在 scripts/ 下写入 config.json，至少包含：

{
  "file_path": "<数据源 Excel 绝对路径>",
  "group_name": "<组的名字>",
  "theme": "<主色调 hex>",
  "operators": [],
  "name_map": {}
}

operators 留空 [] 时，脚本会自动从「所属人员」列识别运营名单；也可显式列出。
name_map 用于把数据源里的别名归并到标准名，例如 {"刘勇": "柴峰"}（同一人两姓名交替出现）。
其余阈值（腰客范围、目标 ARPU、低效/流失阈值等）见第 5 节，按需覆盖。

若 config.json 已存在，跳过询问，直接按既有配置工作；如需改组名/主色调，编辑该文件即可。

3. 日常更新流程

每次新数据到达，按以下顺序执行（缺一步都可能出错）：

改 config.json 的 file_path（指向新 Excel），必要时改 data_date / current_day（不填则按文件名或当天自动推断）。跨月时同步改 last_month_days（上月实际天数，如 7 月=31、2 月=28）。
运行脚本：
```
<venv-python> scripts/generate_dashboard.py
```
（使用隔离 Python 环境，已安装 pandas / openpyxl。若依赖缺失，先 pip install pandas openpyxl。）
JS 语法校验（关键，避免页面空白）：抽取 HTML 内联 <script> 用 node --check 验证通过后再部署。
部署：将生成的 dashboard.html 复制到 dist/ 并部署到 CloudStudio 固定链接（用 workbuddy_cloudstudio_deploy，directory 指 dist/，entry=index.html）。
缓存穿透核实：用 curl -H "Cache-Control: no-cache" 带随机 ?cb= 参数访问线上链接，确认 data_date 已是新日期（CDN 偶尔回源旧版，首次部署 verified:false 时重试一次）。

部署前务必 node --check：曾因编辑误删一行导致整个看板空白，校验可拦截此类事故。

4. 数据源与表头约定

脚本按列名匹配，不依赖列顺序，对下列「规范列名」提供别名兼容（数据源列名写成别名也能识别）：

| 规范列名 | 常见别名示例 | |---|---| | 子账号名称 | 子帐号名称、子账户名称、账户名称、账号名称 | | 子账号ID | 账号ID、子账号编号、account_id | | 客户主体名称 | 主体名称、投放主体、客户名称 | | 所属人员 | 归属运营、所属运营、运营、负责人、优化师 | | 上月消耗 | 上月花费、上个月消耗 | | 本月消耗 | 本月花费、当月消耗 | | 昨日消耗 | 昨天消耗、昨日花费 | | 前日消耗 | 前天消耗 | | 首消日期 | 首次投放日期、首投日期、开通日期 | | 专业号一级行业 | 一级行业、行业 | | 昨日账户预算 | 昨日预算、账户预算 | | 昨日账户预算使用率 | 预算使用率 | | 连续停投天数 | 停投天数、连续未投天数 | | 本周消耗 / 上周消耗 | 本周花费 / 上周花费（可选） |

数据 Sheet 自动识别：扫描各 Sheet 列命中率，优先名称含「指标明细/明细/账户/投放/数据」的表。
Sheet2（可选）：第二个 Sheet 视为「必须考核主体名单」，自动识别其中的主体/客户名列。
缺失的可选列（本周/上周消耗、连续停投天数等）自动补 0/空，不中断生成。

5. 配置项（config.json 全字段，均有合理默认值）

| 字段 | 说明 | 默认 | |---|---|---| | file_path | 数据源 Excel 路径 | E:/桌面/运营投放数据.xlsx | | data_date | 数据日期 YYYY-MM-DD；留空自动推断 | 空 | | current_day | 本月第几天；0=从 data_date 推断 | 0 | | last_month_days | 上月天数（跨月切换） | 31 | | this_month_days | 本月天数 | 31 | | group_name | 组名（看板标题） | 运营投放 | | theme / theme_dark | 主色调 / 深色（留空自动加深） | #3182ce | | yaok_label | 中段客户追踪标签 | 腰客 | | operators | 运营名单；空=自动识别 | [] | | name_map | 别名→标准名映射 | {} | | yaok_min / yaok_max | 中段客户（腰客）上月主体消耗区间 | 3000 / 6000 | | yaok_target_arpu | 中段客户目标月 ARPU | 4500 | | inefficient_threshold | 低效户阈值（昨日消耗<该值且>0） | 100 | | churn_days | 流失判定：连续停投>该天数 | 7 | | detail_keywords | 明细 Sheet 识别关键词 | 见脚本 | | must_assess_sheet_index | 考核名单 Sheet 位置 | 1 | | max_history_embed / max_history_disk | 看板内嵌/本地归档天数 | 30 / 365 |

6. 看板 8 个 Tab 口径

完整定义、字段与排序规则见 references/requirements.md。要点：

运营消耗汇总：每运营本月消耗、月活（本月有消耗账户数）、账均月 ARPU、日 ARPU、日均；以及昨日维度（消耗、在投户、ARPU、增减、预算使用率、无效户、流失）。
腰客/中段客户追踪（主体维度）：上月主体消耗落在 yaok_min~yaok_max 为主体；纳入 Sheet2 必考主体；含整体月 ARPU 预估 banner 与达标率。
掉量客户：本月消耗 < 上月日均 × 当前天数。
停投客户：①月维度停投（上月>0 且本月=0）；②本月近期停投（本月>0 且昨日=前日=0 且连续停投>0）。
低效客户：昨日消耗>0 且 < inefficient_threshold。
数据洞察：运营日均环比、账户质量分布、Top15 本月消耗账户、一级行业分布。
昨日增减盘点：按运营分组，增量 TOP10 + 掉量 TOP20（对比前日/昨日）。
本月新增账户：上月无消耗(=0)且本月有消耗(>0)，含首次投放时间。

7. 记忆与日期回看（已内置）

每个工作日更新时，当日快照写入历史库；看板顶部「数据日期」下拉框可切换回看任意已存档日期的完整看板。
跟进勾选 / 备注按日期隔离存储（localStorage），切到历史日期看到的是当天自己的标注，互不串。
自动记住上次选的日期与停留的 Tab，下次打开回到原处。
历史范围从首次使用起逐日累积；更早的源文件若已删除则无法回填。

8. 注意事项

优先在隔离 Python 环境运行；依赖缺失先装 pandas/openpyxl。
部署后务必缓存穿透核实线上 data_date，避免"部署成功但页面滞后"。
跨月时 last_month_days 必须改成上月真实天数，否则掉量/日均口径会偏。
各运营名称与数据须严格一一对应，仅在数据范围内做延申分析，不篡改数据。