shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsAPI key required

指掌天下客户分析

这个技能用于用户需要对客户数据进行深度分析时使用。 当用户上传销售明细和客户列表（Excel/CSV 或连接器），希望进行 SABC 客户级别划分、客户活跃分析、潜力客户识别、老客增品推荐时自动触发。 触发词：客户分析, 客户维度分析, 客户深度分析, 客户分层, 客户级别, SABC, 客户活跃分析, 客户生命周期, 潜力客户, 老客增品, 客户推荐, RFM, 客户洞察, 经营分析, 销售增长分析。 支持掌天下超级进销存等系统导出的数据。

personAuthor: user_77d366fahubcommunity
downloadDownload package

客户维度深度分析

概述

深度客户分析技能，从销售明细和客户列表中提取客户价值、识别休眠客户和增长机会，输出交互式 HTML 报告。

适用场景

  1. Excel 上传分析：用户上传销售明细 Excel + 客户列表 Excel
  2. MCP 连接器数据分析：通过 MCP 服务直接拉取销售明细和客户列表数据，无需手动上传 Excel

MCP 连接器

当用户未提供本地文件或明确要求通过连接器获取数据时，使用 MCP 服务拉取数据。

  • MCP 地址：https://c.handday.com/gateway/mcpservice/mcp
  • 认证方式：API Key（由用户在对话时提供）
  • ⚠ 必需请求头（2026-09 实测）：所有请求必须额外携带 X-CORP-ID: <corpId>（从 JWT payload 的 corpId 字段解析）与 hdsaas: always 两个请求头，否则正式网关返回 503 SERVICE_UNAVAILABLE "Unable to find instance for mcpservice"。hdsaas: always 是网关做服务实例路由的关键头，缺失时后端服务不可达（勿误判为服务下线）
  • 503 自动重试（已内置，无需手动处理）：scripts/mcp_fetcher.py 的 mcp_call() 函数检测到 503 / Unable to find instance for mcpservice 时，自动在 headers 中补 hdsaas: always 后重试（指数退避 1/2/4s，最多 3 次）。首次请求忘带 hdsaas 也能自动恢复，日志输出 [503] 第 N 次重试（已补 hdsaas）
  • 数据获取：通过 MCP 工具调用获取销售明细和客户列表，转为 pandas DataFrame 后进入统一分析流程
  • 拉取执行：直接调用 scripts/mcp_fetcher.py sales 子命令（推荐）；也可在脚本中 import 使用 fetch_sales_range(corp, token, start, end, out_dir)

