客户反馈分析（QSC + NPS）

Skill 职责边界：本 Skill 专注客户反馈的量化分析与报告生成（QSC 评分 + NPS 计算 + 多平台聚合 + NLP 情感 + 区域/门店对比）。不联动工单系统——只输出"问题列表"供用户手工分发。不联动配方/营养 Skill——反馈数据是客服线，与 recipe-and-cooking-process 解耦。

触发路由总览

| 用户意图 | 触发词 | 加载内容 | |---------|--------|---------| | 数据导入 | 导入/CSV/Excel/问卷/点评 | references/platform-specs/ + scripts/data_importer.py | | 平台特定导入 | 大众点评/美团/淘宝闪送/京东秒送/品牌问卷 | 对应 references/platform-specs/platform-{name}.md | | QSC 评分 | QSC/品质/服务/环境卫生 | references/qsc-nps-scoring.md + scripts/qsc_calculator.py | | NPS 计算 | NPS/净推荐值/推荐意愿 | references/qsc-nps-scoring.md + scripts/nps_calculator.py | | NLP 情感分析 | 情感/语义/差评/正面/负面 | references/nlp-engine.md + scripts/nlp_local_analyzer.py | | 调用云 NLP | 阿里云/百度云/NLP API | references/cloud-nlp-alibaba.md 或 cloud-nlp-baidu.md | | 报告生成 | 周报/月报/日报/分析报告 | scripts/report_generator.py | | 看板可视化 | 看板/可视化/趋势图/排名 | assets/report-templates/dashboard.html + scripts/dashboard_generator.py | | 区域对比 | 区域对比/区域排名/大区/分公司 | references/region-comparison.md + scripts/region_analyzer.py | | 预警 | 预警/差评预警/异常检测 | references/alert-rules.md + scripts/alert_engine.py | | 问题列表 | 问题列表/差评列表/差评清单 | scripts/issue_extractor.py |

核心数据流

5 平台原始数据（CSV/Excel）
  ↓
[1] data_importer.py        读取各平台文件
  ↓
[2] data_normalizer.py      字段标准化 → 统一 schema
  ↓
[3] qsc_calculator.py       QSC 评分（品质/服务/环境卫生）
  +
[4] nps_calculator.py       NPS 计算（推荐者 - 贬损者）
  +
[5] nlp_local_analyzer.py   情感分析（本地 NLTK + 词库）
  或
