njh20030605-code 越南美妆类目 · 竞争格局周报
固定输入：两周店铺级 GMV 榜单导出。固定输出：6 张图 + 1 个 xlsx + 一套结论。 每周重复的部分全部脚本化，人只需要做判断。
关键原则
这份数据只有"结果"，没有"原因"。 能看出谁涨了、涨的量从哪个渠道来，看不出对手怎么做到的。所有归因都是推断，必须落到"要补什么数据来验证"。第 5 步的待补清单不是可选项。
口径错了数字全对结论也是反的。 开工前读 references/pitfalls.md，十条里至少有三条每周都会碰到。最容易犯的两个：拿两周 Top200 全量比总量（门槛不同）、按店铺而不是品牌看多店铺对手（结论会完全相反）。
流程
1 · 落盘 + 确认周期
把用户粘贴的两段文本各存成一个 TSV（保留平台原始表头，脚本按表头名定位列，列序变了也能读）。如果用户上传的是文件，直接用文件路径。
开跑前必须跟用户确认两件事（一次问完，别分两轮）：
- 本周和上周分别是哪个日期区间（用于图标题和文件名）
- 有没有大促（8.8 / 9.9 / 11.11 / 12.12 / 平台活动），大促周的解读方式完全不同
2 · 查实时汇率
web_search 查当日 USD→CNY 中间价，记下来源和时间。--rate 必填，没有默认值——用旧汇率出的图会和财务口径打不上。
3 · 跑脚本
cd scripts
python run_all.py --cur <本周.tsv> --pri <上周.tsv> --rate 6.7476 \
--rate-note "Xe.com 中间价，2026-08-11 00:05 UTC" \
--cur-label "本周 08.03-08.09" --pri-label "上周 07.27-08.02" \
--outdir ./out
run_all.py 依次做：metrics.py（指标汇总，同时写 metrics.txt）→ 6 张图 → xlsx（自动调 /mnt/skills/public/xlsx/scripts/recalc.py 重算公式）。
常用参数：--focus 店铺自播 换散点图和梯队图看的渠道（默认达人直播）｜--only 1,3,6 只跑指定图｜--skip-xlsx 跳过工作簿。单张图也可以单独跑，参数同 run_all。
每张图出来后 view 一遍。 标签避让算法在数据分布变化时会失手，挤在一起的图不能给用户。常见修法见下面「图表微调」。
4 · 写结论
读 metrics.txt，按 references/analysis_playbook.md 的五步走：大盘定调 → 增量来源 → KANS 定位 → 竞争格局（三类打法）→ 下周动作。
每个判断后面跟一个数。口径换了导致结论和上次不一样，明确说"上次说 X，改成 Y，原因是 Z"，不要悄悄改。
5 · 交付
present_files 给图和 xlsx。用户要写进周报时，按 references/report_template.md 出正文（250–350 字 + 2 张图，不要写成竞品罗列）。
六张图
| 图 | 内容 | 用在哪 |
|---|---|---|
| 01 渠道结构对比 | 左：大盘渠道占比两周对比；右：KANS 各渠道增幅 vs 大盘同渠道，标跑赢/跑输 pp | 周报第一、二部分 |
| 02 中国品牌梯队 | 上：两周 GMV + 环比；下：focus 渠道占比位移 | 周报第三部分 |
| 03 异动定位散点 | X=总GMV环比，Y=focus 渠道占比位移，气泡=本周GMV，带四个结论标注框 | 附录 / 口头汇报 |
| 04 KANS 渠道结构 | KANS 五渠道金额对比 + 占比结构 | 内部复盘 |
| 05 TopN 排名与 GMV | 实心本周 / 虚线框上周 + 名次变化，KANS 不在 TopN 时单独补一行 | 内部复盘 |
| 06 品牌渠道占比对比 | 指定品牌组 100% 堆叠 + GMV + 排名，分「确认中国品牌 / 疑似中国跨境（待核）/ 国际·本地对照」 | 深度对标 |
图6 的分组可以改：--group "组名=店铺A|品牌B" --group "另一组=..."。键名用店铺原名，或 common.MULTI_STORE 里的品牌名（如 珂拉琪）。
图表微调
标签重叠是最常见的问题，按这个顺序试：
- 散点图密集区挤在一起 →
chart3用线性轴 + 超限箭头（已内置，CAP取 97 分位）。不要用对数轴，会把主密集区压缩得更紧。 - 结论标注框压住数据点 → 挪
annotate的xytext，优先放图的四个角；先画完所有点再找空白区。 - 数值标签和环比标签打架 → 把环比提到面板顶部单独一行（
chart2已这么做），不要堆在柱子上方。 - 红色区/参考带出现断层 → 别用断轴。断轴会把背景色带切成两截。
- 标题和副标题重叠 →
suptitle的y和fig.text的y至少差 0.03。
配色、字体、涨跌色（涨红跌绿，中文习惯）都在 common.py，别在单图里覆盖。
单周数据怎么办
只给一周时，02/06 图和渠道占比结构仍然能出（不需要对比），但环比、排名变化、异动判定全部失效。这种情况直接告诉用户缺上周数据、能出哪些不能出哪些，不要用零填充硬跑。
品牌映射维护
common.py 里两处需要随榜单变化更新：
MULTI_STORE：同品牌多店铺关系。新对手开二店时补上，否则会被当成两个品牌算。CN_NAME：店铺 → 中文名。带?的是归属未核实，出图时保留问号或单独分组，核实后再去掉。不要把待核品牌混进CN_TIER（确认中国品牌梯队）——这批往往是增速最快的一层，归错会让整体结构结论失真。
文件
scripts/
common.py 字体/配色/口径/品牌归并/解析（所有图的唯一真源）
metrics.py 指标汇总，写结论前先跑
chart1..chart6_*.py 六张图，可单独跑
build_xlsx.py 人民币口径工作簿（4 sheet，含公式）
run_all.py 一键跑完
references/
pitfalls.md 口径陷阱十条 ← 开工前必读
analysis_playbook.md 五步分析框架 + 待补数据清单
report_template.md 周报正文模板与写法约定
examples/
week_current_0803_0809.tsv 2025-08-03~09 真实导出（200 行）
week_prior_0727_0802.tsv 2025-07-27~08-02 真实导出（200 行）
用示例数据自检：
cd scripts && python run_all.py \
--cur ../examples/week_current_0803_0809.tsv \
--pri ../examples/week_prior_0727_0802.tsv \
--rate 6.7476 --outdir /tmp/selftest
预期（大促周基准值，可用来判断脚本有没有跑歪）：大盘总 GMV 环比 +48.1%、五渠道合计 +50.8%、达人直播 +105.6%、KANS 总 GMV +103.6% 排名 38→23、珂拉琪 4 店合计 -2.8%。