MCP 数据获取流程

  1. 确认用户已提供 API Key（如未提供，主动询问）

  2. 使用 MCP 地址连接服务，列出可用工具

  3. 默认数据规则（重要）：若用户未指定获取什么数据，统一默认获取商品销售明细统计——调用 get_sales_detail 工具（订单级明细穿透，返回含单据信息、客户信息、商品信息、价格金额、成本利润的完整销售明细），按天逐日拉取（见数据完整性规则）后进入分析流程。仅在用户明确指定其他数据（如客户列表、库存、品类汇总等）时才调用对应工具。

  4. 数据完整性规则（重要，防漏数）：get_sales_detail 存在环境差异，必须先行探测确认所在环境行为再定拉取策略：

    • dev/pre 网关（dev-hdsaas.facehand.cn / pre-hdsaas.facehand.cn）：单次调用最多返回 200 条（limit 传多大都只返回 200；不传 limit 默认只返回 50 条；无翻页参数），跨多天一次调用会在 200 条处静默截断丢数据、不报任何错。因此必须：
      • 按天循环拉取：每天单独一次调用（start_date = end_date = 当天，limit: 200），将全部天数的结果累加合并（建议直接调用 scripts/mcp_fetcher.py sales，内部已实现并发+重试+校验）；
      • 触顶检测：某天返回恰好 200 条 → 该天可能被截断，记录为触顶日；
      • 触顶兜底（按序尝试，每步自验证）：① 先不传 limit 重拉该天（部分网关/环境默认返回全量，若 > 200 条则直接采用）；② 再按品类拆分重拉该天（品类来自已拉数据 distinct + get_top_categories 当月排行，逐品类传 category 参数）——注意部分网关会静默忽略 category 过滤，必须比对拆分前后条数自验证，无效则保留截断警告，不得谎报已完整；customer_id 参数要求数字型 ID 且无清单接口可获取，不可作为拆分维度；
    • 正式网关（c.handday.com，2026-09 实测）：行为相反——不传 limit 返回当天全量（实测单日 245 条 > 传 limit=200 的截断值 200；无上限截断），传 limit: 200 则被截断在 200。策略：按天逐日 + 不传 limit，最稳；仍建议逐日而非跨月（跨月单次响应过大易超时，整月一次调用曾被观察到长时间无响应/进程被杀）。工具集仅 5 个（get_sales_detail / get_top_selling_products / get_product_list / get_stock_status_list / get_stock_status_summary），无客户档案/趋势/客户分析等工具，客户维度分析只需 get_sales_detail（明细内嵌客户全名+分类+部门）。
    • 触顶判定：单日返回 n == 200 才判为触顶（恰好命中截断值），n > 200 是正常（返回了 200+ 条全量），不得误报为截断。
    • 去重收尾：合并后按「单据编号 + 商品名称 + 规格 + 销售数量」组合键去重（防拆分重拉交叉重复），并在报告开头标注触顶日的兜底处理情况。

  5. 全量自检（必跑）：拉取完成后调用 scripts/mcp_fetcher.py validate-sales 校验已落盘数据：

    python scripts/mcp_fetcher.py validate-sales \
    --raw-dir <mcp_raw 目录> --start <start> --end <end>

    输出 ok: true 表示覆盖完整；ok: false 时检查 warnings 列表（missing_days / hit_top_days / zero_record_days）并补拉。validate 输出 JSON，可直接写入报告头部展示给用户。

  6. 调用 MCP 工具拉取客户列表数据（如服务支持，且用户明确需要时）

  7. 将返回数据转为 DataFrame，传入 scripts/main.py 的分析流程（与 Excel 数据同路径）

分析方法

1. SABC 客户级别

按销售额累加占比划分级别（阈值可自定义，默认 40/60/80）：

| 级别 | 累加占比 | 经营策略 | |------|----------|----------| | S 类 | 0-40% | 深度绑定，资源倾斜 | | A 类 | 40-60% | 升级培育，向 S 类转化 | | B 类 | 60-80% | 激活复购，提升客单价 | | C 类 | 80-100% | 标准化服务，筛选高潜 |

2. 客户活跃分析

按交易频率分类（4 级，阈值可自定义）。基于「数据截止日 = 全量最大日期」向前推算时间窗口，交易次数按单据编号去重：

统一判定模型（v1.6.0）：每级判定条件统一为「近 N 天内，按（累计 / 每周 / 每月）口径，交易 ≥ M 次」，天数、口径、次数三级各自独立设置。

| 状态 | 判定条件（默认） | 行动 | |------|------------------|------| | 高活 | 近30天，每周平均 ≥ 1 次 | 深度绑定，交叉销售 | | 中活 | 近30天，累计 ≥ 2 次 | 提升频次，培育高活 | | 低活 | 近90天，累计 ≥ 1 次 | 定向触达，优惠唤醒 | | 休眠 | 未达到低活判定条件（自动判定） | 紧急干预，1v1 挽回 |

口径枚举（每周/每月为业务频率表达方式，判定在数学上等价于累计阈值）：

  • total 累计：窗口内交易总次数 ≥ M

  • weekly 每周：总次数 × 7 ÷ 天数 ≥ M（如 30天每周≥1次 ⟺ 30天内 ≥ 4.3 笔；不做整数化换算，浮点比较）

  • monthly 每月：总次数 ÷ 窗口覆盖的自然月数 ≥ M（按实际自然月，含首尾月，如近90天 = 3 个自然月）

  • 分类采用级联判断：先判休眠（未达低活条件）→ 高活 → 中活 → 低活；三级窗口互不联动

  • 设置面板按级别导向组织：高活/中活/低活/休眠 4 行级别卡，每行展示「近 __ 天内 [累计/每周/每月▾] 交易 ≥ __ 次」；休眠行为只读展示

  • 前端重算基于客户 txnDates（按单据去重的交易日期列表）对任意天数/口径真实重算，窗口修改即时生效

