商品维度深度分析
概述
深度商品分析技能，从销售明细和库存状况中提取商品价值、识别零动销与慢动商品和增长机会，输出与客户维度深度分析同构的交互式 HTML 报告。
适用场景
- Excel 上传分析：用户上传销售明细 Excel（必须）+ 库存状况 Excel（可选，支持多个文件自动合并）
- MCP 连接器数据分析：通过 MCP 服务直接拉取商品销售明细数据，无需手动上传 Excel
MCP 连接器
当用户未提供本地文件或明确要求通过连接器获取数据时，使用 MCP 服务拉取数据。
- MCP 地址：默认
https://c.handday.com/gateway/mcpservice/mcp；若用户提供了自己的 MCP 地址，必须用用户给的地址，不得用本技能默认地址 - 认证方式（正式网关 c.handday.com 实测必需 3 头）：API Key（JWT）通过
X-API-Key: <key>+X-CORP-ID: <key payload 中的 corpId>两个请求头传递；同时必须携带hdsaas: always头（服务路由标识，缺失时网关返回 503Unable to find instance for mcpservice，不是地址/协议问题）。不能用Authorization: Bearer替代 X-API-Key - 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） - 环境区分：c.handday.com（正式，工具精简 5 个）/ dev-hdsaas.facehand.cn、pre-hdsaas.facehand.cn（预发/开发，工具 24 个）；三套网关请求头相同（X-API-Key+X-CORP-ID+hdsaas: always），dev/pre 可直接连通，正式网关必须带 hdsaas 头
- 数据获取：通过 MCP 工具调用获取商品销售明细（默认
get_sales_detail）和库存状况（get_stock_status_list），转为 pandas DataFrame 后进入统一分析流程 - 拉取执行：直接调用
scripts/mcp_fetcher.py的sales/stock/validate-sales/validate-stock子命令；也可在脚本中 import 使用对应函数
MCP 数据获取流程
- 确认用户已提供 API Key（如未提供，主动询问）
- 使用用户提供的 MCP 地址连接服务，列出可用工具（dev/pre 24 个 / 正式 c.handday.com 仅 5 个：get_sales_detail、get_top_selling_products、get_product_list、get_stock_status_list、get_stock_status_summary；正式网关无趋势/客户档案类工具）
- 默认数据规则：若用户未指定获取什么数据，统一默认获取商品销售明细统计——调用
get_sales_detail（订单级明细穿透，返回含单据信息、客户信息、商品信息、价格金额、成本利润的完整销售明细）；需要库存分析时再调用get_stock_status_list - 将返回数据转为 DataFrame，传入
scripts/main.py的分析流程（与 Excel 数据同路径）
MCP 拉取关键经验（2026-09-04 正式网关实测更新）：
- get_sales_detail 单次条数上限随环境不同：dev 网关 limit 传多大都只返回 200 条（不传 limit 只返回 50 条默认值）；正式网关 c.handday.com 不传 limit 反而返回单日全量（实测 245 条 > limit=200 的截断值）。无翻页参数；category/sku 过滤参数部分网关静默忽略（需自验证）。必须按下述「数据完整性规则」按天逐日拉取，否则超限部分被静默丢弃不报错。
- 库存 get_stock_status_list：page_size 最大 100（默认 20），需按 page 循环翻页（9611 SKU ≈ 97 页）；enable 传 -1 可含停用商品；可用 summary_only: true 先取合计。
- 库存文本输出有定宽截断：文本表格按固定列宽对齐，商品名称列宽约 18 显示字符、规格约 10——超过列宽的名称/规格会被静默截断（9611 行实测名称截断 3.4%、规格截断 7.4%），无法从文本侧恢复。补救：用已拉销售明细的完整商品名称对库存截断名前缀修复（唯一前缀才替换，实测可将库存名→销售全名集合命中率提升）；仍截断的库存独有商品（无销售记录）不影响分析主体。
- 库存数据异常清洗（防污染库存金额口径，必须在解析层处理）：正式环境库存档案含大量历史异常——负库存量行（出库冲销）、成本均价荒谬行（负库存÷小额产生的千万级均价）。实测 9611 行中 7,795 行库存金额需归零（库存量 ≤0 或 库存金额 <0 的行 → 库存金额=0，负库存=欠货不算资产），成本均价 >10000 元的荒谬值置空（17 行）。清洗后真实库存资产口径与清洗前（-4.6 亿虚值）差异巨大，必须清洗否则 KPI/饼图/占比全被污染。
- 库存 get_stock_status_list 每页最多 100 条，需循环分页（8712 SKU 约 88 页）。
- 响应为 | 分隔文本表格，可能含 emoji 截断的孤立代理字符（U+D800~U+DFFF），落盘前 sanitize；源码注释描述代理范围时写 U+D800~U+DFFF 勿写转义字面量（会导致脚本编译失败）。
- 沙箱环境 rm/os.remove 可能被拦截 → 拉取脚本用 'w' 覆盖模式自清理。
- pre 环境真实企业可能堆积「导入重算」测试数据（如 2026-03-05 单日 3000 条占全量 93%），分析前按商品名含「导入重算/测试」、客户编码 260xxx 剔除，并同时产出「全量版+真实业务版」双报告。
数据完整性规则（拉取 get_sales_detail 必须遵守）
工具单次上限 200 条且无翻页、静默截断不报错，大区间一次调用必然漏数据。拉取时必须：
- 按天循环拉取：
start_date与end_date均设为同一天，显式传limit=200（dev/pre）/ 不传limit（正式网关），逐日调用后合并。禁止大区间（跨多天）单次调用。 - 触顶检测：某天恰好返回
200条即标记为触顶日（超出部分被静默丢弃；n > 200是正式网关正常返回全量，不得误报为截断）。 - 触顶兜底（按序尝试，每步自验证）：
- 先不传limit重拉该天——部分网关/环境（如 pre）不传 limit 返回全量；若返回条数 > 200 则直接采用。注意 dev 网关不传 limit 只返回 50 条（默认值），此步无效时继续下一步。
- 再按品类拆分重拉该天：品类来自触顶日已返回记录的「商品分类」字段 + 当月品类排行；逐品类传category参数重拉后合并。比对拆分前后条数自验证——部分网关会忽略 category 过滤（拆分后条数不变），此时兜底无效，保留截断警告，不得谎报已完整。 - 去重收尾：按「单据编号+商品名称+规格+销售数量」组合键去重（兜底重拉会与原始记录重复）。
- 全量自检（必跑）：拉取完成后调用
scripts/mcp_fetcher.py validate-sales校验已落盘数据：
bash python scripts/mcp_fetcher.py validate-sales \ --raw-dir <mcp_raw 目录> --start <start> --end <end>
输出ok: true才进入下一步；ok: false时按warnings数组处理。报告标注：分析报告中注明触顶且兜底无效的日期，提示该部分数据可能不完整。
库存拉取完整性（get_stock_status_list）
page_size: 100（实测最大）+enable: -1（含停用商品），按页循环拉取；首轮探测首页返回的「共 N 条」确定总页数（total_pages = ⌈N/100⌉）。- 断点续传：
stock_p*.txt已存在即跳过；可安全重入。 - 多轮重试：未拉到的页串行重试，最多 5 轮。
- 拉取完成后必跑 validate-stock：
bash python scripts/mcp_fetcher.py validate-stock --raw-dir <stock_raw 目录> [--expected <首页探测的总数>]
-pages_count == total_pages且continuous == true（页号 1..total_pages 无缺失）
-total_sku与首页探测的共 N 条一致（差异 < 1% 视为探测时点不同）
-empty_pages/short_pages应为空（中间页应接近 100 条，末页可不满）
- 输出ok: true才进入下一步
分析方法
1. SABCD 商品五级分类（帕累托累加）
按销售额降序累加占比划分级别（阈值可自定义，默认 40/60/80/100；v1.6.0 更新：C 阈值上限 100，D 类显式规则）：
| 级别 | 累加占比 | 经营策略 |
|---|---|---|
| S 级 | 0-40% | 爆款保障，优先备货 |
| A 级 | 40-60% | 重点培育，向 S 级转化 |
| B 级 | 60-80% | 关注趋势，择优推广 |
| C 级 | 80-100% | 标准运营，控制库存 |
| D 级 | 销售额=0（显式判定） | 淘汰评估，清仓减负 |
- v1.6.0 D 类显式规则：销售额=0 的商品（含库存有但销售明细无的）直接判 D，不参与累加占比分段
- 汇总表含「SA合计」「SAB合计」「总计」行；级别行与饼图扇区可点击穿透到明细
2. 商品动销分析（4 级，统一口径模型）
复用客户维度 v1.6 的统一判定模型：每级判定条件统一为「近 N 天内，按（累计 / 每周 / 每月）口径动销 ≥ M 次」。动销次数 = 窗口内有销售的日期数（按日去重）；基于「数据截止日 = 全量最大日期」向前推算窗口。
| 状态 | 判定条件（默认） | 行动 |
|---|---|---|
| 畅销 | 近30天，每周平均 ≥ 1 次 | 爆款主推，保障供应 |
| 正常 | 近30天，累计 ≥ 2 次 | 稳定补货，常规推荐 |
| 慢动 | 近90天，累计 ≥ 1 次 | 促销激活，组合搭售 |
| 零动销 | 未达到慢动判定条件（自动判定） | 清仓评估，处理积压 |
口径枚举：
- total 累计：窗口内动销总次数 ≥ M
- weekly 每周：总次数 × 7 ÷ 天数 ≥ M（浮点比较，不做整数化换算）
- monthly 每月：总次数 ÷ 窗口覆盖的自然月数 ≥ M（按实际自然月，含首尾月）
- 分类采用级联判断：先判零动销（未达慢动条件）→ 畅销 → 正常 → 慢动；三级窗口互不联动
- 前端重算基于商品
txnDates（按日去重的动销日期列表）对任意天数/口径真实重算，窗口修改即时生效
3. 潜力商品识别（4 种类型，单标签，优先级从高到低）
| 类型 | 判定条件 | 策略 |
|---|---|---|
| 退货预警型 | 退货率 ≥ max(20%, P90) 且退货额 ≥ ¥500 | 排查质量/描述问题，及时止损 |
| 单客户依赖型 | 动销客户数 = 1 且销售额 ≥ P50 | 拓展采购商，降低依赖风险 |
| 高毛利低销量型 | 毛利率 ≥ P75 且销量 ≤ P25 | 主推引流，以点带面 |
| 薄利多销型 | 销量 ≥ P75 且毛利率 ≤ P25 | 保障供应，组合搭售提毛利 |
4. 库存概况与库销比
- 商品粒度：按「名称+规格」归一聚合（同一商品多个编号时：库存量/库存额求和、成本均价按库存量加权、任一编号上架即视为上架）
- 库存独有商品：库存中有但销售明细中无的商品，以零动销身份进入商品列表（D 级）
- 库销比 = 库存总量 ÷ 统计期总销量；≥ 3 时表格中红色警示
- 库存上下限预警：库存 < 下限 → 红色「建议补货」；库存 > 上限 → 橙色「积压风险」（在抽屉库存概况区块展示）
- 库存数据口径：库存状况 Excel 优先读取「修改」sheet（人工修正过成本价的版本），表头在第 2 行
5. 库存状态分析（6 级，阈值可自定义）
以「日均销量 = 统计区间总销量 ÷ 区间天数」为基准，按级联判定（库存档案缺失的商品不参与）：
| 状态 | 判定条件（默认阈值 3/15/30 天） | 颜色 |
|---|---|---|
| 断货 | 库存数量 ≤ 0 | 红 #ef4444 |
| 零动销积压 | 日均销量 = 0 且库存 > 0（自动判定） | 灰 #6b7280 |
| 断货紧急 | 库存 ≤ 日均 × 3 | 橙 #f97316 |
| 低库存 | 日均 × 3 < 库存 ≤ 日均 × 15 | 黄 #eab308 |
| 正常 | 日均 × 15 < 库存 ≤ 日均 × 30 | 绿 #06d6a0 |
| 超额库存 | 库存 > 日均 × 30 | 紫 #7209b7 |
> v1.6.0 更名：无货 → 断货、缺货预警 → 断货紧急、库存积压 → 超额库存（判定逻辑不变，仅更名）
- 积压超额金额 = (库存数量 − 积压线天数 × 日均销量) × 成本单价，适用于超额库存+零动销积压商品（零动销时超额 = 全部库存 × 成本）；成本缺失时用 stockValue/stockQty 兜底
- SABCD 汇总新列（v1.6.0 更新为 16 列）：库存占比 = 该级别库存总额 ÷ 全部库存总额；断货 = 库存总量 ≤ 0 商品数；断货紧急 = 库存 ≤ 日均 × 紧急线且库存 > 0 商品数；超额库存 = 积压 + 零动销积压商品数；积压超额金额(万)；拿货客户=1 商品数
- SABCD 库存占比饼图：按各级别库存总额（万元）分布，点击扇区穿透
- 前端修改库存阈值后基于 dailyAvg 即时重分类，汇总表新列与两个饼图同步重建
- 分析区间 < 14 天时标题追加「⚠周期较短仅供参考」
使用流程
方式 A — Excel 上传
1. 用户上传销售明细 Excel/CSV（必须含商品名称、优惠后金额）
2. 用户上传库存状况 Excel/CSV（可选，支持多个文件；文件名含「库存」自动识别）
3. Skill 自动解析、分析、渲染
4. 输出自包含 HTML 交互报告
方式 B — MCP 连接器
1. 用户提供 API Key
2. Skill 通过 MCP 地址拉取商品销售明细（和库存状况）
3. 数据进入统一分析流程
4. 输出自包含 HTML 交互报告
输出报告结构
- 顶部：数据范围（全量明细最小~最大日期）+ KPI 8 卡
- 商品总数/有动销、零动销商品/慢动、潜力商品/高毛利低销量、总销售额/交易笔数
- 总毛利/毛利率、断货商品(断货+断货紧急分计)、超额库存商品(超额库存+零动销积压分计)、负毛利商品/合计亏损
- 图表区 Row 1（全宽）：SABCD 商品级别饼图 + 16 列级别统计表格
- 统计表格列：级别、商品数、占比、销售额(万)、销售额占比、毛利(万)、毛利率、毛利占比、动销客户数、库存总额(万)、库存占比、断货、断货紧急、超额库存、积压超额金额(万)、拿货客户=1
- 断货红色 / 超额库存紫色 / 单客玫红高亮；积压超额金额按当前积压线动态计算
- 合计行：S 行后插「SA合计」、B 行后插「SAB合计」、末行「总计」
- 穿透交互：点击 S/A/B/C/D 级别行或饼图扇区 → 穿透查看商品级别明细
- 图表区 Row 2（两栏）：库存状态分析饼图（6 级）+ 商品动销分析饼图（4 级：畅销/正常/慢动/零动销）
- 图表区 Row 3（两栏，有库存档案时）：SABCD 库存占比饼图（按库存总额分布）+ SABCD 级别销售额与毛利对比柱状图
- SABCD/动销/库存状态饼图标题旁有 ⚙ 齿轮图标，点击可打开设置面板调整级别/动销/库存预警计算阈值（SABCD 四阈值 + 动销三级参数 + 库存预警三阈值「断货紧急/低库存/超额库存」+ 零动销自动判定说明）
- 设置面板修改阈值后，前端基于
txnDates/dailyAvg即时真实重算，无需重新分析；库存阈值校验 1 ≤ 紧急 < 低库存 < 积压 - 顶部时间筛选：仅过滤下方商品列表，不重算 KPI/级别/动销分析
- 库存状态饼图标题显示「3/15/30 天 · 日均销量基于 N 天数据」，点击扇区穿透筛选商品列表
- 中部：AI 经营建议面板（4 个 Tab：商品级别策略 / 库存优化策略 / 提升动销策略 / 潜力商品策略；每个潜力策略卡片带类型名 badge）
- 库存优化策略：按库存状态 6 级（断货/断货紧急/低库存/正常/超额库存/零动销积压）生成优化建议卡片，含商品数与库存金额
- 底部：商品级别明细（四 Tab：📋 商品级别明细 + 🧩 商品结构优化 + 💰 员工薪酬绩效 + 📦 库存优化建议；明细表格按每页 100 条分页，18 列）
- 列：# / 商品名称 / 规格 / 级别 / 销售额 / 毛利 / 毛利率 / 销量 / 订单数 / 客户数 / 首次动销 / 最近动销 / 累加占比 / 动销 / 潜力 / 库存总量 / 库存状态（彩色徽标） / 库销比（含 ⓘ 口径提示）
- 点击行打开商品详情抽屉；级别筛选下拉含 D 级与 4 种潜力类型；工具栏含库存状态筛选下拉（6 级 + 全部）
- 快捷筛选标签动态计数：SABCD/零动销/潜力标签数字仅受穿透条件影响（图表穿透 / KPI 卡片穿透 / 结构优化穿透），不受工具栏搜索 / 下拉 / 时间范围等筛选影响。穿透后标签显示穿透范围内各商品级别的分布，工具栏筛选只过滤表格显示不改标签数字
- KPI 卡片点击穿透：8 张 KPI 卡片支持点击穿透到商品明细列表——商品总数/总销售额/总毛利→清除所有穿透；零动销→穿透到 dormant；潜力→穿透到 potential；缺货→穿透到 out+urgent；积压→穿透到 over+dead；负毛利→穿透到 profit<0。穿透时卡片高亮 + 显示穿透提示条
- 🧩 商品结构优化 Tab（v1.3.0 新增，v1.3.1/v1.3.2 交互升级，v1.6.0 列扩展；位于商品级别明细后方；16 列统计口径与 SABCD 汇总表一致）
- 14 个子分类（每行显示分类定义）：
- S 级：S1 高毛利核心（毛利率≥高毛利线 且 累加占比≤线，自动）/ S2 自有品牌重点商品（手动）/ S3 重点新品（手动）/ S4 行业畅销·公司缺量（手动）
- A 级：A1 中毛利（中毛利线≤毛利率<高毛利线 且 累加占比≤线，自动）/ A2 有返利费用（手动，默认从累加占比≤线中选）
- B 级：B1 低毛利（低毛利线≤毛利率<中毛利线 且 累加占比≤线，自动）/ B2 待发展潜力股 C 级商品（手动，累加占比线~100%）
- C 级：C1 超低毛利（毛利率<低毛利线 含负毛利 且 累加占比≤线，自动）/ C2 可备库存·能欠账·可退货（手动，线~100%）/ C3 必备滞销品（手动，线~100%）
- D 级：D1 淘汰品（v1.6.0 改为手动：从 C 类商品中手动选择必须淘汰的品，默认筛选 C 类可扩大范围）/ D2 零动销占库存（销量=0 且 库存>0，自动）/ D3 停用占库存（销量=0 停用且库存>0，自动；无停用状态字段时恒为 0）
- 分类优先级（v1.6.0 更新）：手动分类 > D3 > D2 > S1/A1/B1/C1（毛利率分段互斥，C1 吸收原 D1 负毛利商品）> 其他；商品不可多归（手动归类自动移出其他手动分类与自动分类）
- 累加占比线（默认 80%）独立于 SABCD 级别阈值，页面有提示文案避免混淆
- 汇总行：S/A/B/C/D 各级汇总（子分类并集）+ SA 汇总 + SAB 汇总 + 其他（未归类，弹窗显示逐商品原因）+ 总计，共 23 行数据 + 5 个级别分组头
- 分组化表格布局（v1.3.1）：S/A/B/C/D 各级前有跨列分组头（级别色条 + 描述）；子分类行缩进；级别汇总行加粗浅底；SA/SAB 跨级汇总琥珀色底；空手动分组数字列显示「—」整行弱化（区别于真实 0）
- 穿透弹窗（v1.3.1，替代跳 Tab）：点击任意行弹出 1100px 宽明细弹窗（不切换页签）；支持搜索/动销状态/库存状态/毛利率区间/分类/品牌筛选 + 50 条分页；单组穿透含 SABCD 原级别列，多组穿透含结构分类列，「其他」穿透含未归类原因列；底部操作条支持 转移至手动分组 / 移除（仅手动分组可移除，移除后回落自动规则）/ 导出 CSV（带 BOM，跟随当前排序）
- 弹窗表格样式与明细表统一（v1.3.2）：斑马纹 + hover 高亮、SABCD 彩色方块徽标、销售额 ¥万格式加粗、累加占比带进度条、动销彩点标签、库存状态彩色标签、序号列、商品名超长省略悬停全名
- 全选交互（v1.3.2 重构）：表头复选框 = 三态切换当前页全选/取消；「全选 ▾」下拉 = 全选当前页 / 全选筛选结果（N 条）/ 取消全部已选；底部操作条只保留纯操作（已选计数 + 转移/移除/导出）
- 表头点击排序（v1.3.2，三处统一补齐）：商品级别明细表（销售额/毛利/毛利率/销量/订单数/客户数/累加占比/库存总量/库销比 9 列）+ 穿透弹窗与选择商品弹窗（销售额/毛利率/累加占比/销量），点击切换降序↔升序，箭头指示；累加占比列始终按销售额降序口径计算（帕累托语义与显示排序无关）
- 手动分类交互：行内「＋添加商品」按钮 → 选择弹层（1100px 宽；搜索/级别/累加占比/动销状态/库存状态/毛利率区间/分类/品牌筛选；默认定位到分类对应级别与占比区间，可自由切换；50 条分页 + 表头按页全选 + 全选下拉）；数据持久化在 localStorage（页面有提示）
- 毛利率阈值设置：Tab 内独立 ⚙ 幽灵按钮入口（白底主色描边 + hover 浮起，与 SABCD/库存阈值分离），可配置高毛利线/中毛利线/低毛利线/累加占比线（默认 15/8/6/80），校验 0<低<中<高、线∈[50,99]；应用后即时重算
- 💰 员工薪酬绩效 Tab（v1.4.0 新增，位于商品结构优化后方；按结构优化级别的薪酬测算工具，不改自动 SABCD 口径）
- 数据联动：级别行（S/A/B/C/D）= 结构优化页签对应级别全部子分组并集（S=S1~S4，A=A1~A2，B=B1~B2，C=C1~C3，D=D1~D3），在结构优化页签添加/转移/移除商品后本表实时联动重算（包装 renderOptSummaryTable 实现，不侵入原逻辑）；未归类商品不计入并显示提示
- 表格 9 列：级别 / 商品数 / 销售额(万) / 毛利(万) / 毛利率 / 月任务(万) / 任务绩效 / 超任务奖金 / 预计奖金（后 4 列表头带 ⓘ 口径提示）
- 行结构：S → A → SA合计 → B → SAB合计 → C → D → 总计（SA/SAB 为部分合计行，总计=五级并集），全部行可点击穿透弹窗查看商品明细（复用结构优化穿透弹窗）
- 单元格直接编辑：月任务(万) / 任务绩效(%) / 超任务奖金(%) 三列点击变输入框，Enter/失焦保存、Esc 取消；非法输入（非数字/负数/提成>100）自动还原不保存；完全由用户填写，不设默认值；配置持久化在 localStorage（
prodInsight_salaryCfg_v1） - 预计奖金阶梯公式：预计奖金 = min(销售额, 月任务) × 任务绩效% + max(0, 销售额 − 月任务) × 超任务奖金%；月任务未填显示 —，绩效/超任务未填按 0 计；部分合计行奖金=各级别之和、提成点显示 —
- 指掌建议（静态 4 条）：卖高销量高毛利超额高提成 / 低毛利引流品 0 提成 / 指掌天下「不同商品不同提成点」落地 / 总奖金与改革前保持相对一致
- AI 建议（动态规则）：未填配置引导从 S 级开始；超任务奖金 ≤ 任务绩效 激励不足预警；预计奖金合计占毛利比 >15% 红线预警 / <5% 激励偏弱；C 级低毛利 0 提成建议（已设提成则警示）；D 级不设提成清仓建议
- 📦 库存优化建议 Tab（v1.5.0 新增，位于员工薪酬绩效后方；按结构优化级别的库存结构分析与优化建议）
- 数据联动：与薪酬绩效相同，级别行 = 结构优化页签对应级别全部子分组并集，结构优化页签变更后实时联动重算；未归类商品不计入并显示提示
- 表格 9 列：级别 / 商品款数 / 库存金额(元) / 库存占比 / 可售天数 / 断货款数 / 断货紧急款数 / 超额库存款数 / 积压超额金额(元)（全部自动计算，表头带 ⓘ 口径提示）
- 可售天数 = 该级别库存总量 ÷ 该级别日均销量（日均销量 = 统计区间总销量 ÷ 区间天数）；≤ 断货紧急线红色、> 超额库存线橙色；有库存但区间无销量显示 ∞；无库存档案显示 —
- 行结构：S → S1~S4 → A → A1~A2 → SA合计 → B → B1~B2 → SAB合计 → C → C1~C3 → D → D1~D3 → 总计（每级 1 级行 + 子分组行 + 部分合计 + 总计；空手动组整行 — 弱化），全部行可点击穿透弹窗
- 积压超额金额口径（与 SABCD 商品汇总表一致）：(库存数量 − 积压线天数 × 日均销量) × 成本单价，零动销商品全额计；断货 = 库存总量 ≤ 0（方案C 口径）
- 4 张优化建议卡片：断货治理（断货/断货紧急款数 + 指掌天下智能采购建议）/ 可腾出资金（SAB/C/D 积压超额金额 + 原因文案 + 占总库存比）/ 仓库效率（SAB 近验货台、C/D 分区，拣货路径减半）/ 仓库面积（C+D 库存金额与占比）
- 指掌建议（静态）：智能采购 / 库存上下限设置；AI 建议（动态规则）：断货风险 / SAB 拍脑袋进货积压 / C 品小批量勤补货 / D 级占比告警 / SAB 库存集中度评估
- 抽屉（点击商品行）：7 区块
- 核心指标（销售额/毛利/毛利率/总销量/订单数/动销客户数）
- 动销周期（首次/最近动销/成交均价/排名）
- 库存概况（库存总量/可用/成本均价/库存总额/库销比/上下架 + 上下限预警 + 库存状态徽标 + 可售天数 = 库存 ÷ 日均销量，零动销显示 ∞；库存表无此商品时显示降级文案）
- AI 建议（按级别+动销+潜力+库存状态生成）
- 业务员推销话术（按动销状态四分支：畅销=爆款主推/正常=稳定推荐/慢动=促销推荐/零动销=清仓培育；带一键复制按钮）
- 销售额趋势图（monthlySales 月度柱图，缺月补 0）
- Top 采购客户表（名称/销售额/销量/占比，Top5）
- 导出（v1.6.0 升级为 5 页签工作簿「商品维度深度分析.xlsx」，导出前自动重算结构分组，与页面当前状态一致）：
- 商品级别明细：22 列，含规格/动销客户数/库存总量/库存状态/日均销量/单位/库销比/成本均价/库存总额，按销售额降序
- 商品结构优化：19 列级别汇总表（分组/名称/类型/定义 + 15 项统计，与页面 16 列表口径一致），含 S/A/SA/B/SAB/C/D 级汇总行 + 其他 + 总计
- 员工薪酬绩效：级别/说明/商品数/销售额/毛利/毛利率 + 月任务/任务绩效/超任务奖金（取自页面已填的 localStorage 配置）/预计奖金，含 SA/SAB/总计合计行
- 库存优化建议：级别/分组 9 列（商品款数/库存金额/库存占比/可售天数/断货/断货紧急/超额库存/积压超额金额），含各级 + 分组 + SA/SAB/总计行，可售天数 ∞ 表示有库存无销量
- 商品结构优化明细：16265 个商品逐行展示优化后的对应结构（排名/商品/SABCD级别/优化后分组/分组名称/自动手动/销售额/毛利/毛利率/累加占比/库存状态/未归类原因）
时间区间口径（顶部数据范围与筛选）
- 数据范围：顶部显示全量销售明细的最小~最大日期
- 业务日期口径：统一优先使用「录单时间」作为业务日期（掌天下等系统批量过账时「过账时间」常为同一时间戳）；「录单时间」缺失时回退「过账时间」，两者皆无时该行不参与日期相关计算
- 筛选规则：点击「筛选商品」后，按「最近动销日期落在所选区间内」过滤下方商品列表（零动销商品无日期时保留显示）；KPI/级别/动销/潜力/AI 建议基于全量数据不随筛选重算
- 日期基准统一：动销分析时间窗口以「数据截止日 = 全量最大日期」为基准，不使用当前系统日期
字段降级策略
| 缺失字段 | 降级处理 |
|---|---|
| 成本金额 | 毛利 = 销售额，毛利率 = 100% |
| 单据编号 | 订单数 = 行数估算 |
| 规格 | 商品粒度退化为按名称聚合 |
| 库存状况文件 | 库存列/库存概况/库销比/上下限预警不可用，仅销售分析 |
| 上下架状态/上下限 | 抽屉库存概况相应项显示「—」 |
| 分类/品牌 | 可选字段（normalizer 已预埋别名映射：分类/商品分类/类别/品类；品牌/厂牌/商标）。源数据有则透传到 DATA，弹窗筛选项自动显示；无则自动隐藏，不影响其他功能 |
技术架构
数据源 → normalizer.py（字段归一化） → analyzer.py（计算引擎） → template.html（渲染）
scripts/normalizer.py：销售/库存 Excel 解析、字段别名映射、库存多编号聚合、日期归一scripts/analyzer.py：SABCD 分级、动销统一口径模型、潜力识别、库存状态 6 级分类、库存合入、KPI、AI 建议scripts/main.py：主入口，协调三阶段流程scripts/template.html：与客户维度 v1.6 同构的数据驱动 HTML 模板scripts/mcp_fetcher.py（v1.6.2 新增）：MCP 数据拉取工具，含 503 自动重试（自动补 hdsaas: always）+ 断点续传 + 按天并发（销售）/ 翻页并发（库存）+ 全量校验；CLI 子命令sales/stock/validate-sales/validate-stock
执行流程
当用户触发此 Skill 时，严格按照以下步骤执行：
Step 1 — 确认数据来源
方式 A：Excel 上传
- 确认用户提供的销售明细文件路径（必须）
- 确认库存状况文件路径（可选，可多个）；未指定时提示可补充以解锁库存/库销比分析
方式 B：MCP 连接器
- 确认 API Key（corpId 从 JWT payload 解析）
- 调用 scripts/mcp_fetcher.py sales 拉取销售明细（内部已实现按天逐日 + 5 并发 + 断点续传 + 串行重试 3 轮 + 503 自动重试 + 全量校验）：
bash
python scripts/mcp_fetcher.py sales \
--corp <corpId> --token <JWT> \
--start <start> --end <end> --out <mcp_raw 目录>
- 调用 scripts/mcp_fetcher.py stock 拉取库存（自动探测总页 + 5 并发翻页 + 多轮重试）：
bash
python scripts/mcp_fetcher.py stock \
--corp <corpId> --token <JWT> \
--out <stock_raw 目录> [--page-size 100 --enable -1]
- 拉取完成后必跑 validate（防漏数自检）：
bash
python scripts/mcp_fetcher.py validate-sales \
--raw-dir <mcp_raw 目录> --start <start> --end <end>
python scripts/mcp_fetcher.py validate-stock \
--raw-dir <stock_raw 目录> [--expected <首页探测的总数>]
都返回 ok: true 才进入下一步；不通过按 warnings 处理
- 拉取完成后将明细文本转 Excel 后传入分析流程（用 parse_mcp_text.py / parse_stock_text.py 或类似解析脚本）
Step 2 — 安装依赖（如需要）
- 检查 pandas、openpyxl、xlrd 是否已安装；缺失时在运行时虚拟环境安装：
bash pip install pandas openpyxl xlrd xlsxwriter
Step 3 — 运行分析
# 销售明细 + 库存（显式指定）
python scripts/main.py "销售明细.xlsx" --stock "库存状况1.xls" "库存状况2.xls"
# 自动识别：文件名含「库存」的自动作为库存档案
python scripts/main.py "销售明细.xlsx" "库存状况1.xls" "库存状况2.xls"
- main.py 输出 JSON 摘要（含 success、output_path、summary：商品总数/SABCD 分布/库存商品数）
- success 为 false 时向用户报告错误信息
Step 4 — 呈现报告
- 读取输出的 HTML 文件路径（命名：
商品维度深度分析_{timestamp}.html） - 使用
present_files将 HTML 报告展示给用户
Step 5 — 引导使用
- ⚙ 齿轮图标可调整 SABCD 阈值（默认 40/60/80/100，v1.6.0 更新：C ≤ 100，销售额=0 显式判 D）、动销阈值（统一句式：天数 + 累计/每周/每月口径 + 次数，三级独立）和库存预警阈值（默认断货紧急 3 / 低库存 15 / 超额库存 30 天）
- 点击商品行可查看详情抽屉（含库存概况与业务员推销话术）
- 级别行/饼图扇区可穿透筛选
- 「导出 Excel」按钮导出 5 页签工作簿（商品级别明细 / 商品结构优化 / 员工薪酬绩效 / 库存优化建议 / 商品结构优化明细）
注意事项
- 依赖项：Python 3.8+、pandas、openpyxl、xlrd（.xls 库存文件）、xlsxwriter
- 数据要求：销售明细必须包含「商品名称」和「优惠后金额」字段
- 文件格式：支持 .xlsx / .xls / .csv
- 库存口径：优先读取「修改」sheet（人工修正成本价版本），表头在第 2 行；多文件按名称+规格聚合
- 数据量：10 万行以内数据处理时间约 30-60 秒
- 不包含敏感信息：所有脚本仅做本地数据处理，不上传任何数据
- 报告为自包含 HTML：无需网络即可查看图表（ECharts CDN 有本地降级）
- 掌天下适配：支持掌天下导出的字段命名，normalizer.py 自动映射
- MCP 连接器：MCP 返回数据字段需与 normalizer.py 字段映射对齐，如字段名不一致需在 normalizer.py 中补充别名映射
