dkd-brand-data-analysis - 门店/品牌分析数据报表技能

1️⃣ 定位与设计

采用 MCP 接口：scripts/chain_business.py 内置 MCP_URL，通过 HTTP JSON-RPC 直连（Streamable HTTP + Bearer 认证），自带 Token 独立运行。
产物：9 种可视化 HTML 报表（门店对齐 / 门店单平台 / 品牌 × 日/周/月）+ 近N天分析（周报模板）+ *_AI分析.md 深度分析文本 + ai_diagnosis_{门店/品牌}_{类型}.json 诊断文件（回填用）。
三份文档分工：本文件 = 完整规范（怎么干）；AGENTS.md = 多工具操作速查（前置配置/脚本/路由/输出）；CLAUDE.md = Claude Code 快速上手。文档间以本文件为准，改动须三处同步。

2️⃣ 🔀 一键优先路由（强制执行 · 最高优先级 · 先于一切流程）

任何报表/分析需求，生成前必须走这三步（不可跳过）：

五维拆解（对象×时间×粒度×指标×动作，见「8️⃣ 接口编排 · ⓪」）确定需求语义
对照「5️⃣ 报表体系」9 类表：命中 → 直接用对应 generate_* 一键脚本（参数按「AI 执行规则」填入，零自写代码、零现场编排）；未命中 → 才允许进入「8️⃣ 接口编排」
自问三连：① 这是不是 9 类报表之一？② 是 → 对应的 generate_* 脚本是哪个？③ 不是 → 才能用 extend_query / 现场编排

三层降级（只能逐级往下，不得跳过）：

① 9 类标准报表命中     → generate_* 一键脚本（默认路径，唯一正确做法）
② 未命中但属高频场景   → scripts/extend_query.py 封装动作（--action，仅取数）
③ 仍覆盖不了           → 用 chain_business.py 现场编排（最后手段）

🚫 禁止条款（DO NOT）：

禁止为 9 类覆盖范围内的需求自写/复制编排脚本——generate_* 已内置环比对比期、商圈排名、门店等级分档、健康体检、6 层诊断框架、趋势图，自写脚本必然缺维度
禁止改写 generate_* 脚本本体（需要新报表形态 → 走接口编排产出 HTML/文字，不改标准脚本）
禁止命中 9 类时用 extend_query / chain_business 现编替代一键脚本

⚠️ 反面案例（真实事故）：生成「XX品牌 2026年7月品牌月报」时，绕过 generate_brand_report.py --brand "XX品牌"，自写 3 套脚本现场编排 → 结果缺环比对比期（6月）、缺商圈排名/门店等级分档/健康体检，维度不全。重跑一键脚本一次补齐。9 类场景 = 一键脚本，没有例外。

3️⃣ 前置配置与安装

3.1 独立配置文件 config.json

本技能独立配置：接口地址与 Token 统一放在 scripts/config.json（脚本同目录），不硬编码在脚本中（无兜底，缺失/占位符时引导填写）。

{
  "mcp_url": "https://api.diankeduo.net/chain/business/mcp",
  "mcp_token": "<客户Token>"
}

Token 管理（三级优先级，自动生效）：

环境变量 CHAIN_MCP_TOKEN（最高，临时覆盖，不改文件）
  ↓
scripts/config.json → mcp_token（常规修改入口）
  ↓
无兜底（缺失/占位符时由 check_token / 脚本引导填写）

日常换 Token：编辑 scripts/config.json 的 mcp_token 字段即可，无需改脚本
临时覆盖：设置环境变量 CHAIN_MCP_TOKEN 可临时换 Token（不改文件）
Token 从【店客多 AI 技能中心】https://ka.diankeduo.net/#/crayfish/index 获取；401 时引导用户重新获取；429 为每日额度限制，隔天自动恢复
⚠️ 分发/共享技能包时注意清除 config.json 中的真实 Token（分发包默认即为占位符，安装后须先配置）

3.2 🔑 安装 / 首次使用：Token 检查（必做）

分发包 zip 默认不携带 Token（config.json 为占位符），安装后先执行检查：

python scripts/check_token.py

显示「✅ 已配置」→ 可直接使用
显示「❌ 未检测到有效 Token」→ 打开 scripts/config.json，把 mcp_token 占位符替换为真实 Token（获取方式：【店客多 AI 技能中心】https://ka.diankeduo.net/#/crayfish/index），再运行 check_token.py 确认
所有脚本内置同样校验：Token 缺失/占位符时不会静默使用无效 Token，而是提示引导后退出

3.3 🛠️ 多工具适配（Trae / Qoder / Codex / Cursor / Cline / Claude Code）

本技能可在主流 AI 编程工具中直接使用，方式二选一：

方式 A：指令文件驱动（推荐，零配置） 把 dkd-brand-data-analysis/ 整个目录放进项目（或技能目录），各工具会自动读取： | 工具 | 读取的文件 | 说明 | |---|---|---| | Trae / Qoder | AGENTS.md | 项目根自动识别，对话中直接按速查调用脚本 | | Codex | AGENTS.md | 自动加载为上下文指令 | | Cursor | AGENTS.md + CLAUDE.md | 两者都读，规则叠加 | | Cline | AGENTS.md | 自动注入上下文 | | Claude Code | CLAUDE.md | 自动加载项目指令 |

方式 B：MCP 直连（对话中直接取数） 将 mcp.example.json 的内容注册为工具的 MCP server（Streamable HTTP + Bearer）：

{
  "mcpServers": {
    "dkd-chain-business": {
      "type": "http",
      "url": "https://api.diankeduo.net/chain/business/mcp",
      "headers": { "Authorization": "Bearer <客户token>" }
    }
  }
}

Trae：设置 → MCP → 导入 JSON；Qoder：设置 → MCP；Cursor：Settings → MCP（.cursor/mcp.json）；Codex：codex mcp add；Cline：MCP 设置导入
注册后工具可直接调用 query_history_daily / query_history_list / query_evaluate_detail / search_shops 等接口，无需跑脚本
⚠️ 把 <客户token> 替换为真实 Token（获取方式见上方「3.1 Token 管理」）

多工具下的一致约定：报表命令/参数/时间路由/输出三件套与 WorkBuddy 完全一致（见 AGENTS.md 速查与「7️⃣ 输出规范」），保证任何工具下行为相同。

3.4 ✅ Token 配置成功后 · 上手引导（先试这些场景）

check_token.py 显示 ✅ 后无需任何额外配置，直接自然语言提问，AI 自动路由（全量路由见 5.3 提示词解析速查 / 13 场景速查）：

"分析 XX门店昨天的数据" → 门店对齐日报
"分析 XX品牌本月经营数据，做月度总结" → 品牌月报
"XX品牌今天实时数据怎么样 / 今天收入前10的门店" → 实时汇总 / TOP10
"XX门店美团近7天数据 / 最近的好差评" → 单平台周报 / 评价分析

📚 更全的场景清单：🗣️ 用户场景话术库.md（40 场景：定时 12 / 数据使用 28，含话术+执行路径）；🔗 接口能力与应用场景.md（8 个 MCP 工具 + 5 类查询场景 + 自定义接口编排）。 💡 第一次跑通后，常用需求可设为定时任务（如「每天早上 9 点发昨日品牌日报」），详见话术库定时场景章节。

4️⃣ 目录结构

dkd-brand-data-analysis/
├── SKILL.md                  # 本文件（完整规范）
├── AGENTS.md                 # 🤖 多工具适配：Trae / Qoder / Codex / Cursor / Cline 读取的操作速查
├── CLAUDE.md                 # 🤖 Claude Code / Cursor 读取的快速上手
├── mcp.example.json          # 🔌 MCP 注册配置示例（复制到各工具 MCP 配置，即可对话中直连数据源）
├── 接口能力与应用场景.md      # 🔗 chain_business 接口能力全集：8 个 MCP 工具 / 5 类查询场景 / 一站式导出 / 应用场景速查
├── 美团门店诊断逻辑.md        # 🔬 美团单平台诊断体系：7 大维度判定标准 + 综合体验分/店铺分公式 + 11 个官方功能
├── 淘宝门店诊断逻辑.md        # 🔬 淘宝闪购单平台诊断体系：7 大维度 + 口味满意度/淘宝店铺分公式 + 10 个官方功能
├── 用户场景话术库.md          # 🗣️ 40 场景话术库：定时场景(12) / 数据使用场景(28)，含话术示例与执行路径
├── scripts/
│   ├── config.json            # ⚙️ 独立配置（mcp_url / mcp_token，换 Token 改这里）
│   ├── chain_business.py      # HTTP MCP 接口封装（读取 config.json，含缓存与异常处理）
│   ├── check_token.py         # 🔑 Token 检查 + 配置成功后上手话术引导
│   ├── extend_query.py        # 🧩 接口编排 5 个高频示例（realtime-summary / realtime-top / history-top / growth-top / realtime-shop）
│   ├── diagnostic_data.json   # 📄 最近一次报表的诊断输入数据（AI 深度诊断读取用，可删）
│   ├── generate_store_daily.py    # 门店对齐日报
│   ├── generate_store_weekly.py   # 门店对齐周报（自然周 / 近N天）
│   ├── generate_store_monthly.py  # 门店对齐月报（自然月）
│   ├── generate_brand_daily.py    # 品牌日报
│   ├── generate_brand_weekly.py   # 品牌周报（自然周 / 近N天）
│   ├── generate_brand_report.py   # 品牌月报（自然月）
│   ├── generate_platform_daily.py    # 门店单平台日报（--platform 必填）
│   ├── generate_platform_weekly.py   # 门店单平台周报（自然周 / 近N天）
│   ├── generate_platform_monthly.py  # 门店单平台月报（自然月）
│   ├── chart.umd.min.js           # 📊 图表库（Chart.js）
│   ├── echarts.min.js             # 📊 图表库（ECharts，漏斗图）
│   ├── .cache/shop_list_all.json  # 🗄️ 门店列表缓存（加速检索，可删）
│   └── ai_diagnosis_*.json        # 📄 AI 诊断文件（回填用，放脚本同目录）
└── examples/
    ├── ai_diagnosis_XX品牌（XX门店）_daily.json   # 诊断文件格式示例
    └── ai_diagnosis_XX品牌_weekly.json                # 诊断文件格式示例