3. 潜力客户识别（4 种类型）

| 类型 | 判定条件 | 策略 | |------|----------|------| | 高频低客单型 | 订单数≥P75 + 客单价≤P25 + 毛利率≥P50 | 组合推荐，提升客单价 | | 降频需激活型 | 末购>30天 + 客单价≥P50 + 销售额≥P50 | 定向活动，重新激活 | | 高毛利低销量型 | 毛利率≥P75 + 销售额≤P50 + 订单≥2 | 爆品引流，以点带面 | | 品类单一型 | 品类数=1 + 销售额≥P50 + 非新客 | 关联推荐，品类渗透 |

4. 老客增品推荐

同组构建优先级：客户分类 > 销售区域 > SABC 级别 推荐条件：同组中 ≥1/3 客户买过但该客户未购的商品，按覆盖率降序 推荐列表包含字段：客户名称、推荐商品、商品毛利率、同组购买率、预计增收、推荐理由 预计增收口径（v1.5.2 起）：该商品同组已购客户成交均价 × 人均月销量。人均月销量 = 同组客户购买该商品的总销量 ÷ 购买人数 ÷ 购买月数，历史数据不足时回退 10 件/月；同组 = 同 SABC 级别（客户分类/销售区域字段暂未接入分组）。表头 ⓘ 图标点击弹出口径说明弹层（不可用原生 title 悬浮——内嵌预览中不触发）；每行预计增收金额可点击，弹层展示该行具体计算式（如"历史均价 ¥150/件 × 预计月销 0.8 件（同组人均月销）= ¥120"），数据含 avgPrice/estQty 字段

使用流程

方式 A — Excel 上传

  1. 用户上传销售明细 Excel/CSV（必须含客户名称、优惠后金额）
  2. 用户上传客户列表 Excel/CSV（可选）
  3. Skill 自动解析、分析、渲染
  4. 输出自包含 HTML 交互报告

方式 B — MCP 连接器

  1. 用户提供 API Key
  2. Skill 通过 MCP 地址拉取销售明细和客户列表数据
  3. 数据进入统一分析流程
  4. 输出自包含 HTML 交互报告

输出报告结构

  • 顶部：数据范围（全量明细最小~最大日期）+ KPI 卡片
    • KPI 卡片包含：总客户数、总销售额、总毛利、总订单数、S类客户数、休眠客户数等关键指标
  • 图表区 Row 1（全宽）：SABC 客户级别饼图 + 13 列级别统计表格
    • 统计表格列：级别、客户数、占比、销售额、销售额占比、毛利、毛利率、毛利占比、订单数、客单价、客均单数、客均拿货SKU、拿货SKU=1客数（该级别中只拿过 1 个 SKU 的客户数）
    • 合计行：S 行后插入「SA合计」行（S+A 各列合计）、B 行后插入「SAB合计」行（S+A+B 各列合计）、末行为「总计」行（全部客户各列合计）
    • 穿透交互：点击 S/A/B/C 级别行或饼图扇区 → 穿透查看客户级别明细（自动切换到明细 Tab、按级别筛选、清空其他筛选、滚动到表格区），表格上方显示「已穿透」提示条可一键清除；标题旁有 💡 提示标注该交互
  • 图表区 Row 2（两栏）：客户活跃分析饼图（4 级：高活/中活/低活/休眠）+ SABC 级别销售额与毛利对比柱状图（分组柱状图，按级别对比销售额和毛利）
    • SABC 饼图和活跃分析饼图标题旁有 ⚙ 齿轮图标，点击可打开设置面板调整级别/活跃计算阈值
    • 设置面板修改阈值后，前端即时重算级别/活跃分类结果，无需重新分析
    • 顶部时间筛选：仅过滤下方客户列表（规则见「时间区间口径」），不重算 KPI/级别/活跃分析
  • 中部：AI 经营建议面板（3 个 Tab：级别策略 / 提升活跃策略 / 潜力客户策略；每个潜力策略卡片带类型名 badge，如「高频低客单型」）
  • 底部：客户级别明细 + 老客增品推荐（Tab 切换；表格按每页 100 条分页，页码按钮动态生成，总数与筛选数实时显示）
    • 客户级别明细中客户名称为蓝色链接样式，点击行或名称可打开客户详情抽屉
  • 抽屉：点击客户行 → 详情 + 个性化 AI 建议 + 增品推荐 + 真实月度销售额趋势
  • 导出：点击「导出 Excel」按钮，生成单个 .xlsx 文件，包含客户级别明细和老客增品推荐两个页签

