{"name":"write_to_file","arguments":{"path":"_bmad-output/analysis/ana-20261028-competitor-kpi-lineage.md","content":"# 跨境电商竞品分析：L1 数据采集 ➔ L3 决策算子血缘拓扑规范\n\n采用“可溯源观测 ➔ 单位与口径统一 ➔ 可复算算子 ➔ 非补偿性门禁”，替代盲目跟卖和模型凭感觉选品。11 个商品字段是最低采集面，而不是六项决策指标的充分输入：销量标定、成本、历史序列、竞争样本和差评原文必须补齐，否则对应指标不得给出通过结论。\n\n- 工件标识：ANA-20261028-COMPETITOR-LINEAGE；版本：1.0；状态：PROPOSED。\n- 授权：仅创建本分析工件；不授权生产实现、终端运行、测试执行、ADR 转正或计划归档。\n- 场景：structural；会话标识：null；日期：2026-10-28。\n- 默认分析口径：Amazon 美国站、USD、单件可比商品；其他平台和国家须重新配置币种、税费、尺寸分级及物流规则。\n- 当前工作区根目录回执仅列出草稿目录；未发现项目事实基线、已接受 ADR 或活动计划入口。不把草稿中的历史提案绑定为当前执行计划，也不创建或覆盖活动计划。\n\n## 1. 顶层战略裁决\n\n### 1.1 目标、约束与非目标\n\n目标：每个立项结论均能回到商品、时间、品类、采集来源、规则版本以及具体成本或评论证据；物理限制和单品经济学优先于需求分数。\n\n- L1 保存原始观测及来源，区分平台显示值、服务商估计值和缺失值；“原始”不等于“真实销量”。\n- L2 只做可审计清洗、单位换算、窗口对齐和带证据的语义标注；禁止凭模型补齐未知重量、成本或销量。\n- L3 对固定输入与版本化参数进行确定性计算；确定性不能消除上游测量误差或语义模型的不确定性。\n- 不允许一个高需求分数抵消超规格、亏损、缺证据或未解决的合规风险。\n\n非目标：\n\n1. 不建设全平台爬虫、代理池或绕过访问控制。\n2. 不自动下单、跟卖、发布文案、采购或调整广告。\n3. 不把 BSR 估算包装为真实销售账，也不从差评密度推断真实退货率。\n4. 不训练专有模型，不编造平台推荐权重，不进行运行时验证或部署。\n\n### 1.2 证据裁决与输入纠偏\n\n- 本地资料明确提出：模型逐条打标并保留评论证据，再由确定性程序聚合；这支持职责分离，但不证明资料中的商业效果数字。\n- 本地 E-GEO 文本研究固定候选集上的 LLM 重排序，使用平均排名改善，而非 Rufus 生产推荐率；其原文强调事实保真，不支持将“结构化事实可信度”当作已经公开的精确平台权重。\n- “最高约 40% 可见性改善”可定位到本地 2024 GEO 摘要，其对象是生成式回答中的可见性，不等同于 2026 电商被推荐率提升 40% 以上。\n- “2026 超过 60% 零点击”、指定参数对推荐率的独立因果作用及 Buy Box 丢失后的算法权重衰减，现有原始证据不足：Insufficient evidence。它们不进入公式或硬门禁。\n- 《Product Research 101: Find Winning Products to Sell on Amazon and Beyond》的公开书目作者为 Renae Clark，而非用户输入中的 Rena Govindarajan。[10](cite:10) $20–$70、18×14×8 英寸及 20 磅在本工件中保留为用户指定的初筛政策，不声称已核实出自该书，也不宣称是 2026 官方尺寸分级。\n- Chevalier 与 Goolsbee 的原始研究涉及 Amazon 与 Barnes and Noble 的在线图书需求及销量秩转换；不能据此保证全品类共用一个系数。[6](cite:6) 本规范将用户给出的 β 区间视为待标定先验。\n- 下文的市场阻力、需求动量权重、利润底线及抽样要求均为版本化提案，不冒充专著原公式或实测结果。\n\n### 1.3 三遍解构与收敛结论\n\n1. 基线扫描：11 字段覆盖排名、需求估计、价格、口碑、年龄和包装；缺成本、评论文本、销售锚点、历史排名以及合规证据。\n2. 因果检查：评论多不必然形成壁垒；BSR 上升可能来自折扣或供给变化；差评集中不等于改款必然赚钱。\n3. 虚拟重实现：补齐输入闭包、拒绝缺失值伪零、保持估算标签、检测收费体积重后，方案可行；停止增加不必要的实时代理和黑箱评分组件。\n\n立项只输出“候选通过”“拒绝”“证据不足”“需人工复核”。候选通过仅表示所配置筛选门禁通过，不是采购授权或合规认证。\n\n## 2. L1 物理事实采集清单\n\n以下严格保留 11 个业务字段；表中的采集来源是接口适配要求，并不表示本次已抓取真实商品。\n\n| 最小字段 | 单位与严格口径 | 采集来源与缺失处理 |\n|---|---|---|\n| [bsr_rank](ana-20261028-competitor-kpi-lineage.md:1) | 正整数，名次；绑定同站点、同品类、同商品层级与时间 | 商品页或获准数据接口；无排名为缺失，不能设为 0 |\n| [search_volume](ana-20261028-competitor-kpi-lineage.md:1) | 非负整数，次/日；同查询集合、区域和服务商口径 | 搜索分析接口；服务商估计须标记；0–100 热度指数不能混作次数 |\n| [price_current](ana-20261028-competitor-kpi-lineage.md:1) | USD/件；有效折扣后商品价格，不含销售税与买家运费；本版假设买家免运费 | 详情页或报价接口；不同报价、优惠和税基不得混接 |\n| [price_history_90d](ana-20261028-competitor-kpi-lineage.md:1) | 日期与 USD/件；观察日前 90 个自然日内每天至多一笔可比价 | 价格历史接口或自存快照；空列表表示未取得历史，不表示价格为零 |\n| [review_count](ana-20261028-competitor-kpi-lineage.md:1) | 非负整数，条；区分父体共享和单变体口径 | 评论摘要；须与竞争样本的商品层级一致 |\n| [rating_score](ana-20261028-competitor-kpi-lineage.md:1) | 1–5 星，有限数；无评论允许缺失 | 评论摘要；禁止把未知评分写成 0 星 |\n| [listing_age_days](ana-20261028-competitor-kpi-lineage.md:1) | 非负整数，日；参考同站点上线日期 | 可验证上架日期；首次被采集不能冒充上架日期 |\n| [package_dimensions](ana-20261028-competitor-kpi-lineage.md:1) | 三个正数及 cm/in；单个可售件的包装尺寸，非裸机尺寸 | 包装规格或供应商测量；保留原顺序，在 L2 排序 |\n| [shipping_weight](ana-20261028-competitor-kpi-lineage.md:1) | 正数及 kg/lb；单个包装件实际重量，不是计费重 | 包装规格或实测；净重与计费重不得覆盖此字段 |\n| [is_oversize](ana-20261028-competitor-kpi-lineage.md:1) | 严格布尔或缺失；表示上游报告的分级 | 平台或服务商分级；未知不能默认否；与政策计算冲突时复核 |\n| [seller_type](ana-20261028-competitor-kpi-lineage.md:1) | 自营、第三方 FBA、第三方 FBM、未知四类 | 卖家与履约信息；FBA 不等于平台自营，也不代表 Buy Box 归属 |\n\n### 2.1 必需的溯源信封\n\n信封不计入 11 个业务字段：商品与快照标识、站点、品类、UTC 观察时间、币种、报价口径，以及每个字段的来源定位和采集状态。来源应能定位原始响应或授权导出，不要求绕过权限保存网页。\n\n- 状态分为观测、服务商估计、缺失；缺失须带原因。\n- 快照主键为站点、品类、商品标识、观察时间；保存不可变快照及实际计算输入清单。\n- 历史价格保持同一报价和变体口径；排名序列不能跨品类拼接。\n- 评论语义抽取版本、方面词典、输入摘要和证据片段独立保存；隐私字段不进入分析工件。\n\n### 2.2 六指标的附属原始数据闭包\n\n这些输入仍属于 L1 附属数据或显式参数，不能伪装成仅由 11 字段推导的特征。\n\n| 补充输入 | 来源要求 | 缺失时受阻的指标 |\n|---|---|---|\n| 同品类销售锚点、时间周期、模型版本及验证残差 | 获准订单账或可核验销量标定集；服务商模型标明估算属性 | 帕累托销量估算 |\n| 同品类 BSR 最靠前的 10 个可比、去重商品及样本清单 | 完整定义竞争样本域与采样时间；不足 10 个不得替代 | 市场阻力 |\n| 连续 60 个自然日同口径搜索观测、当天和 7 天前排名 | 历史快照或获准历史接口；不得重复月度估计冒充日序列 | 需求动量 |\n| 采购、关税、头程、履约、佣金、广告、仓储、退款损失、合规摊销、汇兑、资金及管理分摊成本 | 自有供应链报价、费表和预算；明确有效期、税基、数量与币种 | 净利率及物流红线 |\n| 承运商体积重除数、线路、日期和物流报价 | 获准费率或报价；除数不得硬编码成全球常量 | 计费货值重量比 |\n| 去重的 2–3 星评论、评论标识、原文与负面方面证据 | 获准评论接口或导出；明确采样窗口和偏差 | 差评缺陷密度 |\n| 若要求合规结论：适用标准、认证、知识产权及改款成本证据 | 可验证证书、法律或供应链审查；不是详情页自称认证 | 人工立项审批；无证不得自动放行 |\n\n## 3. 指标血缘 DAG 拓扑映射表\n\n### 3.1 有向无环图与数学口径\n\n拓扑：L1 商品快照/附属原始数据 + 版本化参数 → L2 单位统一、样本对齐、成本聚合、证据标签 → L3 六项算子 → 非补偿性门禁 → 候选裁决。\n\n- L3 不反向修改 L1；当期裁决不回填为当期销量锚点，防止标签泄漏。\n- 排名 R 无量纲；P 为 USD/件；W 为 kg/件；V 为 cm³/件；D 为 cm³/kg。销量数值统一为件/日，α 与此周期绑定。\n- 空值传播到受影响指标，并附理由；不使用任意极小数掩盖零分母，也不将无样本误判为零风险。\n\n| L3 指标名称 | 业务意义 | 依赖 L2 清洗特征 | 溯源 L1 物理字段 | 确定性数学公式 (LaTeX) | 决策门禁红线 (Hard Gates) | 文献/专著出处 |\n|---|---|---|---|---|---|---|\n| 帕累托销量反推：估算而非真实销售账 | 估计同品类需求规模 | 可比排名 R、已标定 α/β、标定版本 | 排名；附属销量锚点与品类/时间信封 | $\\widehat S=\\exp(\\alpha-\\beta\\ln R)$ | R>0；无标定不输出绝对销量；β∈[0.8,1.2] 为本版先验，越界阻塞并重标定 | Chevalier & Goolsbee 原始研究支持秩转换背景。[6](cite:6) 区间及跨品类应用未核实 |\n| 市场阻力指数 [KQI_barrier](ana-20261028-competitor-kpi-lineage.md:1) | 评论积累壁垒代理，不是市场份额 | 同域 Top 10 评论均值、政策阈值 T | 10 个商品的评论数、排名及样本信封 | $\\bar C=\\frac1{10}\\sum_{i=1}^{10}C_i,\\quad K=\\bar C/T$ | 恰好 10 个可比去重商品；T>0；仅 K<1 通过，K=1 拒绝 | 用户《Product Research 101》摘录；公式为本规范提案，书目纠偏见 §1.2 |\n| 需求动量 [KPI_velocity](ana-20261028-competitor-kpi-lineage.md:1) | 需求与排名改善的联合代理 | 相邻 30 日搜索总量、7 日排名、90 日价格中位数、年龄 | 搜索量、排名、价格历史、现价、年龄；附属历史序列 | $g_S=(S_{30,r}-S_{30,p})/S_{30,p};\\ g_R=(R_{t-7}-R_t)/R_{t-7};\\ M=0.5g_S+0.5g_R$ | 前窗搜索>0；窗口完整；本版要求 gS>0、gR>0、M≥0.10；年龄<60日或价格较历史中位数下降≥15%转复核 | 用户 Fisher/Raman 早期信号、Thomson/Hansen 飞轮摘录；30/7 日及权重为提案，非已知平台算法 |\n| 单品经济学净利率 [Net_Margin](ana-20261028-competitor-kpi-lineage.md:1) | 拟售自有商品的预期全成本单位利润，不是竞品真实利润 | 可比净售价 P、完整单位成本 C | 现价；附属自有成本与费率、报价信封 | $N=(P-C)/P;\\quad C=\\sum_j C_j$ | P>0；成本不可缺项或混币；基准 N≥20%，全部成本增加20%的压力情景 N≥10% | 用户 Fisher/Raman 成本与损失纪律；净利公式、20%/10% 为本版政策 |\n| 计费货值重量比 [Value_to_Weight](ana-20261028-competitor-kpi-lineage.md:1)；附带真正的货值体积比 | 防止轻抛货的物流吞利；名字不能混淆重量与体积 | 排序包装尺寸、实际重、计费重、物流单位成本 | 包装尺寸、重量、现价、上游超规格；附属承运商 D 与物流报价 | $W_b=\\max(W,V/D);\\ Q_w=P/W_b;\\ Q_v=P/(V/1000);\\ F=C_{log}/P$ | W,V,D,P>0；按用户政策尺寸各轴严格小于18/14/8英寸，重<20磅；上游超规格冲突转复核；本版物流占价 F≤20% | 用户初筛摘录；体积重、两个比值与物流红线为独立工程政策，不冒充书中公式 |\n| 差评物理缺陷密度 [Review_Defect_Density](ana-20261028-competitor-kpi-lineage.md:1) | 定位可改款缺陷，不是真实退货率 | 2–3 星去重评论数 N、负面物理方面计数 A、证据标签 | 附属评论正文/星级/标识；商品评分与评论数仅作采样背景，不能代替正文 | $D_f=A/N$ | N>0；证据与评论逐条绑定；建议 N≥30 后进入机会筛选；密度≥0.5仅触发人工改款评审，不直接通过采购 | 用户 Hu & Liu 方面挖掘机理；密度公式与阈值为本规范定义，非原论文已核实判据 |\n\n### 3.2 门禁参数与重要边界\n\n- 初筛售价为 $20–$70，含端点；包装三边先由大到小排序，严格小于用户的三轴上限。等于任一上限即不通过；重量等于 20 磅也不通过。\n- 评论阻力阈值 T 的演示值为 500 条；只是提案。运营批准并记录品类阈值前，不把演示值用于真实立项。\n- 动量权重 0.5/0.5 固定在本版本。价格历史至少覆盖此前 90 日的 72 日才允许执行折扣混杂检查；未覆盖时为证据不足。搜索窗口使用此前完整 60 日，当日尚未完成的搜索不计入。\n- 物流比值没有通用品类最低值；没有经批准的比值底线时仅排序。物流占售价与净利压力情景才是本版本经济性门禁。\n- 2–3 星样本包括窗口内全部合格评论；分子只计负面物理方面，物流与客服问题不进入分子。同一评论同一标准方面重复提及计一次；不同方面可各计一次。因此密度可大于 1，不能施加上界 1。\n- Buy Box 状态不是卖家类型；11 字段不足以观测其变化。未取得 Buy Box 时间序列时不生成所谓算法权重衰减。\n- 评分和上架年龄不是销量替代变量；低评分不单独否决可修复机会，高评分不豁免合规或利润门禁。\n\n### 3.3 经典机理的保留扩展：缺数据则停用\n\n| 扩展算子 | 提案公式与业务用途 | 尚缺的原始输入 | 当前状态及归属 |\n|---|---|---|---|\n| 品类穿透率 | $P_c=B_c/B_{all}$；观察品类买家占比 | 同周期品类独立买家数与全域独立买家数 | 停用；用户 Cox 摘录。不是评论数占比 |\n| 价格交叉弹性 | $\\epsilon_{ij}=\\partial\\ln Q_i/\\partial\\ln P_j$；观察替代与互补 | 双商品价格/销量面板、促销及供给控制变量 | 停用；用户 Cox 摘录。价格共变不能冒充因果弹性 |\n| 库存损失 | $L(q)=C_u\\,E[(D-q)^+]+C_o\\,E[(q-D)^+]$ | 需求分布、缺货机会成本与滞销折价成本 | 停用；用户 Fisher/Raman 损失平衡机理；本公式为标准化建模提案 |\n| GEO 事实完整性审查 | $G=\\sum_j w_j e_j/\\sum_j w_j$；e 为字段证据是否充分 | 应有事实清单、证据、场景与审查权重 | 仅未来审查提案；不是 Bagga 已公布的推荐概率模型 |\n\n## 4. 数据契约定义\n\n### 4.1 契约职责\n\n下列为 Pydantic V2 的完整、内嵌契约示例，尚未创建生产模块，也未运行。正文中 [ProductL1RawRecord](ana-20261028-competitor-kpi-lineage.md:1)、[ProductL2CleanedFeature](ana-20261028-competitor-kpi-lineage.md:1) 与 [ProductL3DecisionMetrics](ana-20261028-competitor-kpi-lineage.md:1) 分别表示观测、清洗特征和决策输出。\n\n- 所有对象拒绝未知字段和非法类型；拒绝非有限数值。所有物理量都绑定单位字段或明确的字段单位后缀。\n- 在 Python 对象入口，日期与时间须为对应对象；JSON 入口使用 ISO 日期/带时区时间。禁止适配器随意把布尔值或数字字符串转成指标。\n- L1 的 11 字段全部要求出现，但允许显式缺失；来源状态须与值一致。L2 特征为可空且必须出现，未算出的值必须带阻塞说明。\n- 数值示例使用有限浮点数；数学结果以规定误差复核。真实财务结算不是本契约职责，下游成本台账应使用十进制定点并显式规定换算与舍入。\n- 契约检查形状、范围和一致性，不证明采集来源真实，也不替代公式复算、跨层关联及门禁测试。\n\n```python\nfrom datetime import date, timedelta\nfrom typing import Annotated, Literal\n\nfrom pydantic import (\n AwareDatetime, BaseModel, ConfigDict, Field,\n StrictBool, StrictFloat, StrictInt, StrictStr, model_validator,\n)\n\nText = Annotated[StrictStr, Field(min_length=1)]\nCount = Annotated[StrictInt, Field(ge=0)]\nRank = Annotated[StrictInt, Field(ge=1)]\nFinite = Annotated[StrictFloat, Field(allow_inf_nan=False)]\nPositive = Annotated[StrictFloat, Field(gt=0, allow_inf_nan=False)]\nNonNegative = Annotated[StrictFloat, Field(ge=0, allow_inf_nan=False)]\nRating = Annotated[StrictFloat, Field(ge=1, le=5, allow_inf_nan=False)]\n\n\nclass Contract(BaseModel):\n model_config = ConfigDict(\n strict=True, extra=\"forbid\", frozen=True, allow_inf_nan=False,\n )\n\n\nclass Provenance(Contract):\n status: Literal[\"observed\", \"estimated\", \"missing\"]\n source_ref: Text\n collected_at: AwareDatetime\n missing_reason: Text | None = Field(description=\"缺失时必填\")\n\n @model_validator(mode=\"after\")\n def check_reason(self):\n if (self.status == \"missing\") != (self.missing_reason is not None):\n raise ValueError(\"missing_reason 必须与缺失状态一致\")\n return self\n\n\nclass Dimensions(Contract):\n values: tuple[Positive, Positive, Positive]\n unit: Literal[\"cm\", \"in\"]\n\n\nclass Weight(Contract):\n value: Positive\n unit: Literal[\"kg\", \"lb\"]\n\n\nclass PricePoint(Contract):\n day: date\n value: Positive = Field(description=\"USD/件；与现价相同报价口径\")\n\n\nclass ProductL1RawRecord(Contract):\n schema_version: Literal[\"1.0\"]\n snapshot_id: Text\n product_id: Text\n marketplace: Literal[\"amazon_us\"]\n category_id: Text\n observed_at: AwareDatetime\n currency: Literal[\"USD\"]\n price_basis: Literal[\"discounted_item_ex_sales_tax_free_shipping\"]\n bsr_rank: Rank | None\n search_volume: Count | None = Field(description=\"同查询集合，次/日\")\n price_current: Positive | None = Field(description=\"USD/件\")\n price_history_90d: tuple[PricePoint, ...] = Field(max_length=90)\n review_count: Count | None\n rating_score: Rating | None\n listing_age_days: Count | None = Field(description=\"日\")\n package_dimensions: Dimensions | None\n shipping_weight: Weight | None\n is_oversize: StrictBool | None\n seller_type: Literal[\"amazon_retail\", \"third_party_fba\",\n \"third_party_fbm\", \"unknown\"]\n provenance: dict[Text, Provenance] = Field(min_length=11, max_length=11)\n\n @model_validator(mode=\"after\")\n def check_snapshot(self):\n names = {\n \"bsr_rank\", \"search_volume\", \"price_current\", \"price_history_90d\",\n \"review_count\", \"rating_score\", \"listing_age_days\",\n \"package_dimensions\", \"shipping_weight\", \"is_oversize\", \"seller_type\",\n }\n if set(self.provenance) != names:\n raise ValueError(\"11 个字段必须分别提供来源\")\n for name in names:\n value = getattr(self, name)\n missing = value is None\n if name == \"price_history_90d\":\n missing = len(value) == 0\n if name == \"seller_type\":\n missing = value == \"unknown\"\n if (self.provenance[name].status == \"missing\") != missing:\n raise ValueError(\"值与来源状态冲突: \" + name)\n days = [p.day for p in self.price_history_90d]\n today = self.observed_at.date()\n if days != sorted(set(days)):\n raise ValueError(\"价格历史必须按日升序且不重复\")\n if any(not today - timedelta(days=90) <= d < today for d in days):\n raise ValueError(\"价格历史超出此前 90 日窗口\")\n return self\n\n\nclass SalesCalibration(Contract):\n category_id: Text\n model_id: Text\n source_ref: Text\n valid_through: date\n sales_unit: Literal[\"units_per_day\"]\n alpha: Finite\n beta: Annotated[StrictFloat, Field(ge=0.8, le=1.2, allow_inf_nan=False)]\n holdout_mape: NonNegative = Field(description=\"比例，不是百分数\")\n holdout_n: Annotated[StrictInt, Field(ge=1)]\n\n\nclass LogisticsRule(Contract):\n source_ref: Text\n valid_through: date\n divisor: Positive\n divisor_unit: Literal[\"cm3_per_kg\"]\n\n\nclass UnitCostBundle(Contract):\n source_ref: Text\n valid_through: date\n currency: Literal[\"USD\"]\n unit: Literal[\"USD_per_unit\"]\n cogs: NonNegative\n duties: NonNegative\n inbound: NonNegative\n fulfillment: NonNegative\n referral: NonNegative\n advertising: NonNegative\n storage: NonNegative\n returns_loss: NonNegative\n compliance: NonNegative\n fx_loss: NonNegative\n financing: NonNegative\n allocated_overhead: NonNegative\n other: NonNegative\n\n\nclass ProductL2CleanedFeature(Contract):\n schema_version: Literal[\"1.0\"]\n feature_id: Text\n product_id: Text\n category_id: Text\n as_of: AwareDatetime\n raw_snapshot_refs: tuple[Text, ...] = Field(min_length=1)\n auxiliary_evidence_refs: tuple[Text, ...]\n transform_version: Text\n blocked_reasons: tuple[Text, ...]\n bsr_current: Rank | None\n bsr_day_minus_7: Rank | None\n search_recent_30d: Count | None\n search_previous_30d: Count | None\n complete_search_days: Annotated[StrictInt, Field(ge=0, le=60)]\n price_usd: Positive | None\n price_median_90d_usd: Positive | None\n valid_price_days: Annotated[StrictInt, Field(ge=0, le=90)]\n top10_review_counts: tuple[Count, ...] = Field(min_length=0, max_length=10)\n cohort_product_ids: tuple[Text, ...] = Field(min_length=0, max_length=10)\n listing_age_days: Count | None\n package_dimensions_cm: tuple[Positive, Positive, Positive] | None\n package_volume_cm3: Positive | None\n actual_weight_kg: Positive | None\n billed_weight_kg: Positive | None\n source_is_oversize: StrictBool | None\n policy_standard_size: StrictBool | None\n seller_type: Literal[\"amazon_retail\", \"third_party_fba\",\n \"third_party_fbm\", \"unknown\"]\n critical_reviews_n: Count | None\n negative_physical_aspects_n: Count | None\n aspect_evidence_refs: tuple[Text, ...]\n total_unit_cost_usd: NonNegative | None\n logistics_unit_cost_usd: NonNegative | None\n calibration: SalesCalibration | None\n logistics_rule: LogisticsRule | None\n costs: UnitCostBundle | None\n\n @model_validator(mode=\"after\")\n def check_consistency(self):\n if self.package_dimensions_cm is not None:\n a, b, c = self.package_dimensions_cm\n if not a >= b >= c:\n raise ValueError(\"L2 三边必须按长、中、短排序\")\n if len(self.top10_review_counts) != len(self.cohort_product_ids):\n raise ValueError(\"竞争样本标识与评论计数长度不符\")\n if len(set(self.cohort_product_ids)) != len(self.cohort_product_ids):\n raise ValueError(\"竞争样本商品必须去重\")\n if self.calibration is not None and self.calibration.category_id != self.category_id:\n raise ValueError(\"销量标定品类不符\")\n if self.billed_weight_kg is not None:\n if self.actual_weight_kg is None or self.billed_weight_kg < self.actual_weight_kg:\n raise ValueError(\"计费重不能小于实际重\")\n if self.negative_physical_aspects_n not in (None, 0) and not self.aspect_evidence_refs:\n raise ValueError(\"负面物理方面必须有证据\")\n return self\n\n\nclass GateResult(Contract):\n gate_id: Text\n status: Literal[\"pass\", \"reject\", \"insufficient\", \"review\"]\n reasons: tuple[Text, ...] = Field(min_length=1)\n evidence_refs: tuple[Text, ...]\n\n\nclass ProductL3DecisionMetrics(Contract):\n schema_version: Literal[\"1.0\"]\n feature_ref: Text\n policy_ref: Text\n operator_version: Text\n sales_estimated_units_per_day: NonNegative | None\n kqi_barrier: NonNegative | None\n kpi_velocity: Finite | None\n net_margin: Annotated[StrictFloat, Field(le=1, allow_inf_nan=False)] | None\n value_to_weight_usd_per_kg: Positive | None\n value_to_volume_usd_per_litre: Positive | None\n review_defect_density: NonNegative | None\n gates: tuple[GateResult, ...] = Field(min_length=1)\n decision: Literal[\"candidate_pass\", \"reject\", \"insufficient\", \"review\"]\n\n @model_validator(mode=\"after\")\n def check_decision(self):\n ids = [g.gate_id for g in self.gates]\n if len(ids) != len(set(ids)):\n raise ValueError(\"门禁标识不得重复\")\n statuses = {g.status for g in self.gates}\n expected = (\n \"reject\" if \"reject\" in statuses else\n \"insufficient\" if \"insufficient\" in statuses else\n \"review\" if \"review\" in statuses else \"candidate_pass\"\n )\n if self.decision != expected:\n raise ValueError(\"裁决与非补偿性门禁不一致\")\n metrics = (\n self.sales_estimated_units_per_day, self.kqi_barrier,\n self.kpi_velocity, self.net_margin, self.value_to_weight_usd_per_kg,\n self.value_to_volume_usd_per_litre, self.review_defect_density,\n )\n if self.decision == \"candidate_pass\" and any(v is None for v in metrics):\n raise ValueError(\"核心指标缺失时不得候选通过\")\n return self\n```\n\n### 4.2 下游必须补齐的关联与复算约束\n\n这些不是上述局部模型已经实现的防护；下游必须单独实现并验证。\n\n1. 校验 L2 引用的全部快照归属同商品或声明的竞争样本、同站点、同品类和同报价；观察时间、窗口截止时间与 UTC 口径一致。\n2. 成本包、承运商规则及销量标定未过期；来源不可空且不得使用未来订单标定历史裁决。完整成本包必须逐项出现，0 必须代表明确不适用，而不是未知。\n3. 复算尺寸、体积、计费重、成本总和及物流成本；换算常量为 1 in = 2.54 cm、1 lb = 0.45359237 kg。物流成本定义为头程加履约配送，本版其余成本不得计入或重复计入。\n4. 复算六项 L3 值，禁止接受外部传入的自称通过结果；极端指数上溢、下溢为计算阻塞，不截断成虚假安全值。\n5. 必需门禁集合包含数据完整性、售价、规格、销售标定、竞争阻力、动量、净利及压力情景、物流、评论证据；只有“有一项通过”不足以候选通过。人工合规与改款评审保留在采购前独立审批。\n6. 每个不可用指标须生成对应证据不足门禁；其他明确失败仍保留，裁决优先级为拒绝 > 证据不足 > 人工复核 > 候选通过，不丢失全部原因。\n7. “冻结”模型不等于深度不可变存储；来源映射与嵌套容器必须在持久化时生成实际内容摘要，保存算子、规则及标注版本。当前没有声称存在该控制器。\n\n## 5. BMAD-Engineer 实施单测背压规范\n\n本节定义未来验收要求，不授权当前执行。测试资产尚未创建；静态契约尚未运行、导入或通过测试。\n\n### 5.1 单测与标定验收矩阵\n\n| 编号 | 用例/输入 | 必须断言的结果 | 验证类型 |\n|---|---|---|---|\n| C01 | 排名=0/-1/布尔；价格=0；数字字符串；NaN/±∞；未知字段；缺失一个业务键 | 契约拒绝，不能静默转换或补零 | 契约单测 |\n| C02 | 搜索=0、评论数=0、年龄=0；未知评分；来源状态与值冲突 | 合法零值接受；未知评分不是0；状态冲突拒绝 | 契约单测 |\n| C03 | 历史价格重复日期、逆序、超过90日、当日未完成记录 | 拒绝；空历史可保存但不能通过价格稳定性门禁 | 窗口单测 |\n| S01 | α=ln(10000)、β=1、R=100/1000/10000 | 分别为100/10/1件每日；相对误差≤1e-9；不是实测销量 | 数学单测 |\n| S02 | β=0.8/1.2 与0.79/1.21；未知 α；跨品类/过期标定 | 端点合法；越界、缺标定或不匹配阻塞绝对销量 | 参数与关联单测 |\n| S03 | 无噪声合成数据覆盖至少3个数量级的秩 | α/β拟合绝对误差≤1e-6；按时间切分防泄漏 | 合成拟合单测 |\n| S04 | 独立、可核验真实销量留出集，不使用本模型估值充当标签 | 本版建议n≥30、MAPE≤20%；真实零销量单独报告MAE，不能零除或剔除后宣称全样本通过 | 工程阶段标定验收，非当前实测 |\n| S05 | 极端α/R导致指数上溢或下溢 | 记录计算阻塞；不返回∞、0或饱和值冒充有效估算 | 数值边界单测 |\n| B01 | Top10均值499/500/501，演示T=500 | K为0.998/1/1.002；仅第一组通过 | 阈值单测 |\n| B02 | 样本仅9个、重复父体、品类混接或T=0 | 证据不足或参数拒绝；不补虚拟第10个样本 | 样本与零除单测 |\n| V01 | 搜索前窗1000、后窗1300，排名1000→800 | gS=0.3、gR=0.2、M=0.25；较小BSR代表改善 | 数学单测 |\n| V02 | 前窗搜索=0、缺1日、缺7日前排名；搜索下降但排名改善 | 前三者证据不足；最后不得用加权总分掩盖搜索硬门禁失败 | 零除与非补偿单测 |\n| V03 | 年龄59/60日；价格历史71/72日；现价比中位数下降恰好15% | 59日复核；72日满足覆盖门槛；下降15%进入折扣混杂复核 | 窗口边界单测 |\n| M01 | 售价40，总单位成本30，其中头程2、履约5 | 净利25%；物流占价17.5%；成本增加20%后净利10%，压力端点通过 | 单位经济学单测 |\n| M02 | 费用一项缺失、佣金重复、混币、税基不符、过期报价；售价0 | 缺项或口径冲突阻塞；拒绝零价；不得从卖家类型补费用 | 成本闭包与零除单测 |\n| M03 | 基准净利19.999%/20%；成本高于售价 | 精确政策端点比较；前者拒绝；负利润保留，不裁剪为0 | 门禁边界单测 |\n| W01 | 未排序包装8/18/14英寸；20磅 | L2排序为18/14/8；等于任一尺寸/重量上限不通过 | 换算与严格边界单测 |\n| W02 | 包装45×35×20cm、实际重0.2kg、D=5000cm³/kg、价40、物流15.75 | V=31500cm³；计费重6.3kg；Qw≈6.349206USD/kg；Qv≈1.269841USD/L；物流占价39.375%，拒绝。即使初筛尺寸合格也不得抵消经济失败 | 极端轻抛货单测 |\n| W03 | 同W02，D改6000；D=0；单位缺失；尺寸/重量为0 | D=6000时计费重5.25kg、Qw≈7.619048；其他非法输入拒绝，禁止沿用5000 | 费率版本与零除单测 |\n| W04 | 上游超规格报告与按政策尺寸计算冲突 | 保留两份事实并进入复核，不覆盖上游原始值 | 溯源冲突单测 |\n| R01 | 10条2–3星去重评论、12个负面物理方面 | 密度1.2合法；同评论同方面重复不增计；客服方面不进分子 | 聚合单测 |\n| R02 | 无评论；有评论但无物理方面；评论证据断链；抽样<30 | 依次为证据不足、密度0、拒绝证据、不足以机会放行；0与缺失严格区分 | 零除与证据单测 |\n| R03 | 真实人工标注集与固定抽取版本 | 建议抽检100条，不足则全量；负面物理方面precision/recall分别≥90%；统计在固定标签上逐项一致；未通过不得伪装为低缺陷 | 工程阶段抽取验收 |\n| G01 | 所有分数优秀但一个规格失败；门禁漏项；传入伪造L3值 | 第一组拒绝；漏项不能通过；外部值必须经L2复算核对 | 决策与关联单测 |\n| G02 | 同时拒绝、缺证据、需复核；固定输入和版本重复运行 | 按拒绝优先裁决并保留全部原因；纯算子重复结果一致，原始证据不变 | 组合与复现单测 |\n\n数学单测一般使用相对误差 1e-9、绝对误差 1e-12；合成拟合另用表中容差。政策端点不得借数值容差放宽，财务台账按获准舍入规则做十进制比较。真实标定与语义验收是不同门禁，合成测试通过不能证明两者已通过。\n\n### 5.2 下游顺序与证据要求\n\n1. 先建立获授权的工程实例，确认政策参数、数据授权、依赖版本和测试路径；不继承本工件的任何“绿灯”。\n2. 创建契约、纯算子与相关测试资产；先验证输入闭包，再验证数学和门禁，不附加无关业务单测或全站抓取。\n3. 单独取得标定集和人工标注集，明确输出为估算；销量标定或方面抽取不达标时保留阻塞。\n4. 保存真实命令、工作目录、目标、退出状态与关键输出；失败、超时、缺依赖或缺证据即暂停受影响交付。\n\n拟执行验证命令：尚未绑定。测试模块、依赖锁定和目标路径尚不存在，当前不捏造可执行文件名或声称命令可用；下游须在获准工程阶段补齐并使用串行、前台、非交互、进程级有界超时执行。\n\n### 5.3 证据索引与交付边界\n\n- [6](cite:6) Chevalier & Goolsbee，2003，《Measuring Prices and Price Competition Online: Amazon and Barnes and Noble》；本次检索返回原论文来源，支撑原始研究对象与秩转换背景，不支撑所有用户系数断言。\n- [10](cite:10) 《Product Research 101》公开商品书目，ISBN 9781537483733；作者 Renae Clark。作者纠偏有书目支持，具体筛选阈值尚未核实。[10](cite:10)\n- 本地 [bcec-gem.md](_scratch/bcec-gem.md:155)，重点为155–173行的逐条证据打标与确定性聚合主张；它是历史对话草稿，不是已接受项目事实。\n- 本地 [geo-2024.md](_scratch/geo-2024.md:35)，35–49行摘要与出版信息；“最高约40%”指生成式回答可见性。\n- 本地 [geo-2026.md](_scratch/geo-2026.md:64)，64–88行的重排序研究范围、220行的平均排名指标、371–386行的事实保真与结构化特征；本地副本不等于已核验线上发布或生产效果。\n- 用户专著摘录：Fisher/Raman《The New Science of Retailing》、Cox《Retail Analytics: The Secret Weapon》、Thomson/Hansen《The Amazon Marketplace Dilemma》以及 Hu & Liu 方面挖掘机理。本次没有原书页码或论文全文证据，不为其新增原文引语、精确权重或页码。\n\n交付结论：已形成可供下游审阅的血缘与契约提案；11 字段之外的必要输入被显式暴露，六项核心指标均有公式、边界和背压用例。该结论属于静态架构分析，不代表采集、计算、测试、实施、采购或部署已经完成。\n"}}

