零售"人货场"数据分析 Skill
面向多门店、多渠道的中小零售体系，接收原始业务数据表（销售明细、库存、客流、会员、门店档案），完成数据清洗与口径校验、关键指标计算、人·货·场三维度结构化分析、跨维度交叉分析、趋势与异常识别，最终输出中文结构化分析报告与可落地行动建议。
何时使用
用户提出以下任一意图时使用本 Skill：
- "用这个月的销售明细和库存表，做个人货场完整分析"
- "帮我看下我们门店的经营数据，人、货、场三个维度都要"
- "分析一下客流、成交、库存周转，找出问题在哪"
- "把这几家店的销售和会员数据跑一遍，输出经营诊断报告"
- "人效、坪效、连带率这些指标都算一下，看看哪家店最差"
新手入门场景（数据分析新手学习/套模板）：
- "教我做商品数据分析"、"有没有新手能用的分析模板"
- "商品销售占比怎么分析"、"怎么做同环比对比"
- "帮我出一份商品数据分析报表，带图表"
新手场景直接加载 references/beginner-methods.md 方法体系，并用 scripts/template_analysis.py 一键出结果（6 大模型：基准值对比/同环比趋势/占比结构/ABC分类/商品×门店/异常诊断）。
以下场景不使用本 Skill：仅做单项计算（如"帮我把这个月的销售合计算一下"）、格式转换（如"把这张表转成 PDF"）、仅做库存或仅做销售的单一维度报表。
工作流程
第 1 步：收集输入数据
向用户确认或读取以下数据表（Excel/CSV 均可，路径以用户提供的为准）。字段名允许中英文，脚本会自动匹配同义字段；关键字段缺失时给出明确提示，不硬编推算。
| 数据表 | 建议字段 | 必需性 |
|---|---|---|
| 销售明细 | 门店、日期、货号/SKU、商品名称、品类、数量、金额、导购/营业员、会员ID（可选） | 必需 |
| 库存表 | 门店、货号/SKU、商品名称、品类、库存数量、成本价（可选）、日期 | 必需 |
| 客流表 | 门店、日期、客流量（进店客流，可选含试穿量） | 可选 |
| 会员表 | 会员ID、门店、注册日期、消费金额、消费次数（或关联销售明细） | 可选 |
| 门店档案 | 门店、渠道/区域、面积、员工数（导购数）、开业日期 | 可选 |
输入文件放在用户指定位置，脚本只读取、不修改原始文件。
第 2 步：确定指标口径
- 默认使用
references/config/metrics_config.yaml中的内置口径（基于零售知识库方法论）。 - 若用户有自定义口径（如自有客单价口径、特殊连带率算法），按以下方式覆盖：
- 优先读取用户传入的--config路径（YAML/JSON）；
- 未传则读取references/config/metrics_config.yaml；
- 配置文件中只覆盖需要变化的指标项，其余沿用默认。 - 输出报告时在"指标口径"章节注明实际采用的口径及来源。
第 3 步：运行分析
在 Python 3.10+ 环境（需 pandas、openpyxl、pyyaml）执行：
python scripts/run_rhc_analysis.py \
--sales <销售明细文件> \
--inventory <库存文件> \
--customer-flow <客流文件(可选)> \
--members <会员文件(可选)> \
--stores <门店档案(可选)> \
--config <口径配置(可选)> \
--output <报告输出路径(可选，默认 output/人货场分析报告_YYYYMMDD.xlsx)>
退出码 0 表示成功；非 0 表示失败，错误信息输出到 stderr。缺客流表时坪效/进店率/试穿率等指标标记为"无法计算（缺客流数据）"，不影响其余指标输出。
第 4 步：检查输出
报告为 Excel 多 Sheet 工作簿（不覆盖任何输入文件），默认包含：
总览：人·货·场三板块核心指标汇总 + 门店排名 TOP/N人的维度：员工结构（人效/店效/导购业绩排名）、顾客/会员（复购率、客单价、VIP 分级）货的维度：品类结构（销售占比/库存占比/动销率/售罄率）、库存周转（周转率/存销比）、TOP/N 尾部商品场的维度：门店/渠道/区域对比（销售额/坪效/成交率/进店率）、门店五级分类交叉分析：商品×门店矩阵、客流×转化、品类×区域趋势与异常：月度/周度趋势、异常清单（缺货/滞销/低人效/低坪效）行动建议：按门店/维度的可落地改进动作表明细：清洗后的标准化数据（供复核）
报告关键发现需在对话中同步总结（表格+要点），不可只交付文件。
第 5 步：输出前自查
- [ ] 所有指标有明确口径且与配置一致
- [ ] 缺失数据有明确提示，无硬编推算
- [ ] 门店/品类名称与源数据一致，无拼写错乱
- [ ] 建议针对具体门店/品类，非泛泛而谈
- [ ] 未修改任何输入文件
指标定义（默认口径）
| 指标 | 公式/口径 |
|---|---|
| 销售额 | Σ(销售明细.金额) |
| 客单价 | 销售额 ÷ 成交单数 |
| 连带率 | 销售件数 ÷ 成交单数 |
| 成交率 | 成交单数 ÷ 客流（试穿/进店） |
| 进店率 | 进店客流 ÷ 门前客流（缺客流数据则不计算） |
| 动销率 | 有销量的SKU数 ÷ 在售SKU总数 |
| 售罄率 | 期间销量 ÷ (期初库存+期间到货) |
| 库存周转率 | 期间销售成本 ÷ 平均库存成本 |
| 存销比 | 期末库存金额 ÷ 期间日均销售额 |
| 坪效 | 销售额 ÷ 门店面积 |
| 人效 | 销售额 ÷ 导购人数 |
| 会员复购率 | 有≥2次消费的会员数 ÷ 有消费的会员总数 |
详见 references/methodology.md；口径可经 YAML 配置覆盖。
新手商品数据分析方法体系
面向数据分析新手的基础方法体系（语言通俗、步骤可照做），详见 references/beginner-methods.md，包含 6 大分析模型：
| 模型 | 适用场景 | 关键输出 |
|---|---|---|
| 一、基准值对比 | 谁好谁差、谁低于平均线 | 各对象 vs 平均值的偏差率 + 评级 |
| 二、同环比趋势 | 生意变好还是变差 | 月度/周度趋势 + 环比/同比增速 |
| 三、占比结构 | 品类结构是否合理 | 销售/库存占比对比 + 缺货/积压诊断 |
| 四、ABC 分类 | 识别重点商品（二八法则） | A/B/C 分类 + 帕累托图 |
| 五、商品×门店 | 铺货诊断（有货没卖/没货可卖） | 缺货/滞销/正常四象限 |
| 六、异常诊断 | 找异常波动的原因 | 异常点 + 原因排查 + 建议动作 |
每个模型均包含：适用场景、所需指标、计算步骤、结果解读要点 + 可手工复算的商品示例。
一键模板脚本
python scripts/template_analysis.py \
--sales <销售明细文件> \
--inventory <库存文件(可选)> \
--output <输出Excel路径(可选)>
- 自动完成 6 大模型的计算与图表（柱状图/折线图/饼图/帕累托图/热力图）；
- 图表以图片形式嵌入 Excel"图表"Sheet，可直接放进周报/月报；
- 提供库存表后自动增加"结构对比（模型三）"与"商品×门店（模型五）"分析；
- 示例数据：
assets/sample_data/商品分析示例.xlsx（3 店 × 5 个月，含缺货/滞销/异常教学场景）。
质量与边界
- 不做任何虚构推算：指标缺数据即标注"无法计算（缺XX数据）"。
- 不修改、不覆盖用户提供的任何原始数据文件，报告另存新文件。
- 不分析超出用户指定范围的数据（如未提供的区域/门店不猜测）。
- 报告与对话输出统一使用中文。
- 金额单位默认元（¥），数量单位默认件；有特殊单位在报告中注明。
停止条件
出现以下情况时停止并询问用户：
- 必需表（销售明细、库存）缺失，无法启动分析；
- 关键字段（门店、日期、金额）大面积缺失无法修复；
- 用户提供的文件不是 Excel/CSV 且无法读取；
- 口径配置 YAML 语法错误且用户未提供替代口径。
