这份设计覆盖 Amazon 与 Shopify 的 55 项经营指标，逐项写清计算、取值、展示、数据状态和操作边界，并给出卡片筛选与排序、跨市场展示、参数弹窗、洞察引擎、处理闭环、数据表和可交互页面原型。
| 模块 | 设计内容 | 在链路中的作用 |
|---|---|---|
| 1 | 设计目标与商家价值主张 | 为什么做这个功能，商家凭什么会用 |
| 2 | 指标池总览：55 项 · 分平台清单与命名规范 | 我们到底会有多少指标池 |
| 3 | 指标定义规范（Metric Spec Schema） | 每个指标要定义哪些字段才算设计完成 |
| 4 | Amazon 指标章节（22 项，逐项三层逻辑） | 计算逻辑 / 取值逻辑 / 展示逻辑 |
| 5 | Shopify 指标章节（33 项，逐项三层逻辑） | 同上，独立维护 |
| 6 | 同名异实对照表（12 组） | 为什么必须分平台，不能合并 |
| 7 | 展示决策管线（三道闸门 + 全静默兜底） | 没变化怎么展示？都没大变化呢？ |
| 8 | 卡片交互：通用基础 + 6 类原型 + 逐指标矩阵 | 每个指标的交互效果 |
| 9 | 详情参数弹窗 GUI 规范 | 参数选择、提示词编辑、确认发送 |
| 10 | 洞察引擎（三层分工） | 事实、归因、动作分别由谁生成 |
| 11 | 数据链路、表结构与双语（zh / en） | 工程落地 |
| 12 | 可交互原型 | 点击、展开和参数弹窗怎么操作 |
| 13 | 完整交付合同、验收与运行校准 | 怎样把整条链路做完并证明可用 |
这个功能如果只是「把数字搬到页面上」，商家没有理由多看第二眼——他们在平台后台就能看到数字。它要成立，必须回答商家真正的三个问题：我该操心什么、为什么会这样、现在该做什么。指标卡片负责第一问，洞察文案负责第二问，参数弹窗 + Skill 负责第三问。
| 原则 | 含义 | 违反后果 |
|---|---|---|
| ① 风险优先于变化 | 指标达到官方绩效阈值、商家目标或已配置的提醒线，即使环比没有变化也必须展示；阈值来源同时显示。 | 长期问题因「没变化」被永久隐藏，商家误以为一切正常 |
| ② 分平台独立维护 | 同名指标在两平台各有独立的 metric_id、口径、阈值、文案。禁止「一套逻辑加 if platform」。 | Shopify 净销售额与 Amazon 订购商品销售额不是同一字段，不能混用 |
| ③ 数字只有一个来源 | 卡片数值一律来自 calculator 输出字段，不在前端二次计算、不由模型生成。 | 卡片与 Skill 报告数字不一致，信任崩塌 |
| ④ 经营区永不空屏 | 全静默、样本不足和拉取失败有明确页面状态；unsupported/not_applicable 不单独出卡，只在能力矩阵或平稳摘要中计数。 | 既不能用空白让商家以为功能坏了，也不能让不适用能力占据经营注意力 |
| ⑤ 洞察可降级 | 文案生成链路（事实层/行动层代码，或归因层模型/规则）失败时，卡片仍能渲染数值 + 状态 + 按钮。 | 模型超时导致整页不可用 |
| 指标 | 目标 | 为什么这个数能说明价值 |
|---|---|---|
| 卡片区曝光→点击详情率 | ≥ 12% | 作为上线起始验收线；按卡位、指标和店铺类型分层观察并持续校准 |
| 弹窗打开→确认发送率 | ≥ 55% | 低于此说明参数/提示词默认值不合理，用户放弃 |
| 发送→Skill 会话完成率 | ≥ 80% | 验证预填契约是否真的让 Skill 免澄清 |
| 数值错误投诉率 | ≤ 0.1% | 原则③的硬底线；超标即停止或回滚受影响指标的计算版本与卡片展示，模型归因不承担数字生成 |
| 7 日回访率（卡片区） | ≥ 40% | 验证「不是一次性新鲜感」——文案疲劳会直接打到这个数 |
指标池固定为 55 项，但每项能否运行取决于平台权限、报表、历史深度和外部连接器。每个 Metric Spec 都保存 capability 与 availability；缺权限、缺历史或数据源不满足时按第 3.4 与 7.6 节降级，不用近似字段冒充。
| platform | dimension | 含义 | 对应 Skill 维度 |
|---|---|---|---|
| amz | rev | 收入表现 | D1 Revenue Health / revenue |
| shp | inv | 库存健康 | D2 Inventory Risk / inventory |
| — | prod | 商品表现 | D3 Product Performance / product |
| — | cust | 客户健康 | D4 Customer Health / customer（Amazon 无） |
| — | ops | 运营履约 | D5 Operations Efficiency |
| — | fin | 费用与利润 | D1 延伸（Amazon 费用结构 / Shopify 毛利代理） |
| 维度 | Amazon | Shopify | 差异根因 |
|---|---|---|---|
| rev 收入表现 | 6 | 6 | 数量相当但口径完全不同：Amazon 有会话/转化率，Shopify 有渠道/国家结构与折扣依赖度 |
| inv 库存健康 | 5 | 6 | Shopify 以 variant × location 和订单路由判断可履约性；Amazon 以 marketplace × sellerSKU/FNSKU × FBA 项目记录可售、占用与在途状态 |
| prod 商品表现 | 6 | 7 | Amazon 有 Featured Offer / Listing 健康；Shopify 有 5 类商品角色与毛利代理 |
| cust 客户健康 | 0 · design_na | 7 | Amazon 不提供买家身份数据，整维度设计性 N/A |
| ops 运营履约 | 3 | 4 | Shopify 多「弃单漏斗」；Amazon 履约逾期仅对自发货部分成立 |
| fin 费用利润 | 2 | 3 | Amazon 费率结构来自 financial events；Shopify 依赖 unit_cost 是否录入 |
| 合计 | 22 | 33 | 55 |
55 项是指标池（可计算、可入库、可被弹窗参数引用），不是卡片位。首屏最多渲染 6 张卡片。三层定位如下。
第 4、5 章每一项指标都按这张表填满才算「设计完成」。这套 schema 同时是配置表结构——阈值、文案、交互原型、预填契约全部外置，不写进代码。
| 字段 | 归属层 | 说明 |
|---|---|---|
| metric_id | 标识 | 平台·维度·slug，全局唯一 |
| issue_group / issue_scope_fields / merge_version | 标识 | 声明可合并的经营主题、作用对象字段与合并规则版本。issue_group 为空时等于 metric_id；issue_key = hash(store_id, marketplace_id, issue_group, normalized_scope, merge_version)，相同对象和主题才可合并。 |
| tier | 标识 | 1 / 2 / 3，决定是否参与首屏竞争 |
| formula | 计算逻辑 | 可执行的数学定义，含窗口与分母口径 |
| window_start/end / date_basis | 计算逻辑 | 完整日、[start,end)、事件日期口径与对比基准；销售/流量常用 7 日，库存销速 28 日，PFC 固定 7 日，LSR 固定 10/30 日，客户/退货按 cohort 成熟窗 |
| unit / precision | 计算逻辑 | pct / pp / count / currency / days；小数位 |
| higher_is_good | 计算逻辑 | 决定 _change_class 的方向语义 |
| source_pipeline | 取值逻辑 | 产出数据的 pipeline 脚本 |
| source_field | 取值逻辑 | calculator 输出 JSON 里的确切字段路径 |
| availability_status | 取值逻辑 | ok / partial / estimated / insufficient_sample / permission_denied / unsupported / not_applicable / source_failed / stale。原始 pipeline outcome 先通过 outcome_map 映射：permission_missing→permission_denied，connector_error/failure_na→source_failed，design_na→not_applicable；unavailable 与 data_not_available 必须继续细分，不能作为最终状态。0 与任何不可用状态严格分开。 |
| maturity / coverage | 取值逻辑 | 每项指标独立保存 provisional / settling / final，以及 covered_count、eligible_count、coverage_pct、exclusions |
| comparison_status / reason_code | 取值逻辑 | comparison_status 只取 comparable / no_baseline / insufficient_history / incompatible；reason_code 保存 zero_denominator / cost_missing / no_velocity / window_incomplete 等具体原因。它们不进入 availability_status，也不与 maturity 拼成一个字符串。 |
| comparability_key | 取值逻辑 | metric、source、date_basis、window、timezone、marketplace、currency、formula 与 threshold version 全部兼容才允许计算变化 |
| outcome_map | 取值逻辑 | 拉取失败时的 _outcome 取值与对应提示语 |
| thresholds / threshold_type | 展示逻辑 | 四态区间与来源：platform_hard / merchant_target / storeclaw_internal / adaptive_baseline / eligibility_gate；平台官方线永不被内部线覆盖 |
| has_official_platform_threshold | 展示逻辑 | 仅用于真正的官方绩效要求；卡片显示“官方绩效阈值”与来源链接，和 StoreClaw 提醒线分开 |
| change_significance | 展示逻辑 | 「算显著变化」的最小幅度，闸门 1 候选池判定用 |
| delta_mode / delta_unit | 展示逻辑 | relative_pct / absolute_pp / absolute_value 与相应单位；change_significance 必须使用同一 mode，页面不得根据指标单位自行猜测 |
| priority_key | 展示逻辑 | 所有候选指标使用第 7.3 节同一 priority_vector；数值向量 DESC 后再用 stable_metric_id ASC，组成唯一确定性排序键 |
| owner / due_at / task_status | 闭环 | 负责人、截止时间与 unassigned / assigned / in_progress / blocked / verifying / done / reopened；验证通过前不能进入 done |
| copy_key | 展示逻辑 | 双语文案键（zh / en 两套） |
| interaction | 交互 | 6 类原型之一（见第 8 章） |
| prefill | 交互 | 目标 Skill、维度、默认参数、默认提示词模板 |
不新造一套状态机。两个 Skill 的 scoring / calculator 脚本已经在用下列字段，卡片体系直接沿用，保证卡片与 Skill 报告口径一致。
| 已有字段 | 来源脚本 | 在卡片体系中的用途 |
|---|---|---|
| status: normal / watch / alert / na | amazon_health_scoring · shopify_health_scoring | 直接映射卡片四态配色 |
| _outcome: insufficient_data 等 | 两平台 scoring | 属于 pipeline 原始结果；先经 outcome_map 归一为 canonical availability_status，再决定页面分支 |
| _sample_count | 两平台 scoring | 填入「仅 N 单，低于 10 单最低样本」提示 |
| _change_class(x, higher_is_good=) | 两平台 scoring | 变化方向的好坏判定，卡片箭头颜色 |
| data_gap / velocity_only | amazon_inventory_calculator | 库存类指标的部分可信状态 |
| turnover_days_low_confidence | amazon_health_scoring | 周转天数卡片加「低置信」角标 |
| conversion_available: False | amazon_health_scoring · amazon_product_calculator | Amazon 商品级转化率指标不渲染而非显示 0 |
| sessions_available: False | shopify_revenue_calculator | Shopify 会话/转化类指标不渲染 |
| unit_cost_available | shopify_inventory / product calculator | 毛利代理类指标的前置开关 |
| design_na | store-health-diagnostics 原始错误分类 | 映射为 not_applicable；Amazon 客户维度整体不出现在页面，也不出现「不可用」提示 |
除了上面复用的降级词汇，Metric Spec 还需要两个新增字段。它们不描述指标算什么，而描述指标的数据行为——沉降方式与可视化方式，两者都由第 11.3 节的 A/B/C 分类推导。
| 字段 | 取值 | 决定什么 |
|---|---|---|
| settle_class | A_volume / A_ratio / B_point / C_longtail | 成熟度阶梯（settle_age 取值）、漏跑是否可自愈、对比基准选结算基准还是同龄基准。这是最根本的分类，其余两项都从它推导 |
| chart_form | rolling_window_sum / rolling_window_ratio / point_in_time / mature_cohort_weekly | 迷你图画什么、窗口如何计算、点数和末端虚线几段。window_days、numerator、denominator 与 history_days 由每项 Metric Spec 明确给出；末点必须等于卡片头条。 |
每项能力先判断数据属于平台直接事实、StoreClaw 可复算指标、外部系统补充，还是只能估算/人工核对。能力状态按店铺、市场、权限、角色和数据历史逐项保存，不用一份全局“支持/不支持”清单替代真实连接状态。
| 数据项 | 平台字段或报告 | 权限与前提 | 粒度 / 时间 | StoreClaw 处理与页面标注 |
|---|---|---|---|---|
| Shopify 销售、AOV、毛利 | ShopifyQL sales / profitability | read_reports；毛利还需销售时历史 COGS | 销售/冲销事件、店铺时区、币种 | 商品净销售、净收款、毛利、贡献利润分开；成本覆盖不足显示 partial，不给整店实际利润结论 |
| Shopify 流量与归因 | ShopifyQL sessions；Order.customerJourney；GA4/Web Pixel | 报表/客户数据权限及外部连接器 | CustomerJourney 只描述已转化订单前 30 天路径 | 完整 PV/UV/sessions/全站转化分母用流量源；订单路径不冒充全部访客 |
| Shopify 广告成本与投放 | Meta Marketing API、Google Ads API、TikTok Ads API | 各广告账户分别授权；归因窗、时区、币种和账户范围必须登记 | campaign/ad/product 与各平台归因时间 | Shopify 本身不提供跨平台广告成本真值。只有对应连接器已授权才显示 spend、impressions、clicks、CPC、平台归因转化与 ROAS；广告归因销售不等于 Shopify 店铺总销售，未连接时状态为 not_connected/conditional，不用 0 补齐 |
| Shopify 客户与 LTV | Customers、完整 Orders、cohort | read_all_orders 与受保护客户数据批准可能需要 | customer/cohort，91/180/365 天或生命周期 | 历史收入 LTV、历史毛利 LTV、预测 CLV 分开；API 近 60 天截断和分页不完整时降级 |
| Shopify 订阅 | SubscriptionContract / billing attempts | 应用拥有合同、own subscription scope、平台批准、商家实际使用 | 合同、扣款尝试、每日快照/webhook | billing attempt 不是变更史；没有历史快照时不计算新增/流失/平均订阅时长 |
| 普通网页 SEO | Search Console Search Analytics / URL Inspection | 站点验证与 GSC 权限 | query/page 与单 URL 索引状态 | Google Indexing API 只用于 JobPosting 或 VideoObject 内 BroadcastEvent，不用于普通商品/博客收录 |
| Bing 与 AI 搜索可见性 | Bing Webmaster API；AI 搜索人工抽查或独立第三方监测 | Bing 需验证站点并授权；AI 搜索监测需登记 provider、查询、地区、时间与采样方法 | Bing 的关键词、流量、抓取与 URL 提交；AI 搜索按查询样本观测 | Bing 可通过官方 Webmaster API 补充。ChatGPT Search、Perplexity 等通用模型/搜索 API 不被当成站点级“已收录查询 API”；没有经过核验的官方站点收录接口时，只能写“本次查询样本中出现/未出现”，不能写成全局收录结论。这一能力属于外部监测，不纳入 55 项经营指标池 |
| Amazon 销售与转化 | Sales & Traffic Business Report | 账号角色、市场和报表资格 | marketplace、ASIN、完整日 | Ordered Product Sales、Units、Order Items、Sessions、Unit Session Percentage 按官方字段对账；Orders API 不静默替代 |
| Amazon 广告 | Amazon Ads API Reporting v3：impressions、clicks、cost、sales14d、purchases14d、acosClicks14d、roasClicks14d、searchTerm | 广告账户授权、profile/marketplace 与归因窗口 | SP / SB / SD；campaign、ad group、ad、keyword、search term | 广告归因销售/订单不等于店铺总销售；ACOS/ROAS 只在同一广告类型、归因窗、币种与市场内比较，不能与 Sales & Traffic 销售静默合并 |
| Amazon 库存与费用 | FBA Inventory、Inventory Planning/Aged/Excess、Finances v2024-06-19 | 对应市场、角色、报表与财务权限 | 库存时点；财务 posted time | 历史库存靠每日快照；估算仓储费与实际扣费分开；无法归因费用单列 |
| Amazon 综合利润 | 自建：Ads cost + Finances + COGS/头程/履约；可选第三方：LingXing get_profit_report_msku | 多源授权、MSKU/ASIN/订单映射与成本覆盖；第三方连接需单独授权 | marketplace × MSKU/ASIN × 日期/订单 | 当前 55 项池只把可匹配平台费率与退款金额率作为事实，不把它们称为净利润。启用综合利润时固定显示 provider、匹配覆盖率、广告归因窗和未分配费用；LingXing 聚合值与自建值是两条互斥来源，不能混加 |
| Amazon 促销 | Promotion Performance / Coupon Performance reports | 相应角色、Brand Registry、市场和账户资格 | 活动/优惠券、报表周期 | 状态写 conditional，不笼统写“没有 API” |
| Amazon 自然排名 | SP-API 无官方精确自然位次；第三方 provider 可补充 | 第三方授权与采样条件 | 关键词、地区/邮编、设备、采样时间 | 始终显示 provider 与 estimated；不与官方广告 search term 混写 |
Amazon 的 22 项指标分别来自 Sales & Traffic、Orders、FBA Inventory、Performance、Finances 与商品状态数据。销售、库存、绩效和财务事件的时间口径并不相同，必须按 seller、marketplace、SKU/FNSKU、订单、币种和事件日期分别落库；页面只比较口径兼容的数据。
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| amz.rev.gmv_wow 订购商品销售额变化 T1 稳定 ID；页面名对齐 Ordered Product Sales |
delta_pct = (current_7d − previous_7d) ÷ abs(previous_7d) × 100% 金额只取 Sales & Traffic 的 orderedProductSales，同一 marketplace、币种、时区下比较两个完整 7 日窗；不把 Order Total 当作静默回退。 |
源：Sales & Traffic Business Report → orderedProductSales 保存 date_basis=order_date、窗口、币种、时区、marketplace、公式版本。前窗为 0 时写 comparison_status=no_baseline、reason_code=zero_baseline；报表无权限、未同步或窗口不完整分别映射 availability_status 或 reason_code，不能当 0。 |
状态以店铺历史基线和商家目标判断；相对变化用 %，不是 pp。阈值类型固定显示 adaptive_baseline 或 merchant_target。排序由第 7.3 节唯一算法计算。 |
| amz.rev.orders_trend 日均订单项数趋势 T1 |
daily_order_items = totalOrderItems_7d ÷ 7，与前一完整 7 日窗比较；断流检测使用逐日 totalOrderItems，连续 ≥3 日为 0 时还要结合历史活跃基线确认 | 源：Sales & Traffic 的 totalOrderItems 及逐日结果。若产品要展示去重订单数，必须另从同一 Orders cohort 按 AmazonOrderId 去重，不能与订单项数混用 | 连续 3 日为 0且此前活跃时置 forced_incident=1；其它变化按相对百分比判定，显著性写 |Δ%| ≥ 10%，不是 pp |
| amz.rev.aov_change 每订单项销售额变化 T1 稳定 ID；页面不把它称为客单价 |
sales_per_order_item = orderedProductSales ÷ totalOrderItems。若另做真正的每单金额，必须在同一 Orders cohort 内用商品销售额 ÷ 去重 AmazonOrderId，并使用不同 canonical 字段 | 取 Sales & Traffic 的 orderedProductSales 与 totalOrderItems。分母为 0 时 value 为空并写 reason_code=zero_denominator；口径不一致写 comparison_status=incompatible；样本不足写 availability_status=insufficient_sample，不使用笼统的 insufficient_data。 | 它是结构信号，不设置平台处罚状态；默认只在变化超过店铺历史噪声带时进入候选。相对变化用 %，页面同时显示分子、分母和口径名。 |
| amz.rev.conversion_rate 转化率 T1 |
Unit Session Percentage = unitsOrdered ÷ sessions × 100%；优先直接读取官方 unitSessionPercentage。变化用 delta_pp=current_pct−previous_pct，绝不使用 orders ÷ sessions 冒充官方转化率。 | 源：Sales & Traffic Business Report。保存 unitsOrdered、sessions 与官方百分比以便对账。报表无权限、同步中、市场不支持和样本不足分开显示。 | 默认用店铺历史基线识别异常，threshold_type=adaptive_baseline；StoreClaw 可配置观察线必须明确标为内部提醒。数据失败只出数据状态，不出经营判断。 |
| amz.rev.sessions_trend 会话量趋势 T2 |
(sessions近 − sessions前) ÷ sessions前 × 100% page_views 作为辅助显示不单列指标 |
源：current.sessions / page_views na 条件：同 conversion_rate（同一份报表） |
作为 gmv_wow / conversion_rate 卡片的次级相关信号，不独立占卡位；相对变化显著性示例为 |Δ%| ≥ 10% |
| amz.rev.discount_rate 折扣金额率 T2 |
merchandise_discount_rate = matched_item_promotion_discount ÷ matched_pre_discount_merchandise_sales × 100%。运费折扣使用独立字段和运费基数，不进入商品折扣率。分子、分母必须来自同一 marketplace、币种和订单项集合。 | 只有能够按订单项匹配商品折扣与折前商品金额时才计算；缺字段或匹配覆盖不足时返回 partial/unsupported，不以运费折扣或账号级促销金额代替。0 与“没有数据”严格分开。 | 25% 等数值只能作为 storeclaw_internal 可配置观察线，不是 Amazon 绩效标准。它说明折扣金额占比变化，只能与商品结构、促销类型和利润一起作为排查线索，不能证明销售由折扣带来。 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| amz.inv.stockout_risk_count 断货风险 SKU 数 T1 |
DoC = fulfillable_quantity ÷ daily_velocity_28。风险条件为 预计售罄日 < 最早可补到日 + safety_days；14 天只作为没有补货周期配置时的 StoreClaw 默认提醒线，同时输出命中数和有效 SKU 占比。 | 源：amazon_inventory_calculator → summary 中 critical_stockout + replenish_soon 计数 na 条件：SKU 行 status=data_gap（无库存数据）不计入分子也不计入分母；velocity_only 行只有销速无库存，单列提示 MFN/自发货 SKU 无 FBA 库存 → 排除并在卡片脚注说明排除数量 |
命中 SKU 集合、受影响销售占比或预计售罄日发生变化即重新排序。页面标注 marketplace、库存项目、销速窗口、在途阶段和补货周期；不能显示“账号级共享”这一未经逐项目确认的结论。 |
| amz.inv.overstock_count 积压滞销 SKU 数 T1 |
优先读取 Amazon 的 days of supply、estimated excess quantity 与 sell-through；没有官方派生值时才用 DoC > configured_overstock_days 或“完整 28 日无销量且有可售库存”估算。90 天是 StoreClaw 内部默认，不是平台标准。 | 源：FBA Inventory/Restock 报告与库存快照。成本存在时计算成本库存价值；缺成本时只显示 retail_inventory_value，不得写成资金占用。新品、季节备货、受限商品和活动备货需要排除或单独标注。 | 按估计多余数量、成本价值、受影响 SKU 占比和持续天数排序；页面同时显示成本覆盖率、计算方式与提醒线来源。 |
| amz.inv.turnover_days 平均周转天数 T2 |
Σ(fba_sellable) ÷ Σ(daily_velocity)，按 SKU 销量加权；当 Σ(daily_velocity)=0 时不做除法，value 为空。 | 源：amazon_health_scoring → D2 turnover_days na 条件：无有效销速写 availability_status=insufficient_sample、reason_code=no_velocity；销速样本偏薄写 availability_status=insufficient_sample、reason_code=low_velocity_sample。只有可计算且达到最低样本、但覆盖率偏低时才显示数值并加「低置信」角标。 |
StoreClaw 内部观察线：🔴 >120 天 ｜ 🟢 30~120 天 ｜ 🟡 <30 天（过低时与断货风险联合核查）；StoreClaw 内部显著性线：|Δ| ≥ 15 天。三条都不是 Amazon 标准；排序按第 7.3 节统一字段。 |
| amz.inv.inbound_coverage 在途补货覆盖 T2Amazon 独有 |
在断货风险 SKU 中，只有 预计断货日前可到仓数量 ≥ 到货前需求缺口 + 安全库存 才记为 covered。只有数量、没有 ETA 或阶段时只能记录 inbound_present。 | 源：Working/Shipped/Receiving 等在途阶段、预计到仓日、数量、当前可售和补货建议。缺 ETA 或数量时写 availability_status=partial 与相应 reason_code；缺报表权限时写 availability_status=permission_denied，两种情况都不输出“已覆盖”。 | 作为断货卡片的证据行，显示“已覆盖 / 有在途但无法确认 / 无在途”三组；提醒线由商家补货周期与安全库存决定。 |
| amz.inv.sku_data_gap 库存数据缺口 T3 |
data_gap SKU 数 ÷ 总 SKU 数；含 sku_cleaning 排除项统计 | 源：summary data_gap / velocity_only 计数 + sku_cleaning（return_tracking_subsku / orphan_inventory / total_excluded） | 不做阈值告警。仅在其它库存卡片的数据说明 tooltip 内出现，用于解释「为什么这里 SKU 数和你后台不一样」——这条能显著降低数值争议投诉 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| amz.prod.buybox_deficit_count Featured Offer 占比不足 ASIN 数 T1Amazon 独有 |
count(ASIN where buy_box_pct < 80) 仅统计窗口内有销售或有流量的 ASIN |
源：Sales & Traffic Business Report 的 ASIN 窗口数据，由 amazon_product_calculator 读取 buy_box_pct / buy_box_status。它是可按原窗口重拉的 A_ratio，不是只存在于采集当时的库存类时点值。 na 条件：sales_traffic 不可用 → 整项不渲染 Shopify 侧不存在此指标，不是置 0 而是配置表里根本没有这条记录 |
80% 仅为 storeclaw_internal 默认观察线；它会影响默认购买入口和转化机会，但不是平台处罚线，也不等于商品完全不能销售。ASIN 集合变化时重新进入候选；趋势按同一窗口的分子分母重算。 |
| amz.prod.return_rate FBA 退货率 T1 |
fba_return_rate_30d = 同一 FBA 发货 cohort 在发货后 30 天内的 returned_units ÷ shipped_units。30 天为 StoreClaw 默认观察期，写入 observation_horizon_days=30 与版本；若只能按退货发生日读取 FBA Returns，页面明确标注事件期视图，不能除以本期新订单。 | 源：FBA Customer Returns + 同批 FBA 已发货商品。保存 fulfillment_scope=FBA、原订单/订单项、ASIN/SKU、发货日、退货日、退货原因和处置结果；MFN 发货和排除件数常显。cohort 尚未成熟时写 maturity=settling；已发货件数不足时写 availability_status=insufficient_sample，不把两者拼成一个状态。 | 卡片和报告标题始终保留“FBA”范围。阈值优先使用店铺/品类历史基线；显示 returned/shipped 分子分母、30 天观察期、成熟度、MFN 排除范围和 Top 原因。与退款金额率同时触发时合并成一张卡，避免重复告警。 |
| amz.prod.top3_concentration Top-3 ASIN 集中度 T2 |
Top-3 ASIN 的 Ordered Product Sales ÷ 店铺 Ordered Product Sales × 100% | 源：concentration_pct（health_scoring D3）或由 _by_asin 排序推导 | 60%/80% 只能作为内部观察线。集中度需结合店型、商品生命周期、利润、库存和自身历史判断；单品店或新品期不因高集中度自动判为风险。 |
| amz.prod.listing_flag_count Listing 异常数 T1Amazon 独有 |
count(SKU with 任一 listing_flag) 按 flag 类型分组计数 |
源：SKU 行 listing_flags，四类标签：listing_suppressed→suppressed、listing_quality_risk→quality-flagged、pricing_above_market→priced above market、buybox_loss_non_price→losing Featured Offer on non-price grounds na 条件：listing_health_outcome != success → 不渲染；listing_health_covered_skus 需在脚注披露覆盖范围 |
🔴 有任一 suppressed（forced_incident=1）｜🟡 有 quality_risk 或 pricing_above_market ｜🟢 无 suppressed 不受普通卡位配额阻挡，其余按统一 priority_key 排序 |
| amz.prod.traffic_only_count 有流量零转化 ASIN T2Amazon 独有 |
count(ASIN where sessions > 阈值 且 units_sold = 0) 阈值默认 50 sessions/窗口，避免长尾噪声 |
源：amazon_product_calculator 中 traffic_only: True 行 + summary traffic_only_skus / traffic_matched_skus na 条件：sales_traffic 不可用 → 不渲染 |
🟡 ≥3 个 ｜ 🟢 0~2 个 这是机会信号而非平台故障；按受影响访问量、持续时间和趋势字段进入统一排序 |
| amz.prod.cancel_rate_note 商品级取消率 T3 |
— | 源：SKU 行 cancel_rate_pct 恒为 None（Amazon 不在商品层给出取消数据） | 永不渲染卡片。保留在指标池仅为文档完整性与弹窗参数说明，避免后续开发误以为遗漏。属 design_na |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| amz.ops.cancel_rate 发货前取消率 T1 |
PFC rate = 7日内卖家在确认发货前取消的 MFN 订单数 ÷ 7日全部 MFN 订单数 × 100%。排除 FBA、买家和 Amazon 发起的取消。 | 源：Amazon Account Health/相关绩效数据与可验证的订单取消发起方。卡片必须展示分子/分母；拿不到取消发起方时按实际原因映射为 permission_denied / unsupported / source_failed / partial / insufficient_sample，不得保留 unavailable，也不得用全部 cancelled 近似。 | threshold_type=platform_hard：官方要求低于 2.5%；≥2.5% 为 official alert，2.0%–<2.5% 为 StoreClaw 预警。硬绩效项不因样本少而隐藏，但要显示样本量。 |
| amz.ops.overdue_rate 迟发率（Late Shipment Rate） T1 |
分别计算滚动 10 日与 30 日：晚于 expected ship date 才确认发货的 MFN 订单 ÷ 同窗全部 MFN 订单 × 100%，不含 FBA。 | 源：Amazon 绩效数据及订单的 expected/actual ship time。全 FBA 店铺为 design_na；混合履约只统计 MFN，并显示两个窗口的分子、分母和截止时间。 | threshold_type=platform_hard：任一官方窗口 ≥4% 为 official alert；3%–<4% 为内部预警。不能保留泛化的 28 日或 5% 规则。 |
| amz.ops.shipped_gap 发货缺口 T2Amazon 独有 |
overdue_unshipped_count = count(MFN open orders where LatestShipDate < as_of)；如展示比例，分母是截至 as_of 已到应发日的 MFN 订单。 | 源：Orders 明细的履约状态与 LatestShipDate。按每单承诺日期判断，不统一扣除最近两日；预售、暂停和已取消订单按明确规则排除。 | 这是内部待办证据，不是 Amazon 绩效率。作为迟发率卡片的订单清单，包含逾期时长、订单金额、仓库/履约方式、负责人和处理状态。 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| amz.fin.fee_rate 综合费率 T1Amazon 独有 |
platform_fee_rate = abs(eligible_posted_fees) ÷ matched_merchandise_sales × 100%。销售与费用必须来自同一匹配交易集合；推荐费、FBA、仓储、服务费、退款、赔偿和调整分项展示。 | 源：Finances API v2024-06-19 listTransactions。按 seller、marketplace、order/orderItem、SKU/ASIN、currency、event time 关联；无法归因的账号费用放入 unallocated_account_fees，不按销售额硬摊。 | 卡片主数值为可匹配交易费率，并显示匹配覆盖率和未分配费用。它不是利润；贡献利润还需 COGS、入仓/头程、广告和其他可变成本。 |
| amz.fin.refund_rate 退款金额率 T2 |
refund_amount_rate_30d = 同一原订单 cohort 在订单后 30 天内的 matched_refund_principal ÷ cohort_matched_merchandise_sales × 100%。默认 cohort_window_days=30、observation_horizon_days=30，按同龄前一 cohort 比较并随 Metric Spec 版本化。财务事件发生期只展示 posted refund amount，不把本期退款直接除以本期新订单销售。 | 源：同一 Finances 交易集合；保存退款事件日期、原订单日期、币种、匹配状态、观察龄和覆盖率。无法回连原订单的退款单列，不进入 cohort 比率分子。 | 与 FBA 商品退货率同时触发时合并为一张卡片，分别写清“FBA 件数 cohort”和“退款金额 cohort”；30 天是内部运营观察期，不是 Amazon 官方退款期限，阈值使用商家目标或店铺历史基线。 |
Shopify 的 33 项指标来自销售事件、订单、Inventory Level、客户、退货、履约、弃单和利润数据。会话、转化与营销归因在权限和数据源满足时可取，不应写成平台天然缺失；订单的 CustomerJourney 只覆盖已转化订单路径，完整访客分母仍需 ShopifyQL sessions 或 GA4。Shopify 没有 Amazon 式的卖家绩效阈值，因此多数状态来自商家目标、店铺历史和 StoreClaw 明示的内部提醒线。
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| shp.rev.net_revenue_wow 商品净销售额变化 T1 稳定 ID；canonical name 为 net_sales_wow |
net_sales = gross_sales − discounts − sales_reversals；delta_pct=(current_7d−previous_7d)÷abs(previous_7d)×100%。按 Shopify 销售事件日比较两个完整 7 日窗。 | 源：ShopifyQL sales → net_sales。旧订单在本期发生的退货、取消或改单会在本期形成 sales reversal，卡片要披露事件口径。前窗为 0、权限不足、同步中和窗口不完整分别降级。 | 中文固定写“商品净销售额”，不是净收入或到账。状态以商家目标和店铺历史基线判断；相对变化用 %，排序引用第 7.3 节唯一算法。 |
| shp.rev.gross_sales_wow 毛销售额周环比 T2 |
delta_pct=(current_7d.gross_sales−previous_7d.gross_sales)÷abs(previous_7d.gross_sales)×100%，比较店铺时区内两个完整 7 日销售事件窗；前窗为 0 时标 new_baseline，不计算无穷大。 | 源：ShopifyQL sales → gross_sales。权限不足、同步中、币种/Markets 范围不同、窗口不完整或销售事件口径不一致时不计算变化，并映射为相应 availability_status。 | 不独立占卡位。作为净销售额卡片的次级行：毛销售额基本持平而净销售额下降时，分别展示折扣与销售冲销的变化，供商家核查 |
| shp.rev.orders_trend 日均订单量趋势 T1 |
daily_orders = count(distinct eligible order_id by createdAt, shop timezone)；比较两个完整 7 日窗的 sum(daily_orders)，页面可同时展示日均。连续 3 个完整日 daily_orders=0 且此前活跃才置 forced_incident。 | 源固定为 ShopifyQL orders 或同一 Orders cohort，不从 sales reversal 事件数组推断订单断流。默认排除 test orders，是否纳入已取消订单必须由 Metric Spec 明确并在两个窗口保持一致；权限不足、窗口不完整、订单数 <10 分别降级。历史活跃且连续 3 个完整日为 0 的断流检测先于普通样本门槛执行，不能被 <10 单规则压掉。 | 🔴 连续 3 日为 0且店铺此前活跃（forced_incident=1，不受样本门槛阻挡）｜🔴 ≤ −25% ｜🟡 −25%~−15% ｜🟢 −15%~+15% 相对变化显著性写 |Δ%| ≥ 10%，不是 pp；订单少于样本门槛只关闭普通涨跌判断并写 availability_status=insufficient_sample。 |
| shp.rev.aov_change 客单价变化率 T1 |
AOV = (gross_sales excluding post-order adjustments − discounts excluding post-order adjustments) ÷ orders；后续退款与销售冲销不回写下单时 AOV。 | 优先直接读取 ShopifyQL average_order_value；同时保存订单数和金额分子。任一窗订单为 0 时 value 为空并写 reason_code=zero_denominator；样本不足写 availability_status=insufficient_sample，禁止用 net_sales/orders 代替。 | AOV 是结构信号，不设平台处罚状态；相对变化用 %。页面同时显示商品/渠道结构和折扣金额率作为相关线索，不能直接写成因果。 |
| shp.rev.discount_dependency 折扣金额率 T1 |
merchandise_discount_rate = (line_item_discounts + 分摊至商品的 order_discounts) ÷ gross_sales × 100%；shipping discounts 使用独立运费基数，单独计算和展示。 | 源：discount_rate_pct；health 侧 discount_dependency_pct 与布尔量 discount_dependency_high（>20 触发） na 条件：无折扣字段置 na 不置 0 |
商品、订单和运费折扣分开显示。20% 等值只可标 storeclaw_internal 或商家目标；它说明折扣侵蚀程度，不证明销售依赖或由折扣驱动。 |
| shp.rev.channel_mix 渠道结构 T3Shopify 独有 |
sales_channel_mix = 各 Shopify sales channel 的 net_sales ÷ total_net_sales；营销归因来源另列，不与销售渠道混用。 | 源：revenue_mix / channel_mix / country_mix | 不做阈值。详情可限定销售渠道、国家与币种；营销来源只在有 ShopifyQL/GA4/广告平台归因数据时出现。CustomerJourney 只能解释已转化订单，不承担全站 sessions 与 conversion 的分母。 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| shp.inv.stockout_risk_count 断货风险变体数 T1 |
按 variant × 可履约 location 计算：needed = velocity_28 × (lead_time_days+safety_days)；gap=max(0,needed−available−confirmed_incoming_before_need)。缺补货周期时才用 DoC≤14 天作内部估算。 | 源：shopify_inventory_calculator → summary critical_stockout + replenish_soon na 条件：tracked=False 的变体不参与计算（Shopify 允许不跟踪库存），排除数量由 untracked_variant_count 给出并在脚注披露 粒度是 variant 不是 SKU——同一 product 多变体各自独立 |
命中集合、预计缺口、受影响销售占比或预计售罄日变化时进入候选。页面显示仓库可履约范围、补货周期、已确认在途、排除的未跟踪变体和估算标记。 |
| shp.inv.overstock_value 积压库存金额 T1 |
excess_units=max(0,serviceable_available+confirmed_incoming−target_cover_days×velocity_28)；excess_cost_value=excess_units×historical/current unit_cost。 | 源：Inventory Level、incoming/transfer ETA、销量与成本。缺成本时写 availability_status=partial、reason_code=cost_missing，只可另列 retail_inventory_value=excess_units×current_price，不能冒充现金占用。 | 按成本价值、数量、持续天数和销售影响排序；新品、季节/活动备货、预售与下架商品按配置排除。目标覆盖天数显示为商家目标或 StoreClaw 内部线。 |
| shp.inv.turnover_days 平均周转天数 T2 |
Σ(serviceable_available) ÷ Σ(daily_velocity)，只纳入能服务当前销售渠道的 location，并保留 variant × location 分布。 | 源：Inventory Level、订单路由/配送配置和近 28 日销量；销速为 0 时 value 为空并写 availability_status=insufficient_sample、reason_code=no_velocity，覆盖不足显示低置信。 | 30/120 天只可作为内部默认；页面优先采用商家库存目标或店铺历史基线，并同时展示主仓断货与长尾积压，不能只给全店平均。 |
| shp.inv.transfer_opportunity 可调拨机会数 T1Shopify 独有 |
source_surplus=max(0,source_available−source_velocity×(source_safety_days+transfer_eta))；dest_gap=max(0,dest_need−dest_available−confirmed_incoming)；transfer_qty=min(source_surplus,dest_gap)。 | 源：shopify_specific.transfer_opportunities / multi_location / locations na 条件：multi_location=False → 整项不渲染（单仓店铺无此概念，属结构性不适用） |
只有两仓都可履约该变体、ETA 能赶在缺货前且预计避免的损失高于调拨成本时才给建议；否则只展示库存不均衡事实。执行后回读 transfer 状态与目标仓 available。 |
| shp.inv.committed_backlog 已分配库存占比 T2Shopify 独有 |
committed_inventory_share = committed ÷ (available+committed) × 100%，只说明库存已分配给未履约订单。 | 源：变体行 committed / on_hand / incoming na 条件：untracked 变体排除 |
不设置固定经营红绿灯。它与订单年龄、承诺发货日、暂停/预售状态和 shp.ops.overdue_rate 联合解释；占比高本身不能证明仓库堵塞。 |
| shp.inv.untracked_share 未跟踪库存占比 T3 |
untracked_variant_count ÷ 总变体数 | 源：summary tracked_variant_count / untracked_variant_count | 不做阈值告警。仅在库存卡片 tooltip 内说明覆盖率，作用同 amz.inv.sku_data_gap——降低「数字和我后台不一样」的争议 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| shp.prod.refund_rate 实物退货件数率 T1 |
return_rate_30d = 同一 fulfilled cohort 在履约后 30 天内的 returned_quantity ÷ fulfilled_quantity。30 天是默认观察窗，按 Metric Spec 版本化；退款金额率、销售冲销件数率和实物退货率分别计算。 | 源：ShopifyQL returns/sales 与原履约订单 cohort。若只有 reversed_quantity，指标只能显示“销售冲销件数率”；cohort 未成熟或样本不足时不着经营状态。 | 使用商家目标或店铺/品类历史基线；展开列出 Top 商品、退货原因、实际件数、损失金额、成熟度和成本覆盖。与 Amazon 退货事件口径不可直接比较。 |
| shp.prod.no_restock_share 退款未回库决策占比 T1Shopify 独有 |
NO_RESTOCK quantity ÷ known-restock-type refund quantity × 100%，只表示退款处理时没有把数量补回库存。 | 源：变体行 no_restock_share_pct；店铺级由 restock_type_breakdown 推导 na 条件：退款件数 < 5 时不计算（比例失真） |
不能据此直接推断商品损坏、不可再售或利润损失；需要结合退货处置、仓库记录和 COGS。固定 30%/60% 只可作为内部观察线。 |
| shp.prod.top3_concentration Top-3 集中度 T2 |
先合并 variants，再算 Top-3 product 的商品净销售额 ÷ 全店商品净销售额 × 100% | 源：sku_gmv（health_scoring）排序推导 | 优先用店铺历史和商家目标解释；60%/80% 只是内部观察线。单品品牌、新品期和多品类店采用不同基线，集中度高不自动等于经营风险。 |
| shp.prod.hero_dependency 爆款依赖 T2Shopify 独有 |
hero_net_sales_share = hero 商品净销售额 ÷ 全店商品净销售额，同时显示 hero_count；hero 定义由 calculator 的商品角色分类给出。 | 源：角色分类后的商品明细（product_id、role、net_sales），聚合得到 hero_count、hero_net_sales 和 total_net_sales。只有 hero_count 而没有角色商品金额时，不计算金额占比。 | 与 top3_concentration 合并展示，不单独占卡位；作用是把集中度落到具体商品和变化方向 |
| shp.prod.return_risk_count 高退货风险商品数 T1Shopify 独有 |
eligible product 必须满足最小 fulfilled units，且 30 天退货观察窗成熟；主判定只使用同一 cohort 的 returned_quantity ÷ fulfilled_quantity 相对店铺/品类基线。return_loss = 已退商品退款金额 + 不可回收历史 COGS + 已确认退货处理/标签成本 − 已确认回收价值，只有各项覆盖可披露时才参与影响排序。 | 源：成熟退货 cohort、退回商品对应退款、历史 COGS、处理成本与回收处置；分类器和 30 天窗口都版本化。样本不足时写 insufficient_sample；成本或处置缺失时 loss 为 partial，但不影响退货件数率本身。 | 列表先按退货率相对基线与 returned_quantity 判定风险，再按有覆盖的 return_loss 排序；退款金额只作辅证，不和实物退货率混成同一公式。与实物退货率合并为同一主题卡。 |
| shp.prod.slow_mover_count 滞销商品数 T2Shopify 独有 |
统计 active + published、上架时间达到最低观察期、可履约库存>0，且 velocity_28 低于基线或 DoC 高于目标的商品。 | 源：商品上架时间、销售渠道、location 库存、近 28 日销量与活动配置；新品、季节品、预售和活动备货显式排除。 | 与积压成本金额合并为“库存处理”主题，按资金影响排序；不能只看商品个数。 |
| shp.prod.listing_gap_count 信息缺失商品数 T2Shopify 独有 |
count(变体 归类为 listing_gap)——缺主图/缺描述/缺分类等 | 源：summary listing_gap_count | 🟡 ≥3 个 ｜ 🟢 0~2 个；这是资料待办，不是平台故障。对应 Amazon 的 listing_flag_count，但不与 suppressed 使用同一严重度 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| shp.cust.repeat_rate 复购率 T1 |
returning_customer_rate = 本期购买且本期首单前已有历史订单的可识别客户 ÷ 本期可识别购买客户 × 100%，变化用 pp。 | 源：完整订单史或 ShopifyQL returning customer 合同；游客订单单列 coverage。默认订单 API 只有近 60 天，未获 read_all_orders 时不能把截断历史当完整复购。 | 10%/20%/35% 只能作为内部冷启动线；稳定状态优先采用店铺自身历史或商家目标。页面显示可识别客户覆盖率、观察窗和历史范围。 |
| shp.cust.churn_risk 流失风险客户与金额 T1 |
eligible customer 的历史订单数≥2；购买周期来自商家设置或同 cohort 历史间隔中位数；recency_days > expected_cycle × configured_multiplier 时进入风险池。 | 源：summary churn_risk_count / churn_risk_value；kpi churn_risk{count, value, delta_pct, direction} | 主数值写“风险客户的历史商品净销售/历史毛利贡献”，不能写成可挽回收入。召回前必须检查营销同意与联系方式；任务回读实际触达、回购和毛利结果。 |
| shp.cust.returning_gmv_share 老客商品净销售占比 T1 stable ID；canonical name 为 returning_customer_net_sales_share |
order_index>1 客户的 net_sales ÷ 全部可识别客户 net_sales；游客销售单列 coverage。 | 源：summary returning_customer_gmv_share_pct / new_customer_gmv_share_pct；kpi returning_gmv_share | 20%/65% 不是平台标准。新店、订阅、成熟品牌和 B2B 店的结构不同，采用商家目标或自适应基线；页面同时显示新客净销售、游客覆盖和获客数据可用性。 |
| shp.cust.rfm_shift RFM 分层迁移 T2 |
transition_count(from_group,to_group) 只统计同一 customer_id 在两个可比快照中的 RFM 组变化；不能把两期不同人群的聚合占比称为迁移。 | 迁移源：按 customer_id + snapshot_date + rfm_group + rfm_model_version 保存的客户级 RFM 快照，两期必须使用同一模型版本。segments_rich 只有聚合段（segment、customers、share_pct、total_gmv、avg_recency_days、action），只能展示“分层构成变化”，不能生成迁移矩阵。 na 条件：缺任一期客户级快照、模型版本不一致或客户数过小时不分层 |
展开区优先显示同一批客户的迁移矩阵；只有聚合数据时改为“分层构成变化”条形对比，不使用迁移措辞。不独立占首屏卡位，作为 repeat_rate 或 churn_risk 卡片的展开内容；action 字段只作为经审定的行动建议文案。 |
| shp.cust.guest_share 未关联客户订单占比 T2Shopify 独有 stable ID 沿用 guest_share，展示名按真实数据口径修正 |
unlinked_customer_order_share = customer_id 为空的订单数 ÷ eligible orders × 100% | 源：订单 customer_id 与 summary 的 guest_order_count / guest_share_pct。这些旧字段只按未关联客户解释；只有取得 checkout 登录/账号选择证据时，才能另算真正的 guest_checkout_share。 | 仅说明无法按 customer_id 关联客户的订单占比，不等于顾客一定选择了游客结账、不等于不能营销，也不自动意味着必须强制注册；客户档案、账号状态和营销同意分别展示。 |
| shp.cust.email_reach 邮件营销同意率 T2Shopify 独有 canonical name 为 email_marketing_consent_rate |
有邮箱且 consent=SUBSCRIBED 的客户 ÷ 有邮箱客户 × 100% | 源：summary subscribed_count / subscribed_share_pct / email_reach_low（布尔量，直接用） | 它表示营销同意，不表示邮件可送达；真实触达率需要 ESP 的 delivered/bounced 数据。与流失风险联动时，未同意客户不能进入邮件召回任务。 |
| shp.cust.ltv_proxy 客户价值 cohort 指标 T3 |
realized_revenue_ltv_180d = 首购 cohort 在首购后 180 天累计 net_sales ÷ cohort customers；realized_gross_profit_ltv_180d 同理用已覆盖历史成本的 gross profit。默认展示 180 天，允许切换 91/180/365 天且随 Metric Spec 版本化；预测值另名 predicted_clv_N。 | 源：完整历史订单、首购 cohort、销售冲销与历史 COGS。预测 CLV 还需保存 prediction_as_of、horizon、训练窗与置信区间。total_lifetime_spend/customers 只能叫历史人均累计消费。 | 不做通用红绿灯；作为获客预算、客户分层和 cohort 分析的上下文。订阅数据只在应用拥有合同、权限获批且商家实际使用订阅时出现；billing attempts 不是合同变更史。 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| shp.ops.cancel_rate 订单取消率 T1 |
cancellation_rate_7d = 近 7 日创建且在 7 日观察期内取消的 eligible orders ÷ 同窗创建的 eligible orders；默认观察窗为 7 天并随 Metric Spec 版本化，按取消原因分解。 | 只从一个权威订单 cohort 管线取值，保存 createdAt、cancelledAt、cancelReason 与观察成熟度。若按 cancelledAt 事件日展示，只能叫 cancellation events，不能除以当日新订单。 | Shopify 没有统一处罚线；2.5%/5% 等只能是商家目标或 StoreClaw 内部线。样本不足时显示分子分母，不着经营状态。 |
| shp.ops.overdue_rate 履约逾期率 T1 |
overdue_rate = fulfillBy 落在窗口且逾期履约或截至 as_of 仍未履约的订单 ÷ 同窗应履约订单。 | 源：supporting 块 overdue_rate_pct，依赖 fulfillment_file na 条件：fulfillment_outcome = design_na → 整项不渲染且不给提示（该店铺履约模式不产生时效数据）；文件缺失 → 灰态可修复提示 |
阈值来自商家 SLA 或店铺历史基线，不是 Shopify 平台标准。预售、on hold 和商家配置的例外需排除；展开列具体订单、逾期时长、仓库、负责人和截止时间。 |
| shp.ops.abandoned_gmv_at_risk 未恢复弃单商品价值 T1Shopify 独有 canonical name 为 open_abandoned_checkout_value |
sum(current checkout merchandise amount)，只纳入窗口内仍未 recovered/completed 的唯一 checkout ID；税、运费、折扣与商品价值分开。 | 源：shopify_abandoned_checkouts_pipeline → total_gmv_at_risk / abandonment_type_distribution / step_distribution / inventory_unavailable_count / discount_code_count / shop_pay_count na 条件：abandoned_checkouts_outcome != success → 不渲染；step_analysis_sampled=True 时步骤分布加「抽样」角标 |
它是潜在结账价值，不是已流失或保证可追回收入，不设通用 40% 线。展开显示唯一可联系客户、已恢复价值、步骤分布、数据抽样与当时库存证据；缺货原因只有在事件证据存在时才写。 |
| shp.ops.fulfillment_distribution 履约状态分布 T3 |
各履约状态订单占比（unfulfilled / partial / fulfilled 等），并按 0–1、2–3、4–7、>7 天分龄。 | 源：fulfillment_status_distribution；fulfilled_order_count | 不做阈值。作为 overdue_rate 卡片的展开内容与弹窗参数选项 对应 Amazon 的 amz.ops.shipped_gap，但那是单一比率、这里是多态分布，属同名异实 |
| 指标 | 计算逻辑 | 取值逻辑 | 展示逻辑 |
|---|---|---|---|
| shp.fin.margin_proxy 实际毛利率与成本覆盖 T1Shopify 独有 |
covered_net_sales = 仅有销售时历史 COGS 的商品净销售额；covered_gross_profit = covered_net_sales − covered_COGS_at_sale；observed_gross_margin = covered_gross_profit ÷ covered_net_sales；cost_coverage = covered_net_sales ÷ total_merchandise_net_sales。缺成本商品不进入毛利分子分母，也不把已覆盖 cohort 的毛利率外推到整店。 | 源：ShopifyQL sales/profitability 与销售时历史成本。当前 unitCost 回填历史只能另列 estimated_margin_current_cost；成本缺失必须写 availability_status=partial、reason_code=cost_missing。 | 页面同时显示 observed_gross_margin 与 cost_coverage；覆盖不足时标题明确为“已覆盖商品毛利率”，不为整店实际毛利着经营状态。贡献利润另扣支付费、平台费、实际履约/物流、广告、退货处理和其他可变成本；税不作为收入，客户运费收入与商家运费成本各计一次。 |
| shp.fin.profit_drag_count 利润拖累商品数 T1Shopify 独有 |
统计历史成本覆盖达标，且商品 gross_profit<0 或 gross_margin 低于商家底线的商品。 | 源：商品净销售、销售时 COGS、毛利与贡献利润成本；按 product 聚合 variants，保存成本覆盖和公式版本。 | 列表按绝对毛利损失/贡献利润损失排序，主数值显示损失金额及销售占比，不用“商品个数≥3”决定严重度。 |
| shp.fin.discount_gmv_share 折扣订单商品净销售占比 T2Shopify 独有 canonical name 为 discounted_sales_share |
有商品/订单折扣的订单之 net_product_sales ÷ 全部 net_product_sales；运费折扣另列。 | 源：变体行 discount_gmv_share_pct / discount_driven | 只说明多少商品净销售伴随折扣成交，不证明折扣带来这些销售。阈值只能来自商家目标、自适应基线或明示的内部观察线。 |
两边可以共享页面组件和经营主题，但不能共享指标口径。下面 12 组看似相同的经营问题，在数据来源、时间、粒度、分母或阈值性质上不同；跨平台视图只在 comparability key 兼容时比较，不用相同颜色掩盖不同定义。
| # | 指标名 | Amazon 侧 | Shopify 侧 | 合并后会犯的错 |
|---|---|---|---|---|
| 1 | 收入环比 | amz.rev.gmv_wow Sales & Traffic 的 Ordered Product Sales，按下单日、marketplace 与币种。 |
shp.rev.net_revenue_wow Shopify 商品净销售额，按销售/冲销事件日。 |
只比较各自趋势并并列口径说明；日期归属不同，绝对金额和百分比不能被解释成完全相同的经营事件。 |
| 2 | 客单价 | Sales & Traffic 可对账的是每订单项销售额；真正每单金额需去重 AmazonOrderId 后另算。 | Shopify AOV = 下单时商品毛销售额减折扣 ÷ 订单数，不扣后续冲销。 | 页面分别使用“每订单项销售额”和“AOV”的准确名字，不做绝对值排名。 |
| 3 | 退货 / 退款率 | amz.prod.return_rate FBA 成熟发货 cohort 的 returned units ÷ shipped units；MFN 明确排除。 |
shp.prod.refund_rate 成熟履约 cohort 的 returned quantity ÷ fulfilled quantity；退款与冲销另列。 |
只有 cohort 观察窗、成熟度和商品粒度一致时才比较；事件期视图不与 cohort 率混用。 |
| 4 | 取消率 | amz.ops.cancel_rate 7 日 MFN 卖家发货前取消率，官方阈值 2.5%。 |
shp.ops.cancel_rate 同创建 cohort 在观察期内取消的订单率，无平台处罚线。 |
Amazon 的官方状态单独展示；Shopify 只用商家目标、历史基线或明示内部线。 |
| 5 | 断货风险 | 按 marketplace × sellerSKU/FNSKU 的 fulfillable、在途阶段与 28 日需求判断。 | 按 variant × 可履约 location 的 available、incoming ETA、订单路由与需求判断。 | 两边都按真实库存范围落库；不预设 Amazon 账号共池，也不把 Shopify 所有仓简单相加。 |
| 6 | 可售库存定义 | fba_sellable（FBA 仓可售） 另有 fba_inbound_total 在途 |
直接读取 available；committed、reserved、damaged 与 incoming 分开。 | 可售只使用平台定义的可履约库存；不从 on_hand 自行反推，也不把在途当可售。 |
| 7 | 周转天数 | Σ eligible fulfillable ÷ Σ对应市场销速，保存覆盖与低置信。 | Σ serviceable available ÷ Σ对应渠道销速，保留 location 分布。 | 公式相似，但有效库存集合不同；全店平均必须能下钻到 SKU/variant 与仓库。 |
| 8 | 折扣依赖度 | amz.rev.discount_rate 商品促销折扣占商品销售基数，运费折扣单列。 |
shp.rev.discount_dependency 商品/订单折扣占 gross sales，运费折扣单列。 |
两边都只说明折扣金额占比；20%/25% 是内部默认，不作为平台标准或因果结论。 |
| 9 | 商品信息异常 | amz.prod.listing_flag_count suppressed 是已验证的强制事件，其余状态分组展示。 |
shp.prod.listing_gap_count 仅信息不全（缺图/缺描述） 严重性：待办级，无红态 |
Amazon suppressed 可强制置顶；Shopify 信息缺失进入普通待办，不能共用状态与动作。 |
| 10 | 发货 / 履约缺口 | amz.ops.shipped_gap 已过 LatestShipDate 仍未发货的 MFN 订单及比例。 |
shp.ops.fulfillment_distribution 履约状态分布与订单年龄分桶。 |
Amazon 侧是到期订单待办；Shopify 侧是分布证据，逾期另按 fulfillBy 判断。 |
| 11 | 履约逾期率 | 分母＝自发货订单（不含 FBA） 全 FBA 店铺整项不渲染 |
分母＝应发货订单 fulfillment_outcome=design_na 时不渲染 |
Amazon 使用官方 10/30 日 MFN 迟发合同；Shopify 使用商家 fulfillBy/SLA，两者阈值来源不同。 |
| 12 | 退款金额率 | amz.fin.refund_rate 来源 financial events，金额口径 依赖 financial_events_outcome |
Shopify 退款现金、销售冲销和实物退货分开；退款金额可按发生期或原订单 cohort 计算。 | 两边都必须对齐财务事件与销售集合；同一笔退款可以解释净销售变化，但不能被当成两次独立损失相加。 |
某个指标没变化时，不能统一隐藏。“没变化”有四种情况，只有健康且平稳的一类适合折叠，其余情况分别处理。
| # | 情况 | 示例 | 待遇 | 理由 |
|---|---|---|---|---|
| ① | 越界但平稳 常驻 |
退货率连续 6 周稳定在 9.2% 取消率稳定 6.1% |
必须展示 红/黄态卡片 |
「稳定地在出血」比「突然出血」更危险。这类长期病灶正是商家自己扫报表最容易漏掉的——数字不动，眼睛就滑过去了。若因「无变化」隐藏，功能反而帮商家把问题藏起来了 |
| ② | 健康且平稳 降级 |
退货率 3.1%（上周 3.0%） 断货风险 0 个 |
降级 折叠进「一切正常」摘要行 |
这才是真正该让位的一类。不占卡位，但不能彻底消失——商家需要知道「我们看过了，这些没问题」，这是信任来源。以「12 项指标正常」的单行摘要 + 可展开列表呈现 |
| ③ | 刚跨越阈值边界 优先 |
退货率 4.9% → 5.1% （绝对变化仅 0.2pp，但跨了黄线） |
优先展示 worsening_crossing=1 |
变化幅度小但状态发生了跃迁。纯按变化幅度排序会把它排到末位，而它恰恰是最佳干预时机——刚越线时纠偏成本最低 |
| ④ | 数据缺失导致「看起来没变」 区分 |
本周 sales_traffic 拉取失败，转化率与上周同值（都是旧值或都是 na） | 灰态展示 说明数据状态 |
最危险的一类：把「没数据」误当成「没变化」。必须在取值层就区分——依据 _outcome 而非依据数值是否相等来判断有无变化 |
55 项先经过数据可用性与可比性检查，再按经营状态、显著变化、状态跃迁和未关闭任务进入候选池。数据不可信时只说明数据问题，不能继续给补货、清仓或调价动作。
每个候选指标先生成同一套排序键，再按 Metric Spec 声明的 issue_group 与 issue_scope_fields 计算 issue_key，合并同一经营主题和同一作用对象。每个 issue 选排序最高的成员作为主指标，其余成员进入证据层；issue 继承主指标的排序键。相同键时用稳定 metric_id 决定主指标，因此分组和顺序都能回放。
| 键 | 取值 | 判定合同 |
|---|---|---|
| forced_incident | 1 / 0 | 只用于已验证的经营事件，如 listing suppressed、此前活跃店铺的订单断流。授权失效属于 system_incident/data_banner_priority，进入数据横幅而非经营 issue 排序。 |
| official_platform_breach | 1 / 0 | 只用于 Amazon PFC 2.5%、LSR 4% 等官方绩效要求；StoreClaw 内部线不能占这一位 |
| impact_band | 3 / 2 / 1 / 0 | 受影响销售、订单、利润或 SKU 占比：≥20%、10–<20%、1–<10%、<1%/未知；跨币种不直接比原始金额 |
| urgency_band | 3 / 2 / 1 / 0 | 不可逆处理窗口 ≤24h、≤3d、≤7d、其余/未知 |
| severity_band | 2 / 1 / 0 | alert / watch / normal-positive；状态依据相应 threshold_type |
| worsening_crossing | 1 / 0 | 仅在两张可比快照由好转坏时为 1 |
| consecutive_breach_days | 0–7 | 长期未处理问题只加不减，不因卡片疲劳而降权 |
第三问：排序后的候选池，怎么变成页面上的 ≤6 张卡？两步——先强制，再约束。候选不足或全静默时另有兜底（见 7.5）。
当候选池为空（无任何越界、无任何显著变化）时触发。这是健康店铺的常态而非异常，必须有正式设计——空屏或一句「暂无异常」会让商家认为功能坏了，而这类店铺往往是我们最该留住的优质用户。
| 段落 | 内容规则 | 数据来源 |
|---|---|---|
| ① 状态确认 | 分别写「已检查且健康 N 项、数据待核对 M 项、结构不适用 K 项」。N 取实际成功检查数，不取空候选池数量 | availability + business status 计数 |
| ② 连续性 | 「连续 N 周无越界指标」——从 store_daily_metrics 历史快照回溯计算。这句话把平稳从「没消息」变成「成绩」 | 历史快照回溯 |
| ③ 数据边界 | 显示数据截止时间、待核对数量、不适用数量和历史不足项，避免把“没有卡片”误解成“所有数据都正常” | availability、coverage、maturity 与 source_as_of |
| ④ 可选机会入口 | 只有真的存在且数据充分的机会信号时才显示，例如有流量零转化商品或满足调拨约束的库存机会；没有机会信号时整段省略 | Tier-2 机会指标通过能力与数据闸门后的结果 |
指标有值但不正常渲染时，按「商家能做什么」归并为四类。核心原则：展示数据状态，不给编造的原因——每个状态只说事实，且只给商家真正能采取的行动。
| 类别 | 触发条件 | 卡片形态 | 文案与行动（严格对齐 Caveat sourcing rule） |
|---|---|---|---|
| 数据不可用 | insufficient_sample / permission_denied | 灰态卡 无数值（权限不足时带按钮） |
样本不足显示 numerator/denominator 与最低门槛，不着经营状态；Amazon 官方绩效项仍显示官方状态并同时展示小样本。权限不足提供授权入口。unsupported/not_applicable 只走下方“不渲染”合同。 |
| 数据源故障 | source_failed / stale；调度未产出、连接器故障、数据超过指标 TTL | 单卡灰态 / 维度级横幅 / 整区降级 | source_failed 显示失败原因与重试/授权路径，不沿用旧数装成当前；stale 可显示 last_success，并在主文案写“数据截至……”，同时关闭补货、清仓、调价等强动作。整维度失败合并为一条数据横幅，不逐项重复。 |
| 部分可信 | partial / estimated；data_gap、velocity_only、低置信、覆盖不足或第三方估算 | 正常卡 + 角标 |
展示数值、覆盖率、排除项、估算来源和截止时间；只有达到配置的 coverage gate 才允许弱经营状态。partial/estimated issue 进入“待核对数据”区，不进入强动作排序。 |
| 不渲染 | not_applicable / unsupported | 不渲染 | 不出现卡片，也不出现任何说明文字。平台天生没有的能力不值得占用注意力，提了反而制造「能开通」的错误预期 |
Skill 侧的规则是默认单一主市场（US 若活跃，否则清单第一个），只有商家明确点名才展开。但页面与对话不同——页面没有「商家点名了哪个市场」这个信号。一个五市场卖家打开店铺详情页应该看到什么，必须单独设计。
页面固定使用“市场概览条 + 默认市场 + 告警上浮”。概览条负责让所有活跃市场的严重状态可见，卡片区始终只展示一个市场的独立数据；不同币种、不同 marketplace 的金额不相加，商家点击市场后只切换物化行。
| 组成 | 设计 |
|---|---|
| ① 市场概览条 | 卡片区顶部一行，每个活跃市场一个小格，只显示该市场的告警数与最严重状态色（如「DE · 3 项告警」红点）。不显示任何金额，因此不构成跨市场聚合。当前市场高亮，点击即切换。 |
| ② 默认市场 | 先比较各市场最高 priority_key，默认打开风险最高市场；都没有 issue 时打开商家设定的主市场。所有金额保留该市场币种，不跨币种相加。 |
| ③ 跨市场摘要 | 顶部列出每个市场的最高状态与 issue 数；所有 official platform breach 和 forced incident 都可见。点击直接切换，不把不同市场金额聚合为一个经营数。 |
| ④ 切换为纯读取 | 数据已按 marketplace_id 分行落库（11.2），切换市场不触发任何计算与 API 调用，只是换一行 JSON 渲染。切换动作应当是瞬时的。 |
把 7.2 到 7.4 的三道闸门在构造数据上完整跑一遍。示例为 Amazon US 单市场；先对 Amazon 12 项 Tier-1 做能力与数据检查，再从可用指标形成 issue。
| metric_id | 当日 status | 变化 / 影响证据 | priority inputs 与闸门 |
|---|---|---|---|
| amz.prod.listing_flag_count | alert | 1 个 suppressed；该 ASIN 近 7 日销售占比 24%；需 24h 内处理 | vector=(1,0,3,3,2,0,1)；经营事件强制 |
| amz.ops.cancel_rate | official alert | PFC 2.8%，14 / 500 MFN；刚跨过 2.5% | vector=(0,1,1,3,2,1,1)；官方阈值 |
| amz.inv.stockout_risk_count | alert | 3 SKU；影响销售占比 22%；最早 3 日内售罄；已持续 2 日 | vector=(0,0,3,2,2,1,2)；昨日 watch→alert |
| amz.rev.gmv_wow | alert | Ordered Product Sales −23.4%；处理窗口 7 日内 | vector=(0,0,3,1,2,0,1)；自适应基线告警 |
| amz.rev.aov_change | watch | 每订单项销售额 −18.9%；影响分档 1 | vector=(0,0,1,1,1,0,1)；结构信号 |
| amz.prod.buybox_deficit_count | watch | 2 ASIN；近 7 日销售占比 13%；已持续 2 日 | vector=(0,0,2,1,1,0,2)；内部观察线，不是官方处罚 |
| amz.rev.conversion_rate | watch | Unit Session Percentage −2.2pp；影响分档 2；昨日 normal | vector=(0,0,2,1,1,1,1) |
| amz.inv.overstock_count | normal | 1 SKU，无显著变化 | 不入选（闸门 1 两条标准均未达） |
| amz.prod.return_rate | normal | FBA 退货率 6.2%，无显著变化；MFN 排除 | 不入选 |
| 其余可用项 | normal | 在各自基线或目标范围内 | 进入健康摘要 |
55 项指标共用卡片骨架与状态机，按数据形态落入 6 类交互原型；30 项 Tier-1 都在逐指标矩阵中声明展开内容和行动路径。实现复用交互结构，业务口径仍逐项独立。
| 区 | 内容与硬规则 |
|---|---|
| ① 标题区 | 指标名 + 窗口口径 + 状态标签。窗口口径必须常显不放 tooltip——「近 7 日 vs 前 7 日」是理解数值的前提 |
| ② 数值区 | 主数值 26px/800 + 辅助绝对值 + 对比基准行（含基准日期）。基准日期必须可见，这是数值争议的第一道防线 |
| ③ 洞察区 | 1–2 句结论。由洞察引擎生成（第 10 章）。此区失败时卡片仍完整可用——降级为纯阈值模板句 |
| ④ 行动区 | 主按钮（打开参数弹窗 → Skill）+ 次按钮（原地展开趋势/明细）。健康态仅次按钮且视觉减重 |
| ⑤ 元信息区 （前置至标题行） | 持续天数：watch ≥3 天或 alert ≥1 天显示。官方绩效徽标：只在 has_official_platform_threshold=true 时显示，并链接官方定义。阈值来源、覆盖率、估算、成熟度、数据截止日、负责人、截止时间和任务状态按需常显，不藏在 tooltip。 |
| 交互动作 | 通用行为 | 禁止事项 |
|---|---|---|
| hover | 卡片抬升 2px + 阴影加深；数值区显示 tooltip（完整公式 + 口径 + 排除项 + 数据来源 pipeline） | 禁止在 hover 时才暴露窗口口径与基准日期——这两项必须常显 |
| click 卡片空白区 | 原地展开次级内容（趋势/明细），不跳转不弹窗 | 禁止整卡点击直接触发 Skill 会话——误触成本过高 |
| click 主按钮 | 打开参数弹窗（第 9 章），不直接发消息 | 禁止「一键直接问」——参数不可见会让商家不信任结果 |
| click 次按钮 | 原地展开该指标 Metric Spec 指定的趋势或明细。序列由批处理提前写入当前行的滚动缓冲区，页面仍只读一次主记录 | 页面不为趋势单独调用 pipeline，也不临时跨行拼接；窗口按单项指标合同执行，不设全局 28/91 日选项 |
| 键盘 | 卡片区 Tab 可达，Enter 等价主按钮，Esc 收起展开区；状态标签带 aria-label 文字描述 | 禁止仅用颜色表达状态——色盲用户无法区分红/绿，必须同时有文字标签 |
分类依据是指标的数据形态，而非业务维度。同一形态共用展开区组件与趋势渲染逻辑，各指标只配置字段映射与文案。
| # | metric_id | 原型 | 展开区内容 | 主按钮文案（zh） |
|---|---|---|---|---|
| 1 | amz.rev.gmv_wow | P1 | 滚动 7 日订购商品销售额折线 + 订单项数/每订单项销售额双辅线 | 核查订购商品销售额变化 |
| 2 | amz.rev.orders_trend | P1／P6 | 滚动 7 日订单项数趋势；断流时切 P6 逐日时间线 | 排查订单项数下滑 / 排查订单断流 |
| 3 | amz.rev.aov_change | P1 | 每订单项销售额折线 + 商品折扣金额率叠加 | 核查每订单项销售额变化 |
| 4 | amz.rev.conversion_rate | P1 | 转化率折线 + 会话量柱状双轴 | 分析转化率下降 |
| 5 | amz.inv.stockout_risk_count | P2 | 风险 SKU 表（DoC / 库存 / 销速 / 补货建议日），可勾选 | 生成补货计划 |
| 6 | amz.inv.overstock_count | P3 | 积压 SKU 按 estimated excess quantity 分解；有成本时显示成本价值，缺成本只显示零售库存价值 | 核查滞销与清库方案 |
| 7 | amz.prod.buybox_deficit_count | P2 | ASIN 表（Featured Offer 占比 / 状态 / 报价与库存证据），可勾选 | 核查 Featured Offer 缺失 |
| 8 | amz.prod.return_rate | P1 | FBA 退货率折线 + FBA 退货 Top SKU 表；常显 MFN 排除范围 | 排查 FBA 退货原因 |
| 9 | amz.prod.listing_flag_count | P2／P6 | 按 flag 分组的 SKU 表；有 suppressed 时切 P6 | 处理 Listing 异常 |
| 10 | amz.ops.cancel_rate | P1 | 卖家自配送预配送取消率折线 + 官方绩效阈值带 | 排查卖家取消订单 |
| 11 | amz.ops.overdue_rate | P1 | 逾期率折线（仅自发货口径，标注分母订单数） | 排查发货延迟 |
| 12 | amz.fin.fee_rate | P1 | 费率折线 + FBA/佣金/服务费三段堆叠条 | 拆解费用结构 |
| 13 | shp.rev.net_revenue_wow | P1 | 净销售额折线 + 毛销售额、折扣与销售冲销对照 | 核查净销售额变化 |
| 14 | shp.rev.orders_trend | P1／P6 | 同 #2 | 排查订单量下滑 / 排查订单断流 |
| 15 | shp.rev.aov_change | P1 | AOV 折线 + 折扣依赖度叠加 | 分析客单价变化 |
| 16 | shp.rev.discount_dependency | P1 | 折扣金额率折线 + 含折扣净销售额占比对照 | 评估折扣策略 |
| 17 | shp.inv.stockout_risk_count | P2 | 风险变体表（含 location 列），可勾选 | 生成补货计划 |
| 18 | shp.inv.overstock_value | P3 | 积压金额按变体分解 + 成本价覆盖率标注 | 分析滞销与清库方案 |
| 19 | shp.inv.transfer_opportunity | P2 | 调拨对表（源仓 / 目标仓 / 建议数量 / 可避免断货天数） | 生成调拨建议 |
| 20 | shp.prod.refund_rate | P1 | 退款率折线 + 退款 Top 5 变体 + 回库类型分解 | 排查退款原因 |
| 21 | shp.prod.no_restock_share | P1 | 退款未回库决策占比折线 + restockType、商品/变体与仓库记录 | 核查退款回库决策 |
| 22 | shp.prod.return_risk_count | P2 | 高风险商品表（退款率 / 销量 / 角色标签，可展开到变体证据） | 核查高退款商品 |
| 23 | shp.cust.repeat_rate | P1 | 复购率折线 + RFM 分层迁移条（P4 嵌入） | 分析复购与客户分层 |
| 24 | shp.cust.churn_risk | P3 | 风险客户的历史商品净销售/历史毛利贡献分层 + 客户清单 + 邮件营销同意率；实际送达需 ESP 数据 | 制定合规召回方案 |
| 25 | shp.cust.returning_gmv_share | P1 | 老客/新客商品净销售占比双面积图；只有商家目标或稳定自适应基线存在时才画区间带 | 核查新老客结构 |
| 26 | shp.ops.cancel_rate | P1 | 取消率折线 + 取消个数柱状（Shopify 有绝对数） | 排查订单取消原因 |
| 27 | shp.ops.overdue_rate | P1 | 逾期率折线 + 履约状态分布（P4 嵌入） | 排查发货延迟 |
| 28 | shp.ops.abandoned_gmv_at_risk | P5 | 三段漏斗 + 库存不可用的开放结账单列 + 弃单类型分布 | 分析开放弃单 |
| 29 | shp.fin.margin_proxy | P1 | 毛利率折线 + 按商品毛利分布直方（可展开到变体）+ 历史成本覆盖率 | 核查毛利结构 |
| 30 | shp.fin.profit_drag_count | P2 | 拖累商品表（销量 / 毛利率 / 净销售额占比，可展开到变体），可勾选 | 核查低毛利商品 |
卡片发现问题，Skill 帮助核对和分析，经营任务负责把事情做完。点击、发送或报告生成都不是成功；只有平台回读或后续指标证明问题恢复，任务才算完成。
| 字段 | 合同 | 页面行为 |
|---|---|---|
| task_status | unassigned / assigned / in_progress / blocked / verifying / done / reopened | 处理证据提交后进入 verifying；验证通过才 done，失败自动 reopened，不可比继续 verifying 或 blocked |
| owner / due_at | 负责人、分配时间、截止时间与优先级 | 无负责人或已逾期的 issue 在任务层提示，不改动经营指标事实 |
| evidence / resolution_note | 平台回读、截图/链接、变更记录、处理说明 | 只记录用户实际提交或系统实际回读的证据，不用“已打开页面”冒充完成 |
| before_snapshot_id / after_snapshot_id | 处理前后不可变快照 | 用相同口径比较；口径变化时标不可比，不制造恢复率 |
| verification_metric / window | 进入 verifying 后观察什么、观察多久 | 补货看库存/入仓，Listing 看状态恢复，履约看订单队列与绩效率，召回看实际触达与回购；before/after 不可比时不得完成 |
点击主按钮不直接发消息，而是打开参数弹窗。三个理由：① 参数不可见的分析结果商家不信任——「它到底按哪个时间段算的」是第一个疑问；② 默认参数猜错就要浪费一整轮对话，而弹窗把纠正成本从「一轮 Skill 执行」降到「一次下拉选择」；③ 商家真正想调的东西（分析范围、对比基准、关注哪几个 SKU）恰好是 Skill 澄清轮次里最常问的，前置到 GUI 就能整轮省掉。
| 区 | 规则 |
|---|---|
| ① 上下文 | 只读，复述卡片的指标、数值、对比基准与结论。作用是让商家确认「我要问的正是这件事」，同时这段文字会作为消息的一部分发出，Skill 因此不必重新计算即可知道触发场景 |
| ② 参数 | 按交互原型给出可调项（见 9.2）。全部有默认值且默认值即最佳猜测——弹窗的目标是「看一眼就能点确认」，不是让商家填表 |
| ③ 提示词 | 可编辑 textarea；参数变化可以重新生成提示词，手工修改不反向解析参数（见 9.3）。上限 800 字 |
| ④ 高级 | 默认折叠：目标 Skill（可见但一般不改）、输出深度（快照 / 趋势简报 / 完整诊断）、回复语言（zh / en） |
| ⑤ 操作 | 确认发送 / 取消 / 恢复默认。Cmd/Ctrl+Enter 等价确认，普通 Enter 保留为提示词换行，Esc 等价取消；确认后弹窗关闭并进入会话，不在弹窗内等待结果 |
| 参数 | 控件 | 取值范围 | 默认值规则与约束 |
|---|---|---|---|
| 分析窗口 | 单选段 | 由该指标的 Metric Spec 给出；必要时允许自定义 | 默认等于触发卡片的口径，不提供一套全局窗口。销售与流量常用 7 日，库存销速常用 28 日，Amazon 预配送取消率固定滚动 7 日，迟发率固定 10 日或 30 日，退货与客户指标使用成熟 cohort 窗口。自定义值必须满足平台可回溯范围、成熟度和可比性约束 |
| 数据模式 | 单选段 | 解释当前快照 / 刷新后分析 | 默认 explain_snapshot，不重新取数；refresh_and_analyze 会重新取数、生成新 snapshot，并在报告并列旧新时间与差异。选择多个市场时强制切为刷新后分析。 |
| 对比基准 | 单选段 | 前一等长窗口 / 去年同期 / 无对比 | 默认「前一等长窗口」。「去年同期」仅在 store_daily_metrics 有足量历史时可选，否则灰掉并提示「历史数据不足」——不允许静默降级为前一窗口 |
| 市场 / 站点 | 多选 | 该账号 active marketplaces | Amazon 专属。默认＝当前视图所在市场（即 7.7 的概览条高亮项），而非全选、也非账号主市场——商家从 DE 视图的卡片点进来，默认就该是 DE。多选时走 Skill 的 multi-marketplace-mode（一次 pipeline 调用带全部 marketplace_ids，不做 Agent 侧循环），弹窗需提示「将分别输出每个市场的独立结论，不做汇总」 |
| 渠道 / 国家 | 多选 | channel_mix / country_mix 的键 | Shopify 专属。默认全选。这里直接复用 Tier-3 结构指标作为选项来源——T3 指标的主要价值就在这里 |
| Location | 多选 | shopify_specific.locations | Shopify 库存类专属。默认全选；multi_location=False 时整项不显示 |
| 关注维度 | 多选 | 收入 / 库存 / 商品 / 客户 / 运营 / 费用利润 | 默认＝卡片所属维度。关键约束：勾选 4 个及以上时，弹窗提示「将切换为完整店铺诊断」并把目标 Skill 自动改为 store-health-diagnostics——这条与两个 Skill 的既有路由规则一致，不能让弹窗产出违反路由约定的请求 |
| 分析对象范围 | 勾选列表 | 展开区中命中的 SKU / 变体 / ASIN / 客户 | P2、P3 原型专属。默认＝命中项 Top 10；商家在展开区勾选的结果直接带入。上限 50 项，超出时提示改用完整诊断。此值写入 focused_identifier → Skill 的 request_scope |
| 输出深度 | 单选 | 快照 / 趋势简报 / 完整诊断 | 高级区。默认「趋势简报」。对应 store-health-diagnostics 的三档窗口模式（Health Snapshot / Health Trend Brief / Full Store Ops Diagnostic） |
| 回复语言 | 单选 | 中文 / English | 高级区。默认跟随界面语言。仅这两种（第 11 章） |
| 原型 | 暴露的参数 | 提示词模板骨架 |
|---|---|---|
| P1 | 分析窗口、对比基准、市场/渠道、关注维度 | 核查我 {平台}{市场} {窗口} {指标名} 的 {变化描述}，对比 {基准}。{维度侧重句}。分开列出已知事实、相关信号、待验证假设与处理建议，没有事件或实验依据时不得给确定原因。 |
| P2 | 分析窗口、分析对象范围、市场/Location | 核查我 {平台}{市场} 这 {N} 个{对象类型}的{问题描述}：{标识列表}。逐项列出已知事实、相关信号、待验证假设与处理优先级；没有事件或实验依据时不得输出确定原因。 |
| P3 | 分析窗口、分析对象范围、金额口径（成本价/售价） | 我 {平台}{市场} 有 {金额} 的{问题描述}（占{参照}的{占比}）。分析构成、证据覆盖与优先核查顺序；不得把开放金额或历史金额写成可追回收入。 |
| P4 | 分析窗口、对比基准、结构维度选择 | 分析我 {平台}{市场} {窗口}{结构名}的变化，重点说明占比变化最大的分段及其影响。 |
| P5 | 分析窗口、开放结账步骤、是否只看出现库存不可用证据的记录 | 分析我 Shopify 店铺 {窗口} 的开放结账金额与步骤分布，单列出现库存不可用证据的记录，并给出可验证的处理动作。 |
| P6 | 分析窗口、影响范围（只读） | 我 {平台}{市场} 出现 {事件描述}，从 {开始日期} 起已持续 {天数}，涉及 {范围}。请排查原因并给出恢复步骤。 |
发送的消息体分「可见文本」与「结构化请求」两部分。浏览器只提交 snapshot_id 和用户选择；服务端按登录租户重新读取并校验不可变快照，再构造给 Skill 的可信元数据。
| 元数据字段 | 作用与硬规则 |
|---|---|
| connection_id | 不信任浏览器传值。服务端根据已登录 tenant/store 和 snapshot 所属连接重新解析 connector-precheck 原值，再作为 Skill 的 _connection_id；卡片体系不得自行生成或从会话文本推断。 |
| target_skill | 由「关注维度」数量决定：1–3 个维度 → store-operation-analysis；≥4 个或选了「整体概览」→ store-health-diagnostics。这条映射直接照搬两个 Skill 已有的路由规则，弹窗不发明新路由 |
| dimensions | 2–3 个维度时 Skill 走 combined-mode 并追加跨维度洞察合成步骤。弹窗需在勾选第 2 个维度时提示「将额外输出跨维度关联分析」——这是卖点不是副作用 |
| request_scope | P2/P3 勾选的对象标识列表，映射到 Skill 的 focused_identifier。为 null 时 Skill 走全店范围 |
| snapshot_id | 默认模式是 explain_snapshot：Skill 读取指定不可变快照，不重新拉数；报告的数值、窗口、币种、市场、成熟度与 source_as_of 必须逐项一致。客户端展示用 snapshot preview 不作为事实来源。 |
| mode | 上下文区常显“解释当前快照（默认）/ 刷新后分析”。选择 refresh_and_analyze 时，客户端不提交任何市场的 source_snapshot_id；服务端按已登录店铺和每个 marketplace 解析各自当前快照，先登记 previous_snapshot_ids，再重新取数生成新 snapshot，报告逐市场并列旧、新取数时间与差异。不允许解释旧卡片时静默换数。 |
| 多市场选择 | explain_snapshot 只允许当前市场。勾选多个市场会明确切换为 refresh_and_analyze，为每个市场分别生成新 snapshot 并独立输出；不能把 US snapshot_id 配给 DE/JP。 |
事实数字由代码生成，归因文字由 DeepSeek 生成并用规则兜底，下一步动作由代码查表。三层各自负责一件事，详细规则都放在本章。
| 层 | 实现 | 职责 | 铁律 |
|---|---|---|---|
| L-事实层 必有 |
代码：槽位填充 + 阈值判定 + status 分类 | 数字、变化量、基准、方向、状态——全部事实陈述 | 模型不得改动一个数字。status 由配置表判定后作为输入给模型，模型不得自行判断「9.2% 算高」 |
| L-归因层 模型主生成 · 规则兜底 |
DeepSeek 主生成（一次调用一店一天），规则引擎兜底（模型失败 / 闸门拦截 / 服务不可用时回退） | 相关信号与待验证假设：哪些指标同步变化、接下来核查什么 | 模型只负责措辞与关联，不产出任何新数字，也不能把相关性写成因果；证据不足时省略解释句 |
| L-行动层 必有 |
代码：metric_id + status（+ 命中规则）查固化动作库 | CTA 按钮 + 预填深度分析提示词 + 跳转 Skill | 行动层不交给模型。行动建议错了比说得不好听危险得多；同指标同状态必须给出相同的、可审计的动作 |
卡片洞察区是 1–2 句话，由三层拼成：事实句（必有）→ 归因句（尽力而为）→ 行动入口（必有，表现为按钮而非句子）。行动层在视觉上不是文案行，而是卡片底部的主按钮（第 8.1 节五区结构的④行动区）。
| 层 | 生成方式 | 示例（订购商品销售额下滑场景） |
|---|---|---|
| L-事实层 必有 |
纯槽位填充，一定能生成。模板：{指标名} {当前值}，{方向} {变化量}（基准 {基准值}） | 订购商品销售额 $18,240，环比下降 23.4%（基准 $23,810） |
| L-归因层 模型 / 规则 |
DeepSeek 生成一句相关信号或核查假设；规则引擎命中时使用已审定文案；两者皆不可用则省略 | 同期订单项数下降 4.1%，每订单项销售额下降 18.9%，折扣金额率上升 6.2pp；先核查商品结构和促销记录 |
| L-行动层 必有 |
代码查固化动作库，渲染为按钮 + 预填提示词，不渲染为句子 | [核查销售额变化]（主按钮，点击打开参数弹窗 → 发起 Skill 深度分析） |
归因层是三层里唯一由模型生成的部分，也是唯一「尽力而为」的部分——拿不到好的归因，宁可省略，不给错的。模型与规则引擎的关系是主备而非并行：默认走模型，模型不可用时规则引擎顶上，两者都不可用时省略。
| # | 平台 | 触发条件 | 归因文案 | 行动建议 |
|---|---|---|---|---|
| R1 | AMZ | amz.rev.gmv_wow.delta_pct ≤ −15%，abs(amz.rev.orders_trend.delta_pct) < abs(amz.rev.gmv_wow.delta_pct) ÷ 2，且 amz.rev.aov_change.delta_pct < 0 | 订单项数降幅较小，每订单项销售额同步下降 | 核查商品结构、促销设置与折扣叠加记录 |
| R2 | AMZ | amz.rev.gmv_wow.delta_pct < 0、amz.rev.conversion_rate.delta_pp < 0，且 amz.rev.sessions_trend.change_band = steady | 流量规模基本持平，官方转化指标同步下降 | 检查 Featured Offer、价格和库存可售状态 |
| R3 | AMZ | amz.rev.gmv_wow.delta_pct < 0 且 amz.rev.sessions_trend.delta_pct ≤ −15% | 销售额和访问量同期下降 | 有 Ads 数据时核查投放；无 Ads 数据时只检查自然流量、Listing 与库存记录 |
| R4 | AMZ | amz.prod.buybox_deficit_count.value > amz.prod.buybox_deficit_count.baseline 且 amz.rev.gmv_wow.delta_pct < 0 | Featured Offer 缺失与销售额下降同期发生 | 优先核查报价、价格竞争力与库存可售状态 |
| R5 | AMZ | amz.prod.listing_flag_count.components.suppressed_count > 0 | 有链接被平台限制展示，直接影响可售性 | 立即处理 suppressed 链接，优先级高于其它事项 |
| R6 | AMZ | amz.fin.fee_rate.delta_pp ≥ 2 且 amz.rev.gmv_wow.change_band = steady | 匹配到订单或订单项的费用率上升，销售额基本持平 | 拆解费用交易，核查 FBA 尺寸分段与服务费变动 |
| R7 | AMZ | amz.inv.stockout_risk_count.value ≥ amz.inv.stockout_risk_count.threshold_value 且 amz.inv.inbound_coverage.value < 30% | 多数断货风险 SKU 的确认在途数量与 ETA 尚不足以覆盖缺口 | 按预计断货日、补货周期和安全库存下发采购 |
| R8 | AMZ | amz.prod.traffic_only_count.value ≥ 3 且 amz.rev.conversion_rate.delta_pp < 0 | 存在有流量零转化的链接 | 核查这些链接的价格、主图与库存状态 |
| R9 | SHP | shp.rev.net_revenue_wow.delta_pct < 0 且 shp.rev.gross_sales_wow.change_band = steady | 毛销售额基本持平，折扣或销售冲销金额同期增加 | 分别核查折扣明细、退货、取消与订单修改 |
| R10 | SHP | shp.cust.repeat_rate.business_status ∈ {alert, watch} 且 shp.cust.guest_share.value > 50% | 回头客比例偏低，同时未关联客户的订单占比较高 | 分别核查账户注册、营销同意和完整客户历史 |
| R11 | SHP | shp.cust.churn_risk.business_status ∈ {alert, watch} 且 shp.cust.email_reach.business_status ∈ {alert, watch} | 历史高价值流失风险客户中，营销同意覆盖有限 | 按同意状态拆分可执行召回对象；送达能力另行核验 |
| R12 | SHP | shp.ops.abandoned_gmv_at_risk.business_status ∈ {alert, watch} 且 shp.ops.abandoned_gmv_at_risk.components.inventory_unavailable_count > 0 | 开放结账中存在库存不可用记录 | 核对相应商品库存，并跟踪这些结账是否随后恢复成交 |
| R13 | SHP | shp.inv.stockout_risk_count.value > 0 且 shp.inv.transfer_opportunity.value > 0；后者已通过源仓余量、目标仓缺口、ETA 与调拨成本约束 | 部分断货风险存在可执行的仓间调拨方案 | 核对源仓安全库存、目标仓需求与预计到达时间后执行 |
| R14 | SHP | shp.prod.refund_rate.maturity = final、shp.prod.refund_rate.delta_pp > 0，且 shp.prod.no_restock_share.value > 60% | 实物退货件数率与退款未回库决策占比同期偏高 | 分别核查退货原因、restockType、仓库处置与商品记录；不能仅凭 NO_RESTOCK 推断损坏或实际损耗 |
| R15 | SHP | shp.fin.margin_proxy.components.cost_coverage ≥ coverage_gate、shp.fin.margin_proxy.delta_pp < 0，且 shp.fin.discount_gmv_share.delta_pp > 0 | 有历史成本覆盖的商品毛利率与含折扣商品净销售占比同期恶化 | 按商品核对折扣、历史成本和毛利变化 |
| R16 | SHP | shp.fin.profit_drag_count.value > 0 且 shp.fin.profit_drag_count.components.net_sales_share_pct ≥ 15% | 净销售额占比不低的商品处于低毛利或负毛利 | 重定价、停用无效折扣或调整推广资源 |
| R17 | SHP | shp.ops.overdue_rate.delta_pp > 0 且 shp.inv.committed_backlog.value > 40% | 逾期订单增加，同时较多库存处于已分配状态 | 核查逾期订单、仓内状态和承运交接记录 |
| R18 | SHP | shp.cust.returning_gmv_share.value > 65% 且 shp.rev.net_revenue_wow.delta_pct < 0 | 老客商品净销售占比较高，整店商品净销售额同期下降 | 分别核查新客订单趋势、老客贡献和获客渠道数据 |
| 设计点 | 做法 | 理由 |
|---|---|---|
| 调用粒度 | 一个店铺（Amazon 为一个 marketplace）一天一次，把该店当日候选池全部指标一次性送入，一次返回全部卡片归因句 | 逐指标调用会丢掉跨指标关联能力——那是模型相对代码的唯一实质优势；一次调用还把 system prompt 开销从「× 指标数」摊薄到「× 1」 |
| 输入内容 | 代码先完成 issue 合并、排序与选卡；模型输入包含店铺元信息、全量候选事实，以及 selected_issues[{issue_id, primary_metric_id, member_metric_ids}]。每个 metric 只给当前值、基准、变化、status、阈值、单位、构成字段和已核验事件。 | 一张卡可能合并多个 metric_id，模型必须围绕最终 issue 写一句解释；节日、促销和广告只有输入有明确证据时才能引用。 |
| 输出格式 | 强制 JSON：{issue_id: {related_signal, hypothesis_to_verify, evidence_metric_ids, confidence}}，另加店铺级 cross_metric_note | evidence_metric_ids 必须是本次 payload 中该 issue 的成员；输出不含 action，动作仍由审定动作库提供。 |
| 长度约束 | 单条归因句 ≤ 60 字（中文）/ ≤ 140 字符（英文），硬截断 | 卡片洞察区只有 2 行空间。让模型写长了再截断会断在句子中间，必须在 prompt 里就约束 |
| 双语 | 一次调用同时产出 zh 与 en，不做两次调用也不做机器翻译 | 同一次调用里两种语言共享上下文，语义一致性更好；成本上仅增加输出 token |
| 温度 | temperature 取低值（0.2–0.3） | 这是「把事实写成句子」的任务，不需要创造力。低温同时降低幻觉概率与文案漂移 |
行动层由代码生成，不交给模型。实现方式是一张纯映射表。
| 设计点 | 做法 | 示例 |
|---|---|---|
| 查询键 | full metric_id + status（+ 命中的组合规则） | amz.rev.gmv_wow + alert →「核查订购商品销售额变化」；禁止用裸 slug 作为动作键 |
| 动作库内容 | 每个键 1 个主按钮（打开参数弹窗 → Skill）+ 1 个次按钮（原地展开趋势/明细），另配预填提示词（第 9 章参数弹窗） | 主按钮「核查销售额变化」→ 预填「核查订购商品销售额近 7 日下降 23.4% 的关联信号」 |
| 兜底动作 | 未配置专属动作的 metric_id + status 一律落入通用兜底：「进入深度分析 / 查看完整报告」 | 「深度分析」主按钮 → 打开该指标的完整 Skill 会话 |
| 一致性保证 | 同键同文案，纯查表，可单测、可审计、可解释 | 任何结论都能回溯到具体规则与阈值，逐句解释 |
模型输出不直接入库，必须通过五道机械校验。任一条失败则对应 issue 回退到规则引擎；规则也未命中时省略该 issue 的归因句。事实层与行动层由代码生成，不受影响。
| 监控指标 | 目标 | 处置 |
|---|---|---|
| 闸门整体通过率 | ≥ 95% | 低于 90% 触发告警并暂停模型归因，全量切规则兜底（开关级切换，见 10.6） |
| 闸门 1 拦截率 | ≤ 2% | 持续偏高说明 prompt 未有效约束数字来源，需修 prompt 而非放宽闸门 |
| 日批完成时间 | 页面首次访问前完成 | 超时则该店当日归因走规则兜底，不阻塞页面 |
| 人工抽检合格率 | ≥ 98%（每周抽 200 条） | 闸门是机械校验，抓不住「话说得对但没价值」。抽检覆盖这一层 |
| 失败点 | 表现 | 降级动作 |
|---|---|---|
| 模型 API 不可用 | 调用超时或报错 | 批内重试 2 次（间隔递增），仍失败 → 该店全部指标归因走规则引擎。页面无感知 |
| 单 issue 未通过闸门 | 闸门 1–5 任一失败 | 该 issue 单独回退规则归因，其余 selected issue 保留模型归因；回退粒度与最终卡片单位一致。 |
| 规则引擎也未命中 | 模型不可用 且 规则无匹配 | 省略归因句，卡片呈现「事实层 + 行动层」。绝不猜测归因 |
| 日批部分完成 | data_status = partial | 成功维度发布当前数值和与当前 payload_hash 对齐的洞察；失败维度写 canonical availability、raw_error 与修复入口，不无标识继承旧维度值。 |
| 日批整体失败 | data_status = failed | 整区可显示上一成功 snapshot，但必须标 stale，常显 last_success_at/source_as_of，并关闭补货、清仓、调价、召回等强动作；旧洞察只有与展示的旧 snapshot hash 一致时才出现。 |
| 数据过旧仍展示 | 重拉失败，旧数据继续展示 | 页面标注「数据截至 X 月 X 日」，商家自行判断时效（第 11.2b 节修订流水记录） |
| 洞察与数值不匹配 | 同日重跑后 insight 仍引用旧 payload | insight 与 card snapshot 必须同一事务发布，并校验 snapshot_id、display_run_id 与 payload_hash；只比 stat_date 不足以识别同日重跑。不一致时只渲染事实层与行动层。 |
| 质量事故（说错话） | 抽检或客诉发现 | 全局开关一键切规则兜底（分钟级生效），同时该文案模式进入回归测试集 |
| 开关 | 粒度 | 作用 |
|---|---|---|
| insight_engine | 全局 | rule_only | rule_plus_llm。总闸，异常时一键切回纯规则 |
| llm_scope | 全局 | 固定为 attribution_only。模型只管归因层单句 |
| llm_store_allowlist | 店铺 | 灰度名单。内部店铺与试点商家先进 |
| llm_rollout_pct | 店铺（hash 分桶） | 按 hash(store_id) 稳定分桶，保证同一店铺不会在两种归因风格间来回跳 |
| llm_metric_blocklist | 指标 | 指定指标永不交给模型。默认包含所有金额型指标（P3）与事件告警型指标（P6）——这两类的错误代价最高 |
| gate_strict_mode | 全局 | 闸门拦截后的行为：fallback（落回规则归因，默认）| drop（丢弃归因层只留事实与行动） |
卡片系统的性能与可靠性几乎完全取决于这一章。页面渲染时不得触发平台 API；常规指标由每日批处理生成，高风险事件由平台通知或高频巡检触发增量计算，页面只读取已经落库的结果。
| 要点 | 设计 |
|---|---|
| 作业粒度 | 一个店铺 × 一个市场 = 一个独立作业。Amazon 多市场店铺展开成多个作业，互不影响——这与 Skill 的「不跨市场聚合」规则一致，也保证单市场失败不污染其它市场。 |
| 市场数放大效应 | 第 7.7 节的「跨市场告警上浮」要求所有活跃市场都跑日批，否则无法得知非默认市场是否有 alert。因此作业数 = 店铺数 × 活跃市场数，五市场卖家的成本是单市场卖家的五倍。 缓解：对长期零订单的市场降频（连续 14 天零订单 → 改为按周更新，概览条上标注「数据截至 X 月 X 日」）。不少卖家开通了市场但无实际销量，这类市场每天拉数纯属浪费。但不能只跑默认市场——那等于放弃告警上浮能力。 |
| 执行时点 | 按店铺所在市场的本地时区错峰调度，在当地凌晨完成，保证商家早上打开页面看到的是完整的前一日数据。错峰同时避免所有作业挤在同一小时打平台 API。 |
| 高风险事件 | Listing 被限制展示、账号绩效越界、订单临近或超过最晚发货时间等经营事件不能等到次日日批；连接授权失效属于 system_incident 数据横幅，不混入经营 issue 的 priority_key。通知或轻量巡检命中后，可以只重拉受影响数据源，但必须把新指标与其余当前缓存指标一起重跑该市场完整候选池、issue 合并、排序、配额与 display。随后在同一事务中 upsert 当日 store_daily_metrics 的 metrics/insights/display/computed_at/observation_count，更新 store_card_state 与店铺级 market_overview，并建立新的 display_run_snapshot 和 card_snapshot。任一步失败整笔不发布，页面继续读取上一成功 run。 |
| Amazon 特殊性 | Reports API 是 submit → poll → download 的异步流程，单次可能耗时数分钟到数十分钟。作业需支持长轮询与断点续跑，且遵守 Skill 的规则：同一 pipeline + 市场在一次运行内不重复调用。原始 failure_na 先保留在 raw_error，再映射为 canonical source_failed，其它维度继续运行。 |
| 失败隔离 | 维度级隔离。某个 pipeline 失败只把该维度的指标标记为不可用（对应第 7.6 节的异常卡形态），其它维度照常落库。data_status 记 partial。 |
| 重跑策略 | 失败作业进入重试队列，间隔递增（30 分钟起）。重跑覆盖同一 stat_date 的行而不是插入新行，由主键唯一约束保证。当日多次重跑成功后 data_status 可从 partial 升级为 ok。 |
| 重跑无法覆盖的部分 | A 类按各自原始历史窗口重拉，C 类重算未达到 settle_age 的 cohort/自然周，因此漏跑可在后续观测中自愈。Sales & Traffic 中的 Featured Offer 占比属于可重拉的 A_ratio。B 类时点指标（库存水位、实时在售状态、店铺评分）只回答“现在”，漏跑的历史点永久不存在；B 类作业失败必须单独告警。 |
| 与 Skill 的关系 | 卡片、Skill 与报告通过 snapshot_id 对齐。默认 explain_snapshot 读取卡片当时的不可变快照；用户明确选择 refresh_and_analyze 时才调用 pipeline 生成新快照，并把旧、新取数时间和差异一并写入报告。 |
| 字段 | 类型 | 说明 |
|---|---|---|
| store_id | string | 主键组成。对应连接器解析出的店铺 |
| connection_id | string | 写入时记录的连接 id。不作为主键——连接重建会换 id，但历史指标应保留。用于校验数据归属与缓存隔离 |
| platform | string | amazon | shopify。决定读哪套指标配置 |
| marketplace_id | string | 主键组成。Amazon 为实际市场 id；Shopify 为固定占位值（保持表结构统一，避免 nullable 主键） |
| stat_date | date | 主键组成。统计日期而非计算日期——两者可能因重跑而不同 |
| metrics | JSONB | 指标主体。以 metric_id 为键，每项保存 Metric Spec 的运行时输出以及独立的 source_as_of、observed_age_days、maturity、coverage 与 availability。不同指标不能共用一条成熟度结论 |
| insights | JSONB | 存归因层最终产出（rule / llm / none）、issue_id、evidence_metric_ids、zh/en 句子、payload_hash 与闸门结果。事实层和行动层在读取时由代码模板渲染，不写入此字段。 |
| display | JSONB | 三道闸门筛选后的展示结果：首屏卡位顺序、摘要行指标、Steady State 标记。筛选在日批完成，页面不做排序计算 |
| display_run_id | string | 指向本行当前已发布的不可变 display run；事件重算只有在整个事务成功后才切换该指针 |
| data_status | string | ok | partial | failed。复用 Skill 已有的同名字段语义 |
| failed_dimensions | JSONB | 每项同时保存 canonical availability_status 与 pipeline 原始 raw_error。页面只按 permission_denied/source_failed/stale 等 canonical 状态渲染；data_not_available 等原始名称必须继续细分并保留，不能直接成为页面分支。 |
| computed_at | timestamp | 本行最后一次成功计算的时刻，即认知时间（第 11.3 节）。页面用它显示「数据更新于」 |
| metrics.*.observed_age_days | int | 每个指标自己的观测龄，由该指标的 source_as_of、事件窗口和认知时间计算；用于选择同龄或结算基准 |
| metrics.*.maturity | string | provisional | settling | final。按平台 × 指标 × 数据源分别判断，不能因为同一行中的销售已定稿，就把退款、退货或费用也标成 final |
| observation_count | int | 该 stat_date 被重复观测的次数。持续为 1 说明滚动窗口没有生效，是一个可监控的健康信号 |
| schema_version | int | 指标配置版本号。阈值或公式变更时递增，避免拿新口径的今天和旧口径的上周做对比 |
这些记录的写入条件和生命周期不同，不能全部塞进 store_daily_metrics。指标主表保存可重算的日度结果；其它表分别承担漂移审计、展示状态、不可变取证、执行闭环和报告回放。
| store_metric_revisions | 设计 |
|---|---|
| 字段 | observation_id, old_observation_id, new_observation_id, metric_id, drift_pct, created_at |
| 写入条件 | 它是从完整观测流水派生出的漂移摘要；同一 stat_date 漂移超过配置线（冷启动可用 0.5%）时写入，用于告警、聚合和运营排查。它不承担完整审计或同龄取值。 |
| 用途 | 提供超过配置线的显著漂移告警、运营排查索引和摘要报表；完整漂移分布与 settle_age 校准只读 store_metric_observations，避免阈值筛选造成样本偏差。 |
| 保留 | 90 天，服务近期显著漂移排查；完整观测流水按校准与审计所需窗口单独保留。 |
| store_metric_observations | 设计 |
|---|---|
| 字段 | observation_id, store_id, marketplace_id, stat_date, metric_id, observed_at, observed_age_days, value, maturity, source_as_of, comparability_key, payload_hash |
| 写入条件 | 首次及每次有效观测都写，不以漂移大小过滤；所有用于卡片、比较或报告的版本必须可定位。商家实际看到的内容由 card_snapshot 取证，同龄基准和 settle_age 校准读取此表。 |
| C 类重算 | 未达到 settle_age 的 cohort/自然周每次日批都重拉并按 key 生成新 observation；final 点锁定。B_point 只追加当前时点，漏跑形成永久缺口。 |
| store_card_state | 设计 |
|---|---|
| 字段 | store_id, marketplace_id, stat_date, slot, issue_key, primary_metric_id, layer_variant, status, consecutive_days, task_id |
| 性质 | 记录的是我们自己的输出，不是平台数据。因此它没有成熟度、没有认知时间、没有准确性问题，也不需要修订流水——这是它必须独立成表的根本原因 |
| 用途一：抗疲劳 | 第 10.3a 节的同义模板轮换需要知道「上次用的是哪个 variant」，连续告警计数需要知道「这是第几天」。没有这张表，同一张告警卡会连出六天一字不变 |
| 用途二：跨日连续性 | 保存 issue_key、primary_metric_id、上一展示 variant、连续天数与关联 task_id，供持续角标、文案轮换和 reopened 判断。当前 run 的主题合并只按当次候选 issue_key 完成，不能因为昨天展示过就隐藏今天的问题。 |
| 用途三：满卡率监控 | 6 是上限，不是每天必须填满的目标。系统持续记录实际出卡数、各卡位点击和主题分布，用真实使用数据校准阈值、卡位数与主题合并规则 |
| 保留 | 30 天。轮换与连续计数都只回看近期 |
| display_run_snapshots | 设计 |
|---|---|
| 字段 | display_run_id, store_id, marketplace_id, stat_date, config_version, schema_version, candidate_issues, member_metric_ids, priority_keys, merge_result, quota_result, final_slots, created_at, payload_hash |
| 性质 | 不可变。它保存整次候选池、issue 合并、排序与卡位结果；页面顺序从这里回放，事件重算成功后才切换主表的 display_run_id。 |
| card_snapshots | 设计 |
|---|---|
| 字段 | snapshot_id, display_run_id, slot, issue_key, primary_metric_id, member_metrics JSONB, priority_key, schema_version, copy_version, layer_variant, action_key, rendered_copy JSONB, created_at, payload_hash。member_metrics 每项保存 metric_id、value、baseline、delta_pct、delta_pp、change_band、business_status、window、currency、source_as_of、maturity、coverage、availability、comparison_status、reason_code、comparability_key、threshold_value、threshold_type、threshold_version 与 components；rendered_copy 固化商家当时看到的 fact_text、insight_text、action_text、labels 与 locale。 |
| 性质 | 不可变。卡片出现在页面、用户点击分析或任务建立时固化当时的完整口径和数值。任何刷新都会新建 snapshot_id，不能覆盖旧快照 |
| 用途 | 单卡内容由 snapshot_id 回放；整页顺序由其 display_run_id 回放。卡片、Skill、报告和处理前后对比引用同一不可变证据。 |
| action_tasks | 设计 |
|---|---|
| 字段 | task_id, snapshot_id, status, owner, due_at, resolution_note, evidence, before_snapshot_id, after_snapshot_id, verification_metric, verification_window, verification_due_at, verification_status, verified_at, completed_at, reopened_at, reopen_reason |
| 状态 | unassigned / assigned / in_progress / blocked / verifying / done / reopened；verification_status 为 pending / passed / failed / not_comparable。只有 evidence 存在、before/after comparability_key 兼容且验证通过才能进入 done；失败进入 reopened，不可比继续 verifying 或 blocked。 |
| report_runs | 设计 |
|---|---|
| 字段 | run_id, mode, input_snapshot_ids, output_snapshot_ids, skill, status, started_at, completed_at, report_uri, error_type |
| 用途 | 记录报告究竟解释了哪份快照、是否主动刷新、是否成功交付。报告只引用这里登记的快照，不从当前主表临时取一个“最新值”替换 |
快照的一行不是「那天的真相」，是「我们在某个时刻对那天的认知」。这个区分是整章的语义基础。如果一行是那天的真相，真相就不该每天变；可它确实每天在变——所以只有后者能自洽。
| 类别 | 例子 | 两条时间轴的关系 | 后果 |
|---|---|---|---|
| A 可重算聚合 | 订购商品销售额、净销售额、订单项数/订单数、会话量、每订单项销售额/AOV、转化率、Sales & Traffic 的 Featured Offer 窗口占比 | 认知时间可以晚于事件时间，且认知快速收敛 | 可按原窗口重拉，漏跑能自愈。settle_age 按平台与指标的实测漂移配置 |
| B 时点观测 | FBA 可用库存、实时在售状态、店铺评分 | 认知时间只能等于事件时间。平台只回答「现在」 | 不可重拉，漏跑即永久缺失。天生 final，无成熟度问题 |
| C 长尾结算 | 退款率、退货率、费用结构、Reimbursement | 认知时间可以晚很多，收敛很慢 | 可重拉，但成熟期按月算。settle_age = 30 天 |
| # | 消费方 | 需要跨行历史 | 不存会怎样 |
|---|---|---|---|
| 1 | A 类趋势迷你图 P1 原型 | 不需要 | 不缺。每天拉的 14 天本身就是一条序列，日批算好塞进当天行的 metrics 即可。这一项常被误认为需要快照表。画什么形态见第 11.3e 节 |
| 2 | B 类趋势迷你图 库存 / 实时状态 | 必须 | 每次拉取只返回一个时点值，历史只能靠逐日观测。跨行读取只发生在日批，页面读取物化 trend_buffer。Featured Offer 的 Sales & Traffic 窗口占比不走这条路径。 |
| 3 | 历史位次 「创近 N 周新高」 | 必须 | 只有积累满 N 周且口径、成熟度可比时才可生成；否则 Steady State 只陈述检查范围、连续性和数据边界 |
| 4 | 卡片状态延续 store_card_state | 必须 | 第 10.3a 节抗疲劳完全失效。读的是自己的输出，不是平台数据，所以独立成表（第 11.2b 节） |
| 5 | 漂移审计 内部 | 必须 | settle_age 只能拍脑袋，无法用实测漂移率验证 |
| 基准 | 做法 | 代价 | 适用 |
|---|---|---|---|
| 结算基准 | 两期都取 final 值，窗口整体后移 settle_age | 首屏最新一天是 T-4 而不是 T-1 | 金额与费用类。数字准确性优先于时效 |
| 同龄基准 | 本期取当前值，上期从完整 store_metric_observations 取相同观测龄时的值 | 依赖完整观测流水，卡片需标注口径 | 订单数、会话量等沉降快的量值。可正常展示 T-1；store_metric_revisions 只做显著漂移摘要，不能承担同龄回读 |
上面这套机制里，只有四样东西会浮到界面上。
| 商家看到 | 实际含义 | 要防的误解 |
|---|---|---|
| 迷你图上的断点 | 那天我们没有采到数据 | 误解成「那天是 0」。所以断开而不连线，不插值——插值会造出一个从未存在过的数字 |
| 「数据更新于 X 月 X 日」 | 这一行的认知时间 | 误解成「数据完整到 X 月 X 日」。它只说明我们算到哪天 |
| 最新一天标「初值」 | 这个数还会小幅变动 | 四样里唯一真正重要的一条，见下方 |
| 「创近 12 周新高」 | 当前值在已有且满足成熟度要求的 12 周历史分布中的位次 | 误解成「历史最高」。文案必须带明确窗口；历史不足 12 周时不展示 |
| 类别 | 画什么 | 点数 | 理由 |
|---|---|---|---|
| A 类量值 销售额·订单项·会话 | 按 Metric Spec 窗口滚动求和 | 由 history_days−window_days+1 决定，页面上限 12 | 7 日指标在 14 日缓冲区得到 8 点；其它窗口按自己的合同执行。末点就是头条数字，日度原值只能放在详情中。 |
| A 类比率 转化率·AOV·毛利率·费率·Featured Offer | 按指标窗口滚动；分子、分母分别汇总后再相除 | 由窗口与历史长度决定，页面上限 12 | 末点必须等于卡片头条；PFC 使用 7 日，LSR 同时展示 10/30 日，Featured Offer 使用 Sales & Traffic 的同一窗口，其余读取 Metric Spec，不能用日度比率冒充窗口比率。 |
| B 类时点值 库存·实时在售状态·评分 | 日度时点值 | 14 | 滚动求和对存量值无语义。缺失日断线，不补 0，也不回填不存在的历史时点。 |
| C 类长尾 退款率·退货率·费用 | 成熟 cohort 周度点 | 8–12 | 每点只使用达到相同成熟度的 cohort；日度过稀且未结算，不用假精度制造波动。 |
| 项 | 设计 |
|---|---|
| 配置来源 | 阈值不硬编码在计算代码里，而是从指标配置表读取，键为 (metric_id, scope)。scope 支持 global / platform / marketplace / store，按由细到粗回退 |
| 默认值来源 | 默认阈值必须与 Skill 的 references/defaults.md 保持同一份真值。卡片说「高于 8% 阈值」而 Skill 报告用 10% 判定，是这套系统最容易出现也最伤信任的不一致 |
| 店铺级覆盖 | 支持商家设置经营目标，但官方绩效阈值不可被覆盖。内部提醒值的修改要显示作用范围、即时预览和审计记录，避免通过调松阈值掩盖问题 |
| 变更留痕 | 阈值变更必须递增 schema_version 并记录生效日期。历史行不回溯重算——回溯重算会让商家昨天看到的告警今天凭空消失 |
| 样本量门槛 | _MIN_ORDERS_D1_D5 = 10 与 _MIN_SHIPPED_D3 = 10 同样外置，与 Skill 共用同一配置 |
| settle_age | 按 平台 × 指标类别配置，初值 Amazon A 类 3 天 / Shopify A 类 1 天 / C 类 30 天 / B 类不适用。这些初值都是推测，上线后从完整 store_metric_observations 按平台 × 指标 × 观测龄计算漂移分布：某平台某指标在观测龄 N 天后漂移率稳定低于 0.5%，则 settle_age 收敛到 N。store_metric_revisions 只保留超过配置线的摘要，用于告警和排查，不能作为校准的唯一输入。 |
| 指标窗口 | 窗口属于单项 Metric Spec，不设全局白名单。日度销售、订单、会话和转化通常使用 7 日或其它 7 的倍数；库存销速使用 28 日；Amazon 预配送取消率按官方滚动 7 日，迟发率按官方 10 日或 30 日；退货、退款、LTV 与客户指标使用各自成熟 cohort。任何比较都必须同时满足同市场、同币种、同口径版本和成熟度可比；窗口不足写 comparison_status=insufficient_history，不把它塞进 availability_status。 |
| 项 | 设计 |
|---|---|
| 语言范围 | 仅中文与英文两种。卡片系统不跟随 Skill 报告的多语言范围——卡片文案需要逐条人工撰写与审校，扩语种的边际成本远高于报告渲染层的机器翻译 |
| 键命名 | card.{platform}.{dimension}.{slug}.{layer}.{variant}。layer ∈ fact / attribution / action / button / label；variant 用于同义模板轮换（第 10.3a 节） |
| 规模估算 | 30 项 T1 指标的按钮文案 60 键（第 8.4 节）+ 55 项指标的事实层与标签 + 18 条规则 × 3–4 个同义模板 × 归因与行动两层，合计约 700–900 个键 × 2 语言。这是一次性投入，但不是小投入 |
| 完整性校验 | 复用两个 Skill 已沉淀的 tools/i18n.py 体系做键完整性检查。缺键必须在构建阶段失败，不允许运行时回退到键名——商家看到 card.amz.rev.gmv_wow.action.1 比看到英文更糟 |
| en 独立撰写 | 英文不是中文的直译。中文习惯「客单价环比下降 18.9%」，英文更自然的是 "AOV down 18.9% WoW"。直译会让英文商家一眼看出这是翻译过来的产品 |
| 数字与日期本地化 | 货币符号、千分位、日期格式、百分号位置按语言处理。数字格式化统一复用 scoring 脚本已有的 _fmt_* 系列，保证卡片与 Skill 报告完全一致 |
| 语言选择来源 | 默认始终跟随当前 UI language preference；弹窗可仅对本次请求覆盖，关闭后不单独记忆。若产品持久化，持久化的是用户 UI 语言设置，不是卡片参数。 |
下面的可操作原型演示悬浮、展开、参数弹窗和发送动作。卡片放在左栏输入框下方，让经营信号与后续对话处于同一条操作路径；右栏保留低频配置。动效总时长不超过 1.4 秒并响应 prefers-reduced-motion，只用于说明状态变化和引导视线。
FULUPET Store 是一家在亚马逊平台上运营的店铺，专门销售宠物相关产品。
Generated from Amazon · Updated Jul 8, 2026
No tasks linked
这套能力要作为一个完整经营闭环交付：数据接得上、公式算得准、卡片排得出、分析说得清、任务有人接、处理结果能回读。任何一环缺失，都不能把“生成了一张卡片”当成完成。
| 类别 | 指标 | 验收线 | 说明 |
|---|---|---|---|
| 正确性 最高优先级 | 卡片数值与 Skill 报告数值一致率 | 100% | 同一口径同一窗口下必须逐位一致。不一致即阻塞发布，无例外——这是第 1 章「数字只有一个来源」原则的验收方式 |
| 解释文案中出现输入快照之外的数字 | 0 例 | 事实层只做结构化槽位填充；解释层由数字白名单闸门校验 | |
| 阈值判定与 defaults.md 一致率 | 100% | 用构造样本覆盖每个阈值的上下边界与等值点 | |
| 商家反馈的数值错误投诉率 | ≤0.1% | 按周活跃店铺数计。超线即回滚相关指标 | |
| 可用性 | 页面卡片区首字节时间 | <200ms | 一次数据库 round-trip 读取 market_overview 与默认市场物化行，不含前端渲染 |
| 日批当日成功率（data_status = ok） | ≥95% | Amazon 因 Reports API 异步特性预计低于 Shopify，需分平台单独看 | |
| 空屏率 | 0% | 包含全链路失败、全店平稳、新店无数据三种极端情况。第 1 章「永不空屏」原则 | |
| 使用价值 进入日常工作 | 卡片曝光 → 点击详情 | ≥12% | 作为起始运营线；按卡位、指标与店铺类型分层观察，长期偏低时重新审视指标、文案和排序 |
| 弹窗打开 → 确认发送 | ≥55% | 低于此值指向参数设计过于复杂或默认值不合理 | |
| 发送 → Skill 完成并交付报告 | ≥80% | 主要失败源是 pipeline 失败，与卡片系统本身无关但会被商家算在这个功能头上 | |
| 7 日回访率 | ≥40% | 与任务认领和完成数据一起判断功能是否进入商家日常工作流 | |
| 处理闭环 真正完成 | 需处理卡片 → 建立或关联任务 | ≥60% | 无任务的卡片只能证明被看见，不能证明有人处理 |
| 任务在 24 小时内认领 | ≥80% | 按事件严重度分层，官方绩效和 Listing 事件单独看 | |
| 任务按时完成率 | ≥75% | 以 due_at 和 completed_at 计算，blocked 单列，不混入完成 | |
| 处理后指标恢复率 | 按指标设目标 | 必须使用可比的 before/after snapshot；不同指标验证窗口不同 | |
| 已完成任务重开率 | ≤10% | 偏高说明完成定义过松、处理动作无效或验证窗口设置错误 | |
| 模型归因专属 | 闸门通过率 / 拦截率 | ≥95% / ≤2% | 通过率过低说明 prompt 有问题；拦截率过高说明模型在越界 |
| 人工抽检合格率 | ≥98% | 每周抽样，重点看「正确但无用」这类闸门无法识别的问题 |
| 对象 | 固定合同 | 允许怎样用运行数据调整 |
|---|---|---|
| 内部提醒阈值 | 官方绩效阈值固定；内部提醒值配置化并标明来源。 | 每 4–8 周查看触发频次、误报和任务恢复。某指标在绝大多数适用店铺长期告警时，调整内部阈值或适用条件，并递增版本；不改写历史快照。 |
| 首屏卡位 | 桌面上限 6 张，移动端可单独配置；候选不足时不凑满。 | 按位次看曝光、点击与任务建立率。第 5、6 位长期无使用价值时可收缩，官方绩效与强制事件仍优先。 |
| Amazon 客户维度 | Amazon 没有可用于本设计客户分层的稳定买家身份数据，D4 不生成指标和空占位；只有存在同一商家的 Shopify 连接时才给跨店入口。 | 商家反馈只影响说明文案和入口，不改变数据能力事实，也不用估算客户身份补空。 |
| Shopify 成本覆盖 | observed_gross_margin 只在有销售时历史 COGS 的 cohort 内计算，并常显 cost_coverage；覆盖不足不外推整店毛利。折扣销售占比不依赖成本，照常计算。 | 监控历史 COGS 覆盖率和补齐完成率；只改数据补齐入口和 coverage gate，不把当前 unitCost 静默回填历史。 |
| 18 条解释规则 | 未命中且模型不可用时省略解释句，事实层与行动层照常工作。 | 按真实候选组合、命中率与人工抽检价值扩充高频规则；每次修改版本化，不按条数凑覆盖。 |
| 主题合并与配额 | issue_group、merge_version、维度上限和正向卡上限全部外置；官方绩效与强制事件不受普通配额阻挡。 | 根据候选集、卡位点击和被合并指标展开率调整主题粒度与限制，旧 display_run_snapshot 保持可回放。 |
| 万级店铺容量 | 本地时区错峰、按数据源配额排队、长期零订单市场降频；高风险事件走轻量通知或巡检。超出配额时先保留官方绩效、订单和 Listing 事件，不减少指标定义，也不静默漏掉市场。 | 容量测试持续记录平台配额、单作业耗时、失败率和活跃市场数分布，用它调整 freshness_policy 与低风险源刷新频率。 |
| 移动端布局 | 卡片布局响应式，P4 结构分布型与 P5 漏斗型在窄屏使用纵向明细，不压成不可读小图。 | 按真实访问端和阅读完成率调整展开形态与卡位数，数据口径不随端变化。 |
| 移动端趋势点 | 只允许减少可见标签或抽稀展示点；必须保留头条对应末点和对比基准端点，不能改变 rolling_window_sum/ratio 结果。 | 按真实屏宽、交互与阅读完成率决定抽稀密度，原始趋势缓冲和快照保持完整。 |
| 项目 | 运行合同 |
|---|---|
| 指标池规模 | 55 项，Amazon 22 / Shopify 33。每项按能力表声明权限、报表、外部依赖和降级状态；缺权限或数据源时明确返回不可用，不伪造替代值 |
| 分平台策略 | 两平台完全独立配置。跨平台视图可并列展示各自趋势与口径；只有 comparability_key 兼容且 Metric Spec 声明 cross_platform_comparable=true 时才计算归一化相对变化，其余不排名。 |
| 无变化处理 | 越界但平稳仍展示；健康且平稳进入摘要；刚跨越阈值由 worsening_crossing 进入唯一 priority_key；数据缺失显示明确灰态 |
| 全店平稳 | Steady State 显示已检查且健康的指标数、数据待补数、不适用项和数据截止时间；只有真的存在机会信号时才给机会入口，不强行制造正向结论 |
| 卡片交互 | 6 类原型覆盖 30 项 T1 指标；P1 19 项、P2 7 项，合计 26 / 30 = 86.7%。逐指标差异下沉到配置，按钮文案仍逐条维护。 |
| 迷你图形态 | 图上的量必须等于卡片头条数字。量值按各自窗口滚动求和；比率按各自窗口汇总分子、分母后相除；时点值画日度点；长尾指标画成熟 cohort 周度点。点数由窗口与缓冲区决定，末端未成熟区用虚线表达。 |
| 点击详情 | 参数弹窗，10 类参数按卡片选择性展示 + 可编辑提示词 + 结构化请求。默认解释同一 snapshot_id；用户选择刷新后分析才生成新快照。 |
| 洞察引擎分工 | 事实层永远代码、归因层模型主生成 + 规则兜底、行动层永远代码查表（第 10 章）。行动层不交给模型——行动错了比说得不好听危险得多。模型只在归因层创造增量价值，且受五道闸门约束；模型不可用只是少一句解释，不是少一个下一步 |
本附录记录平台官方统计口径，并把官方绩效阈值与 StoreClaw 内部提醒值分开。14 天、20%、50 Sessions、80%、90 天等内部参数必须标明来源和适用条件，不能包装成平台规定。
| 平台 | 页面用词 | 官方统计口径 | 在这份设计里要分清的事 |
|---|---|---|---|
| Amazon | Ordered Product Sales | Sales & Traffic 报表里的订购商品销售额。 | 若改取 Orders API 的 OrderTotal 或已发货销售额，必须另写名称，并说明税费、运费和日期口径。 |
| Amazon | Units Ordered | 窗口内订购的商品件数。 | 它不是去重订单数，也不是订单项数。 |
| Amazon | Total Order Items | 窗口内的订单项数。 | 用它做每订单项销售额时，不能再把结果称为每张订单 AOV。 |
| Amazon | Unit Session Percentage | 订购件数相对 Sessions 的比例，即 Units Ordered ÷ Sessions。 | 不是 Orders ÷ Sessions；要与 Seller Central 对账时直接用官方字段。 |
| Amazon | Featured Offer | 商品详情页默认 Add to Cart 对应的报价。 | 80% 只能作为内部提醒值；没有 Featured Offer 也不等于商品绝对不能销售。 |
| Amazon | FBA fulfillable | 当前可以拣货、打包和发出的 FBA 可售库存。 | 按 marketplace、SKU/FNSKU 与履约项目核对；不能先假设整个账号只有一池共享库存。 |
| Amazon | FBA inbound | Working、Shipped、Receiving 等不同在途阶段。 | inbound > 0 只说明有货在流程中，不能证明数量够或能在断货前到仓。 |
| Amazon | Pre-fulfillment Cancel Rate | 7 天内卖家自配送订单中，由卖家在确认发货前取消的比例；要求低于 2.5%。 | 不含 FBA，也不能把买家或 Amazon 发起的取消一并放进分子。 |
| Amazon | Late Shipment Rate | 10 天或 30 天内，卖家自配送订单晚于预计发货日确认发货的比例；要求低于 4%。 | 判断必须落到每张订单的 expected ship date，不能使用统一固定天数代替。 |
| Amazon | FBA Customer Returns | 运营中心接收的退回商品、件数、原因和处置结果。 | 是商品退货事件，不是 Orders 状态里的现成“退货订单”；分母要和同一批已发货商品对齐。 |
| Amazon | Financial transactions | 费用、退款、赔偿和调整等财务交易按财务事件时间返回。 | 和下单日销售直接相除会错窗；当前简式只能叫估算净回款，不是利润。 |
| Shopify | Gross sales | 折扣和销售冲销前的商品销售额，不含税、运费、关税和费用。 | 不是到账金额，且可能包含待付款、未付款和取消订单。 |
| Shopify | Discounts | 商品折扣及分摊到商品的订单折扣；运费折扣另算。 | Compare-at price 与售价的差不是报表折扣。 |
| Shopify | Sales reversals | 退货、取消和订单修改等造成的销售冲销。 | 不等于支付退款金额；2026-07 字段已与实际退货件数分开。 |
| Shopify | Net sales | Gross sales − Discounts − Sales reversals。 | 中文应写“净销售额”，不是已扣物流、支付、广告和成本的“净收入”。 |
| Shopify | Average order value | （Gross sales − Discounts）÷ Orders，不扣下单后的调整。 | 不能用 Net sales ÷ Orders 冒充 Shopify AOV。 |
| Shopify | Returned quantity | 实际退回的商品件数。 | 判断商品质量时应优先看这项及退货原因。 |
| Shopify | Reversed quantity | 退款、退货、取消或改单造成的冲销件数。 | 不能全部叫退货件数。 |
| Shopify | Available | 当前可以销售的库存状态。 | 直接读取，不用 on_hand − committed 反推。 |
| Shopify | Committed | 已分配给已下单但尚未履约订单的库存。 | 不等于逾期，也不能单独证明仓库拥堵。 |
| Shopify | On hand | Available、Committed、Reserved、Damaged、Safety stock、Quality control 等状态合计。 | 不是可售库存。 |
| Shopify | Incoming | 正在采购、调拨或入库流程中的库存。 | 还不能卖，不能并入 Available。 |
| Shopify | Days of inventory remaining | 期末库存 ÷ 最近 28 天平均日销量。 | 14 天只是查询示例或内部提醒线，不是所有店统一补货标准。 |
| Shopify | Returning customer rate | 依据客户此前完整订单历史区分回头客。 | 不等于“当前窗口内下过两单的客户占比”。 |
| Shopify | RFM | 按本店客户相对分布计算 R、F、M 五分位并分成 11 个客户组。 | StoreClaw 自算分组必须写清与 Shopify 的差别及实际执行对象。 |
| Shopify | Email marketing consent | 客户是否同意接收营销邮件。 | 不是邮件送达率，也不代表可以忽略退信与地址有效性。 |
| Shopify | Abandoned checkout | 客户留下联系方式但没有完成购买的结账；之后可能恢复成交。 | 开放结账金额不是已损失或保证可追回的销售额。 |
| Shopify | Gross margin | （Net sales − Cost）÷ Net sales。 | 不能用当前 price 和当前 cost 代替历史实际毛利；成本覆盖不足时不能给整店红绿灯。 |
| 编号 | 官方页面 | 本文使用位置 |
|---|---|---|
| A01 | Sales & Traffic Business Report | Ordered Product Sales、Units、Order Items、Sessions、Unit Session Percentage、Featured Offer 百分比。 |
| A02 | FBA report types | FBA 库存、补货、All Orders、Customer Returns 报告及字段范围。 |
| A03 | FBA Inventory API | Marketplace、SKU/FNSKU、可售与库存查询边界。 |
| A04 | Amazon terminology | Featured Offer 现行名称与含义。 |
| A05 | Notification type values | Pricing Health、Featured Offer 与不同通知来源。 |
| A06 | Pre-fulfillment Cancel Rate | 卖家自配送、卖家发起、7 天、低于 2.5%。 |
| A07 | Late Shipment Rate | 卖家自配送、10/30 天、低于 4%。 |
| A08 | Finances API FAQ | 财务交易、费用、退款、赔偿、调整与时间口径。 |
| A09 | Finances v0 removal notice | Finances v0 于 2026-08-28 移除，改用 v2024-06-19。 |
| A10 | Performance report types | GET_PROMOTION_PERFORMANCE_REPORT 与 GET_COUPON_PERFORMANCE_REPORT；可用性受 seller/vendor、Brand Registry、角色、市场资格及报表刷新/请求限制约束。 |
| 编号 | 官方页面 | 本文使用位置 |
|---|---|---|
| S01 | ShopifyQL overview | ShopifyQL 能力范围。 |
| S02 | ShopifyQL schemas | 销售、客户、库存、履约等官方数据域。 |
| S03 | shopifyqlQuery | read_reports 权限。 |
| S04 | Sessions and behavior | Sessions、漏斗与转化率。 |
| S05 | Sales schema | Gross sales、Net sales、AOV、Sales reversals、毛利。 |
| S06 | Sales reports | 销售报表日期、订单与销售冲销记录方式。 |
| S07 | Finance reports | 净销售额、退款和财务报表。 |
| S08 | Sales discrepancies | 退货、退款和报表数字差异。 |
| S09 | Analytics fields | AOV 等报表字段定义。 |
| S10 | Sales reversals field change | 2026-07 销售冲销字段变化。 |
| S11 | Returns schema | 退货商品、原因、状态、日期和实际退货件数。 |
| S12 | RefundLineItemRestockType | NO_RESTOCK 的准确含义。 |
| S13 | Refund and cancel orders | 退款、退货与取消订单操作。 |
| S14 | Inventory quantity states | Available、Committed、On hand 等状态关系。 |
| S15 | Inventory states | 商家端库存状态说明。 |
| S16 | Inventory reports | 库存剩余天数、Sell-through 与库存价值。 |
| S17 | Inventory schema | 库存剩余天数与库存查询。 |
| S18 | Inventory by location | 按仓库存与缺货。 |
| S19 | Order routing | 多仓履约与订单路由。 |
| S20 | Inventory transfers | 调拨与在途库存。 |
| S21 | Customer reports | 新老客、回头客率、Cohort 与 RFM。 |
| S22 | Customers schema | 客户订单史、累计消费、RFM 和订阅字段。 |
| S23 | Managing customers | 客户档案与游客结账。 |
| S24 | Email marketing consent | 营销同意状态。 |
| S25 | Abandoned checkouts | 弃单定义、恢复与限制。 |
| S26 | Profit reports | 成本、毛利、毛利率和历史成本限制。 |
| S27 | Profitability schema | 订单利润分析字段。 |
| S28 | InventoryItem | Unit cost 与读取权限。 |
| S29 | Access scopes | 订单历史范围和 read_all_orders。 |
| S30 | Protected customer data | 姓名、地址、电话和邮箱的访问要求。 |
| S31 | Order object | 取消时间与取消原因。 |
| S32 | Fulfillment time | Fulfill by date 与商家承诺时间。 |
| S33 | Fulfillments schema | 履约、发货和送达时长。 |
| S34 | Bing Webmaster API | 已验证站点的排名、流量、关键词、抓取信息，以及 URL/Sitemap 提交能力。 |
| 常显字段 | 页面合同 |
|---|---|
| 来源与证据状态 | 每张卡常显 source_type（platform_fact / storeclaw_derived / merchant_target / internal_threshold）、availability、source_as_of、coverage、market/currency 与 order/SKU/cohort scope。 |
| 弱证据与强动作 | estimated / partial / stale 和“待核对”不得伪装成确定结论；coverage/freshness gate 未通过时禁用补货、清仓、调价、召回等强动作。 |
| 阈值来源 | “官方绩效阈值”与“StoreClaw 内部提醒线/商家目标”使用不同徽标、文案和来源链接，任何内部线不得借用官方样式。 |