诊断文件放哪：ai_diagnosis_{门店/品牌}_{daily/weekly/monthly}.json 一律放在 scripts/（脚本同目录），脚本按「脚本所在目录」自动查找。

5️⃣ 报表体系（9 种 + 近N天 + 自定义）· 命令唯一来源

本节是全部报表命令的唯一权威来源；「6️⃣ 核心工作流」与「13️⃣ 9报表诊断场景」只引用本节，不重复命令。

5.1 报表一览表（运行于技能根目录）

| 报表 | 脚本 | 周期 | 对比口径 | |------|------|------|----------| | 门店对齐日报 | python scripts/generate_store_daily.py --shop X [--brand Y] | 昨天（或 --date） | 较前日 + 较上周同期 | | 门店对齐周报 | python scripts/generate_store_weekly.py --shop X [--brand Y] | 自然周（周一~周期末） | 较上周 + 同比 | | 门店对齐月报 | python scripts/generate_store_monthly.py --shop X [--brand Y] | 自然月 | 较上月 | | 品牌日报 | python scripts/generate_brand_daily.py --brand <客户品牌> | 昨天 | 较上周同期 | | 品牌周报 | python scripts/generate_brand_weekly.py --brand <客户品牌> | 自然周 | 较上周 | | 品牌月报 | python scripts/generate_brand_report.py --brand <客户品牌> | 自然月 | 较上月 | | 门店单平台日报 | python scripts/generate_platform_daily.py --shop X --platform P | 昨天（或 --date） | 较上周同期 | | 门店单平台周报 | python scripts/generate_platform_weekly.py --shop X --platform P | 自然周 | 较上周 | | 门店单平台月报 | python scripts/generate_platform_monthly.py --shop X --platform P | 自然月 | 较上月 | | 近N天分析 | python scripts/generate_store_weekly.py --shop X --days N（品牌：--brand X --days N；平台：--shop X --platform P --days N） | 昨日往前推 N 天 | 往前推 N 天 | | 自定义日期范围 | 对应周报脚本 + --start YYYYMMDD --end YYYYMMDD | [start, end] | 往前推同样天数 |

generate_platform_*（单平台）：--shop/--shop-id + --platform 均必填；该报表是单一平台独立视图（无「总→分」对比/分平台表/分平台主拖累诊断），保留商圈收入排行+核心指标+利润+流量漏斗+推广+评价+复购+取消+AI诊断。 --brand 必填规则：仅品牌报表（generate_brand_*）必填（不传提示指定并退出）；单店报表可选（仅同名精确过滤；--shop 匹配到多家跨品牌门店时脚本会提示补品牌）。品牌名 = 客户提示词中的品牌，禁止用示例名替代。输出文件（HTML / AI分析.md）生成在当前工作目录，诊断文件在 scripts/ 目录。 门店定位：--shop <关键词>（模糊匹配）或 --shop-id <平台门店ID>（精确），二选一必填。

5.2 🚫 零硬编码 · 全部由用户提示词驱动

脚本内不存在任何固定时间、固定门店名、固定品牌名，所有报表均按当次调用参数生成：

| 维度 | 数据来源 | 说明 | |------|---------|------| | 门店 | --shop <关键词> | 单店报表必填；取值 = 客户提示词中的门店名（如"XX门店"→ --shop XX门店） | | 品牌 | --brand <品牌名> | 单店可选（精确过滤）、品牌报表必填；取值 = 客户提示词中的品牌名（如"XX品牌"→ --brand XX品牌） | | 平台 | --platform <平台> | 仅单平台报表必填（美团外卖/淘宝闪购/京东外卖） | | 日期 | 自动计算或 --date YYYYMMDD | 日报=昨天、周报=上一完整自然周、月报=上完整月；--date 指定周期末（日报=当日、周报=周期末、月报=所在月） | | 近N天 | --days N | 周期 = [昨日-(N-1), 昨日] 共 N 天；对比期 = 再往前推 N 天；用周报模板 | | 自定义日期范围 | --start YYYYMMDD --end YYYYMMDD | 周期 = [start, end]；对比期 = 再往前推同样天数；同比 = 2 倍天数；同样走周报模板（含日趋势/周期汇总/环比） | | 对比口径 | 自动 | 较前日/上周/上月 + 同比，随报表类型自动切换 |

AI 执行规则（强制）：用户提示词中出现门店名 → 填入 --shop；出现品牌名 → 填入 --brand（单店报表可选，仅精确过滤；品牌报表必须）；出现平台名（美团/淘宝/京东等）→ 映射为 --platform（见 5.3 ①）；出现时间词（昨天/本周/上月等）→ 决定报表类型与是否加 --date；出现 "近N天/最近N天/N天数据"（N=3/7/14/30 等）→ 按昨日往前推 N 天，用周报模板并加 --days N。禁止用任何示例名替代用户提示词中的名称；用户未提品牌时：单店报表直接不传 --brand 正常生成；仅当是品牌报表且未给品牌名时，先确认品牌名再运行。

5.3 🧭 提示词解析速查（用户问法 → 参数）· 含近N天智能路由

① 平台别名映射（用户提到平台 → --platform 值）：

| 用户说 | 标准平台名（--platform） | |--------|------------------------| | 美团 / 美团外卖 / 美团的 | 美团外卖 | | 淘宝 / 淘宝闪购 / 闪购 / 淘鲜达 | 淘宝闪购 | | 京东 / 京东外卖 | 京东外卖 | | 饿了么 / 饿了么外卖 | 淘宝闪购（统一口径：饿了么并入淘宝闪购，数据同源） |

② 时间词全映射（用户说时间 → 报表类型 / 周期）：

| 用户说 | 处理 | 周期 | |--------|------|------| | 今天 / 今日 / 当天 / 实时 / 现在 / 目前数据 | ① 实时优先：先调 realtime 接口（品牌→query_realtime_summary；单店/门店→query_realtime_list）拿当天实时数据；② 实时无数据（返回空）→ 回退日报（默认昨日） | 实时（当天） | | 昨天 / 数据怎么样（未给时间） | 日报（默认昨日；当天数据未出全） | 单日 | | 前天 | 日报 + --date <前天日期> | 单日 | | 本周 / 这周 / 上周 / 星期 | 周报（上一完整自然周周一~周日） | 自然周 | | 本月 / 这个月 / 上月 / 月度总结 | 月报（上一完整自然月） | 自然月 | | 去年同期 / 同比 / 和去年比 | 对应报表（对比期自动含同比口径） | 自动 | | 近N天 / 最近N天 / 过去N天 / N天数据 | 周报模板 + --days N（见下表） | [昨日-(N-1), 昨日] |

③ 近N天口语数字映射：

| 用户说 | --days 值 | |--------|----------| | 近3天 / 最近3天 | 3 | | 近一周 / 最近7天 / 7天数据 | 7 | | 近半个月 / 近14天 | 14 | | 近一个月 / 近30天 / 月度近期 | 30 | | 近两个月 / 近60天 | 60 |

④ 门店 + 品牌 / 平台组合路由：

| 用户说 | 路由命令 | |--------|---------| | "XX品牌的XX门店昨天怎么样" | 门店对齐日报 + --shop XX门店 --brand XX品牌（品牌作精确过滤） | | "XX门店美团近7天" | 平台周报 + --shop XX门店 --platform 美团外卖 --days 7 | | "XX品牌这个月怎么样" | 品牌月报 + --brand XX品牌 | | "XX品牌 XX门店美团昨天" | 平台日报 + --shop XX门店 --brand XX品牌 --platform 美团外卖 |

⑤ 歧义处理（仅意图不明显时确认，意图明确直接生成）：

核心原则：能用最少信息确定唯一报表 → 直接生成，不确认；存在多种合理解读 → 才确认。

✅ 意图明确 → 直接生成（不问）——以下情况参数自足，立即运行：

有明确门店名 + 时间（"XX门店昨天怎么样"）→ 单店日报
有明确品牌 + 时间（"XX品牌上周数据"）→ 品牌周报
有门店 + 平台 + 时间（"XX门店美团近7天"）→ 单平台周报 + --days 7
有明确品牌/门店 + "直接出/不用问/随便" → 用最合理默认（品牌整体 / 单店 + 昨日）并注明假设

⚠️ 意图不明显 → 先确认（禁止擅自默认）——存在多种合理解读时，不要自行假设后直接出报表：