[5'] nlp_cloud_analyzer.py  云 API（阿里云/百度云）
  ↓
[6] alert_engine.py         预警（差评激增/关键词命中/连续低分）
  +
[7] region_analyzer.py      区域/门店对比
  ↓
[8] dashboard_generator.py  HTML 看板（Plotly 图表）
  +
[9] report_generator.py     周报/月报（HTML/PDF）
  +
[10] issue_extractor.py     问题列表（按门店/类型聚合，导出 Excel）

场景A：批量导入多平台反馈

触发词：导入 / CSV / Excel / 问卷 / 点评

工作流：

Step 1 → 用户准备 5 平台 CSV/Excel（按 references/platform-specs/ 模板）
Step 2 → 调 scripts/data_importer.py --platform {name} --input {file}
Step 3 → 字段映射（自动识别/手动指定列名）
Step 4 → 标准化（写入 SQLite/JSON 统一 schema）
Step 5 → 输出标准化文件 + 导入报告（多少条成功/失败/异常）

典型命令：

# 导入品牌问卷
python scripts/data_importer.py --platform brand_survey --input data/brand_2026Q2.csv

# 批量导入 5 平台
python scripts/data_importer.py --batch --input-dir data/2026Q2/

# 只看导入示例
python scripts/data_importer.py --demo

完整内容：见 references/platform-specs/ + scripts/data_importer.py --help

场景B：QSC 评分 + NPS 计算

触发词：QSC / 品质 / 服务 / 环境卫生 / NPS / 净推荐值 / 推荐意愿

QSC 评分规则（详见 references/qsc-nps-scoring.md）：

| 维度 | 子项示例 | 评分（1-5） | 权重 | |------|---------|-----------|------| | Q 品质 | 口味/分量/温度/食材新鲜度 | 1-5 | 40% | | S 服务 | 响应速度/态度/专业度/错误率 | 1-5 | 35% | | C 环境卫生 | 桌面/地面/卫生间/餐具/异味 | 1-5 | 25% |

NPS 计算：

推荐者（9-10 分）占比 - 贬损者（0-6 分）占比 = NPS（-100 ~ +100）
行业基准：餐饮 NPS ≥ 50 为优秀，30-50 为良好，< 30 需改进

典型命令：

# 计算 QSC
python scripts/qsc_calculator.py --input data/normalized_2026Q2.csv --output reports/qsc_score.csv

# 计算 NPS
python scripts/nps_calculator.py --input data/normalized_2026Q2.csv --group-by store

完整内容：见 references/qsc-nps-scoring.md + scripts/qsc_calculator.py --help / nps_calculator.py --help

场景C：NLP 情感分析

触发词：情感 / 语义 / 差评 / 正面 / 负面 / 关键词 / 评论分析

双引擎：

本地（默认）：NLTK + 中文情感词典（scripts/sentiment_lexicon_zh.json）
云 API（可选）：阿里云 NLP / 百度云 NLP（用户填 API key）

本地分析输出：

情感极性（positive/neutral/negative）+ 置信度
关键词提取（Top 10 高频词）
差评根因标签（出餐慢/态度差/份量少/异物/温度低...）

云 API 增强：

更准的情感分类（深度学习模型）
细粒度情绪（愤怒/失望/惊喜/期待...）
实体识别（具体菜名/服务环节）

典型命令：

# 本地分析
python scripts/nlp_local_analyzer.py --input data/normalized_2026Q2.csv --output reports/nlp_local.csv

# 云 API（阿里云）
python scripts/nlp_cloud_analyzer.py --provider alibaba \
    --api-key YOUR_KEY --api-secret YOUR_SECRET \
    --input data/normalized_2026Q2.csv

# 云 API（百度云）
python scripts/nlp_cloud_analyzer.py --provider baidu \
    --api-key YOUR_KEY --api-secret YOUR_SECRET \
    --input data/normalized_2026Q2.csv

完整内容：见 references/nlp-engine.md + cloud-nlp-alibaba.md + cloud-nlp-baidu.md

场景D：区域/门店对比

触发词：区域对比 / 区域排名 / 大区 / 分公司 / 门店排名

对比维度：

QSC 三维度对比（雷达图）
NPS 排名（横向条形图）
差评率（时间趋势）
关键词云（区域特征）

典型命令：

# 全量区域对比
python scripts/region_analyzer.py --input data/normalized_2026Q2.csv --output reports/region_compare.html

# 指定区域（如华东 vs 华南）
python scripts/region_analyzer.py --input data/normalized_2026Q2.csv \
    --regions "华东,华南" --output reports/region_hd_hn.html

# 单店深度分析
python scripts/region_analyzer.py --input data/normalized_2026Q2.csv \
    --store-id SH001 --detail

完整内容：见 references/region-comparison.md + scripts/region_analyzer.py --help

场景E：周报/月报自动生成

触发词：周报 / 月报 / 报告 / 分析报告

报告结构：

本期概览（NPS / QSC 总分 / 反馈总量 / 趋势）
Top 5 优秀门店 + Top 5 待改进门店
QSC 三维度拆解（各维度的优劣势门店）
差评根因分析（Top 10 关键词/标签）
区域对比（华东/华南/华北/华中/西南/西北）
预警事件（差评激增/连续低分/敏感词命中）
问题列表（按门店聚合，可导出 Excel 分发）

典型命令：

# 生成周报（HTML + PDF）
python scripts/report_generator.py --period week --date 2026-06-30 --output reports/weekly_2026W26.html

# 生成月报
python scripts/report_generator.py --period month --date 2026-06 --output reports/monthly_2026M06.html

# 只导出问题列表
python scripts/issue_extractor.py --input data/normalized_2026Q2.csv \
    --output reports/issues_2026Q2.xlsx

完整内容：见 assets/report-templates/ + scripts/report_generator.py --help

场景F：看板可视化

触发词：看板 / 可视化 / 趋势图 / 排名

看板内容：

NPS 时间趋势（折线图）
QSC 三维度对比（雷达图）
区域排名（条形图）
差评率热力图（区域 × 时间）
关键词云（差评 Top 50）

典型命令：

# 生成完整看板（HTML 单文件，可邮件发送）
python scripts/dashboard_generator.py --input data/normalized_2026Q2.csv \
    --output reports/dashboard_2026Q2.html

# 仅看某区域看板
python scripts/dashboard_generator.py --input data/normalized_2026Q2.csv \
    --region 华东 --output reports/dashboard_hd.html

完整内容：见 assets/report-templates/dashboard.html 模板 + scripts/dashboard_generator.py --help

场景G：预警

触发词：预警 / 差评预警 / 异常检测 / 敏感词

预警规则（详见 references/alert-rules.md）：

单日差评率突增 50%+ → 高优预警
连续 3 天某门店 QSC < 3.0 → 中优预警
敏感词命中（食物中毒/异物/吃出虫）→ 立即预警
区域 NPS 周环比下降 10+ → 中优预警

典型命令：

# 检测所有预警
python scripts/alert_engine.py --input data/normalized_2026Q2.csv --output reports/alerts_2026Q2.csv

# 只看高优预警
python scripts/alert_engine.py --input data/normalized_2026Q2.csv --level high

完整内容：见 references/alert-rules.md + scripts/alert_engine.py --help

5 平台数据格式对照

| 平台 | 主要字段 | 特殊字段 | 模板文件 | |------|---------|---------|---------| | 品牌问卷 | 自定义（QSC 评分 + NPS + 文本） | 客户 ID/会员等级 | assets/csv-templates/brand_survey.csv | | 大众点评 | 1-5 星 + 评论文本 | 商家回复/有用数/标签 | assets/csv-templates/dianping.csv | | 美团 | 1-5 星 + 口味/环境/服务分 | 配送评分/出餐时长 | assets/csv-templates/meituan.csv | | 淘宝闪送 | 1-5 星 + 配送评分 | 骑手评分/送达时长 | assets/csv-templates/taobao_shansong.csv | | 京东秒送 | 1-5 星 + 配送评分 | 骑手评分/送达时长 | assets/csv-templates/jd_miaosong.csv |

完整字段映射：见 references/platform-specs/platform-{name}.md

scripts 工具集

| 脚本 | 触发场景 | 用法 | |------|---------|------| | data_importer.py | 数据导入（5 平台） | --platform brand_survey --input file.csv | | data_normalizer.py | 字段标准化 | --input raw/ --output normalized.csv | | qsc_calculator.py | QSC 评分 | --input normalized.csv --output scores.csv | | nps_calculator.py | NPS 计算 | --input normalized.csv --group-by store | | nlp_local_analyzer.py | 默认 NLTK 本地情感 | --input normalized.csv | | nlp_cloud_analyzer.py | 可选阿里云/百度云 | --provider alibaba --api-key ... | | alert_engine.py | 预警检测 | --input normalized.csv --output alerts.csv | | region_analyzer.py | 区域/门店对比 | --input normalized.csv --output compare.html | | dashboard_generator.py | HTML 看板 | --input normalized.csv | | report_generator.py | 周报/月报 | --period week --date 2026-06-30 | | issue_extractor.py | 问题列表（导出 Excel） | --input normalized.csv --output issues.xlsx |

完整使用指南见 scripts/README.md

统一数据 Schema（标准化的中间层）

所有平台数据导入后都会被标准化为以下 schema：

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | feedback_id | string | ✅ | 唯一 ID（平台+原始ID） | | platform | enum | ✅ | brand_survey/dianping/meituan/taobao_shansong/jd_miaosong | | store_id | string | ✅ | 门店编号（统一编码） | | region | enum | ✅ | 华东/华南/华北/华中/西南/西北 | | customer_id | string | ❌ | 客户唯一标识（脱敏） | | feedback_time | datetime | ✅ | 反馈时间 | | order_channel | enum | ❌ | dine_in/takeaway/delivery | | rating_overall | int 1-5 | ✅ | 总体评分 | | rating_quality | float 1-5 | ❌ | Q 品质分（平台有则填） | | rating_service | float 1-5 | ❌ | S 服务分 | | rating_cleanliness | float 1-5 | ❌ | C 环境卫生分 | | rating_delivery | float 1-5 | ❌ | 配送分（仅外卖平台） | | nps_score | int 0-10 | ❌ | 推荐意愿（仅品牌问卷） | | comment_text | string | ❌ | 评论原文 | | merchant_reply | string | ❌ | 商家回复 | | tags | json | ❌ | 平台标签 | | language | enum | ❌ | zh/en（默认 zh） |

完整 schema 文档：见 references/data-schema.md（待 P2 阶段产出）

禁忌与注意事项

数据红线

客户隐私保护：customer_id 必须脱敏（hash 或 MD5），不能存明文手机号/姓名
数据所有权：原始数据归门店/平台所有，分析结果归总部
数据留存：建议保存 2 年（合规+对比），过期归档到冷存储
跨店对比限制：不同区域的客群结构不同，跨大区对比需谨慎

分析红线

样本量不足预警：单门店单月 < 30 条反馈时，NPS 不可信（±15 误差）
差评根因不可推断 100%：NLP 是辅助，最终需人工确认
跨平台对比困难：美团/大众点评客群不同，不能简单求平均

报告红线

问题列表不自动派单：本 Skill 不联动工单系统，由用户手工分发
预警不等同于投诉：高优预警需人工核实后升级
门店负面信息脱敏：对外报告中差评客户 ID 必须打码

Markdown 表格陷阱

表格数据行绝不能以两个竖线开头（渲染后多出一列空 cell）。自检命令（在仓库根目录执行） grep -rn '三个连续竖线' SKILL.md references/ assets/ scripts/ → 必须为 0

扩展架构说明（嵌套子模块）

本 Skill 在 v1.0 立项时采用 "数据层 → 评分层 → NLP 层 → 报告层" 4 层架构：

数据层：5 平台导入 + 字段标准化
评分层：QSC + NPS（规则驱动，本地可跑）
NLP 层：本地 NLTK（默认）+ 云 API（可选）
报告层：看板 + 周报 + 问题列表 + 预警

嵌套子目录：

references/
├── platform-specs/    # 5 平台字段映射（按平台独立文件，按需加载）
├── cloud-nlp-*.md     # 云 NLP API 配置（按需加载）
└── (其他主索引文件)

scripts/
├── (10 个核心工具)
└── sample_data/       # 5 平台示例数据

assets/
├── csv-templates/     # 5 平台导入模板
└── report-templates/  # 看板/报告 HTML 模板

未来扩展 TODO 池（占位记录，不主动实现）：

抖音/小红书评论抓取
视频评论（语音转文字）
客服电话录音分析
区域品牌力指数计算
与 recipe-and-cooking-process 联动（差评→配方反向追溯）

Agent 协作偏好（v1.0 沉淀）

| 用户说 | 我的应对 | |--------|---------| | "导入新平台数据" | 先确认平台 + 提供 CSV 模板 → 再跑导入器 | | "分析差评" | 必跑：NLP 情感 + 关键词 + QSC 拆解 → 输出问题列表 | | "出周报" | 默认：HTML 格式 + 含看板链接 + 含问题列表 | | "加新平台" | 先写 platform-{name}.md 字段映射 → 再加 CSV 模板 → 再加导入分支 | | "加新指标" | 先写 references/{metric}-scoring.md → 再加计算脚本 → 再加报告章节 | | "再检查一下" | 主动跑端到端 demo + 输出验证报告 |

连锁餐饮门店消费者反馈分析

客户反馈分析（QSC + NPS）

触发路由总览

核心数据流

场景A：批量导入多平台反馈

场景B：QSC 评分 + NPS 计算

场景C：NLP 情感分析

场景D：区域/门店对比

场景E：周报/月报自动生成

场景F：看板可视化

场景G：预警

5 平台数据格式对照

scripts 工具集

统一数据 Schema（标准化的中间层）

禁忌与注意事项

数据红线

分析红线

报告红线

Markdown 表格陷阱

扩展架构说明（嵌套子模块）

Agent 协作偏好（v1.0 沉淀）