客户详情抽屉计算规则（点击客户行）

| 指标 | 计算规则 | 口径 | |------|----------|------| | 首次购买 | 该客户最早一笔交易的录单时间/过账时间 | 全量数据 | | 最近购买 | 该客户最晚一笔交易的录单时间/过账时间 | 全量数据 | | 末购天数 | 数据截止日 − 最近购买日；数据截止日 = 全量数据最大日期（非当前系统日期） | 全量数据 | | 销售额趋势 | 按「录单时间/过账时间」按月聚合的真实销售额（优惠后金额），缺月补 0，X 轴月份跟随顶部筛选区间 | 全量聚合 | | 末购天数着色 | 按客户活跃分析级别着色：绿 = 高活/中活、橙 = 低活、红 = 休眠；9999 = 无日期字段 | — | | 无日期降级 | 数据源缺日期字段时：末购天数显示「—（数据缺日期）」、趋势图提示无分月数据 | — | | AI 推荐话术 | 基于客户级别 + 活跃状态 + Top2 增品推荐自动生成微信/企微触达话术（休眠→回归唤醒、低活→关怀激活、中活→提频增品、高活→优先配额），带一键复制按钮；发送前可微调 | — |

首次购买/最近购买/末购天数/累计指标均基于全量数据，不随顶部时间筛选变化；趋势图展示范围跟随筛选区间，但数值为全量聚合的真实月度销售额，非估算/模拟。

时间区间口径（顶部数据范围与筛选）

  • 数据范围：顶部「数据范围：起始 ~ 截止」显示全量销售明细的最小~最大日期，由 get_date_range() 计算（优先「录单时间」，缺失时回退「过账时间」；两者皆无时回退到数据截止日 = 全量最大日期）。
  • 业务日期口径：统一优先使用「录单时间」作为业务日期（掌天下等系统批量过账时「过账时间」常为同一时间戳，录单时间更接近真实业务日期）；「录单时间」缺失时回退「过账时间」，两者皆无时该行不参与日期相关计算；日期相关的数据范围、客户活跃分析、趋势均以此为准。回退到「过账时间」时会在 warnings 中提示。
  • 筛选规则：点击「筛选客户」后，仅按「最近一次购买日期落在所选区间内」过滤下方客户列表；KPI 卡片、SABC 级别、客户活跃分析、潜力识别、增品推荐、AI 建议均基于全量数据，不随筛选重算（前端更新「区间内有交易客户数（全量 N 位）」作参考）。
  • 日期基准统一：末购天数、首购距今（潜力识别）、客户活跃分析的时间窗口统一以「数据截止日 = 全量最大日期」为基准，不使用当前系统日期，保证历史数据口径一致。

字段降级策略

| 缺失字段 | 降级处理 | |----------|----------| | 成本金额 | 毛利 = 销售额，毛利率 = 100% | | 单据编号 | 订单数 = 行数估算 | | 商品名称 | 增品推荐不可用 | | 商品分类 | 品类分析降级 | | 客户分类/销售区域 | 同组构建降级到 SABC 级别 |

技术架构