只说品牌/品类词 + "数据怎么样/怎么样/看看"（如"XX品牌数据怎么样"）——未明确是品牌整体还是某单店、未给日期
只说"分析一下XX"而未给任何时间词（"分析一下XX品牌"→ 品牌 or 门店？哪一天？）
只说时间词（"这周数据"）但没给门店/品牌维度
品牌/门店名模糊匹配多家 → 需要澄清（如"文山店"可能有多平台）

确认清单（一次性问清 2 个参数）：

维度：品牌整体？还是某家具体门店？（品牌 → --brand；单店 → --shop）
日期范围：昨天 / 近7天 / 本周 / 本月 / 自定义区间？

标准确认话术示例：

"XX品牌"匹配到品牌 XX品牌（802 家门店）。请问要分析： ① 品牌整体还是某家具体门店（如XX门店）？ ② 哪个日期范围：昨日 / 近7天 / 本周 / 本月？

确认后路由：

品牌整体 → generate_brand_* --brand <品牌>
具体门店 → generate_store_* --shop <门店>（或单平台 --platform）
日期 → 昨天→日报；近N天→周报+--days N；本周/本月→周报/月报；自定义→--start --end

其他歧义：

品牌报表（generate_brand_*）未给品牌名 → 先确认品牌名再运行
--shop 模糊匹配多家 → 提示补 --brand 或 --shop-id 精确定位
同时出现"品牌+门店+平台" → 平台报表优先（商圈/排名是单平台口径，信息最全）
用户明确说"快点/直接出/不用问" → 采用最合理默认（品牌整体 + 昨日）并说明假设

⑥ 近N天智能路由细则（用户说"近X天/最近X天/X天数据"）：

用户说"分析近7天数据 / 最近3天 / 近半个月"等，按昨日往前推 N 天取周期，采用周报模板汇总分析：

| 用户问法 | 路由命令（近N天模式） | |---------|----------------------| | "XX门店近7天数据怎么样" | python scripts/generate_store_weekly.py --shop "XX门店" --days 7 | | "XX品牌近3天经营分析" | python scripts/generate_brand_weekly.py --brand "XX品牌" --days 3 | | "XX门店美团近14天怎么样" | python scripts/generate_platform_weekly.py --shop "XX门店" --platform 美团外卖 --days 14 |

路由规则：

⚠️ 先确认后生成（强制）：用户表述模糊（只有品牌/品类词+"数据怎么样"、没给日期、没给维度）时，先按「⑤ 歧义处理」清单向用户确认维度+日期，再运行，禁止擅自默认
识别时间词 近N天 / 最近N天 / 过去N天 / N天数据（N=3/7/14/30 等数字）→ 加 --days N，用周报模板（含日趋势、周期汇总、环比对比往前推 N 天）
周期末 = 昨日（昨天），周期 = [昨日-(N-1), 昨日] 共 N 天；对比期 = 再往前推 N 天
不指定维度时按用户提到的门店/品牌自动选择对应周报脚本；同时提到门店+平台 → 平台周报
近30天/近1个月 → 同样可用 --days 30（周报模板，非月报）
用户只说"近N天"但没给门店/品牌 → 先确认维度再运行

判断规则：先按 门店 / 品牌 / 平台 定位维度，再按 时间词（昨天→日报、这周→周报、本月→月报、近N天→周报模板+--days N）定报表；只问"怎么样/数据"未给时间时，默认日报并询问周期。 品牌名 = 客户提示中的品牌（"分析XX品牌"的 XX），不是示例默认值。

6️⃣ 核心工作流（一键分析诊断闭环）

① 生成报表数据  → 运行 generate 脚本（命令见 5.1 报表一览表）→ HTML（AI 区为规则诊断占位）
                 + *_AI分析.md（规则版）
② AI 深度诊断   → 读取报表数据/诊断数据 → 写 ai_diagnosis_{门店/品牌}_{类型}.json
③ 回填重跑      → 再次运行 generate 脚本 → 自动读取诊断文件
                 → AI 诊断覆盖规则版 → 回填 HTML AI 区 + AI分析.md
④ 对话内交付    → 基于最终数据，直接在对话中输出 五段式文字版分析（markdown 表格，图表由 HTML 卡片渲染，见「7️⃣ 输出规范」）
                 + 用 present_files 打开生成的 HTML 报表页面
                 （三件套同时交付：文字结论 / 内嵌图表 / 可滚动页面，见「7.2 对话内输出规范」）

6.1 步骤① 一键生成报表

在技能根目录运行对应脚本（命令见 5.1 报表一览表，不在此重复；品牌脚本必须 --brand，单平台脚本必须 --platform）。

产出（当前工作目录）：

{报表名}.html（可视化报表，AI 区为规则诊断占位——尚无 AI 诊断时的回退版）
{报表名}_AI分析.md（文字版分析结果，一键生成即自动输出，9 类报表全覆盖；含：总览 / 亮点 / 问题&方案 / 行动建议（优先级）/ 一句话结论，AI 诊断回填后自动升级为 AI 深度版）
- 品牌报表结构：品牌文字版分析 · {品牌名}（品牌日报/周报/月报），对比标签按周期（较上周同期/较上周/较上月）自动区分
- 商圈流量对比：领先/达标 → 亮点；低于商圈均值/未达前10%门槛 → 问题（配排查方案），不再误列亮点

脚本按自然周/自然月自动计算周期；也可 --date YYYYMMDD 指定周期末（日报=当日、周报=周期末、月报=所在月；--days N 近N天模式周期末=昨日或 --date）。

6.2 步骤② AI 深度诊断（人工/AI 分析环节）

读取报表数据：打开 HTML 关键板块（KPI/分平台/商圈/趋势）+ scripts/diagnostic_data.json，提取核心指标与对比
深度分析（参考「9️⃣ AI 深度分析」的 6 层框架 / 运营专家视角）：
- 实收/订单/单均、环比/同比、分平台结构
- 下滑归因拆解（实收%≈订单%+单均%；订单%≈曝光%+转化%）
- 商圈地位（排名/倍数/前10%）、复购、毛利、履约
写诊断文件 ai_diagnosis_{门店/品牌}_{类型}.json（放在 scripts/ 目录，脚本同目录）：

{
  "score": 88,
  "grade": "优秀",
  "verdict": "综合结论（数据+对比+定性判断）",
  "opportunities": ["亮点1（含数据）", "亮点2"],
  "risks": [["问题1（含数据）", "方案1"], ["问题2", "方案2"]],
  "report_date": "20260809"
}

report_date 取值：日报=CUR_DATE（如 20260809）、周报/月报=CUR_END_S（如 20260809 / 20260731）、近N天=CUR_END_S——必须与报表周期末一致，否则回填时被跳过。

6.3 步骤③ 回填 AI 深度诊断报告

再次运行同一脚本（无需任何额外参数）
脚本自动：读取 scripts/ai_diagnosis_{...}_{类型}.json → 校验 report_date（匹配则覆盖规则诊断，不匹配则跳过回退规则版）
回填位置：
- HTML 的 AI 诊断区（📝 AI 结论 verdict / 🟢 亮点 / 🔴 问题&方案配对）+ 顶部健康评分（score）
- {报表名}_AI分析.md（同步覆盖为 AI 深度版）
验证：运行日志出现 [AI诊断] 已回填 ai_diagnosis_xxx.json；打开 HTML 确认 AI 结论为 AI 版

6.4 流程记忆点

首次运行（规则占位）→ AI 读数据写诊断 JSON → 重跑（自动回填 AI 版）
已有诊断且日期匹配 → 只需跑一次即出最终版
诊断日期不匹配      → 自动跳过，回退规则诊断（防跨日期/跨周期误回填）

6.5 使用示例

用户：分析XX门店昨日数据（门店名/品牌名取自客户提示词）
→ python scripts/generate_store_daily.py --shop "XX门店" [--brand "XX品牌"]
→ 读取数据 → AI 深度诊断 → 写 scripts/ai_diagnosis_XX门店_daily.json
→ 重跑脚本回填 → 对话内直接输出 文字结论 + 可视化图表（KPI卡组/归因漏斗/平台对比）

用户：分析XX品牌本周经营（品牌名=客户提示中的XX）
→ python scripts/generate_brand_weekly.py --brand "XX"
→ AI 诊断（verdict/亮点/问题方案配对）→ scripts/ai_diagnosis_XX_weekly.json
→ 重跑回填 → 对话内输出 品牌分析 + 门店评分分档图

其余场景（单平台/近N天/评价）流程相同：按 5.1 命令生成 → AI 诊断写文件 → 重跑回填 → 三件套交付，仅命令与诊断文件名（ai_diagnosis_{门店/品牌}_{daily/weekly/monthly}.json）随场景变化。

7️⃣ 输出规范（所有分析强制 · 最高优先级）

7.1 📐 文字版分析输出规范（9 报表格式）

适用范围：一切分析交付——9 类标准报表、近N天/自定义区间、接口编排（extend_query / AI 现场编排）、AI 深度诊断、任何自定义查询结果。 格式基准：所有分析的文字输出必须采用 9 类报表 *_AI分析.md 的五段式结构（下方模板）。数据用 markdown 表格落表呈现；图表一律由可视化组件（HTML 卡片，见 7.2 ④）渲染，文字版/对话内均不使用 Unicode 文本图表（条形图/迷你趋势类已全部取消）——禁止以"纯文字段落"或"只写数字"作为最终输出；无结构 = 未完成，需补齐后交付。 取数与呈现分离（职责分工）：脚本（extend_query / 现场编排）只负责取数——输出 markdown 数据表 + 汇总行即可，不生成任何分析文案；五段式分析（亮点/问题/方案/行动建议/结论）由 AI 依据本规范在对话中组织，不依赖脚本"展示"，脚本里的规则文案一律弃用。