{"name":"write_to_file","arguments":{"path":"_bmad-output/analysis/ana-20261028-competitor-kpi-lineage.md","content":"# 跨境电商竞品分析：L1 数据采集 ➔ L3 决策算子血缘拓扑规范\n\n采用“可溯源观测 ➔ 单位与口径统一 ➔ 可复算算子 ➔ 非补偿性门禁”，替代盲目跟卖和模型凭感觉选品。11 个商品字段是最低采集面，而不是六项决策指标的充分输入：销量标定、成本、历史序列、竞争样本和差评原文必须补齐，否则对应指标不得给出通过结论。\n\n- 工件标识：ANA-20261028-COMPETITOR-LINEAGE；版本：1.0；状态：PROPOSED。\n- 授权：仅创建本分析工件；不授权生产实现、终端运行、测试执行、ADR 转正或计划归档。\n- 场景：structural；会话标识：null；日期：2026-10-28。\n- 默认分析口径：Amazon 美国站、USD、单件可比商品；其他平台和国家须重新配置币种、税费、尺寸分级及物流规则。\n- 当前工作区根目录回执仅列出草稿目录；未发现项目事实基线、已接受 ADR 或活动计划入口。不把草稿中的历史提案绑定为当前执行计划，也不创建或覆盖活动计划。\n\n## 1. 顶层战略裁决\n\n### 1.1 目标、约束与非目标\n\n目标：每个立项结论均能回到商品、时间、品类、采集来源、规则版本以及具体成本或评论证据；物理限制和单品经济学优先于需求分数。\n\n- L1 保存原始观测及来源，区分平台显示值、服务商估计值和缺失值；“原始”不等于“真实销量”。\n- L2 只做可审计清洗、单位换算、窗口对齐和带证据的语义标注；禁止凭模型补齐未知重量、成本或销量。\n- L3 对固定输入与版本化参数进行确定性计算；确定性不能消除上游测量误差或语义模型的不确定性。\n- 不允许一个高需求分数抵消超规格、亏损、缺证据或未解决的合规风险。\n\n非目标：\n\n1. 不建设全平台爬虫、代理池或绕过访问控制。\n2. 不自动下单、跟卖、发布文案、采购或调整广告。\n3. 不把 BSR 估算包装为真实销售账，也不从差评密度推断真实退货率。\n4. 不训练专有模型，不编造平台推荐权重，不进行运行时验证或部署。\n\n### 1.2 证据裁决与输入纠偏\n\n- 本地资料明确提出：模型逐条打标并保留评论证据，再由确定性程序聚合；这支持职责分离，但不证明资料中的商业效果数字。\n- 本地 E-GEO 文本研究固定候选集上的 LLM 重排序，使用平均排名改善，而非 Rufus 生产推荐率；其原文强调事实保真，不支持将“结构化事实可信度”当作已经公开的精确平台权重。\n- “最高约 40% 可见性改善”可定位到本地 2024 GEO 摘要，其对象是生成式回答中的可见性，不等同于 2026 电商被推荐率提升 40% 以上。\n- “2026 超过 60% 零点击”、指定参数对推荐率的独立因果作用及 Buy Box 丢失后的算法权重衰减，现有原始证据不足：Insufficient evidence。它们不进入公式或硬门禁。\n- 《Product Research 101: Find Winning Products to Sell on Amazon and Beyond》的公开书目作者为 Renae Clark，而非用户输入中的 Rena Govindarajan。[10](cite:10) $20–$70、18×14×8 英寸及 20 磅在本工件中保留为用户指定的初筛政策，不声称已核实出自该书，也不宣称是 2026 官方尺寸分级。\n- Chevalier 与 Goolsbee 的原始研究涉及 Amazon 与 Barnes and Noble 的在线图书需求及销量秩转换；不能据此保证全品类共用一个系数。[6](cite:6) 本规范将用户给出的 β 区间视为待标定先验。\n- 下文的市场阻力、需求动量权重、利润底线及抽样要求均为版本化提案，不冒充专著原公式或实测结果。\n\n### 1.3 三遍解构与收敛结论\n\n1. 基线扫描：11 字段覆盖排名、需求估计、价格、口碑、年龄和包装；缺成本、评论文本、销售锚点、历史排名以及合规证据。\n2. 因果检查：评论多不必然形成壁垒；BSR 上升可能来自折扣或供给变化；差评集中不等于改款必然赚钱。\n3. 虚拟重实现：补齐输入闭包、拒绝缺失值伪零、保持估算标签、检测收费体积重后，方案可行；停止增加不必要的实时代理和黑箱评分组件。\n\n立项只输出“候选通过”“拒绝”“证据不足”“需人工复核”。候选通过仅表示所配置筛选门禁通过，不是采购授权或合规认证。\n\n## 2. L1 物理事实采集清单\n\n以下严格保留 11 个业务字段；表中的采集来源是接口适配要求，并不表示本次已抓取真实商品。\n\n| 最小字段 | 单位与严格口径 | 采集来源与缺失处理 |\n|---|---|---|\n| [bsr_rank](ana-20261028-competitor-kpi-lineage.md:1) | 正整数，名次；绑定同站点、同品类、同商品层级与时间 | 商品页或获准数据接口；无排名为缺失，不能设为 0 |\n| [search_volume](ana-20261028-competitor-kpi-lineage.md:1) | 非负整数，次/日；同查询集合、区域和服务商口径 | 搜索分析接口；服务商估计须标记；0–100 热度指数不能混作次数 |\n| [price_current](ana-20261028-competitor-kpi-lineage.md:1) | USD/件；有效折扣后商品价格，不含销售税与买家运费；本版假设买家免运费 | 详情页或报价接口；不同报价、优惠和税基不得混接 |\n| [price_history_90d](ana-20261028-competitor-kpi-lineage.md:1) | 日期与 USD/件；观察日前 90 个自然日内每天至多一笔可比价 | 价格历史接口或自存快照；空列表表示未取得历史，不表示价格为零 |\n| [review_count](ana-20261028-competitor-kpi-lineage.md:1) | 非负整数，条；区分父体共享和单变体口径 | 评论摘要；须与竞争样本的商品层级一致 |\n| [rating_score](ana-20261028-competitor-kpi-lineage.md:1) | 1–5 星，有限数；无评论允许缺失 | 评论摘要；禁止把未知评分写成 0 星 |\n| [listing_age_days](ana-20261028-competitor-kpi-lineage.md:1) | 非负整数，日；参考同站点上线日期 | 可验证上架日期；首次被采集不能冒充上架日期 |\n| [package_dimensions](ana-20261028-competitor-kpi-lineage.md:1) | 三个正数及 cm/in；单个可售件的包装尺寸，非裸机尺寸 | 包装规格或供应商测量；保留原顺序，在 L2 排序 |\n| [shipping_weight](ana-20261028-competitor-kpi-lineage.md:1) | 正数及 kg/lb；单个包装件实际重量，不是计费重 | 包装规格或实测；净重与计费重不得覆盖此字段 |\n| [is_oversize](ana-20261028-competitor-kpi-lineage.md:1) | 严格布尔或缺失；表示上游报告的分级 | 平台或服务商分级；未知不能默认否；与政策计算冲突时复核 |\n| [seller_type](ana-20261028-competitor-kpi-lineage.md:1) | 自营、第三方 FBA、第三方 FBM、未知四类 | 卖家与履约信息；FBA 不等于平台自营，也不代表 Buy Box 归属 |\n\n### 2.1 必需的溯源信封\n\n信封不计入 11 个业务字段：商品与快照标识、站点、品类、UTC 观察时间、币种、报价口径，以及每个字段的来源定位和采集状态。来源应能定位原始响应或授权导出，不要求绕过权限保存网页。\n\n- 状态分为观测、服务商估计、缺失；缺失须带原因。\n- 快照主键为站点、品类、商品标识、观察时间；保存不可变快照及实际计算输入清单。\n- 历史价格保持同一报价和变体口径；排名序列不能跨品类拼接。\n- 评论语义抽取版本、方面词典、输入摘要和证据片段独立保存；隐私字段不进入分析工件。\n\n### 2.2 六指标的附属原始数据闭包\n\n这些输入仍属于 L1 附属数据或显式参数，不能伪装成仅由 11 字段推导的特征。\n\n| 补充输入 | 来源要求 | 缺失时受阻的指标 |\n|---|---|---|\n| 同品类销售锚点、时间周期、模型版本及验证残差 | 获准订单账或可核验销量标定集；服务商模型标明估算属性 | 帕累托销量估算 |\n| 同品类 BSR 最靠前的 10 个可比、去重商品及样本清单 | 完整定义竞争样本域与采样时间；不足 10 个不得替代 | 市场阻力 |\n| 连续 60 个自然日同口径搜索观测、当天和 7 天前排名 | 历史快照或获准历史接口；不得重复月度估计冒充日序列 | 需求动量 |\n| 采购、关税、头程、履约、佣金、广告、仓储、退款损失、合规摊销、汇兑、资金及管理分摊成本 | 自有供应链报价、费表和预算；明确有效期、税基、数量与币种 | 净利率及物流红线 |\n| 承运商体积重除数、线路、日期和物流报价 | 获准费率或报价；除数不得硬编码成全球常量 | 计费货值重量比 |\n| 去重的 2–3 星评论、评论标识、原文与负面方面证据 | 获准评论接口或导出；明确采样窗口和偏差 | 差评缺陷密度 |\n| 若要求合规结论：适用标准、认证、知识产权及改款成本证据 | 可验证证书、法律或供应链审查；不是详情页自称认证 | 人工立项审批；无证不得自动放行 |\n\n## 3. 指标血缘 DAG 拓扑映射表\n\n### 3.1 有向无环图与数学口径\n\n拓扑：L1 商品快照/附属原始数据 + 版本化参数 → L2 单位统一、样本对齐、成本聚合、证据标签 → L3 六项算子 → 非补偿性门禁 → 候选裁决。\n\n- L3 不反向修改 L1；当期裁决不回填为当期销量锚点，防止标签泄漏。\n- 排名 R 无量纲；P 为 USD/件；W 为 kg/件；V 为 cm³/件；D 为 cm³/kg。销量数值统一为件/日，α 与此周期绑定。\n- 空值传播到受影响指标，并附理由；不使用任意极小数掩盖零分母，也不将无样本误判为零风险。\n\n| L3 指标名称 | 业务意义 | 依赖 L2 清洗特征 | 溯源 L1 物理字段 | 确定性数学公式 (LaTeX) | 决策门禁红线 (Hard Gates) | 文献/专著出处 |\n|---|---|---|---|---|---|---|\n| 帕累托销量反推：估算而非真实销售账 | 估计同品类需求规模 | 可比排名 R、已标定 α/β、标定版本 | 排名；附属销量锚点与品类/时间信封 | $\\widehat S=\\exp(\\alpha-\\beta\\ln R)$ | R>0；无标定不输出绝对销量；β∈[0.8,1.2] 为本版先验，越界阻塞并重标定 | Chevalier & Goolsbee 原始研究支持秩转换背景。[6](cite:6) 区间及跨品类应用未核实 |\n| 市场阻力指数 [KQI_barrier](ana-20261028-competitor-kpi-lineage.md:1) | 评论积累壁垒代理，不是市场份额 | 同域 Top 10 评论均值、政策阈值 T | 10 个商品的评论数、排名及样本信封 | $\\bar C=\\frac1{10}\\sum_{i=1}^{10}C_i,\\quad K=\\bar C/T$ | 恰好 10 个可比去重商品；T>0；仅 K<1 通过，K=1 拒绝 | 用户《Product Research 101》摘录；公式为本规范提案，书目纠偏见 §1.2 |\n| 需求动量 [KPI_velocity](ana-20261028-competitor-kpi-lineage.md:1) | 需求与排名改善的联合代理 | 相邻 30 日搜索总量、7 日排名、90 日价格中位数、年龄 | 搜索量、排名、价格历史、现价、年龄；附属历史序列 | $g_S=(S_{30,r}-S_{30,p})/S_{30,p};\\ g_R=(R_{t-7}-R_t)/R_{t-7};\\ M=0.5g_S+0.5g_R$ | 前窗搜索>0；窗口完整；本版要求 gS>0、gR>0、M≥0.10；年龄<60日或价格较历史中位数下降≥15%转复核 | 用户 Fisher/Raman 早期信号、Thomson/Hansen 飞轮摘录；30/7 日及权重为提案，非已知平台算法 |\n| 单品经济学净利率 [Net_Margin](ana-20261028-competitor-kpi-lineage.md:1) | 拟售自有商品的预期全成本单位利润，不是竞品真实利润 | 可比净售价 P、完整单位成本 C | 现价；附属自有成本与费率、报价信封 | $N=(P-C)/P;\\quad C=\\sum_j C_j$ | P>0；成本不可缺项或混币；基准 N≥20%，全部成本增加20%的压力情景 N≥10% | 用户 Fisher/Raman 成本与损失纪律；净利公式、20%/10% 为本版政策 |\n| 计费货值重量比 [Value_to_Weight](ana-20261028-competitor-kpi-lineage.md:1)；附带真正的货值体积比 | 防止轻抛货的物流吞利；名字不能混淆重量与体积 | 排序包装尺寸、实际重、计费重、物流单位成本 | 包装尺寸、重量、现价、上游超规格；附属承运商 D 与物流报价 | $W_b=\\max(W,V/D);\\ Q_w=P/W_b;\\ Q_v=P/(V/1000);\\ F=C_{log}/P$ | W,V,D,P>0；按用户政策尺寸各轴严格小于18/14/8英寸，重<20磅；上游超规格冲突转复核；本版物流占价 F≤20% | 用户初筛摘录；体积重、两个比值与物流红线为独立工程政策，不冒充书中公式 |\n| 差评物理缺陷密度 [Review_Defect_Density](ana-20261028-competitor-kpi-lineage.md:1) | 定位可改款缺陷，不是真实退货率 | 2–3 星去重评论数 N、负面物理方面计数 A、证据标签 | 附属评论正文/星级/标识；商品评分与评论数仅作采样背景，不能代替正文 | $D_f=A/N$ | N>0；证据与评论逐条绑定；建议 N≥30 后进入机会筛选；密度≥0.5仅触发人工改款评审，不直接通过采购 | 用户 Hu & Liu 方面挖掘机理；密度公式与阈值为本规范定义，非原论文已核实判据 |\n\n### 3.2 门禁参数与重要边界\n\n- 初筛售价为 $20–$70，含端点；包装三边先由大到小排序，严格小于用户的三轴上限。等于任一上限即不通过；重量等于 20 磅也不通过。\n- 评论阻力阈值 T 的演示值为 500 条；只是提案。运营批准并记录品类阈值前，不把演示值用于真实立项。\n- 动量权重 0.5/0.5 固定在本版本。价格历史至少覆盖此前 90 日的 72 日才允许执行折扣混杂检查；未覆盖时为证据不足。搜索窗口使用此前完整 60 日，当日尚未完成的搜索不计入。\n- 物流比值没有通用品类最低值；没有经批准的比值底线时仅排序。物流占售价与净利压力情景才是本版本经济性门禁。\n- 2–3 星样本包括窗口内全部合格评论；分子只计负面物理方面，物流与客服问题不进入分子。同一评论同一标准方面重复提及计一次；不同方面可各计一次。因此密度可大于 1，不能施加上界 1。\n- Buy Box 状态不是卖家类型；11 字段不足以观测其变化。未取得 Buy Box 时间序列时不生成所谓算法权重衰减。\n- 评分和上架年龄不是销量替代变量；低评分不单独否决可修复机会，高评分不豁免合规或利润门禁。\n\n### 3.3 经典机理的保留扩展：缺数据则停用\n\n| 扩展算子 | 提案公式与业务用途 | 尚缺的原始输入 | 当前状态及归属 |\n|---|---|---|---|\n| 品类穿透率 | $P_c=B_c/B_{all}$；观察品类买家占比 | 同周期品类独立买家数与全域独立买家数 | 停用；用户 Cox 摘录。不是评论数占比 |\n| 价格交叉弹性 | $\\epsilon_{ij}=\\partial\\ln Q_i/\\partial\\ln P_j$；观察替代与互补 | 双商品价格/销量面板、促销及供给控制变量 | 停用；用户 Cox 摘录。价格共变不能冒充因果弹性 |\n| 库存损失 | $L(q)=C_u\\,E[(D-q)^+]+C_o\\,E[(q-D)^+]$ | 需求分布、缺货机会成本与滞销折价成本 | 停用；用户 Fisher/Raman 损失平衡机理；本公式为标准化建模提案 |\n| GEO 事实完整性审查 | $G=\\sum_j w_j e_j/\\sum_j w_j$；e 为字段证据是否充分 | 应有事实清单、证据、场景与审查权重 | 仅未来审查提案；不是 Bagga 已公布的推荐概率模型 |\n\n## 4. 数据契约定义\n\n### 4.1 契约职责\n\n下列为 Pydantic V2 的完整、内嵌契约示例，尚未创建生产模块，也未运行。正文中 [ProductL1RawRecord](ana-20261028-competitor-kpi-lineage.md:1)、[ProductL2CleanedFeature](ana-20261028-competitor-kpi-lineage.md:1) 与 [ProductL3DecisionMetrics](ana-20261028-competitor-kpi-lineage.md:1) 分别表示观测、清洗特征和决策输出。\n\n- 所有对象拒绝未知字段和非法类型；拒绝非有限数值。所有物理量都绑定单位字段或明确的字段单位后缀。\n- 在 Python 对象入口，日期与时间须为对应对象；JSON 入口使用 ISO 日期/带时区时间。禁止适配器随意把布尔值或数字字符串转成指标。\n- L1 的 11 字段全部要求出现，但允许显式缺失；来源状态须与值一致。L2 特征为可空且必须出现，未算出的值必须带阻塞说明。\n- 数值示例使用有限浮点数；数学结果以规定误差复核。真实财务结算不是本契约职责，下游成本台账应使用十进制定点并显式规定换算与舍入。\n- 契约检查形状、范围和一致性，不证明采集来源真实，也不替代公式复算、跨层关联及门禁测试。\n\n```python\nfrom datetime import date, timedelta\nfrom typing import Annotated, Literal\n\nfrom pydantic import (\n AwareDatetime, BaseModel, ConfigDict, Field,\n StrictBool, StrictFloat, StrictInt, StrictStr, model_validator,\n)\n\nText = Annotated[StrictStr, Field(min_length=1)]\nCount = Annotated[StrictInt, Field(ge=0)]\nRank = Annotated[StrictInt, Field(ge=1)]\nFinite = Annotated[StrictFloat, Field(allow_inf_nan=False)]\nPositive = Annotated[StrictFloat, Field(gt=0, allow_inf_nan=False)]\nNonNegative = Annotated[StrictFloat, Field(ge=0, allow_inf_nan=False)]\nRating = Annotated[StrictFloat, Field(ge=1, le=5, allow_inf_nan=False)]\n\n\nclass Contract(BaseModel):\n model_config = ConfigDict(\n strict=True, extra=\"forbid\", frozen=True, allow_inf_nan=False,\n )\n\n\nclass Provenance(Contract):\n status: Literal[\"observed\", \"estimated\", \"missing\"]\n source_ref: Text\n collected_at: AwareDatetime\n missing_reason: Text | None = Field(description=\"缺失时必填\")\n\n @model_validator(mode=\"after\")\n def check_reason(self):\n if (self.status == \"missing\") != (self.missing_reason is not None):\n raise ValueError(\"missing_reason 必须与缺失状态一致\")\n return self\n\n\nclass Dimensions(Contract):\n values: tuple[Positive, Positive, Positive]\n unit: Literal[\"cm\", \"in\"]\n\n\nclass Weight(Contract):\n value: Positive\n unit: Literal[\"kg\", \"lb\"]\n\n\nclass PricePoint(Contract):\n day: date\n value: Positive = Field(description=\"USD/件；与现价相同报价口径\")\n\n\nclass ProductL1RawRecord(Contract):\n schema_version: Literal[\"1.0\"]\n snapshot_id: Text\n product_id: Text\n marketplace: Literal[\"amazon_us\"]\n category_id: Text\n observed_at: AwareDatetime\n currency: Literal[\"USD\"]\n price_basis: Literal[\"discounted_item_ex_sales_tax_free_shipping\"]\n bsr_rank: Rank | None\n search_volume: Count | None = Field(description=\"同查询集合，次/日\")\n price_current: Positive | None = Field(description=\"USD/件\")\n price_history_90d: tuple[PricePoint, ...] = Field(max_length=90)\n review_count: Count | None\n rating_score: Rating | None\n listing_age_days: Count | None = Field(description=\"日\")\n package_dimensions: Dimensions | None\n shipping_weight: Weight | None\n is_oversize: StrictBool | None\n seller_type: Literal[\"amazon_retail\", \"third_party_fba\",\n \"third_party_fbm\", \"unknown\"]\n provenance: dict[Text, Provenance] = Field(min_length=11, max_length=11)\n\n @model_validator(mode=\"after\")\n def check_snapshot(self):\n names = {\n \"bsr_rank\", \"search_volume\", \"price_current\", \"price_history_90d\",\n \"review_count\", \"rating_score\", \"listing_age_days\",\n \"package_dimensions\", \"shipping_weight\", \"is_oversize\", \"seller_type\",\n }\n if set(self.provenance) != names:\n raise ValueError(\"11 个字段必须分别提供来源\")\n for name in names:\n value = getattr(self, name)\n missing = value is None\n if name == \"price_history_90d\":\n missing = len(value) == 0\n if name == \"seller_type\":\n missing = value == \"unknown\"\n if (self.provenance[name].status == \"missing\") != missing:\n raise ValueError(\"值与来源状态冲突: \" + name)\n days = [p.day for p in self.price_history_90d]\n today = self.observed_at.date()\n if days != sorted(set(days)):\n raise ValueError(\"价格历史必须按日升序且不重复\")\n if any(not today - timedelta(days=90) <= d < today for d in days):\n raise ValueError(\"价格历史超出此前 90 日窗口\")\n return self\n\n\nclass SalesCalibration(Contract):\n category_id: Text\n model_id: Text\n source_ref: Text\n valid_through: date\n sales_unit: Literal[\"units_per_day\"]\n alpha: Finite\n beta: Annotated[StrictFloat, Field(ge=0.8, le=1.2, allow_inf_nan=False)]\n holdout_mape: NonNegative = Field(description=\"比例，不是百分数\")\n holdout_n: Annotated[StrictInt, Field(ge=1)]\n\n\nclass LogisticsRule(Contract):\n source_ref: Text\n valid_through: date\n divisor: Positive\n divisor_unit: Literal[\"cm3_per_kg\"]\n\n\nclass UnitCostBundle(Contract):\n source_ref: Text\n valid_through: date\n currency: Literal[\"USD\"]\n unit: Literal[\"USD_per_unit\"]\n cogs: NonNegative\n duties: NonNegative\n inbound: NonNegative\n fulfillment: NonNegative\n referral: NonNegative\n advertising: NonNegative\n storage: NonNegative\n returns_loss: NonNegative\n compliance: NonNegative\n fx_loss: NonNegative\n financing: NonNegative\n allocated_overhead: NonNegative\n other: NonNegative\n\n\nclass ProductL2CleanedFeature(Contract):\n schema_version: Literal[\"1.0\"]\n feature_id: Text\n product_id: Text\n category_id: Text\n as_of: AwareDatetime\n raw_snapshot_refs: tuple[Text, ...] = Field(min_length=1)\n auxiliary_evidence_refs: tuple[Text, ...]\n transform_version: Text\n blocked_reasons: tuple[Text, ...]\n bsr_current: Rank | None\n bsr_day_minus_7: Rank | None\n search_recent_30d: Count | None\n search_previous_30d: Count | None\n complete_search_days: Annotated[StrictInt, Field(ge=0, le=60)]\n price_usd: Positive | None\n price_median_90d_usd: Positive | None\n valid_price_days: Annotated[StrictInt, Field(ge=0, le=90)]\n top10_review_counts: tuple[Count, ...] = Field(min_length=0, max_length=10)\n cohort_product_ids: tuple[Text, ...] = Field(min_length=0, max_length=10)\n listing_age_days: Count | None\n package_dimensions_cm: tuple[Positive, Positive, Positive] | None\n package_volume_cm3: Positive | None\n actual_weight_kg: Positive | None\n billed_weight_kg: Positive | None\n source_is_oversize: StrictBool | None\n policy_standard_size: StrictBool | None\n seller_type: Literal[\"amazon_retail\", \"third_party_fba\",\n \"third_party_fbm\", \"unknown\"]\n critical_reviews_n: Count | None\n negative_physical_aspects_n: Count | None\n aspect_evidence_refs: tuple[Text, ...]\n total_unit_cost_usd: NonNegative | None\n logistics_unit_cost_usd: NonNegative | None\n calibration: SalesCalibration | None\n logistics_rule: LogisticsRule | None\n costs: UnitCostBundle | None\n\n @model_validator(mode=\"after\")\n def check_consistency(self):\n if self.package_dimensions_cm is not None:\n a, b, c = self.package_dimensions_cm\n if not a >= b >= c:\n raise ValueError(\"L2 三边必须按长、中、短排序\")\n if len(self.top10_review_counts) != len(self.cohort_product_ids):\n raise ValueError(\"竞争样本标识与评论计数长度不符\")\n if len(set(self.cohort_product_ids)) != len(self.cohort_product_ids):\n raise ValueError(\"竞争样本商品必须去重\")\n if self.calibration is not None and self.calibration.category_id != self.category_id:\n raise ValueError(\"销量标定品类不符\")\n if self.billed_weight_kg is not None:\n if self.actual_weight_kg is None or self.billed_weight_kg < self.actual_weight_kg:\n raise ValueError(\"计费重不能小于实际重\")\n if self.negative_physical_aspects_n not in (None, 0) and not self.aspect_evidence_refs:\n raise ValueError(\"负面物理方面必须有证据\")\n return self\n\n\nclass GateResult(Contract):\n gate_id: Text\n status: Literal[\"pass\", \"reject\", \"insufficient\", \"review\"]\n reasons: tuple[Text, ...] = Field(min_length=1)\n evidence_refs: tuple[Text, ...]\n\n\nclass ProductL3DecisionMetrics(Contract):\n schema_version: Literal[\"1.0\"]\n feature_ref: Text\n policy_ref: Text\n operator_version: Text\n sales_estimated_units_per_day: NonNegative | None\n kqi_barrier: NonNegative | None\n kpi_velocity: Finite | None\n net_margin: Annotated[StrictFloat, Field(le=1, allow_inf_nan=False)] | None\n value_to_weight_usd_per_kg: Positive | None\n value_to_volume_usd_per_litre: Positive | None\n review_defect_density: NonNegative | None\n gates: tuple[GateResult, ...] = Field(min_length=1)\n decision: Literal[\"candidate_pass\", \"reject\", \"insufficient\", \"review\"]\n\n @model_validator(mode=\"after\")\n def check_decision(self):\n ids = [g.gate_id for g in self.gates]\n if len(ids) != len(set(ids)):\n raise ValueError(\"门禁标识不得重复\")\n statuses = {g.status for g in self.gates}\n expected = (\n \"reject\" if \"reject\" in statuses else\n \"insufficient\" if \"insufficient\" in statuses else\n \"review\" if \"review\" in statuses else \"candidate_pass\"\n )\n if self.decision != expected:\n raise ValueError(\"裁决与非补偿性门禁不一致\")\n metrics = (\n self.sales_estimated_units_per_day, self.kqi_barrier,\n self.kpi_velocity, self.net_margin, self.value_to_weight_usd_per_kg,\n self.value_to_volume_usd_per_litre, self.review_defect_density,\n )\n if self.decision == \"candidate_pass\" and any(v is None for v in metrics):\n raise ValueError(\"核心指标缺失时不得候选通过\")\n return self\n```\n\n### 4.2 下游必须补齐的关联与复算约束\n\n这些不是上述局部模型已经实现的防护；下游必须单独实现并验证。\n\n1. 校验 L2 引用的全部快照归属同商品或声明的竞争样本、同站点、同品类和同报价；观察时间、窗口截止时间与 UTC 口径一致。\n2. 成本包、承运商规则及销量标定未过期；来源不可空且不得使用未来订单标定历史裁决。完整成本包必须逐项出现，0 必须代表明确不适用，而不是未知。\n3. 复算尺寸、体积、计费重、成本总和及物流成本；换算常量为 1 in = 2.54 cm、1 lb = 0.45359237 kg。物流成本定义为头程加履约配送，本版其余成本不得计入或重复计入。\n4. 复算六项 L3 值，禁止接受外部传入的自称通过结果；极端指数上溢、下溢为计算阻塞，不截断成虚假安全值。\n5. 必需门禁集合包含数据完整性、售价、规格、销售标定、竞争阻力、动量、净利及压力情景、物流、评论证据；只有“有一项通过”不足以候选通过。人工合规与改款评审保留在采购前独立审批。\n6. 每个不可用指标须生成对应证据不足门禁；其他明确失败仍保留，裁决优先级为拒绝 > 证据不足 > 人工复核 > 候选通过，不丢失全部原因。\n7. “冻结”模型不等于深度不可变存储；来源映射与嵌套容器必须在持久化时生成实际内容摘要，保存算子、规则及标注版本。当前没有声称存在该控制器。\n\n## 5. BMAD-Engineer 实施单测背压规范\n\n本节定义未来验收要求，不授权当前执行。测试资产尚未创建；静态契约尚未运行、导入或通过测试。\n\n### 5.1 单测与标定验收矩阵\n\n| 编号 | 用例/输入 | 必须断言的结果 | 验证类型 |\n|---|---|---|---|\n| C01 | 排名=0/-1/布尔；价格=0；数字字符串；NaN/±∞；未知字段；缺失一个业务键 | 契约拒绝，不能静默转换或补零 | 契约单测 |\n| C02 | 搜索=0、评论数=0、年龄=0；未知评分；来源状态与值冲突 | 合法零值接受；未知评分不是0；状态冲突拒绝 | 契约单测 |\n| C03 | 历史价格重复日期、逆序、超过90日、当日未完成记录 | 拒绝；空历史可保存但不能通过价格稳定性门禁 | 窗口单测 |\n| S01 | α=ln(10000)、β=1、R=100/1000/10000 | 分别为100/10/1件每日；相对误差≤1e-9；不是实测销量 | 数学单测 |\n| S02 | β=0.8/1.2 与0.79/1.21；未知 α；跨品类/过期标定 | 端点合法；越界、缺标定或不匹配阻塞绝对销量 | 参数与关联单测 |\n| S03 | 无噪声合成数据覆盖至少3个数量级的秩 | α/β拟合绝对误差≤1e-6；按时间切分防泄漏 | 合成拟合单测 |\n| S04 | 独立、可核验真实销量留出集，不使用本模型估值充当标签 | 本版建议n≥30、MAPE≤20%；真实零销量单独报告MAE，不能零除或剔除后宣称全样本通过 | 工程阶段标定验收，非当前实测 |\n| S05 | 极端α/R导致指数上溢或下溢 | 记录计算阻塞；不返回∞、0或饱和值冒充有效估算 | 数值边界单测 |\n| B01 | Top10均值499/500/501，演示T=500 | K为0.998/1/1.002；仅第一组通过 | 阈值单测 |\n| B02 | 样本仅9个、重复父体、品类混接或T=0 | 证据不足或参数拒绝；不补虚拟第10个样本 | 样本与零除单测 |\n| V01 | 搜索前窗1000、后窗1300，排名1000→800 | gS=0.3、gR=0.2、M=0.25；较小BSR代表改善 | 数学单测 |\n| V02 | 前窗搜索=0、缺1日、缺7日前排名；搜索下降但排名改善 | 前三者证据不足；最后不得用加权总分掩盖搜索硬门禁失败 | 零除与非补偿单测 |\n| V03 | 年龄59/60日；价格历史71/72日；现价比中位数下降恰好15% | 59日复核；72日满足覆盖门槛；下降15%进入折扣混杂复核 | 窗口边界单测 |\n| M01 | 售价40，总单位成本30，其中头程2、履约5 | 净利25%；物流占价17.5%；成本增加20%后净利10%，压力端点通过 | 单位经济学单测 |\n| M02 | 费用一项缺失、佣金重复、混币、税基不符、过期报价；售价0 | 缺项或口径冲突阻塞；拒绝零价；不得从卖家类型补费用 | 成本闭包与零除单测 |\n| M03 | 基准净利19.999%/20%；成本高于售价 | 精确政策端点比较；前者拒绝；负利润保留，不裁剪为0 | 门禁边界单测 |\n| W01 | 未排序包装8/18/14英寸；20磅 | L2排序为18/14/8；等于任一尺寸/重量上限不通过 | 换算与严格边界单测 |\n| W02 | 包装45×35×20cm、实际重0.2kg、D=5000cm³/kg、价40、物流15.75 | V=31500cm³；计费重6.3kg；Qw≈6.349206USD/kg；Qv≈1.269841USD/L；物流占价39.375%，拒绝。即使初筛尺寸合格也不得抵消经济失败 | 极端轻抛货单测 |\n| W03 | 同W02，D改6000；D=0；单位缺失；尺寸/重量为0 | D=6000时计费重5.25kg、Qw≈7.619048；其他非法输入拒绝，禁止沿用5000 | 费率版本与零除单测 |\n| W04 | 上游超规格报告与按政策尺寸计算冲突 | 保留两份事实并进入复核，不覆盖上游原始值 | 溯源冲突单测 |\n| R01 | 10条2–3星去重评论、12个负面物理方面 | 密度1.2合法；同评论同方面重复不增计；客服方面不进分子 | 聚合单测 |\n| R02 | 无评论；有评论但无物理方面；评论证据断链；抽样<30 | 依次为证据不足、密度0、拒绝证据、不足以机会放行；0与缺失严格区分 | 零除与证据单测 |\n| R03 | 真实人工标注集与固定抽取版本 | 建议抽检100条，不足则全量；负面物理方面precision/recall分别≥90%；统计在固定标签上逐项一致；未通过不得伪装为低缺陷 | 工程阶段抽取验收 |\n| G01 | 所有分数优秀但一个规格失败；门禁漏项；传入伪造L3值 | 第一组拒绝；漏项不能通过；外部值必须经L2复算核对 | 决策与关联单测 |\n| G02 | 同时拒绝、缺证据、需复核；固定输入和版本重复运行 | 按拒绝优先裁决并保留全部原因；纯算子重复结果一致，原始证据不变 | 组合与复现单测 |\n\n数学单测一般使用相对误差 1e-9、绝对误差 1e-12；合成拟合另用表中容差。政策端点不得借数值容差放宽，财务台账按获准舍入规则做十进制比较。真实标定与语义验收是不同门禁，合成测试通过不能证明两者已通过。\n\n### 5.2 下游顺序与证据要求\n\n1. 先建立获授权的工程实例，确认政策参数、数据授权、依赖版本和测试路径；不继承本工件的任何“绿灯”。\n2. 创建契约、纯算子与相关测试资产；先验证输入闭包，再验证数学和门禁，不附加无关业务单测或全站抓取。\n3. 单独取得标定集和人工标注集，明确输出为估算；销量标定或方面抽取不达标时保留阻塞。\n4. 保存真实命令、工作目录、目标、退出状态与关键输出；失败、超时、缺依赖或缺证据即暂停受影响交付。\n\n拟执行验证命令：尚未绑定。测试模块、依赖锁定和目标路径尚不存在，当前不捏造可执行文件名或声称命令可用；下游须在获准工程阶段补齐并使用串行、前台、非交互、进程级有界超时执行。\n\n### 5.3 证据索引与交付边界\n\n- [6](cite:6) Chevalier & Goolsbee，2003，《Measuring Prices and Price Competition Online: Amazon and Barnes and Noble》；本次检索返回原论文来源，支撑原始研究对象与秩转换背景，不支撑所有用户系数断言。\n- [10](cite:10) 《Product Research 101》公开商品书目，ISBN 9781537483733；作者 Renae Clark。作者纠偏有书目支持，具体筛选阈值尚未核实。[10](cite:10)\n- 本地 [bcec-gem.md](_scratch/bcec-gem.md:155)，重点为155–173行的逐条证据打标与确定性聚合主张；它是历史对话草稿，不是已接受项目事实。\n- 本地 [geo-2024.md](_scratch/geo-2024.md:35)，35–49行摘要与出版信息；“最高约40%”指生成式回答可见性。\n- 本地 [geo-2026.md](_scratch/geo-2026.md:64)，64–88行的重排序研究范围、220行的平均排名指标、371–386行的事实保真与结构化特征；本地副本不等于已核验线上发布或生产效果。\n- 用户专著摘录：Fisher/Raman《The New Science of Retailing》、Cox《Retail Analytics: The Secret Weapon》、Thomson/Hansen《The Amazon Marketplace Dilemma》以及 Hu & Liu 方面挖掘机理。本次没有原书页码或论文全文证据，不为其新增原文引语、精确权重或页码。\n\n交付结论：已形成可供下游审阅的血缘与契约提案；11 字段之外的必要输入被显式暴露，六项核心指标均有公式、边界和背压用例。该结论属于静态架构分析，不代表采集、计算、测试、实施、采购或部署已经完成。\n"}}