# Kans Vn Category Competition

> 越南美妆个护类目【竞争格局周报】——从 FastMoss/Kalodata 店铺级导出（Store Name / GMV / Affiliate Video / Self-Account Video / Self-Account Live / Affiliate Live / Shop Tab GMV）做两周对比，输出 6 张标准图 + 人民币口径 xlsx + 可直接进周报的分析结论。当用户粘贴两周（或一周）的店铺 GMV 明细文本/文件，并要求「整理数据 / 做竞品对比 / 渠道结构分析 / 异动品牌 / 市场竞争环境这一节怎么写 / 做图 / 生成周报」时使用。用户只说「这是本周和上周的数据」「跑一下竞争分析」「按老规矩来」也要用。注意与 kans-livestream-charts 的分工：那个处理 KANS 自己直播间的日度数据，这个处理类目级店铺榜单的竞争数据。

- Skill: `njh20030605-code/kans-vn-category-competition` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add njh20030605-code/kans-vn-category-competition`
- Raw SKILL.md: https://api.skillmd.com/api/skills/njh20030605-code/kans-vn-category-competition/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: njh20030605-code (https://skillmd.com/u/njh20030605-code)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/njh20030605-code/kans-vn-category-competition

---


# 越南美妆类目 · 竞争格局周报

固定输入：两周店铺级 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 · 跑脚本

```bash
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` 里的品牌名（如 `珂拉琪`）。

## 图表微调

标签重叠是最常见的问题，按这个顺序试：

1. **散点图密集区挤在一起** → `chart3` 用线性轴 + 超限箭头（已内置，`CAP` 取 97 分位）。不要用对数轴，会把主密集区压缩得更紧。
2. **结论标注框压住数据点** → 挪 `annotate` 的 `xytext`，优先放图的四个角；先画完所有点再找空白区。
3. **数值标签和环比标签打架** → 把环比提到面板顶部单独一行（`chart2` 已这么做），不要堆在柱子上方。
4. **红色区/参考带出现断层** → 别用断轴。断轴会把背景色带切成两截。
5. **标题和副标题重叠** → `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 行）
```

用示例数据自检：

```bash
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%。