① 输出模板（五段式，与 *_AI分析.md 完全一致）：

# {品牌/门店}文字版分析 · {主体}（{场景类型，如：品牌实时收入TOP / 品牌日报 / 门店实时分平台}）
周期：{日期或实时} ｜ {关键评分/等级或合计口径}

## 一、经营总览
- KPI 行：实收 **¥xx** ｜ 订单 **xx** ｜ 单均 **¥xx**
- 核心结论句（+ 对比/占比）

| 维度 | 本期 | 对比 | 判断 |
|---|---|---|---|
| ...（数据必须落表） |

（图表由对话内 HTML 卡片渲染，文字版不画 Unicode 图表）

## 二、亮点
- **xxx** 实收 ¥xx，占 xx%，为收入贡献第一（含数据）

## 三、问题与解决方案
- **xxx 下滑 ¥xx（-x.x%）**
  - 💡 方案：按归因链拆解（实收≈订单+单均，订单≈曝光+转化）……

## 四、行动建议（优先级）
P0｜止血……
P1｜放大/修复……
P2｜监控……

## 五、一句话结论
……

> 数据来源：店客多外卖AI运营系统 · 本分析由 AI 综合 {数据来源} 生成

② 场景类型命名：标准报表用原类型名（品牌日报/门店周报…）；接口编排/自定义查询用「{场景}扩展分析」——如 品牌扩展分析 · XX品牌（收入TOP10）、门店扩展分析 · XX门店（美团vs淘宝双平台对比）。

③ 数据呈现规范（嵌在文字中）：

| 数据形态 | 文字版呈现 | 图表 | |---|---|---| | TOP / 占比 / 趋势 | markdown 表格 + ▲▼（▲涨/▼跌/—持平）；排名变化 ↑2位/↓1位 | 由对话内 HTML 卡片渲染（KPI 卡/进度条/榜单/趋势条，见 7.2 ④），文字版不画 Unicode 条形图/迷你趋势 | | 多指标 | KPI 行（实收 ¥xx ▲8% · 订单 xx ▲5%） | 经营总览首行 |

④ 可选补充（非必需）：数据量极大（>30 行）或用户明确要求时，可另生成 {主题}_扩展分析.html（复用 scripts/chart.umd.min.js）补充交付；五段式文字分析始终是主交付，HTML 仅是附加。

⑤ 呈现约定：红涨绿跌（中国习惯，文本中用 ▲▼ + 正负号表达）、数字四舍五入、金额 ¥ 千分位。

⑥ 深度完整性（强制，与简洁不冲突）：卡片形态可以简洁，但数据信息必须完整，不得因"简洁"遗漏关键维度——

全平台覆盖：分平台分析时所有平台的关键指标都必须呈现（排名/评分/转化率/佣金率等），不能只展示头部平台就省略其他（如展示了美团排名就必须同时展示淘宝闪购排名、京东无商圈数据要标注"无数据"而非留白）
分平台块标准结构（强制 · 每平台都必须有）：分平台数据按平台逐行呈现，每平台必须包含 5 要素——① 实收/订单/占比 ② 环比 ③ 评分 ④ 商圈收入排行（第X/共Y，含前X%判断）⑤ 一句话判断；无商圈数据平台（如京东）标注"无数据/未接入"而非留白；评分、商圈排行是用户重点关注维度，不得省略或只展示头部平台
全维度覆盖：有数据即展示——排名（含商圈 N/M）、评分、转化率、较昨日、佣金、折扣率等各维度不因卡片空间省略；信息确实不存在（如京东无商圈数据）时明确标注"无数据/未接入"
口径透明：每个数字注明口径（实时/历史、单平台/合并、较昨日此时/较前日），防止歧义
判断先行：数据完整呈现后，必须给出 AI 判断（主因/亮点/风险/下一步），不能只罗列数字
评价场景分平台评分（强制）：评价分析中分平台评分是核心维度，必须逐平台呈现——每平台同时展示「平台展示评分（lastScore）」与「近30日评价均分」双口径（展示分带历史权重、滞后于近期口碑，只看展示分会被误导，如京东展示分4.7但近30日均分3.82），并附菜品/包装/配送分维度评分；缺失维度标注"无数据"（如淘宝无配送评分）

7.2 📊 对话内输出规范（标准交付方式，强制 · 上节在标准报表场景的具体化）

一键生成/回填完成后，默认三件套同时交付：文字结论 + 可视化图表 + 打开 HTML 报表页面（present_files）。用户说"直接输出/不要 md/文字结论同时打开页面"时尤其必须遵循。所有输出遵循上方「7.1 文字版分析输出规范」总纲。

⚠️ 默认打开报表页面（强制，无条件执行）：只要生成了 {报表名}.html，本回合就必须用 present_files 打开它——这是默认行为，不依赖用户是否要求，也不受"用户没让打开"影响。生成 → 交付的固定顺序：① 对话内五段式文字结论 + 图表 → ② present_files 打开 HTML 页面（用户可直接滚动查看）→ ③ md 仅存档。任何一次生成报表后漏开页面 = 交付不完整。

① 输出内容结构（文字部分）：对话内文字版与 7.1 五段式模板一致，差异仅两点——① 核心结论先行（1-2 句：健康评分/等级 + 实收环比定性，如"回落属短期波动"）；② 末尾数据口径注明（当期 vs 前日/上周/上月；商圈对比是否单平台口径）。下滑时在中段插入归因链：实收% ≈ 订单% + 单均% → 订单端拆 曝光% + 转化% → 定性主因 → 分平台逐平台拆解（主拖累/亮点）。

② 可视化图表（随文字同步输出，每张图配一段过渡说明）： | 图表 | 内容 | 适用 | |---|---|---| | KPI 概览卡组 | 6 卡：健康评分/实收/订单/单均/转化率/复购，环比红涨绿跌 | 全部报表 | | 归因拆解 + 转化漏斗 | 三因子条形图 + 曝光→进店→下单→成单漏斗 | 下滑/增长均可用 | | 分平台对比 | 各平台实收 + 环比 + 商圈排名标签 | 单店/门店对齐 | | 品牌分档 | 门店评分优秀/一般/差三档 + 各档门店列表 | 品牌报表 | | 趋势图 | 日/周趋势（评价堆叠柱、实收柱） | 多天周期 |

③ 打开 HTML 页面（三件套之一，强制）：

文字结论 + 图表输出完毕后，必须用 present_files 打开生成的 {报表名}.html（对话内直接可滚动查看完整报表：健康体检/核心指标/各数据板块/AI 诊断区）
若用户同时要求看多份报表，一次性批量打开（如 9 报表引导页 00_报表中心或对应日/周/月三份）
md 文件仅作备份存档，不主动交付（用户明确要 md 才给）

④ HTML 经营分析卡片（对话内渲染 · 场景化，用户要求"卡片/可视化输出"或实时速览时用）：

核心原则：卡片形态由 AI 自主决定——按数据形态选组件、按分析重点排信息层次、按用户关注点取舍，不套固定模板、不硬性规定；下方映射表与组件清单仅作参考（帮助快速选型），AI 可自由组合、增删、创新结构；勿直接贴 HTML 源码（用可视化组件渲染）
五段式骨架（强制，卡片与 7.1 文字版结构一致）：所有卡片自上而下遵循五段式骨架——标题+周期行 → ① 经营总览（KPI/进度条/榜单等数据形态，由下方场景映射决定）→ ② 亮点 → ③ 问题与解决方案（每条带 💡 方案）→ ④ 行动建议（P0/P1/P2） → ⑤ 一句话结论 → 数据来源。②~⑤ 为固定骨架（某段无内容时省略该段，不得把卡片做成"一堆数据+要点"的扁平结构）；数字口径与判断先行遵循 7.1 ⑥ 深度完整性
场景 → 卡片形态参考映射（AI 自主决定，非强制；映射决定「① 经营总览」的数据形态，②~⑤ 骨架固定）：