数据源 → normalizer.py（字段归一化） → analyzer.py（计算引擎） → template.html（渲染）
  • scripts/normalizer.py：Excel 解析、字段检测与别名映射、缺失降级
  • scripts/analyzer.py：SABC 级别、客户活跃分析、潜力、增品、AI 建议
  • scripts/main.py：主入口，协调三阶段流程
  • scripts/template.html：锁定样式的数据驱动 HTML 模板
  • scripts/mcp_fetcher.py（v1.6.2 新增）：MCP 数据拉取工具，含 503 自动重试（自动补 hdsaas: always）+ 断点续传 + 按天并发 + 全量校验；CLI 子命令 sales（按天拉销售）/ validate-sales（校验已落盘）

执行流程

当用户触发此 Skill 时，严格按照以下步骤执行：

Step 1 — 确认数据来源

支持两种数据获取方式，优先询问用户选择哪种：

方式 A：Excel 上传

  • 确认用户提供的销售明细和客户列表文件路径
  • 如用户未指定路径，主动询问文件位置

方式 B：MCP 连接器

  • 确认 API Key 已提供（如未提供，主动询问；corpId 从 JWT payload 的 corpId 字段解析）
  • 调用 scripts/mcp_fetcher.py sales 拉取销售明细（内部已实现按天逐日 + 5 并发 + 断点续传 + 串行重试 3 轮 + 503 自动重试 + 全量校验）： 
    python scripts/mcp_fetcher.py sales \
    --corp <corpId> --token <JWT> \
    --start <start> --end <end> --out <mcp_raw 目录>
  • 拉取完成后必跑 validate-sales（防漏数自检）： 
    python scripts/mcp_fetcher.py validate-sales \
    --raw-dir <mcp_raw 目录> --start <start> --end <end>
    输出 ok: true 才进入下一步；ok: false 时按 warnings 数组处理（重拉缺失日 / 检查触顶日 / 复核零数据日）
  • 拉取的明细内嵌客户全名+分类+部门，无需额外拉客户档案；用户明确指定其他数据（如客户列表）时才调用对应工具
  • 将拉取的明细文本转 Excel 后传入分析流程（用 parse_mcp_text.py 或类似解析脚本）

Step 2 — 安装依赖（如需要）

  • 检查 pandas、openpyxl 是否已安装
  • 如缺失，使用运行时虚拟环境安装： 
    pip install pandas openpyxl xlsxwriter

Step 3 — 运行分析

  • 执行 scripts/main.py，传入数据（文件路径或 MCP 返回数据）： 
    # Excel 方式
python scripts/main.py "销售明细.xlsx" "客户列表.xlsx"

# MCP 方式：将拉取的数据保存为临时文件后传入
python scripts/main.py "mcp_sales_temp.xlsx" "mcp_customers_temp.xlsx"
  • main.py 将输出 JSON 摘要（含 success、output_path、summary）
  • 如果 success 为 false，向用户报告错误信息

Step 4 — 呈现报告

  • 读取输出的 HTML 文件路径
  • 使用 present_files 将 HTML 报告展示给用户

Step 5 — 引导使用

  • 告知用户报告中的关键交互：
    • ⚙ 齿轮图标可调整 SABC 级别阈值（默认 40/60/80）和客户活跃分析阈值（统一句式：天数 + 累计/每周/每月口径 + 次数，三级独立）
    • 点击客户行可查看详情抽屉
    • Tab 切换客户级别明细 / 老客增品推荐
    • 「导出 Excel」按钮导出双页签 .xlsx 文件

注意事项

  • 依赖项：Python 3.8+、pandas、openpyxl、xlsxwriter
  • 数据要求：销售明细必须包含「客户名称」和「优惠后金额」字段
  • 文件格式：支持 .xlsx / .xls / .csv
  • 数据量：10 万行以内数据处理时间约 30-60 秒
  • 不包含敏感信息：所有脚本仅做本地数据处理，不上传任何数据
  • 报告为自包含 HTML：无需网络即可查看图表（ECharts CDN 有本地降级）
  • 掌天下适配：支持掌天下导出的字段命名，normalizer.py 自动映射
  • MCP 连接器：通过 https://c.handday.com/gateway/mcpservice/mcp 获取数据时，需用户提供 API Key；MCP 返回数据字段需与 normalizer.py 字段映射对齐，如字段名不一致需在 normalizer.py 中补充别名映射