| 分析场景 | 卡片结构（自上而下） | 核心组件 | |---|---|---| | 实时汇总（品牌/门店） | 标题+周期行 → KPI 卡组（3-5 卡：实收/订单/客单价/佣金/折扣率）→ 关键指标网格（佣金率/毛利率/ROI）→ 要点（涨跌/异常⚠️） | KPI 卡 + 指标网格 | | 单店分平台 | 标题+周期行 → KPI 卡组 → 分平台卡组（必须：每平台「实收/订单/占比/环比 + 评分 + 商圈收入排行第X/共Y·前X%」逐行展示，主平台红 #A32D2D、其余蓝 #378ADD，无商圈数据标注"无数据"） → 要点（佣金对比/折扣率/结构点评/⚠️） | KPI 卡 + 分平台卡（含评分+商圈排行） | | 收入/订单 TOP 排行 | 标题+周期 → 榜首 KPI 大卡（第1名突出）→ 榜单列表（排名/门店/实收/订单/占比/较昨日）→ 头部集中度要点 | 榜单行 + 榜首卡 | | 日报/周报/月报诊断 | 标题+周期 → 健康评分大卡（分数+等级+环比）→ KPI 卡组 → 归因链块（背景色 info/warning）→ 分平台条 → 行动建议 P0/P1/P2 | 评分卡 + 归因块 + 建议列表 | | 近N天/趋势分析 | 标题+周期 → KPI 卡组 → HTML 趋势条（日实收柱状）→ 波动分析要点（峰值/谷值/连续涨跌） | 趋势条 + KPI 卡 | | 评价分析 | 标题 → 评分大卡（评分/好评率/评价数）→ 分平台评分对比卡（必须：每平台「展示评分 + 近30日评价均分 + 菜品/包装/配送分维度」） → 负面标签条形（标签+条数）→ 申诉/整改建议 | 评分卡 + 分平台评分卡 + 标签条 | | 增长/下滑 TOP | 标题+周期 → 增幅榜单（▲/▼ 排序，含增长额与增幅）→ 增长/下滑家数统计 → 共性要点 | 榜单行 + 统计卡 |

通用规范：实收用红涨绿跌强调色（var(--color-text-danger) 涨 / var(--color-text-success) 跌）；金额 ¥ 千分位；占比整数%；每条要点 ≤30 字，异常加 ⚠️；健康评分用 success/warning/danger 色表达等级；背景容器透明（host 提供底色）
组件清单（可自由组合）：KPI 卡（background:var(--color-background-secondary) + border-radius:var(--border-radius-md) + padding 12-16px，label 12px 灰 + 数值 22px/500）、进度条（外 10px 圆角底 + 内 6px 圆角色块）、榜单行（flex space-between + 序号）、归因块（var(--color-background-info) 底 + 结论高亮）、建议块（P0/P1/P2 前缀 + 主色文字）、警示块（var(--color-background-warning) + var(--color-text-warning)）
参考模板（单店分平台·实时 · 五段式骨架，其余场景按映射替换「① 经营总览」数据形态即可）：

<p style="font-size:14px;font-weight:500;margin:0 0 2px;">{品牌}·{门店} · 实时经营分析</p>
<p style="font-size:12px;color:var(--color-text-secondary);margin:0 0 14px;">{日期}实时 · {排名/标签} · {较昨日此时 ▲x%▼x%}</p>

<p style="font-size:13px;font-weight:500;margin:0 0 8px;">一、经营总览</p>
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin-bottom:12px;">
  {KPI卡 × 3-5：<div style="background:var(--color-background-secondary);border-radius:var(--border-radius-md);padding:12px 16px;"><p style="font-size:12px;color:var(--color-text-secondary);margin:0 0 4px;">{label}</p><p style="font-size:22px;font-weight:500;margin:0;color:{涨跌色};">{数值}</p></div>}
</div>
<p style="font-size:13px;font-weight:500;margin:0 0 8px;">分平台结构（每平台含评分 + 商圈收入排行）</p>
<div style="display:flex;flex-direction:column;gap:10px;margin-bottom:14px;">
  {每平台：<div><div style="display:flex;justify-content:space-between;font-size:12px;color:var(--color-text-secondary);margin-bottom:4px;"><span>{平台} ¥{实收} · {订单}单 · 评分{评分} · 商圈{第X/共Y（无则标"无数据"）}</span><span style="color:{主平台?红:蓝};font-weight:500;">{占比}% · {环比}</span></div>
  <div style="background:var(--color-background-secondary);border-radius:6px;height:10px;overflow:hidden;"><div style="width:{占比}%;height:100%;background:{主平台?红:蓝};border-radius:6px;"></div></div></div>}
</div>

<p style="font-size:13px;font-weight:500;margin:0 0 8px;">二、亮点</p>
{亮点 × 1-3：<div style="border-left:3px solid var(--color-text-success);background:var(--color-background-secondary);border-radius:var(--border-radius-md);padding:10px 14px;margin-bottom:8px;"><p style="font-size:12px;margin:0;">{亮点句（数据+判断，≤30字）}</p></div>}

<p style="font-size:13px;font-weight:500;margin:0 0 8px;">三、问题与解决方案</p>
{问题 × 1-3：<div style="border-left:3px solid var(--color-text-danger);background:var(--color-background-warning);border-radius:var(--border-radius-md);padding:10px 14px;margin-bottom:8px;"><p style="font-size:12px;color:var(--color-text-danger);margin:0 0 4px;">{问题（含数据）}</p><p style="font-size:12px;margin:0;">方案：{可执行动作}</p></div>}

<p style="font-size:13px;font-weight:500;margin:0 0 8px;">四、行动建议（优先级）</p>
<div style="display:flex;flex-direction:column;gap:6px;margin-bottom:14px;">
  <p style="font-size:12px;margin:0;"><b style="color:var(--color-text-danger);">P0｜</b>{止血动作}</p>
  <p style="font-size:12px;margin:0;"><b style="color:var(--color-text-warning);">P1｜</b>{放大/修复动作}</p>
  <p style="font-size:12px;margin:0;"><b>P2｜</b>{监控动作}</p>
</div>

<div style="background:var(--color-background-info);border-radius:var(--border-radius-md);padding:12px 16px;margin-bottom:12px;">
  <p style="font-size:12px;margin:0;color:var(--color-text-info);">五、一句话结论：{结论}</p>
</div>

<p style="font-size:11px;color:var(--color-text-tertiary);margin:0;">数据来源：店客多外卖AI运营系统 · {口径}</p>

渲染方式：在 WorkBuddy 对话中用可视化组件（show_widget，HTML 片段）渲染，不要在回复正文里直接贴 HTML 源码（不会渲染成卡片）；_AI分析.md 文件内用 markdown 表格呈现数据（图表由对话内 HTML 卡片承担，见「7.1 文字版分析输出规范」）
红涨绿跌（符合中国习惯）；数据四舍五入展示

8️⃣ 🔗 接口编排（仅当 9 类一键报表覆盖不了时的扩展能力）

先决条件（强制）：本小节只服务「2️⃣ 一键优先路由」三层降级的第 ②③ 层——需求命中 9 类报表（见「5️⃣ 报表体系」表）时必须先跑对应 generate_* 一键脚本，禁止跳级直接编排（见「2️⃣ 禁止条款」）。确认未命中后，才按本节方法论扩展。

核心原则：9 类标准报表是模板，覆盖不了的需求不限制在预设场景里——AI 应像工程师一样，把需求拆解成「意图 → 接口 → 组合」，用 chain_business.py 底层接口动态编排出结果。extend_query.py 只是示例参考（演示编排写法），不是能力上限。

编排方法论（三步 · 完整意图识别表 / 接口组合表见 接口能力与应用场景.md）：

⓪ 五维拆解（面对任何客户数据分析需求的第一步，强制）：把客户的话翻译成 5 个参数——对象（品牌/门店/平台/区域/门店组）× 时间（实时/单日/区间/趋势）× 粒度（汇总/每店/每日）× 指标（营收/订单/转化/评价/推广/结构）× 动作（查询/排名/对比/归因/导出/诊断）。5 维缺哪个问哪个（≤2 问），确定后接口选择唯一化，直接执行不确认。
🔋 最少调用原则（效率优先 · 决定用几个接口前先算这笔账）：一个需求能 1 次调用完成，绝不用 2 次——五维拆解后先问自己"最少需要哪几个接口、各几次"，再动手：
- 一次带全指标：query_history_list / query_history_daily 的 quota_codes 一次传全部所需指标（默认 12 项核心，需要更多就一次传全），禁止同一区间按指标分多次查询
- 实时自带对比：说"今天"用 query_realtime_list，previousValue 即昨日同时段对比——不需要再拉一次 history 算环比（省 1 次）
- 汇总用 summary：只要"品牌总共/区域总共"→ query_history_summary / query_realtime_summary 一次搞定；禁止用 list 拉全量门店再自己求和（省 1 次且更准）
- 粒度三选一勿混：汇总=summary / 每店=list / 每日=daily，一次需求只选一个粒度，不跨粒度重复拉数
- 评价独立单查：评价类需求单独 query_evaluate_detail 一次查全（含评分/内容/标签/申诉字段），不要同时调经营接口；负面标签字段 labels 接口可能不返回，需按「11️⃣ 数据口径 · 负面标签（容错双轨）」处理
- 门店筛选合并：search_shops 一次带全部筛选条件（brand+platform+city+tag），不要分多次筛选再合并
- 复用同批数据：同一门店集合、同一区间的多次分析（如"TOP + 增长 + 占比"）→ 一次 list 拉回全部指标，内存里做多种聚合，不要每类分析各拉一次
- 批量参数合并：多门店一次性传（batch 上限内），不要逐个门店单独调用
- ⚖️ 最少调用 ≠ 浅分析（效率与深度必须平衡）：省的是接口调用次数，不是分析深度——一次调用带回全指标后，AI 必须在内存里挖透：三因子归因（实收≈订单+单均，订单≈曝光+转化）、转化漏斗拆解（曝光→进店→下单→成单）、平台结构占比、环比/同比拆分、推广 ROI 与费效、评分/评价信号。数据一次拿回，深度靠"分析"而非"再调用"；禁止出现"调用少了但输出只有几行数字"的浅交付——宁可调用数相同、也要把同批数据的所有分析维度榨干（对照「7.1 输出规范」五段式 + 深度完整性⑥）
① 意图识别：今天/实时 → realtime 系列（list 自带「较昨日此时」对比：每条 field 含 value 今日 + previousValue 昨日同时段，无需另查历史）；某日/区间/趋势 → history 系列（汇总→summary / 每店→list / 每日→daily 三选一，勿混）；评价/差评 → query_evaluate_detail（独立维度另查）；门店/品牌/城市/平台筛选 → search_shops（先于一切，提供门店列表）；字段/平台口径 → get_metric_fields；导出 → fetch_and_export_*
② 接口组合（按需求语义拼接，可自由嵌套，优先单接口方案）：TOP N = search_shops → query_history_list/query_realtime_list → 聚合排序取 N；两日增长 = 两个日期各一次 list 的差值排序（注意：这是少数必须 2 次调用的情况，因为要对比两个日期）；单店分平台 = search + query_realtime_list（含平台字段 + 昨日此时对比）分组；实时进度对比 = realtime_list 的 previousValue（即昨日同时段值）直接算增幅，无需再拉历史；区间趋势 = query_history_daily；汇总+明细 = summary + list 双查（仅当客户同时要"总数+分店"时）；15 个高频需求组合模板见 接口能力与应用场景.md ③（命中即套用，未命中才现场编排）
③ 结果呈现（遵循「7.1 文字版输出规范」，强制）：编排结果同样采用 9 报表五段式文字版格式——# 品牌/门店扩展分析 · {主体}（{场景}） + 周期行 → ## 一、经营总览（KPI 行 + markdown 指标表）→ ## 二、亮点 / ## 三、问题与解决方案（💡 方案）/ ## 四、行动建议（P0/P1/P2） / ## 五、一句话结论 → 末尾 > 数据来源：店客多外卖AI运营系统 · ...；数据口径注明（实时/历史、聚合方式）

参考实现：scripts/extend_query.py 已把 5 个高频示例封装成 --action（realtime-summary / realtime-top / history-top / growth-top / realtime-shop），只输出数据表（汇总行 + markdown 表格），可直接取数；更复杂的需求请按上面方法论现场编排（可复用该脚本的解析/聚合函数与 _md_table 表格渲染函数；_hbar/_mini_trend 文本图表函数已弃用——图表改由对话内 HTML 卡片渲染，不再用于输出）。

💡 TOP 排行扩展参数（realtime-top / history-top 通用）：--sort-by receipts|orders（默认实收，可改按订单排序，占比列随排序维度联动）；--platform 美团外卖/淘宝闪购/京东外卖（单平台排行，记录层精确过滤，输出平台列；用户说"饿了么"→ 映射为淘宝闪购）。 ⚠️ 门店聚合键（三级，任意一级命中即同一家店）：聚合必须用 _item_store_key——① alignmentId（最权威，同店多平台共享；realtime/history 记录不带，需用 search_shops 构建 {shopUniqueKey: alignmentId} 映射关联）；② shopAliasName；③ shopName；均缺失回退括号内名。展示名用 _item_display_name（与聚合键分离）。原因：同店在美团/淘宝/京东的 shopName 表述可能不同（如京东缺"·火鸡面"），按完整名聚合会拆店漏算（曾漏京东数据）；_norm 统一全角括号与 •/· 分隔符。

判定（强制顺序）：先问 9 类标准报表能否覆盖 → *能则必须 generate_ 一键脚本（禁止自写脚本）**；不能 → 才现场接口编排，不局限于预设场景。

📋 接口能力全集、参数签名、返回结构、组合示例见 接口能力与应用场景.md（技能根目录，随包分发）。

9️⃣ 🧠 AI 深度分析（6 层框架 + 运营专家视角 + 诊断规范）

9.1 6 层框架（逐层下钻，不能只看总量）

分析诊断必须按此框架逐层下钻，不能只看总量——每层都要拆到"可行动的主因"：

① 总量层   实收 = 订单 × 单均          → 整体三因子拆解（下滑时必拆）
② 分平台层 每个平台独立拆解：
           实收% ≈ 订单% + 单均%
           订单% ≈ 曝光% + 转化Δ
           叠加评分/商圈排名/推广投放 → 定位"下滑平台 + 平台内下滑因子"
③ 商圈层   自身 vs 商圈均值 vs 前10%    → 倍数（曝光/进店/下单）、转化率 pp、排名
④ 时间层   环比（前日/上周/上月）+ 同比（上周同期/去年）→ 区分短期波动 vs 趋势性下滑
⑤ 结构层   平台占比变化、新老客结构、复购、毛利 → 健康度
⑥ 行动层   按 P0（止血）/ P1（优化）/ P2（放大）给可执行方案

核心方法——下滑归因链（必须逐层定位主因）：

实收下滑 -X% 
  → 拆：订单 -A% + 单均 -B%（谁贡献大谁是主因）
  → 订单下滑再拆：曝光 -C% + 转化 Δpp（流量端 or 承接端）
  → 定位到平台：哪个平台拖累最大？该平台内部又是哪个因子？
  → 结论 + 专属方案（如：京东实收-26.9% = 订单-30%+单均+3%，主因订单→查活动/排名）

规则版扫描器已内置（关键数据问题自动拆解）：

总量三因子 + 同比 + 单均/订单下滑
分平台逐平台拆解（任一平台环比<-5% 即输出：实收%≈订单%+单均%，主因判定，订单≈曝光%+转化Δ）
商圈对比（转化率低于商圈/前10%）、毛利、复购、取消、推广 ROI 阈值扫描

9.2 🎯 外卖运营专家诊断视角

AI 诊断必须站在专业外卖运营角度——不是罗列数据，而是用运营杠杆拆解问题、给可落地的运营动作。核心 6 大杠杆：

① 流量杠杆   曝光量/曝光结构（自然流量 vs 付费 vs 活动位）
             商圈排名（第X/共Y、前10%）、时段覆盖 → 流量是否充足、地位是否稳固
② 转化杠杆   漏斗效率（曝光→进店→下单）
             进店转化率（门头/首图/评分/活动标识）、下单转化率（菜单/价格带/满减/起送价）
③ 客单杠杆   单均实收、凑单设计（加购/套餐/第二份半价）、满减梯度合理性
④ 复购杠杆   复购率、老客占比、会员/储值、评价引导
⑤ 口碑杠杆   评分/好评率、差评标签集中度、评价回复率
⑥ 推广活动杠杆 ROI、占收比、活动档期节奏、预算分配（高转化平台加投）

诊断输出规范（verdict/问题&方案必须体现运营视角）：

| 数据现象 | 外卖运营解读 | 专业运营方案 | |---------|-------------|-------------| | 曝光下滑/排名降 | 流量端失血（自然排名/活动位收缩）| 检查自然排名因子（评分/销量/复购），评估参与平台大促/满减活动回补流量 | | 进店转化率 < 商圈 | 门头/首图/评分展示承接弱 | 首图卖点重构、门头信息对标商圈头部、评分/销量数字外显 | | 下单转化率低 | 菜单结构/价格带/满减梯度不合理 | 调起送价与满减梯度（如 30-20/50-30）、优化品类排序、突出高毛利爆品 | | 单均低 | 客单价结构失衡（缺凑单设计）| 设加购/套餐/第二份半价，提高满减门槛引导凑单 | | 复购低/下滑 | 顾客粘性不足 | 会员/储值活动、复购券（满X减Y限老客）、评价返券 | | 评分低/差评集中 | 口碑风险（标签集中=品类短板）| 针对差评标签集中整改（口味/包装/时长），差评及时回复+补偿 | | ROI 低/占收比高 | 投放效率差/投放过重 | 收缩低效平台预算，聚焦高转化平台与时段加投 |

诊断句式要求：每个问题 = 数据现象 → 运营归因 → 可执行方案（含具体动作/门槛/活动形式），避免"建议优化"类空话。

9.3 诊断深度要求（参考门店月报标准）

📝 verdict：数据 + 环比/同比 + 定性结论（如"回落属短期波动而非结构恶化"）
🟢 亮点 4-6 条：盈利结构 / 平台均衡 / 转化率优势 / 商圈地位 / 履约 / 口碑
🔴 问题&方案 4-6 组配对：每条问题带具体方案（归因拆解：实收%≈订单%+单均%，订单%≈曝光%+转化%）
诊断文件 JSON 结构：见「6.2 步骤②」；文件命名 ai_diagnosis_{门店/品牌}_{daily/weekly/monthly}.json，report_date 必须匹配报表日期（日报=CUR_DATE、周报/月报=CUR_END_S；近N天=CUR_END_S），不匹配自动跳过回退规则诊断，防跨日期/跨周期误回填

1️⃣0️⃣ 报表统一特性（HTML 布局细节）

健康体检模块（页面顶部）：AI 健康评分大卡（分数+等级+环比）→ 门店/品牌健康体检表（7~8 维度，含商圈排名），点击「查看详情」下钻对应板块
AI 健康评分：三类报表均置于「健康体检」模块顶部（品牌=品牌健康评分，默认 70 分可被 AI 诊断回填覆盖）
AI 诊断建议板块：位于核心指标模块之上（体检 → AI诊断 → 核心指标 → 各数据板块）
单平台评分+商圈并排：门店单平台报表将「门店健康评分」与「商圈收入排行」左右并排展示（核心指标模块不再重复展示商圈排行）
商圈收入排行卡（单平台）：🏆 大数字名次 + TOP徽章（前X%）+ 进度条 + 排名变化对比（▲升N位/▼降N位/持平，红涨绿跌），对比口径随周期（较前日/较上周/较上月）
板块 AI 小结：7 个数据板块（核心/利润/流量/推广/评价/复购/取消）尾部各一条 💡 AI 小结（数据+环比+结论句），融入板块主题色（sec-ai-note）
AI 诊断区：两列形式——🟢 亮点（白卡绿边）+ 🔴 问题诊断&解决方案（每条配 💡 方案）
分平台表：值行 + 下方对比行（日报三行含较上周，周报/月报两行），不新增对比列头
趋势图：周报带日趋势（X 轴含周几，如"8/3 周一"）；月报带日趋势（仅 M/D，31 天标签过密不加周几）；品牌日报无趋势
商圈对比：流量表每平台含"商圈均值"+"商圈前10%"行（自身 vs 门槛 ✓进入/未达），京东无商圈数据标注
流量板块布局：左漏斗图（曝光→进店→下单）+ 右 6 张 KPI 卡（曝光/进店/下单 + 进店/下单/综合转化率，3×2），下方日趋势图
推广板块：推广花费/占收比/ROI/单均成本 4 卡（≤980px 断点 2×2 整齐，与上方模块宽度一致）

1️⃣1️⃣ 数据口径（关键）

财务口径（v124）：财务估算毛利 = 估算财务净毛利 + 门店推广花费；财务估算净毛利 = 估算财务净毛利；毛利率/净毛利率 = 对应毛利 ÷ 财务收入（未扣自动充）。页面不出现英文字段名（billProfitCpc/billRevenueNotAuto 等仅公式注释，公式只在利润板块用纯中文展示）
评分构成：从评价明细统计（过滤 invalidType 无效后：好评4-5星/中评3星/差评1-2星），与负面标签同源；评价总数行标注「有效 X 条 · 无效 Y 条」
评分双口径（评价分析必须区分）：① 平台展示评分 = 明细的 lastScore（平台计算、带历史权重、滞后于近期口碑）；② 近30日评价均分 = 有效评价 commentScore 的算术平均（反映近期真实口碑）。两口径差异大时是危险信号（如展示分 4.7 但近30日均分 3.82），必须同时呈现并解释背离；分维度评分 = 菜品 orderCommentScore / 包装 packingScore / 配送 deliveryCommentScore（0 值视为未评，跳过不计）
负面标签（容错双轨，强制）：评价明细的负面标签字段为 labels（EVALUATE_HEADERS 已映射「评价标签」）。接口可能返回、也可能不返回该字段（实测 evaluate_detail 当前不携带，全平台全记录均无），处理规则：
- ① 若明细含 labels → 直接用平台真实标签归因（比人工归类准确），按标签统计条数，输出标注"来源：平台评价标签"
- ② 若明细无 labels → 回退为差评内容（commentScore≤2）人工归类（如肉质/酱汁/份量/配送/售后主题），输出必须注明"平台未返回标签，按差评内容归类"，不得假装是平台标签
- ③ 聚合脚本需做字段存在性检查（'labels' in record），禁止假定一定有或一定没有；仅统计有效评价（排除删除/不计入评分）
申诉成功评价列表：评价板块新增「⚖️ 申诉成功评价」（appealSuccess==2），展示评分/平台/内容
商圈排名：list 接口（shopIdType=1）单店形式获取，已并入 QUERY_CODES 一次查询（summary 0 调用）
商圈流量对比：daily 接口 + shopIdType=1；周报/月报取周期汇总（量字段求和、比率字段日均）
评分：周期内最新（lastOfShopScore），分平台对比行含评分 pp
营业天数：日实收>0 天数（月报分母按自然月天数）
单平台查询优化：门店单平台报表只查 shopIdType=1 分平台数据（当期/环比/同比 3 次），跳过被覆盖的全平台汇总查询

1️⃣2️⃣ 接口异常处理（chain_business.py 内置）

| 状态 | 处理 | |------|------| | 200 | 正常返回 | | 401 | 打印「请到【店客多 AI 技能中心】https://ka.diankeduo.net/#/crayfish/index 获取有效 Token」+ 抛 RuntimeError | | 429 | 打印「今日调用次数已达上限，隔天自动恢复」+ 抛 RuntimeError | | 其他 | 打印状态码 + 响应体；网络异常打印接口地址 |

1️⃣3️⃣ 📋 9 报表分析·诊断场景（只讲"分析什么 / 诊断看什么"，命令见 5️⃣）

门店对齐报表

| 报表 | 用户问法（触发示例） | 分析重点 | AI 诊断关注点 | |------|--------------------|---------|--------------| | 门店对齐日报 | "XX门店昨天数据怎么样" / "帮我看看XX门店今天的经营" / "XX门店数据怎么样"（当天语境）| 当日实收/订单/单均、较前日+较上周同比、分平台异动、商圈排名日变化 | ① 实收环比下滑 → 三因子拆解（实收≈订单+单均，订单≈曝光+转化）② 分平台主拖累（<-5%）③ 转化率 vs 商圈均值/前10% ④ 单日评分/差评 | | 门店对齐周报 | "XX门店这周/上周怎么样" / "分析下XX门店本周经营" | 自然周汇总 vs 上周、日趋势节奏（周末效应）、分平台均衡度、商圈地位周变化 | ① 周度环比趋势 ② 趋势异常日（骤降/骤升定位）③ 平台结构偏移 ④ 复购与推广效率周对比 | | 门店对齐月报 | "XX门店这个月/上个月数据怎么样" / "这个月XX门店表现如何、月度总结" | 月汇总 vs 上月、30日复购、全勤天数、商圈排名月变化、客单价 | ① 月环比大涨/大跌归因 ② 复购健康度（粘性）③ 商圈地位变动（排名升降）④ 毛利结构与客单价 |

门店单平台报表（单平台口径）

| 报表 | 用户问法（触发示例） | 分析重点 | AI 诊断关注点 | |------|--------------------|---------|--------------| | 门店单平台日报 | "XX门店美团昨天数据怎么样" / "XX门店在美团的表现" | 该平台单日实收/订单/单均、商圈收入排行（第X/共Y）、商圈流量对比（均值/前10%）、单平台转化率 | ① 该平台实收环比下滑归因（订单/单均拆解）② 商圈排名日变化（↑↓位）③ 转化率 vs 商圈均值/前10% ④ 该平台评分/差评 | | 门店单平台周报 | "XX门店美团这周怎么样" / "XX门店在美团周度分析" | 该平台周汇总 vs 上周、日趋势、商圈排名周变化、单平台复购/推广 | ① 周环比趋势 ② 商圈地位周变化（排名升降）③ 该平台转化/复购健康度 | | 门店单平台月报 | "XX门店美团这个月怎么样" / "XX门店美团月度总结" | 该平台月汇总 vs 上月、商圈排名月变化、客单价、毛利结构 | ① 月环比大涨/大跌归因 ② 商圈地位变动 ③ 该平台毛利与客单价 |

品牌报表（全品牌汇总）

| 报表 | 用户问法（触发示例） | 分析重点 | AI 诊断关注点 | |------|--------------------|---------|--------------| | 品牌日报 | "XX品牌昨天怎么样" / "全品牌今天数据" | 全品牌单日实收/订单/单均、平台结构、当日异动 | ① 单日大幅异动（活动效应/闭店/系统问题）② 单均与转化率当日水平 ③ 平台集中度风险 | | 品牌周报 | "XX品牌这周怎么样" / "品牌周经营分析/周度会议" | 品牌周汇总 vs 上周、门店等级分布（商圈前10%）、TOP/下滑门店、新店进度 | ① TOP 门店亮点提炼复制 ② 下滑门店定位止损 ③ 新店爬坡管理 ④ 品类毛利与复购 | | 品牌月报 | "XX品牌这个月怎么样" / "品牌月度总结/扩张决策" | 月汇总 vs 上月、新增门店数、城市分布、门店等级结构、单店盈利分布 | ① 扩张节奏是否健康 ② 单店盈利分布（长尾/集中）③ 新店爬坡期占比 ④ 客单价与转化提升空间 |

场景选择速查（用户问法 → 报表）

"XX门店数据怎么样 / XX门店昨天(今天)怎么样"   → 门店对齐日报
"XX门店这周/上周怎么样"                      → 门店对齐周报
"XX门店这个月/上个月怎么样 / 月度总结"        → 门店对齐月报
"XX门店 美团 昨天/这周/这个月怎么样"          → 门店单平台 日/周/月报（--platform 美团外卖）
"XX品牌 昨天(今天)数据怎么样 / 全品牌数据"    → 品牌日报
"XX品牌 这周怎么样 / 品牌周经营会议"          → 品牌周报
"XX品牌 这个月怎么样 / 品牌月度总结"          → 品牌月报
"XX品牌 XX门店 分析一下 / 看XX门店经营细节"   → 门店对齐系列（含商圈对比/分平台明细）
"看XX品牌健康度/扩张/门店分布"               → 品牌系列（含门店等级/城市分布）
"XX门店 近7天数据 / XX品牌 近3天经营"        → 近N天分析（周报模板 + --days N）
"XX门店 8月1日到8月10日数据" / "XX品牌 7月1日~7月15日分析" → 自定义日期范围分析（周报模板 + --start --end）

1️⃣4️⃣ 🔬 门店诊断（美团 / 淘宝闪购 · 按平台路由）

触发：客户说"诊断XX门店 / 帮我诊断店铺" → 按平台路由：提到美团 → 美团诊断逻辑；提到淘宝/闪购/饿了么（饿了么并入淘宝闪购）→ 淘宝诊断逻辑；未指定平台 → 美团优先（诊断体系最全）。

数据获取（先取数，拿不到才引导）：

一键取数（诊断轻量模式 --diagnose，默认近 7 天）：python scripts/generate_platform_weekly.py --shop X --platform <美团外卖/淘宝闪购> --days 7 --diagnose（仅 3 次接口：当期+上期分平台列表 + 商圈对比；自动跳过评价明细/同比/日趋势/HTML；输出 diagnostic_data.json 含 biz_cmp 商圈均值/前10%）；用户指定周期（近30天/本月等）按指定
判定 = 直接读 scripts/diagnostic_data.json：summary（转化率/评分/复购/新老客占比）+ biz.plat_rank（收入排名/商家数）+ biz_cmp（商圈均值与前10%门槛）+ neg_*（差评标签）+ firstOpenTime/earliestOpenDate/openDays（门店开业信息展示）→ 按对应平台诊断文档七维度阈值逐项判定，无需再读 HTML 或现场检索。口径唯一（强制）：③ 下单转化率一律用 summary.orderConversionRate（进店→下单）对比 biz_cmp.<平台>.orderConversionRateAvg / top_ocr，禁止用 comprehensiveConversionRate（综合转化率是派生指标，勿混）
可判定维度（用接口数据）：① 同行收入排名 ② 曝光总体 ③ 下单转化率 = orderConversionRate（进店→下单；≠ 综合转化率 comprehensiveConversionRate）（总体/新老客）④ 入店转化率（总体/新老客）⑤ 复购率（总体/新老客）⑥ 综合评分 = 门店评分（接口 shopScore 直接判定，≥4.6 合格；子项权重公式作为优化建议参考） ⑦ 店铺名称合理性（用 search_shops 返回的 shopName/shopAliasName 直接诊断，无需后台）——按「品牌+品类+（门店）」格式判定（见各平台诊断文档「名称合理性诊断」）；门店开业信息 = 独立展示项（非判定维度）：用 firstOpenTime/earliestOpenDate/openDays 单独展示开业时间与时长，openDays≤30 标「新店」徽章（仅标识不判优劣，见各平台诊断文档「门店开业信息」）
需引导排查维度（接口无数据 → 引导用户到商家后台查看后回填）：
- 店铺分（100 分制 ≥90 合格；总分子项接口有则判，无则引导商家后台「门店管理/店铺分」；店铺分构成两平台不同，见各平台文档）
- 自然/付费流量占比 → 引导「经营数据/推广后台 → 流量来源」
- 商家配置项（菜品 SKU/分组/福利区/明厨亮灶/海报/店招/橱窗/公告/餐盒费/减配金额等）→ 引导「门店装修/菜品管理」逐一排查

两平台诊断区别对照（重要，判定时按平台选用）：

| 区别点 | 美团外卖 | 淘宝闪购 | |---|---|---| | 评分维度命名 | 商家综合体验分 | 综合评分（最重要的指标） | | 综合评分首子项（权重30%） | 商品满意度 | 口味满意度 | | 店铺分构成 | 含不接单率10%/商家评分20%/差评回复10% | 含最低起送价2%/顾客评分4%/在线联系回复率4%/送达准时率10%/商责取消率10%/有效活动丰富度10%/菜单11% | | 下单转化检测 | 多「菜品分组名称≤8字符」项 | 无该检测项 | | 官方功能清单 | 11 个（含优惠券） | 10 个（无优惠券） | | 活动/功能体系 | 平台独立：活动名称/可用活动按美团后台活动中心为准（天天神券/神枪手等美团系活动） | 平台独立：活动按淘宝闪购后台活动中心为准（勿套用美团活动名） | | 综合评分判定 | = 门店评分 ≥4.6 合格 | = 门店评分 ≥4.6 合格（一致） |

诊断输出：按 7 大维度逐项给「优秀 / 合格 / 需要优化」判定 + 数据支撑 + 建议（配置类给"建议有/建议X"）；接口判不了的维度明确标注"需商家后台确认"并列出排查项，不得凭空判定；结尾附「推荐平台官方功能」名称清单（只给功能名，按平台清单）。

⚠️ 偏低必挂方案（强制）：凡判定为「需要优化」或「合格偏低」的维度，必须自动挂接对应解决方案（含可调用的分析能力如评价分析/推广诊断/差评申诉/自动回复，及平台功能名）——见各平台文档「九、诊断结果→解决方案映射」，不得只给判定不给方案；判定「优秀」的维度可跳过。

诊断卡片形态（强制 · 对话内渲染）：信息量不减的完整五段式，六段齐全、禁止极简砍信息（如只给七维度网格）： ① 标题+周期行 → ② 维度判定网格（8格：①收入排名 ②曝光 ③下单转化 ④入店转化 ⑤复购 ⑥综合评分 ⑦店铺分 ⑧名称，每格=判定+数值，优秀绿/需优化红/需关注琥珀）→ ③ 优秀维度（数据判定）（每维度给数据依据，不重复判定词）→ ④ 需优化维度挂方案（偏低必挂方案，见上）→ ⑤ 行动建议 P0/P1/P2（一行概括，不重复④方案细节）→ ⑥ 一句话结论 + 数据来源。门店开业信息放在标题行下方周期信息行内（显眼位置，非判定）：周期行末尾追加 · 开业 {earliestOpenDate}（约{时长}），openDays≤30 标「新店」徽章，不单独占行。 不设无障碍标题（用户要求：直接显示诊断报告正文即可，省略无障碍标题）。 ③ 下单转化格必须显示 orderConversionRate 正确值（如 27.2% 优秀）；综合转化率 comprehensiveConversionRate（如 0.81%）只作④入店转化维度的成因解释，禁止填入③、禁止出现在"需优化"区。参考模板：

<p style="font-size:14px;font-weight:500;margin:0 0 2px;">{品牌}·{门店} · 美团平台诊断</p>
<p style="font-size:12px;color:var(--color-text-secondary);margin:0 0 14px;">{平台} · {周期}（近7天）· 实收 ¥{实收}({环比}) · 评分 {评分} · 开业 {earliestOpenDate}（约{时长}）{openDays≤30 则加：「新店」}</p>
<p style="font-size:13px;font-weight:500;margin:0 0 8px;">七维度判定</p>
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:8px;margin-bottom:14px;">
  {每维一格：<div style="background:var(--color-background-{success|danger});border-radius:var(--border-radius-md);padding:10px 12px;"><p style="font-size:12px;margin:0 0 2px;color:var(--color-text-{success|danger});">① 收入排名</p><p style="font-size:15px;font-weight:500;margin:0;">优秀 · 第2/28</p></div>}
</div>
<p style="font-size:13px;font-weight:500;margin:0 0 8px;">优秀维度（数据判定）</p>
<div style="display:flex;flex-direction:column;gap:8px;margin-bottom:14px;">
  {每维：<div style="border-left:3px solid var(--color-text-success);background:var(--color-background-secondary);border-radius:var(--border-radius-md);padding:10px 14px;"><p style="font-size:12px;margin:0;"><b>① xxx — 优秀</b>：{数据依据}</p></div>}
</div>
<p style="font-size:13px;font-weight:500;margin:0 0 8px;">需优化维度 → 已自动挂接解决方案</p>
{每维：<div style="border-left:3px solid var(--color-text-danger);background:var(--color-background-warning);border-radius:var(--border-radius-md);padding:10px 14px;margin-bottom:8px;"><p style="font-size:12px;color:var(--color-text-danger);margin:0 0 4px;"><b>④ xxx 2.98% — 需要优化</b>（{对比}）</p><p style="font-size:12px;margin:0;">方案：{能力/功能名}</p></div>}
<p style="font-size:13px;font-weight:500;margin:0 0 8px;">行动建议（优先级）</p>
<div style="display:flex;flex-direction:column;gap:6px;margin-bottom:14px;">
  <p style="font-size:12px;margin:0;"><b style="color:var(--color-text-danger);">P0｜</b>{动作}</p>
  <p style="font-size:12px;margin:0;"><b style="color:var(--color-text-warning);">P1｜</b>{动作}</p>
  <p style="font-size:12px;margin:0;"><b>P2｜</b>{动作}</p>
</div>
<div style="background:var(--color-background-info);border-radius:var(--border-radius-md);padding:12px 16px;margin-bottom:12px;">
  <p style="font-size:12px;margin:0;color:var(--color-text-info);">五、一句话结论：{结论}</p>
</div>
<p style="font-size:11px;color:var(--color-text-tertiary);margin:0;">数据来源：店客多外卖AI运营系统 · {平台}单平台近7天（{周期} vs {上周}）；判定按「{平台}门店诊断逻辑.md」七维度+诊断-方案映射；综合评分=门店评分；流量结构/商家配置项需商家后台确认</p>

完整判定标准：见同目录 美团门店诊断逻辑.md / 淘宝门店诊断逻辑.md（七维度全部阈值 + 检测项 + 综合评分/店铺分公式与子项权重 + 官方功能表）。