{"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- 默认业务场景：Amazon 美国站、美元计价、同一细分类目、可区分变体的实体；其他市场必须重配费率、尺寸分级与校准参数。\n- 验证状态：本地资料有界静态检视；契约代码、拟议单测和命令均未运行。未知会话标识为 null。\n\n## 1. 顶层战略裁决\n\n### 1.1 目标、约束与非目标\n\n目标是把传统“看榜单盲目跟卖”改为“L1 可溯源状态事实 ➔ L2 清洗特征 ➔ L3 确定性数学算子”，先排除物理与单品经济学不可行商品，再根据需求、竞争阻力和可修复缺陷决定是否进入小批量验证。\n\n- 约束：缺失不等于零；排名不等于成交量；预测利润不等于竞品真实利润；评论缺陷不等于真实退货率。\n- 约束：大模型只能输出绑定原文的候选方面标签；数量、比率、费用及门禁必须由确定性代码计算。\n- 非目标一：不实施采集器、运营自动化、全自动选品或文案发布。\n- 非目标二：不训练模型，不绕过登录墙、访问控制或采集权限。\n- 非目标三：不预测平台内部推荐权重，不把 GEO 实验收益转写成真实流量或销量保证。\n- 非目标四：不运行终端、测试、构建、部署，不晋升或归档决策与计划。\n\n### 1.2 证据裁决与反证\n\n本地输入核对位置：[`bcec-gem.md`](_scratch/bcec-gem.md:154)、[`geo-2024.md`](_scratch/geo-2024.md:35)、[`geo-2026.md`](_scratch/geo-2026.md:220)。这些摘录是本次分析输入，不替代在线原版、生产流量实验或目标环境验证。\n\n| 主张 | 本次裁决 | 对规范的影响 |\n|---|---|---|\n| E-GEO 证明“2026 超过 60% 搜索零点击、推荐率提升 40% 以上” | 输入归因存在冲突。2024 摘录的“最高 40%”指生成式回答中的可见度；2026 摘录采用平均推荐排名改善，不能交换统计口径。零点击比例未在已检视 E-GEO 内容中获得对应证据。 | 不进入算子常数、门禁或收益承诺。 |\n| E-GEO 提供商品结构化事实可信度的通用评分公式 | 已检视内容强调事实保持、用户意图和可扫描结构，但不足以建立上述通用公式。Insufficient evidence. | 只规定来源覆盖与事实一致性审计，不发明论文原生可信度分数。 |\n| 基于 BSR 可以反推“真实销量” | 公开研究使用销售排名研究需求；排名是相对量，销量标定需要外部数量基准。[1](cite:1)[2](cite:2)[3](cite:3) | 对外名称保留业务需求，结果一律标记“校准后销量估计”，禁止标记真实成交量。 |\n| 四本书直接给出本规范所有阈值 | Fisher/Raman 的书目归属有公开书目支持；其余用户指定书目及精确阈值未取得足够原文页码证据。[10](cite:10) | 用户提供的经验口径与本规范提出的公式分别标识，不冒充原文定理。 |\n| BSR 的 7 天变化是平台推流核心、卖家类型可以推断 Buy Box | 当前证据不足以支持平台内部因果权重；卖家类型与 Buy Box 所属并非同一观测。Insufficient evidence. | 7 天排名变化仅作代理信号；Buy Box 必须另行采集。 |\n\n证据判断优先保留本地摘录中的指标定义，不沿用蒸馏摘要中无法闭合的因果与数值。用户指定的 $20–$70、尺寸与重量范围在本规范中作为内部候选策略，不宣称它们就是 Amazon 2026 官方分级。\n\n### 1.3 最小充分架构与闭包\n\n1. L1 保留商品核心记录及来源信封；重复快照形成历史，不允许历史回填覆盖原记录。\n2. L2 统一美元、英寸、千克和立方厘米，校验同市场、类目、实体、关键词、报价口径及时间窗。\n3. L3 使用版本化公式、校准参数、成本场景和业务策略计算；每个结果携带输入引用与可用性状态。\n4. 任一失败门禁输出“拒绝”；无失败但存在阻塞输出“待补数据”；全部通过仅输出“通过初筛”，不授权采购。\n\n必须补充而不混入 11 个核心字段的旁路事实：\n\n| 旁路输入 | 用途 | 最小证据要求 |\n|---|---|---|\n| 同实体历史商品快照 | 7 天 BSR 与两段 30 天搜索量 | 原始记录标识、时间窗、市场、类目、关键词、供应商方法版本。 |\n| 同类目 Top 10 竞品集合 | 市场评论阻力 | 按同一时点同类目 BSR 升序选取，固定恰好 10 个去重实体；声明父体/变体规则。 |\n| 已知销量与排名校准样本 | 幂律截距、斜率及留出误差 | 同市场、类目、时间粒度；真实已知销量来源，不以另一个 BSR 估计器当真值。 |\n| 候选单品成本账及物流报价 | 净利率、计费重量 | 采购、头程、尾程履约、平台费、仓储、广告、退货损失、税费及其他摊销；币种、时间、费率版本。 |\n| 2–3 星评论原文及方面标签 | 缺陷密度 | 评论标识、原文、星级、日期、实体范围、抽样方法、文本哈希、标签器版本和原文片段。 |\n| 业务策略 | 阈值及容差 | 评论阻力上限、最低净利率、物流最低货值比、最小评论样本和拟合误差上限，均需业务确认。 |\n\n品类穿透率还需要品类购买者与总体购买者数据；价格交叉弹性还需要跨商品价格及数量面板；加购率需要真实加购与曝光数据；库存损失需要需求分布与缺货/滞销成本。这些不在核心数据闭包内，不伪造附加算子。\n\n## 2. L1 物理事实采集清单\n\n这里的“物理事实”指可回溯的原始观测，不代表所有字段都是物理测量值。搜索量常是供应商估计，平台尺寸分级是报告标签；来源信封必须区分报告值与估计值。\n\n| L1 核心字段 | 单位及严格语义 | 首选来源 | 缺失与清洗规则 |\n|---|---|---|---|\n| `bsr_rank` | 同市场、同类目的正整数名次；1 最优 | 商品详情公开 BSR 或获准数据接口 | 0、负数非法；无榜单为 null；不同类目不可比较。 |\n| `search_volume` | 固定关键词与市场的查询次数/日；非指数、非销量 | 平台授权搜索分析或明确方法的供应商 | 月度量、Google Trends 指数不得悄悄当日查询量；仅能显式转换并保留估计方法。 |\n| `price_current` | USD/件；同一报价口径的商品售价，不含销售税 | 当前商品报价或获准价格接口 | 0 可表示异常/不可售报价，须拒绝初筛；缺报价为 null。 |\n| `price_history_90d` | 过去 90 个完整 UTC 日的日期—USD/件序列 | 获准历史价格接口或自有不可变快照 | 最多 90 个去重日；保留缺口，不用当前价回填。 |\n| `review_count` | 条；平台展示累计评论数量 | 商品页或获准接口 | 0 是真实无评论；未采集为 null；声明父体/变体聚合范围。 |\n| `rating_score` | 星；1–5 范围 | 商品页或获准接口 | 无评分为 null，不能用 0 代替。 |\n| `listing_age_days` | 日；截至快照日期的可验证上架年龄 | 可验证首次上架日期或平台记录 | 若只有首次观测日期，则真实上架年龄为 null，另记首次观测年龄。 |\n| `package_dimensions` | 三边正数，附 in 或 cm 单位；含包装尺寸 | 商品包装参数、供应商实测或履约资料 | 不以裸商品尺寸替代；L2 排序为长边≥中边≥短边。 |\n| `shipping_weight` | 正数，附 lb 或 kg；单件含包装重量 | 包装规格、称重或履约资料 | 不以净重替代；不可用 0 表示未知。 |\n| `is_oversize` | 严格布尔；来源报告的超尺寸标签 | 带版本的履约分级或供应商报告 | 未知为 null；与内部尺寸门禁分开保存，冲突进入复核。 |\n| `seller_type` | AMAZON / THIRD_PARTY_FBA / THIRD_PARTY_FBM / UNKNOWN | 卖家身份与履约方式的明确观测 | UNKNOWN 不代表第三方；不推断 Buy Box。 |\n\n所有 11 个键必须出现，允许值为 null；实体标识、时间、币种、字段级来源引用属于信封元数据，不计入 11 个业务字段。原始响应、字段定位、观测时间、哈希、采集器版本、估计方法及缺失原因必须由来源清单保存。\n\n## 3. 指标血缘 DAG 拓扑映射表\n\n### 3.1 算子约定\n\n- 固定换算：$1\\,\\mathrm{in}=2.54\\,\\mathrm{cm}$，$1\\,\\mathrm{lb}=0.45359237\\,\\mathrm{kg}$。\n- $r_t$ 是同类目当前 BSR；$r_{t-7}$ 是恰好 7 天前的同口径值。\n- $S_1$、$S_0$ 是最近及前一段互不重叠的 30 个完整 UTC 日的查询总量；两段各需 30 个有效日，真实零值保留。\n- $P$ 是候选定价场景采用的 USD 售价；$W$ 是含包装千克重量；$V$ 是包装立方厘米体积。\n- $T_R$、$m_{\\min}$、$h_{\\min}$、$N_{\\min}$ 和 $\\tau_{\\mathrm{fit}}$ 为经确认、版本化的策略参数；不存在文献通用默认值。\n- 下表中“本规范定义”均是设计提案，不是署名作者的原生公式或已验证的经营收益。\n\n| L3 指标名称 | 业务意义 | 依赖 L2 清洗特征 | 溯源 L1 物理字段 | 确定性数学公式 (LaTeX) | 决策门禁红线 (Hard Gates) | 文献/专著出处 |\n|---|---|---|---|---|---|---|\n| 帕累托真实销量反推：校准销量估计 | 估计件/日，不冒充真实成交 | 当前有效 BSR；同类目校准参数与留出误差 | 当前 `bsr_rank`；旁路已知销量样本 | $\\ln\\widehat Q=\\alpha-\\beta\\ln r_t$；$\\widehat Q=e^\\alpha r_t^{-\\beta}$ | $r_t>0$；校准未过期且覆盖目标排名区间；留出对数 RMSE≤$\\tau_{\\mathrm{fit}}$。无校准即阻塞。$\\beta\\in[0.8,1.2]$ 仅作为本任务候选策略，超界须重议，不声称跨品类普适。 | Chevalier & Goolsbee (2003) 为用户指定机制来源；公开排名研究与校准需求有支持。[1](cite:1)[2](cite:2)[3](cite:3) 区间并非本次查证出的原文常数。 |\n| 市场阻力指数 KQI_barrier | 量化同类目头部评论积累阻力，不等于完整竞争指数 | 同时点、去重 Top 10 评论均值；$T_R$ | 10 个竞品的 `bsr_rank`、`review_count`；信封中的类目及实体 | $\\bar R_{10}=\\frac{1}{10}\\sum_{i=1}^{10}R_i$；$\\mathrm{KQI}=\\bar R_{10}/T_R$ | 恰好 10 个有效竞品，$T_R>0$；KQI<1。不足 10 个或缺评论数量均阻塞。 | 用户指定《Product Research 101》评论漏斗；归一化公式为本规范定义，书目归属及精确阈值原文证据不足。 |\n| 需求动量 KPI_velocity | 合并搜索增长与排名改善的代理信号，不声称平台因果推流权重 | $S_1,S_0,r_t,r_{t-7}$；完整日覆盖 | 历史 `search_volume`、`bsr_rank`；`listing_age_days` 用于历史可得性检查 | $g_s=(S_1-S_0)/S_0$；$g_r=(r_{t-7}-r_t)/r_{t-7}$；$\\mathrm{KPI}=0.5g_s+0.5g_r$ | $S_0>0$、$r_{t-7}>0$；两个搜索窗各完整 30 日、BSR 两时点有效；KPI>0 才通过本版初筛。基期零为“无基期”阻塞，不加伪计数。 | Fisher/Raman 需求信号、Thomson/Hansen 平台机制为用户提供的概念线索；0.5 权重、公式及正值门禁为本规范提案。 |\n| 单品经济学净利率 Net_Margin | 候选 SKU、指定价格和成本场景的完全成本净利率 | USD 售价；完整单件成本分项；报价适用范围 | `price_current`、`price_history_90d`、`package_dimensions`、`shipping_weight`、`seller_type`；旁路采购/物流/平台/营销/税费账 | $C= C_{\\mathrm{goods}}+C_{\\mathrm{inbound}}+C_{\\mathrm{fulfillment}}+C_{\\mathrm{platform}}+C_{\\mathrm{storage}}+C_{\\mathrm{ads}}+C_{\\mathrm{return}}+C_{\\mathrm{tax}}+C_{\\mathrm{other}}$；$\\mathrm{NM}=(P-C)/P$ | $P>0$；所有成本分项显式且非负，同币种、同单件及同履约场景；NM≥$m_{\\min}$。成本未知不可默认为零。 | 本地输入的物理参数＋单品经济学原则；成本恒等式为本规范定义，不归为任一书的独有公式。 |\n| 货值重量比 Value_to_Weight | 衡量真实重量的货值承载；单位 USD/kg，不是体积比 | $P,W$；辅助物流计费重量与费率 | `price_current`、`shipping_weight`；物流辅助还依赖 `package_dimensions` 和旁路运价 | $\\mathrm{VW}=P/W$；$W_{\\mathrm{bill}}=\\max(W,V/D)$；$\\mathrm{VW}_{\\mathrm{bill}}=P/W_{\\mathrm{bill}}$ | $W>0,V>0,D>0$；按真实报价的进位规则计算运费；计费货值比≥$h_{\\min}$，且净利率门禁不得被高 VW 抵消。 | 物理门禁来自用户指定初筛原则；货值比与物流式为本规范定义。$D$ 是运价合同参数，不是平台通用常数。 |\n| 货值体积比：辅助指标 | 正式消除“货值体积比”与 Value_to_Weight 的命名冲突；单位 USD/cm³ | $P,V$ | `price_current`、`package_dimensions` | $\\mathrm{VV}=P/V$ | $V>0$；不与 USD/kg 比较或混排；仅作物流诊断，不单独给出选品绿灯。 | 本规范维度分析定义。 |\n| 差评退货缺陷密度 Review_Defect_Density | 每条 2–3 星评论平均提及的物理缺陷方面数量；不是退货概率 | 去重差评数 $N_c$；去重物理负面方面提及数 $M_-$；抽样及标签版本 | 11 字段仅提供实体/评论总量背景；必须另采评论原文、星级及方面标签，不能从 `rating_score` 或 `review_count` 反推 | $\\mathrm{RDD}=M_-/N_c$；$M_-=\\sum_{j=1}^{N_c}\\#\\{\\text{unique negative physical aspects in review }j\\}$ | $N_c\\ge N_{\\min}>0$；原文锚点完整、去重规则固定、样本方法披露。RDD 可大于 1；不设置“越高越好”绿灯，缺陷可修复且成本/安全审查通过才可立项。 | 用户指定 Hu & Liu 的方面挖掘机制；该比率、2–3 星范围及去重规则为本规范定义，不声称论文原生退货公式。 |\n\n### 3.2 拓扑与真理隔离\n\n1. 当前与历史商品记录 → 单位/时间/实体清洗 → BSR、搜索窗、价格、重量和体积特征 → 销量、阻力、动量、货值比。\n2. 包装特征＋版本化运价 → 计费重量与运费 → 完全成本账 → 净利率。只保存一次尾程费用，禁止在物流和利润中重复扣费。\n3. 评论原文 → 带原文片段的方面标签 → 确定性去重计数 → 缺陷密度。语义提取的不确定性不会因末端确定性除法而消失。\n4. 六个必需指标＋物理门禁＋业务策略 → 初筛状态。指标不能向上游反向修改原始事实；若需改款，建立新候选版本及新成本场景。\n\n内部物理门禁：$20\\le P\\le70$；包装三边排序后 $L<18\\,\\mathrm{in},M<14\\,\\mathrm{in},S<8\\,\\mathrm{in}$；含包装重 $W_{\\mathrm{lb}}<20$；来源超尺寸标签必须明确为否。恰好等于尺寸或重量边界即拒绝；标签未知或冲突阻塞复核。\n\n## 4. 数据契约定义\n\n### 4.1 契约与序列化边界\n\n以下是拟供 BMAD-Engineer 实现的 Pydantic V2 契约定义，仅存在于本分析文档，不是已创建的生产模块。严格模式、额外字段拒绝、有限数约束、显式 null 和跨字段一致性均属于拟议验收要求，尚未在目标依赖版本运行验证。\n\n- 原始字段名以本节代码为准；单位携带在量值对象中，美元币种固定在身份信封中。\n- Python 调用须传入 Decimal、日期、带时区时间和 tuple 等声明类型；外部 JSON 由专用适配器解析，金额使用十进制文本，禁止经过二进制浮点中转。\n- 每个来源引用必须解析到不可变来源清单，记录来源、原始定位、时间、哈希、方法版本、报告/估计状态与缺失原因；字符串引用存在不等于来源已经核验。\n- L2 不计算 L3；旁路成本、校准与评论数据必须先经过原始证据清洗，再显式注入，不能用模型默认值创造事实。\n- 同实体、同时间、同场景连接及公式复算需要下游算子和测试保障；数据类的形状校验不证明血缘正确或业务门禁已经执行。\n\n```python\nfrom datetime import date, datetime, timedelta\nfrom decimal import Decimal\nfrom typing import Annotated, Generic, Literal, TypeVar\n\nfrom pydantic import BaseModel, ConfigDict, Field, model_validator\n\nText = Annotated[str, Field(min_length=1, strict=True)]\nCount = Annotated[int, Field(ge=0, strict=True)]\nRank = Annotated[int, Field(ge=1, strict=True)]\nFinite = Annotated[float, Field(allow_inf_nan=False, strict=True)]\nPositive = Annotated[float, Field(gt=0, allow_inf_nan=False, strict=True)]\nNonnegative = Annotated[float, Field(ge=0, allow_inf_nan=False, strict=True)]\nMoney = Annotated[Decimal, Field(ge=0, max_digits=16, decimal_places=4,\n allow_inf_nan=False, strict=True)]\nRefs = Annotated[tuple[Text, ...], Field(min_length=1)]\nSeller = Literal['AMAZON', 'THIRD_PARTY_FBA', 'THIRD_PARTY_FBM', 'UNKNOWN']\n\n\nclass Contract(BaseModel):\n model_config = ConfigDict(strict=True, extra='forbid', frozen=True,\n validate_default=True, allow_inf_nan=False)\n\n\nclass Identity(Contract):\n product_id: Text\n marketplace: Literal['amazon_us']\n category_id: Text\n query_id: Text\n entity_scope: Literal['variant', 'parent']\n currency: Literal['USD']\n as_of: datetime\n manifest_ref: Text\n\n @model_validator(mode='after')\n def timezone_required(self):\n if self.as_of.utcoffset() is None:\n raise ValueError('as_of 必须带时区')\n if self.as_of.utcoffset() != timedelta(0):\n raise ValueError('as_of 必须为 UTC')\n return self\n\n\nclass Dimensions(Contract):\n unit: Literal['in', 'cm']\n length: Positive\n width: Positive\n height: Positive\n\n\nclass Weight(Contract):\n unit: Literal['lb', 'kg']\n value: Positive\n\n\nclass PricePoint(Contract):\n day: date\n price: Money\n source_ref: Text\n\n\nclass ProductL1RawRecord(Contract):\n identity: Identity\n raw_record_ref: Text\n field_sources: dict[Text, Text]\n bsr_rank: Rank | None = Field(...)\n search_volume: Count | None = Field(..., description='查询次数/UTC 日')\n price_current: Money | None = Field(..., description='USD/件，不含销售税')\n price_history_90d: tuple[PricePoint, ...] | None = Field(..., max_length=90)\n review_count: Count | None = Field(...)\n rating_score: Annotated[float, Field(ge=1, le=5, allow_inf_nan=False)] | None = Field(...)\n listing_age_days: Count | None = Field(...)\n package_dimensions: Dimensions | None = Field(...)\n shipping_weight: Weight | None = Field(...)\n is_oversize: bool | None = Field(...)\n seller_type: Seller | None = Field(...)\n\n @model_validator(mode='after')\n def raw_invariants(self):\n fields = set(type(self).model_fields) - {\n 'identity', 'raw_record_ref', 'field_sources'\n }\n if set(self.field_sources) != fields:\n raise ValueError('11 个核心字段均须有来源或缺失证据引用')\n points = self.price_history_90d\n if points is not None:\n days = tuple(p.day for p in points)\n if days != tuple(sorted(set(days))):\n raise ValueError('历史价格日期必须严格递增且去重')\n today = self.identity.as_of.date()\n if any(not today - timedelta(days=90) <= d < today for d in days):\n raise ValueError('历史价格须落在过去 90 个完整 UTC 日')\n return self\n\n\nclass CostInputs(Contract):\n scenario_id: Text\n source_refs: Refs\n goods_usd: Money\n inbound_usd: Money\n fulfillment_usd: Money\n platform_usd: Money\n storage_usd: Money\n ads_usd: Money\n return_loss_usd: Money\n tax_usd: Money\n other_usd: Money\n\n\nclass SalesCalibration(Contract):\n calibration_id: Text\n marketplace: Literal['amazon_us']\n category_id: Text\n quantity_unit: Literal['units_per_day']\n alpha: Finite\n beta: Annotated[float, Field(ge=0.8, le=1.2, allow_inf_nan=False)]\n rank_min: Rank\n rank_max: Rank\n known_sales_sample_count: Annotated[int, Field(ge=3)]\n holdout_log_rmse: Nonnegative\n valid_until: datetime\n source_refs: Refs\n\n @model_validator(mode='after')\n def calibration_invariants(self):\n if self.rank_min >= self.rank_max:\n raise ValueError('校准排名区间必须非退化')\n if self.valid_until.utcoffset() != timedelta(0):\n raise ValueError('校准有效期须带 UTC 时区')\n return self\n\n\nclass ScreeningPolicy(Contract):\n policy_id: Text\n review_mean_limit: Positive\n min_net_margin: Annotated[float, Field(ge=0, lt=1, allow_inf_nan=False)]\n min_billable_value_usd_per_kg: Positive\n min_critical_reviews: Annotated[int, Field(ge=1)]\n max_holdout_log_rmse: Positive\n source_refs: Refs\n\n\nclass ProductL2CleanedFeature(Contract):\n identity: Identity\n feature_ref: Text\n transform_version: Text\n source_refs: Refs\n price_usd: Money | None = Field(...)\n price_median_90d_usd: Money | None = Field(...)\n price_valid_days: Annotated[int, Field(ge=0, le=90)]\n bsr_now: Rank | None = Field(...)\n bsr_7d_ago: Rank | None = Field(...)\n search_recent_30d: Count | None = Field(...)\n search_previous_30d: Count | None = Field(...)\n search_recent_valid_days: Annotated[int, Field(ge=0, le=30)]\n search_previous_valid_days: Annotated[int, Field(ge=0, le=30)]\n top10_valid_count: Annotated[int, Field(ge=0, le=10)]\n top10_review_mean: Nonnegative | None = Field(...)\n package_dimensions_in: tuple[Positive, Positive, Positive] | None = Field(...)\n weight_kg: Positive | None = Field(...)\n weight_lb: Positive | None = Field(...)\n volume_cm3: Positive | None = Field(...)\n is_oversize_reported: bool | None = Field(...)\n seller_type: Seller | None = Field(...)\n volumetric_divisor_cm3_per_kg: Positive | None = Field(...)\n tariff_version: Text | None = Field(...)\n costs: CostInputs | None = Field(...)\n calibration: SalesCalibration | None = Field(...)\n critical_review_count: Count | None = Field(...)\n negative_physical_aspect_count: Count | None = Field(...)\n review_sampling_ref: Text | None = Field(...)\n\n @model_validator(mode='after')\n def cleaned_invariants(self):\n if self.top10_valid_count != 10 and self.top10_review_mean is not None:\n raise ValueError('Top 10 未完整时不允许发布头部均值')\n pairs = ((self.search_recent_30d, self.search_recent_valid_days),\n (self.search_previous_30d, self.search_previous_valid_days))\n if any(total is not None and days != 30 for total, days in pairs):\n raise ValueError('不完整搜索窗口不得发布完整窗口总量')\n dims = self.package_dimensions_in\n if dims is not None and not dims >= dims[1] >= dims[2]:\n raise ValueError('包装三边须降序排列')\n kg, lb = self.weight_kg, self.weight_lb\n if (kg is None) != (lb is None):\n raise ValueError('两种重量单位须同时可用或同时缺失')\n if kg is not None and abs(kg - lb * 0.45359237) > 1e-8 * max(1.0, kg):\n raise ValueError('重量换算不一致')\n if dims is not None and self.volume_cm3 is not None:\n expected = dims * dims[1] * dims[2] * 2.54 ** 3\n if abs(self.volume_cm3 - expected) > 1e-8 * max(1.0, expected):\n raise ValueError('体积换算不一致')\n n, m = self.critical_review_count, self.negative_physical_aspect_count\n if (n is None) != (m is None):\n raise ValueError('评论分子分母必须同时声明')\n if n == 0 and m != 0:\n raise ValueError('无差评时不可能存在缺陷提及')\n return self\n\n\nT = TypeVar('T')\n\n\nclass MetricResult(Contract, Generic[T]):\n value: T | None = Field(...)\n state: Literal['AVAILABLE', 'BLOCKED']\n reasons: tuple[Text, ...]\n source_refs: Refs\n\n @model_validator(mode='after')\n def availability_invariants(self):\n if self.state == 'AVAILABLE' and (self.value is None or self.reasons):\n raise ValueError('可用指标须有数值且无阻塞理由')\n if self.state == 'BLOCKED' and (self.value is not None or not self.reasons):\n raise ValueError('阻塞指标须为空值且有明确理由')\n return self\n\n\nclass GateResult(Contract):\n state: Literal['PASS', 'FAIL', 'BLOCKED']\n evidence_refs: Refs\n reasons: tuple[Text, ...]\n\n @model_validator(mode='after')\n def gate_reason_required(self):\n if self.state != 'PASS' and not self.reasons:\n raise ValueError('失败或阻塞门禁必须解释原因')\n return self\n\n\nclass ProductL3DecisionMetrics(Contract):\n identity: Identity\n feature_ref: Text\n operator_version: Text\n policy: ScreeningPolicy\n sales_estimate_units_per_day: MetricResult[Positive]\n kqi_barrier: MetricResult[Nonnegative]\n kpi_velocity: MetricResult[Finite]\n net_margin: MetricResult[Annotated[float, Field(le=1, allow_inf_nan=False)]]\n value_to_weight_usd_per_kg: MetricResult[Positive]\n value_to_volume_usd_per_cm3: MetricResult[Positive]\n billable_value_usd_per_kg: MetricResult[Positive]\n review_defect_density: MetricResult[Nonnegative]\n gates: dict[Text, GateResult]\n decision: Literal['REJECT', 'NEEDS_DATA', 'PASS_SCREEN']\n\n @model_validator(mode='after')\n def decision_invariants(self):\n required = {'physical', 'sales_fit', 'barrier', 'velocity',\n 'margin', 'logistics', 'defects'}\n if set(self.gates) != required:\n raise ValueError('必须提供全部七项门禁')\n binding = {\n 'sales_estimate_units_per_day': 'sales_fit',\n 'kqi_barrier': 'barrier', 'kpi_velocity': 'velocity',\n 'net_margin': 'margin', 'value_to_weight_usd_per_kg': 'logistics',\n 'billable_value_usd_per_kg': 'logistics',\n 'review_defect_density': 'defects',\n }\n for name, gate in binding.items():\n if getattr(self, name).state == 'BLOCKED' and self.gates[gate].state == 'PASS':\n raise ValueError('缺失必需指标不得通过对应门禁')\n states = {g.state for g in self.gates.values()}\n expected = ('REJECT' if 'FAIL' in states else\n 'NEEDS_DATA' if 'BLOCKED' in states else 'PASS_SCREEN')\n if self.decision != expected:\n raise ValueError('决策必须遵循失败优先、阻塞次之的规则')\n return self\n```\n\n### 4.2 禁止隐式补齐\n\n- 缺少成本、校准、历史窗、评论原文或业务策略时，不发布对应指标数值；若策略对象尚未获确认，暂不创建完整决策记录。\n- 净利率允许负数，不能裁剪为零；缺陷密度允许大于 1，不能误用概率范围约束。\n- 小样本无差评不能视为“无物理缺陷”；精选差评不代表全体顾客，报告不得声称总体退货率。\n- 90 天价格中位数只用于价格稳定性与场景复核，不替代当前价；历史不足 90 日要披露覆盖率，不伪造完整历史。\n- 元数据与来源清单可另行持久化，但本任务未授权创建那些实现资产。\n\n## 5. BMAD-Engineer 实施单测背压规范\n\n### 5.1 单测与对抗用例矩阵\n\n下表所有数字为合成测试夹具或本规范建议门禁，不是实测结果、默认经营阈值或论文原文数值。纯数学单测、校准模型验收和来源审计须分别报告。\n\n| 编号 | 验证对象与输入 | 预期结果与背压 |\n|---|---|---|\n| T01 | 幂律：$\\alpha=\\ln1000,\\beta=1,r=100$ | 估计 10 件/日；浮点相对误差≤$10^{-9}$。固定参数、固定输入保证复现。 |\n| T02 | BSR 1、100、1000，固定 $\\alpha,\\beta>0$；另输入 0、负数、布尔、null | 正排名下估计量严格递减；0、负数与布尔拒绝，null 阻塞，不能取对数后兜底为销量零。 |\n| T03 | 同类目已知销量留出集；样本来源、时间粒度和有效排名区间齐全 | 对数 RMSE=$\\sqrt{\\frac1n\\sum(\\ln\\widehat Q-\\ln Q)^2}$≤经确认的 $\\tau_{\\mathrm{fit}}$；超差阻塞。建议试验容差 0.2 须另获确认，不能当普适精度。 |\n| T04 | 校准已过期、跨类目/市场、目标排名越界、销量真值来自另一估计器 | 拒绝发布销量估计；不得沿用旧校准绿灯。单位从件/月误接件/日必须失败。 |\n| T05 | Top 10 均值 80，合成策略 $T_R=100$ | KQI=0.8，通过；均值恰好 100 时拒绝。9 个竞品、重复实体、缺评论数量时阻塞。 |\n| T06 | $S_0=100,S_1=120,r_{t-7}=100,r_t=80$ | 搜索增长 0.2、排名改善 0.2、KPI=0.2；验证排名下降代表改善的符号。 |\n| T07 | $S_0=0,S_1>0$；前期搜索缺 1 日；错把月查询量/趋势指数接入 | 零基期输出阻塞而非无穷大；29 日不算完整窗；错误单位或不透明估计方法拒绝。不得添加 epsilon 伪造可计算性。 |\n| T08 | $P=30$，完整成本合计 18 USD/件 | NM=0.4；金额分项及合计使用 Decimal，最终比例浮点相对误差≤$10^{-9}$。 |\n| T09 | 售价零、成本未知、币种混合、尾程费用重复、成本大于售价 | 零价拒绝物理筛选且净利指标阻塞；未知成本/币种错配阻塞；重复费用拒绝；亏损保持负净利率并触发失败门禁。 |\n| T10 | $P=30,W=0.5$ kg，$V=1000$ cm³ | VW=60 USD/kg；VV=0.03 USD/cm³；字段单位不能互换。重量/体积零、负数、NaN、无穷大均拒绝。 |\n| T11 | 极端轻泡货：包装 40×35×20 cm，重 0.2 kg，售价 30 USD；合成 $D=5000$ cm³/kg、运价 8 USD/kg，无进位 | $V=28000$；计费重量 5.6 kg；真实 VW=150，但计费 VW≈5.357142857；尾程 44.8 USD，仅尾程就使 NM<0，必须拒绝，不能被高 VW 抵消。 |\n| T12 | 同货物切换运输合同的体积除数或计费进位，或者缺失 $D$ | 必须采用明确合同版本；进位边界两侧使用独立黄金夹具；缺参数阻塞，不固定假设 5000 或 6000。 |\n| T13 | 单位互换：1 lb、1 in；三边次序任意 | 转换为 0.45359237 kg 与 2.54 cm；三边降序后再判门禁；换算误差≤$10^{-8}$ 相对容差。 |\n| T14 | 售价 20、70；三边恰好 18/14/8 in 或重量恰好 20 lb；超尺寸标签未知/冲突 | 售价端点通过；任一尺寸或重量端点拒绝；标签未知/冲突阻塞，不能声称符合当前官方分级。 |\n| T15 | 10 条差评含 15 个去重物理方面；同评论同方面重复出现 | RDD=1.5，合法；同评论同方面只计一次，多方面分别计；物流抱怨不冒充物理缺陷。 |\n| T16 | $N_c=0,M_-=0$；$N_c=0,M_->0$；缺原文、重复评论、未达最小样本 | 无差评密度阻塞，不输出 0；不可能的分子分母组合校验失败；原文不足或小样本阻塞。 |\n| T17 | LLM 输出“破损”标签但原文无对应片段；标签器更换版本 | 原文锚点审计失败；禁止发布该缺陷统计；版本变化重算受影响标签与统计，不能继承旧一致率。 |\n| T18 | 必需键缺失、额外字段、整数传布尔、未知单位、无时区时间、历史重复/未来日期 | 严格契约拒绝；真实缺失以显式 null＋缺失理由传递，不通过类型强制转换隐藏问题。 |\n| T19 | 任一 FAIL＋另一 BLOCKED；无 FAIL 但有 BLOCKED；全部 PASS | 分别为 REJECT、NEEDS_DATA、PASS_SCREEN；必需指标 BLOCKED 不得通过对应门禁。 |\n| T20 | 同父体评论接入变体重量、不同报价/时间/类目连接，或来源引用不可解析 | 血缘连接失败；不允许“类型合法但事实错接”的结果进入初筛。 |\n| T21 | 保存并重新加载同一原始快照、策略、标签与算子版本 | 数值在声明容差内相同；保留原始哈希与输入引用；不承诺外部 LLM 标签跨调用逐位复现。 |\n\n### 5.2 实施阶段门禁与证据\n\n1. 工程接管时建立新实施契约，绑定本提案版本、目标 Python/Pydantic 版本、业务阈值及输入样本；本分析工件不构成执行授权。\n2. 先创建相关契约、算子、来源清单校验与单测资产，再执行针对性验证；不附加无关业务测试。\n3. 证据必须包含真实命令、工作目录、依赖版本、退出状态、关键输出、样本/策略/算子版本以及失败用例定位。\n4. 任一必需测试失败、超时、缺依赖、来源未闭合或拟合证据不足，均停止推进；静态契约不能代替真实验证。\n\n拟议单测资产：[`test_competitor_lineage.py`](tests/test_competitor_lineage.py)，尚未创建；此链接仅表示候选位置，不证明文件存在。\n\n获准实施且资产创建后，候选验证命令为：\n\n```bash\ntimeout 30s python -m pytest -q tests/test_competitor_lineage.py < /dev/null\n```\n\n命令须由下游按实际环境确认可用性并串行前台执行；若超过 30 秒则拆分相关用例组，不删除断言。本阶段没有运行该命令，没有测试通过、官方费率确认、模型生产精度或运行时权限证据。\n\n### 5.3 交付裁决\n\n本规范达到“可交接的静态设计”阈值：六个必需决策指标、重量/体积命名消歧、旁路事实闭包、严格契约与失效背压均已定义。仍待工程与业务确认的事项是目标依赖版本、策略阈值、真实校准样本、物流报价、评论采样及来源审计；这些缺口不阻止提案交付，但阻止生产选品绿灯。\n\n没有发现可绑定的本地活动计划、项目事实基线或已接受 ADR 入口；根目录回执仅列出资料目录，因此本任务不恢复历史、不覆盖旧计划，也不把资料中的提案视为已生效决策。\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- 默认业务场景：Amazon 美国站、美元计价、同一细分类目、可区分变体的实体；其他市场必须重配费率、尺寸分级与校准参数。\n- 验证状态：本地资料有界静态检视；契约代码、拟议单测和命令均未运行。未知会话标识为 null。\n\n## 1. 顶层战略裁决\n\n### 1.1 目标、约束与非目标\n\n目标是把传统“看榜单盲目跟卖”改为“L1 可溯源状态事实 ➔ L2 清洗特征 ➔ L3 确定性数学算子”，先排除物理与单品经济学不可行商品，再根据需求、竞争阻力和可修复缺陷决定是否进入小批量验证。\n\n- 约束：缺失不等于零；排名不等于成交量；预测利润不等于竞品真实利润；评论缺陷不等于真实退货率。\n- 约束：大模型只能输出绑定原文的候选方面标签；数量、比率、费用及门禁必须由确定性代码计算。\n- 非目标一：不实施采集器、运营自动化、全自动选品或文案发布。\n- 非目标二：不训练模型，不绕过登录墙、访问控制或采集权限。\n- 非目标三：不预测平台内部推荐权重，不把 GEO 实验收益转写成真实流量或销量保证。\n- 非目标四：不运行终端、测试、构建、部署，不晋升或归档决策与计划。\n\n### 1.2 证据裁决与反证\n\n本地输入核对位置：[`bcec-gem.md`](_scratch/bcec-gem.md:154)、[`geo-2024.md`](_scratch/geo-2024.md:35)、[`geo-2026.md`](_scratch/geo-2026.md:220)。这些摘录是本次分析输入，不替代在线原版、生产流量实验或目标环境验证。\n\n| 主张 | 本次裁决 | 对规范的影响 |\n|---|---|---|\n| E-GEO 证明“2026 超过 60% 搜索零点击、推荐率提升 40% 以上” | 输入归因存在冲突。2024 摘录的“最高 40%”指生成式回答中的可见度；2026 摘录采用平均推荐排名改善，不能交换统计口径。零点击比例未在已检视 E-GEO 内容中获得对应证据。 | 不进入算子常数、门禁或收益承诺。 |\n| E-GEO 提供商品结构化事实可信度的通用评分公式 | 已检视内容强调事实保持、用户意图和可扫描结构，但不足以建立上述通用公式。Insufficient evidence. | 只规定来源覆盖与事实一致性审计，不发明论文原生可信度分数。 |\n| 基于 BSR 可以反推“真实销量” | 公开研究使用销售排名研究需求；排名是相对量，销量标定需要外部数量基准。[1](cite:1)[2](cite:2)[3](cite:3) | 对外名称保留业务需求，结果一律标记“校准后销量估计”，禁止标记真实成交量。 |\n| 四本书直接给出本规范所有阈值 | Fisher/Raman 的书目归属有公开书目支持；其余用户指定书目及精确阈值未取得足够原文页码证据。[10](cite:10) | 用户提供的经验口径与本规范提出的公式分别标识，不冒充原文定理。 |\n| BSR 的 7 天变化是平台推流核心、卖家类型可以推断 Buy Box | 当前证据不足以支持平台内部因果权重；卖家类型与 Buy Box 所属并非同一观测。Insufficient evidence. | 7 天排名变化仅作代理信号；Buy Box 必须另行采集。 |\n\n证据判断优先保留本地摘录中的指标定义，不沿用蒸馏摘要中无法闭合的因果与数值。用户指定的 $20–$70、尺寸与重量范围在本规范中作为内部候选策略，不宣称它们就是 Amazon 2026 官方分级。\n\n### 1.3 最小充分架构与闭包\n\n1. L1 保留商品核心记录及来源信封；重复快照形成历史，不允许历史回填覆盖原记录。\n2. L2 统一美元、英寸、千克和立方厘米，校验同市场、类目、实体、关键词、报价口径及时间窗。\n3. L3 使用版本化公式、校准参数、成本场景和业务策略计算；每个结果携带输入引用与可用性状态。\n4. 任一失败门禁输出“拒绝”；无失败但存在阻塞输出“待补数据”；全部通过仅输出“通过初筛”，不授权采购。\n\n必须补充而不混入 11 个核心字段的旁路事实：\n\n| 旁路输入 | 用途 | 最小证据要求 |\n|---|---|---|\n| 同实体历史商品快照 | 7 天 BSR 与两段 30 天搜索量 | 原始记录标识、时间窗、市场、类目、关键词、供应商方法版本。 |\n| 同类目 Top 10 竞品集合 | 市场评论阻力 | 按同一时点同类目 BSR 升序选取，固定恰好 10 个去重实体；声明父体/变体规则。 |\n| 已知销量与排名校准样本 | 幂律截距、斜率及留出误差 | 同市场、类目、时间粒度；真实已知销量来源，不以另一个 BSR 估计器当真值。 |\n| 候选单品成本账及物流报价 | 净利率、计费重量 | 采购、头程、尾程履约、平台费、仓储、广告、退货损失、税费及其他摊销；币种、时间、费率版本。 |\n| 2–3 星评论原文及方面标签 | 缺陷密度 | 评论标识、原文、星级、日期、实体范围、抽样方法、文本哈希、标签器版本和原文片段。 |\n| 业务策略 | 阈值及容差 | 评论阻力上限、最低净利率、物流最低货值比、最小评论样本和拟合误差上限，均需业务确认。 |\n\n品类穿透率还需要品类购买者与总体购买者数据；价格交叉弹性还需要跨商品价格及数量面板；加购率需要真实加购与曝光数据；库存损失需要需求分布与缺货/滞销成本。这些不在核心数据闭包内，不伪造附加算子。\n\n## 2. L1 物理事实采集清单\n\n这里的“物理事实”指可回溯的原始观测，不代表所有字段都是物理测量值。搜索量常是供应商估计，平台尺寸分级是报告标签；来源信封必须区分报告值与估计值。\n\n| L1 核心字段 | 单位及严格语义 | 首选来源 | 缺失与清洗规则 |\n|---|---|---|---|\n| `bsr_rank` | 同市场、同类目的正整数名次；1 最优 | 商品详情公开 BSR 或获准数据接口 | 0、负数非法；无榜单为 null；不同类目不可比较。 |\n| `search_volume` | 固定关键词与市场的查询次数/日；非指数、非销量 | 平台授权搜索分析或明确方法的供应商 | 月度量、Google Trends 指数不得悄悄当日查询量；仅能显式转换并保留估计方法。 |\n| `price_current` | USD/件；同一报价口径的商品售价，不含销售税 | 当前商品报价或获准价格接口 | 0 可表示异常/不可售报价，须拒绝初筛；缺报价为 null。 |\n| `price_history_90d` | 过去 90 个完整 UTC 日的日期—USD/件序列 | 获准历史价格接口或自有不可变快照 | 最多 90 个去重日；保留缺口，不用当前价回填。 |\n| `review_count` | 条；平台展示累计评论数量 | 商品页或获准接口 | 0 是真实无评论；未采集为 null；声明父体/变体聚合范围。 |\n| `rating_score` | 星；1–5 范围 | 商品页或获准接口 | 无评分为 null，不能用 0 代替。 |\n| `listing_age_days` | 日；截至快照日期的可验证上架年龄 | 可验证首次上架日期或平台记录 | 若只有首次观测日期，则真实上架年龄为 null，另记首次观测年龄。 |\n| `package_dimensions` | 三边正数，附 in 或 cm 单位；含包装尺寸 | 商品包装参数、供应商实测或履约资料 | 不以裸商品尺寸替代；L2 排序为长边≥中边≥短边。 |\n| `shipping_weight` | 正数，附 lb 或 kg；单件含包装重量 | 包装规格、称重或履约资料 | 不以净重替代；不可用 0 表示未知。 |\n| `is_oversize` | 严格布尔；来源报告的超尺寸标签 | 带版本的履约分级或供应商报告 | 未知为 null；与内部尺寸门禁分开保存，冲突进入复核。 |\n| `seller_type` | AMAZON / THIRD_PARTY_FBA / THIRD_PARTY_FBM / UNKNOWN | 卖家身份与履约方式的明确观测 | UNKNOWN 不代表第三方；不推断 Buy Box。 |\n\n所有 11 个键必须出现，允许值为 null；实体标识、时间、币种、字段级来源引用属于信封元数据，不计入 11 个业务字段。原始响应、字段定位、观测时间、哈希、采集器版本、估计方法及缺失原因必须由来源清单保存。\n\n## 3. 指标血缘 DAG 拓扑映射表\n\n### 3.1 算子约定\n\n- 固定换算：$1\\,\\mathrm{in}=2.54\\,\\mathrm{cm}$，$1\\,\\mathrm{lb}=0.45359237\\,\\mathrm{kg}$。\n- $r_t$ 是同类目当前 BSR；$r_{t-7}$ 是恰好 7 天前的同口径值。\n- $S_1$、$S_0$ 是最近及前一段互不重叠的 30 个完整 UTC 日的查询总量；两段各需 30 个有效日，真实零值保留。\n- $P$ 是候选定价场景采用的 USD 售价；$W$ 是含包装千克重量；$V$ 是包装立方厘米体积。\n- $T_R$、$m_{\\min}$、$h_{\\min}$、$N_{\\min}$ 和 $\\tau_{\\mathrm{fit}}$ 为经确认、版本化的策略参数；不存在文献通用默认值。\n- 下表中“本规范定义”均是设计提案，不是署名作者的原生公式或已验证的经营收益。\n\n| L3 指标名称 | 业务意义 | 依赖 L2 清洗特征 | 溯源 L1 物理字段 | 确定性数学公式 (LaTeX) | 决策门禁红线 (Hard Gates) | 文献/专著出处 |\n|---|---|---|---|---|---|---|\n| 帕累托真实销量反推：校准销量估计 | 估计件/日，不冒充真实成交 | 当前有效 BSR；同类目校准参数与留出误差 | 当前 `bsr_rank`；旁路已知销量样本 | $\\ln\\widehat Q=\\alpha-\\beta\\ln r_t$；$\\widehat Q=e^\\alpha r_t^{-\\beta}$ | $r_t>0$；校准未过期且覆盖目标排名区间；留出对数 RMSE≤$\\tau_{\\mathrm{fit}}$。无校准即阻塞。$\\beta\\in[0.8,1.2]$ 仅作为本任务候选策略，超界须重议，不声称跨品类普适。 | Chevalier & Goolsbee (2003) 为用户指定机制来源；公开排名研究与校准需求有支持。[1](cite:1)[2](cite:2)[3](cite:3) 区间并非本次查证出的原文常数。 |\n| 市场阻力指数 KQI_barrier | 量化同类目头部评论积累阻力，不等于完整竞争指数 | 同时点、去重 Top 10 评论均值；$T_R$ | 10 个竞品的 `bsr_rank`、`review_count`；信封中的类目及实体 | $\\bar R_{10}=\\frac{1}{10}\\sum_{i=1}^{10}R_i$；$\\mathrm{KQI}=\\bar R_{10}/T_R$ | 恰好 10 个有效竞品，$T_R>0$；KQI<1。不足 10 个或缺评论数量均阻塞。 | 用户指定《Product Research 101》评论漏斗；归一化公式为本规范定义，书目归属及精确阈值原文证据不足。 |\n| 需求动量 KPI_velocity | 合并搜索增长与排名改善的代理信号，不声称平台因果推流权重 | $S_1,S_0,r_t,r_{t-7}$；完整日覆盖 | 历史 `search_volume`、`bsr_rank`；`listing_age_days` 用于历史可得性检查 | $g_s=(S_1-S_0)/S_0$；$g_r=(r_{t-7}-r_t)/r_{t-7}$；$\\mathrm{KPI}=0.5g_s+0.5g_r$ | $S_0>0$、$r_{t-7}>0$；两个搜索窗各完整 30 日、BSR 两时点有效；KPI>0 才通过本版初筛。基期零为“无基期”阻塞，不加伪计数。 | Fisher/Raman 需求信号、Thomson/Hansen 平台机制为用户提供的概念线索；0.5 权重、公式及正值门禁为本规范提案。 |\n| 单品经济学净利率 Net_Margin | 候选 SKU、指定价格和成本场景的完全成本净利率 | USD 售价；完整单件成本分项；报价适用范围 | `price_current`、`price_history_90d`、`package_dimensions`、`shipping_weight`、`seller_type`；旁路采购/物流/平台/营销/税费账 | $C= C_{\\mathrm{goods}}+C_{\\mathrm{inbound}}+C_{\\mathrm{fulfillment}}+C_{\\mathrm{platform}}+C_{\\mathrm{storage}}+C_{\\mathrm{ads}}+C_{\\mathrm{return}}+C_{\\mathrm{tax}}+C_{\\mathrm{other}}$；$\\mathrm{NM}=(P-C)/P$ | $P>0$；所有成本分项显式且非负，同币种、同单件及同履约场景；NM≥$m_{\\min}$。成本未知不可默认为零。 | 本地输入的物理参数＋单品经济学原则；成本恒等式为本规范定义，不归为任一书的独有公式。 |\n| 货值重量比 Value_to_Weight | 衡量真实重量的货值承载；单位 USD/kg，不是体积比 | $P,W$；辅助物流计费重量与费率 | `price_current`、`shipping_weight`；物流辅助还依赖 `package_dimensions` 和旁路运价 | $\\mathrm{VW}=P/W$；$W_{\\mathrm{bill}}=\\max(W,V/D)$；$\\mathrm{VW}_{\\mathrm{bill}}=P/W_{\\mathrm{bill}}$ | $W>0,V>0,D>0$；按真实报价的进位规则计算运费；计费货值比≥$h_{\\min}$，且净利率门禁不得被高 VW 抵消。 | 物理门禁来自用户指定初筛原则；货值比与物流式为本规范定义。$D$ 是运价合同参数，不是平台通用常数。 |\n| 货值体积比：辅助指标 | 正式消除“货值体积比”与 Value_to_Weight 的命名冲突；单位 USD/cm³ | $P,V$ | `price_current`、`package_dimensions` | $\\mathrm{VV}=P/V$ | $V>0$；不与 USD/kg 比较或混排；仅作物流诊断，不单独给出选品绿灯。 | 本规范维度分析定义。 |\n| 差评退货缺陷密度 Review_Defect_Density | 每条 2–3 星评论平均提及的物理缺陷方面数量；不是退货概率 | 去重差评数 $N_c$；去重物理负面方面提及数 $M_-$；抽样及标签版本 | 11 字段仅提供实体/评论总量背景；必须另采评论原文、星级及方面标签，不能从 `rating_score` 或 `review_count` 反推 | $\\mathrm{RDD}=M_-/N_c$；$M_-=\\sum_{j=1}^{N_c}\\#\\{\\text{unique negative physical aspects in review }j\\}$ | $N_c\\ge N_{\\min}>0$；原文锚点完整、去重规则固定、样本方法披露。RDD 可大于 1；不设置“越高越好”绿灯，缺陷可修复且成本/安全审查通过才可立项。 | 用户指定 Hu & Liu 的方面挖掘机制；该比率、2–3 星范围及去重规则为本规范定义，不声称论文原生退货公式。 |\n\n### 3.2 拓扑与真理隔离\n\n1. 当前与历史商品记录 → 单位/时间/实体清洗 → BSR、搜索窗、价格、重量和体积特征 → 销量、阻力、动量、货值比。\n2. 包装特征＋版本化运价 → 计费重量与运费 → 完全成本账 → 净利率。只保存一次尾程费用，禁止在物流和利润中重复扣费。\n3. 评论原文 → 带原文片段的方面标签 → 确定性去重计数 → 缺陷密度。语义提取的不确定性不会因末端确定性除法而消失。\n4. 六个必需指标＋物理门禁＋业务策略 → 初筛状态。指标不能向上游反向修改原始事实；若需改款，建立新候选版本及新成本场景。\n\n内部物理门禁：$20\\le P\\le70$；包装三边排序后 $L<18\\,\\mathrm{in},M<14\\,\\mathrm{in},S<8\\,\\mathrm{in}$；含包装重 $W_{\\mathrm{lb}}<20$；来源超尺寸标签必须明确为否。恰好等于尺寸或重量边界即拒绝；标签未知或冲突阻塞复核。\n\n## 4. 数据契约定义\n\n### 4.1 契约与序列化边界\n\n以下是拟供 BMAD-Engineer 实现的 Pydantic V2 契约定义，仅存在于本分析文档，不是已创建的生产模块。严格模式、额外字段拒绝、有限数约束、显式 null 和跨字段一致性均属于拟议验收要求，尚未在目标依赖版本运行验证。\n\n- 原始字段名以本节代码为准；单位携带在量值对象中，美元币种固定在身份信封中。\n- Python 调用须传入 Decimal、日期、带时区时间和 tuple 等声明类型；外部 JSON 由专用适配器解析，金额使用十进制文本，禁止经过二进制浮点中转。\n- 每个来源引用必须解析到不可变来源清单，记录来源、原始定位、时间、哈希、方法版本、报告/估计状态与缺失原因；字符串引用存在不等于来源已经核验。\n- L2 不计算 L3；旁路成本、校准与评论数据必须先经过原始证据清洗，再显式注入，不能用模型默认值创造事实。\n- 同实体、同时间、同场景连接及公式复算需要下游算子和测试保障；数据类的形状校验不证明血缘正确或业务门禁已经执行。\n\n```python\nfrom datetime import date, datetime, timedelta\nfrom decimal import Decimal\nfrom typing import Annotated, Generic, Literal, TypeVar\n\nfrom pydantic import BaseModel, ConfigDict, Field, model_validator\n\nText = Annotated[str, Field(min_length=1, strict=True)]\nCount = Annotated[int, Field(ge=0, strict=True)]\nRank = Annotated[int, Field(ge=1, strict=True)]\nFinite = Annotated[float, Field(allow_inf_nan=False, strict=True)]\nPositive = Annotated[float, Field(gt=0, allow_inf_nan=False, strict=True)]\nNonnegative = Annotated[float, Field(ge=0, allow_inf_nan=False, strict=True)]\nMoney = Annotated[Decimal, Field(ge=0, max_digits=16, decimal_places=4,\n allow_inf_nan=False, strict=True)]\nRefs = Annotated[tuple[Text, ...], Field(min_length=1)]\nSeller = Literal['AMAZON', 'THIRD_PARTY_FBA', 'THIRD_PARTY_FBM', 'UNKNOWN']\n\n\nclass Contract(BaseModel):\n model_config = ConfigDict(strict=True, extra='forbid', frozen=True,\n validate_default=True, allow_inf_nan=False)\n\n\nclass Identity(Contract):\n product_id: Text\n marketplace: Literal['amazon_us']\n category_id: Text\n query_id: Text\n entity_scope: Literal['variant', 'parent']\n currency: Literal['USD']\n as_of: datetime\n manifest_ref: Text\n\n @model_validator(mode='after')\n def timezone_required(self):\n if self.as_of.utcoffset() is None:\n raise ValueError('as_of 必须带时区')\n if self.as_of.utcoffset() != timedelta(0):\n raise ValueError('as_of 必须为 UTC')\n return self\n\n\nclass Dimensions(Contract):\n unit: Literal['in', 'cm']\n length: Positive\n width: Positive\n height: Positive\n\n\nclass Weight(Contract):\n unit: Literal['lb', 'kg']\n value: Positive\n\n\nclass PricePoint(Contract):\n day: date\n price: Money\n source_ref: Text\n\n\nclass ProductL1RawRecord(Contract):\n identity: Identity\n raw_record_ref: Text\n field_sources: dict[Text, Text]\n bsr_rank: Rank | None = Field(...)\n search_volume: Count | None = Field(..., description='查询次数/UTC 日')\n price_current: Money | None = Field(..., description='USD/件，不含销售税')\n price_history_90d: tuple[PricePoint, ...] | None = Field(..., max_length=90)\n review_count: Count | None = Field(...)\n rating_score: Annotated[float, Field(ge=1, le=5, allow_inf_nan=False)] | None = Field(...)\n listing_age_days: Count | None = Field(...)\n package_dimensions: Dimensions | None = Field(...)\n shipping_weight: Weight | None = Field(...)\n is_oversize: bool | None = Field(...)\n seller_type: Seller | None = Field(...)\n\n @model_validator(mode='after')\n def raw_invariants(self):\n fields = set(type(self).model_fields) - {\n 'identity', 'raw_record_ref', 'field_sources'\n }\n if set(self.field_sources) != fields:\n raise ValueError('11 个核心字段均须有来源或缺失证据引用')\n points = self.price_history_90d\n if points is not None:\n days = tuple(p.day for p in points)\n if days != tuple(sorted(set(days))):\n raise ValueError('历史价格日期必须严格递增且去重')\n today = self.identity.as_of.date()\n if any(not today - timedelta(days=90) <= d < today for d in days):\n raise ValueError('历史价格须落在过去 90 个完整 UTC 日')\n return self\n\n\nclass CostInputs(Contract):\n scenario_id: Text\n source_refs: Refs\n goods_usd: Money\n inbound_usd: Money\n fulfillment_usd: Money\n platform_usd: Money\n storage_usd: Money\n ads_usd: Money\n return_loss_usd: Money\n tax_usd: Money\n other_usd: Money\n\n\nclass SalesCalibration(Contract):\n calibration_id: Text\n marketplace: Literal['amazon_us']\n category_id: Text\n quantity_unit: Literal['units_per_day']\n alpha: Finite\n beta: Annotated[float, Field(ge=0.8, le=1.2, allow_inf_nan=False)]\n rank_min: Rank\n rank_max: Rank\n known_sales_sample_count: Annotated[int, Field(ge=3)]\n holdout_log_rmse: Nonnegative\n valid_until: datetime\n source_refs: Refs\n\n @model_validator(mode='after')\n def calibration_invariants(self):\n if self.rank_min >= self.rank_max:\n raise ValueError('校准排名区间必须非退化')\n if self.valid_until.utcoffset() != timedelta(0):\n raise ValueError('校准有效期须带 UTC 时区')\n return self\n\n\nclass ScreeningPolicy(Contract):\n policy_id: Text\n review_mean_limit: Positive\n min_net_margin: Annotated[float, Field(ge=0, lt=1, allow_inf_nan=False)]\n min_billable_value_usd_per_kg: Positive\n min_critical_reviews: Annotated[int, Field(ge=1)]\n max_holdout_log_rmse: Positive\n source_refs: Refs\n\n\nclass ProductL2CleanedFeature(Contract):\n identity: Identity\n feature_ref: Text\n transform_version: Text\n source_refs: Refs\n price_usd: Money | None = Field(...)\n price_median_90d_usd: Money | None = Field(...)\n price_valid_days: Annotated[int, Field(ge=0, le=90)]\n bsr_now: Rank | None = Field(...)\n bsr_7d_ago: Rank | None = Field(...)\n search_recent_30d: Count | None = Field(...)\n search_previous_30d: Count | None = Field(...)\n search_recent_valid_days: Annotated[int, Field(ge=0, le=30)]\n search_previous_valid_days: Annotated[int, Field(ge=0, le=30)]\n top10_valid_count: Annotated[int, Field(ge=0, le=10)]\n top10_review_mean: Nonnegative | None = Field(...)\n package_dimensions_in: tuple[Positive, Positive, Positive] | None = Field(...)\n weight_kg: Positive | None = Field(...)\n weight_lb: Positive | None = Field(...)\n volume_cm3: Positive | None = Field(...)\n is_oversize_reported: bool | None = Field(...)\n seller_type: Seller | None = Field(...)\n volumetric_divisor_cm3_per_kg: Positive | None = Field(...)\n tariff_version: Text | None = Field(...)\n costs: CostInputs | None = Field(...)\n calibration: SalesCalibration | None = Field(...)\n critical_review_count: Count | None = Field(...)\n negative_physical_aspect_count: Count | None = Field(...)\n review_sampling_ref: Text | None = Field(...)\n\n @model_validator(mode='after')\n def cleaned_invariants(self):\n if self.top10_valid_count != 10 and self.top10_review_mean is not None:\n raise ValueError('Top 10 未完整时不允许发布头部均值')\n pairs = ((self.search_recent_30d, self.search_recent_valid_days),\n (self.search_previous_30d, self.search_previous_valid_days))\n if any(total is not None and days != 30 for total, days in pairs):\n raise ValueError('不完整搜索窗口不得发布完整窗口总量')\n dims = self.package_dimensions_in\n if dims is not None and not dims >= dims[1] >= dims[2]:\n raise ValueError('包装三边须降序排列')\n kg, lb = self.weight_kg, self.weight_lb\n if (kg is None) != (lb is None):\n raise ValueError('两种重量单位须同时可用或同时缺失')\n if kg is not None and abs(kg - lb * 0.45359237) > 1e-8 * max(1.0, kg):\n raise ValueError('重量换算不一致')\n if dims is not None and self.volume_cm3 is not None:\n expected = dims * dims[1] * dims[2] * 2.54 ** 3\n if abs(self.volume_cm3 - expected) > 1e-8 * max(1.0, expected):\n raise ValueError('体积换算不一致')\n n, m = self.critical_review_count, self.negative_physical_aspect_count\n if (n is None) != (m is None):\n raise ValueError('评论分子分母必须同时声明')\n if n == 0 and m != 0:\n raise ValueError('无差评时不可能存在缺陷提及')\n return self\n\n\nT = TypeVar('T')\n\n\nclass MetricResult(Contract, Generic[T]):\n value: T | None = Field(...)\n state: Literal['AVAILABLE', 'BLOCKED']\n reasons: tuple[Text, ...]\n source_refs: Refs\n\n @model_validator(mode='after')\n def availability_invariants(self):\n if self.state == 'AVAILABLE' and (self.value is None or self.reasons):\n raise ValueError('可用指标须有数值且无阻塞理由')\n if self.state == 'BLOCKED' and (self.value is not None or not self.reasons):\n raise ValueError('阻塞指标须为空值且有明确理由')\n return self\n\n\nclass GateResult(Contract):\n state: Literal['PASS', 'FAIL', 'BLOCKED']\n evidence_refs: Refs\n reasons: tuple[Text, ...]\n\n @model_validator(mode='after')\n def gate_reason_required(self):\n if self.state != 'PASS' and not self.reasons:\n raise ValueError('失败或阻塞门禁必须解释原因')\n return self\n\n\nclass ProductL3DecisionMetrics(Contract):\n identity: Identity\n feature_ref: Text\n operator_version: Text\n policy: ScreeningPolicy\n sales_estimate_units_per_day: MetricResult[Positive]\n kqi_barrier: MetricResult[Nonnegative]\n kpi_velocity: MetricResult[Finite]\n net_margin: MetricResult[Annotated[float, Field(le=1, allow_inf_nan=False)]]\n value_to_weight_usd_per_kg: MetricResult[Positive]\n value_to_volume_usd_per_cm3: MetricResult[Positive]\n billable_value_usd_per_kg: MetricResult[Positive]\n review_defect_density: MetricResult[Nonnegative]\n gates: dict[Text, GateResult]\n decision: Literal['REJECT', 'NEEDS_DATA', 'PASS_SCREEN']\n\n @model_validator(mode='after')\n def decision_invariants(self):\n required = {'physical', 'sales_fit', 'barrier', 'velocity',\n 'margin', 'logistics', 'defects'}\n if set(self.gates) != required:\n raise ValueError('必须提供全部七项门禁')\n binding = {\n 'sales_estimate_units_per_day': 'sales_fit',\n 'kqi_barrier': 'barrier', 'kpi_velocity': 'velocity',\n 'net_margin': 'margin', 'value_to_weight_usd_per_kg': 'logistics',\n 'billable_value_usd_per_kg': 'logistics',\n 'review_defect_density': 'defects',\n }\n for name, gate in binding.items():\n if getattr(self, name).state == 'BLOCKED' and self.gates[gate].state == 'PASS':\n raise ValueError('缺失必需指标不得通过对应门禁')\n states = {g.state for g in self.gates.values()}\n expected = ('REJECT' if 'FAIL' in states else\n 'NEEDS_DATA' if 'BLOCKED' in states else 'PASS_SCREEN')\n if self.decision != expected:\n raise ValueError('决策必须遵循失败优先、阻塞次之的规则')\n return self\n```\n\n### 4.2 禁止隐式补齐\n\n- 缺少成本、校准、历史窗、评论原文或业务策略时，不发布对应指标数值；若策略对象尚未获确认，暂不创建完整决策记录。\n- 净利率允许负数，不能裁剪为零；缺陷密度允许大于 1，不能误用概率范围约束。\n- 小样本无差评不能视为“无物理缺陷”；精选差评不代表全体顾客，报告不得声称总体退货率。\n- 90 天价格中位数只用于价格稳定性与场景复核，不替代当前价；历史不足 90 日要披露覆盖率，不伪造完整历史。\n- 元数据与来源清单可另行持久化，但本任务未授权创建那些实现资产。\n\n## 5. BMAD-Engineer 实施单测背压规范\n\n### 5.1 单测与对抗用例矩阵\n\n下表所有数字为合成测试夹具或本规范建议门禁，不是实测结果、默认经营阈值或论文原文数值。纯数学单测、校准模型验收和来源审计须分别报告。\n\n| 编号 | 验证对象与输入 | 预期结果与背压 |\n|---|---|---|\n| T01 | 幂律：$\\alpha=\\ln1000,\\beta=1,r=100$ | 估计 10 件/日；浮点相对误差≤$10^{-9}$。固定参数、固定输入保证复现。 |\n| T02 | BSR 1、100、1000，固定 $\\alpha,\\beta>0$；另输入 0、负数、布尔、null | 正排名下估计量严格递减；0、负数与布尔拒绝，null 阻塞，不能取对数后兜底为销量零。 |\n| T03 | 同类目已知销量留出集；样本来源、时间粒度和有效排名区间齐全 | 对数 RMSE=$\\sqrt{\\frac1n\\sum(\\ln\\widehat Q-\\ln Q)^2}$≤经确认的 $\\tau_{\\mathrm{fit}}$；超差阻塞。建议试验容差 0.2 须另获确认，不能当普适精度。 |\n| T04 | 校准已过期、跨类目/市场、目标排名越界、销量真值来自另一估计器 | 拒绝发布销量估计；不得沿用旧校准绿灯。单位从件/月误接件/日必须失败。 |\n| T05 | Top 10 均值 80，合成策略 $T_R=100$ | KQI=0.8，通过；均值恰好 100 时拒绝。9 个竞品、重复实体、缺评论数量时阻塞。 |\n| T06 | $S_0=100,S_1=120,r_{t-7}=100,r_t=80$ | 搜索增长 0.2、排名改善 0.2、KPI=0.2；验证排名下降代表改善的符号。 |\n| T07 | $S_0=0,S_1>0$；前期搜索缺 1 日；错把月查询量/趋势指数接入 | 零基期输出阻塞而非无穷大；29 日不算完整窗；错误单位或不透明估计方法拒绝。不得添加 epsilon 伪造可计算性。 |\n| T08 | $P=30$，完整成本合计 18 USD/件 | NM=0.4；金额分项及合计使用 Decimal，最终比例浮点相对误差≤$10^{-9}$。 |\n| T09 | 售价零、成本未知、币种混合、尾程费用重复、成本大于售价 | 零价拒绝物理筛选且净利指标阻塞；未知成本/币种错配阻塞；重复费用拒绝；亏损保持负净利率并触发失败门禁。 |\n| T10 | $P=30,W=0.5$ kg，$V=1000$ cm³ | VW=60 USD/kg；VV=0.03 USD/cm³；字段单位不能互换。重量/体积零、负数、NaN、无穷大均拒绝。 |\n| T11 | 极端轻泡货：包装 40×35×20 cm，重 0.2 kg，售价 30 USD；合成 $D=5000$ cm³/kg、运价 8 USD/kg，无进位 | $V=28000$；计费重量 5.6 kg；真实 VW=150，但计费 VW≈5.357142857；尾程 44.8 USD，仅尾程就使 NM<0，必须拒绝，不能被高 VW 抵消。 |\n| T12 | 同货物切换运输合同的体积除数或计费进位，或者缺失 $D$ | 必须采用明确合同版本；进位边界两侧使用独立黄金夹具；缺参数阻塞，不固定假设 5000 或 6000。 |\n| T13 | 单位互换：1 lb、1 in；三边次序任意 | 转换为 0.45359237 kg 与 2.54 cm；三边降序后再判门禁；换算误差≤$10^{-8}$ 相对容差。 |\n| T14 | 售价 20、70；三边恰好 18/14/8 in 或重量恰好 20 lb；超尺寸标签未知/冲突 | 售价端点通过；任一尺寸或重量端点拒绝；标签未知/冲突阻塞，不能声称符合当前官方分级。 |\n| T15 | 10 条差评含 15 个去重物理方面；同评论同方面重复出现 | RDD=1.5，合法；同评论同方面只计一次，多方面分别计；物流抱怨不冒充物理缺陷。 |\n| T16 | $N_c=0,M_-=0$；$N_c=0,M_->0$；缺原文、重复评论、未达最小样本 | 无差评密度阻塞，不输出 0；不可能的分子分母组合校验失败；原文不足或小样本阻塞。 |\n| T17 | LLM 输出“破损”标签但原文无对应片段；标签器更换版本 | 原文锚点审计失败；禁止发布该缺陷统计；版本变化重算受影响标签与统计，不能继承旧一致率。 |\n| T18 | 必需键缺失、额外字段、整数传布尔、未知单位、无时区时间、历史重复/未来日期 | 严格契约拒绝；真实缺失以显式 null＋缺失理由传递，不通过类型强制转换隐藏问题。 |\n| T19 | 任一 FAIL＋另一 BLOCKED；无 FAIL 但有 BLOCKED；全部 PASS | 分别为 REJECT、NEEDS_DATA、PASS_SCREEN；必需指标 BLOCKED 不得通过对应门禁。 |\n| T20 | 同父体评论接入变体重量、不同报价/时间/类目连接，或来源引用不可解析 | 血缘连接失败；不允许“类型合法但事实错接”的结果进入初筛。 |\n| T21 | 保存并重新加载同一原始快照、策略、标签与算子版本 | 数值在声明容差内相同；保留原始哈希与输入引用；不承诺外部 LLM 标签跨调用逐位复现。 |\n\n### 5.2 实施阶段门禁与证据\n\n1. 工程接管时建立新实施契约，绑定本提案版本、目标 Python/Pydantic 版本、业务阈值及输入样本；本分析工件不构成执行授权。\n2. 先创建相关契约、算子、来源清单校验与单测资产，再执行针对性验证；不附加无关业务测试。\n3. 证据必须包含真实命令、工作目录、依赖版本、退出状态、关键输出、样本/策略/算子版本以及失败用例定位。\n4. 任一必需测试失败、超时、缺依赖、来源未闭合或拟合证据不足，均停止推进；静态契约不能代替真实验证。\n\n拟议单测资产：[`test_competitor_lineage.py`](tests/test_competitor_lineage.py)，尚未创建；此链接仅表示候选位置，不证明文件存在。\n\n获准实施且资产创建后，候选验证命令为：\n\n```bash\ntimeout 30s python -m pytest -q tests/test_competitor_lineage.py < /dev/null\n```\n\n命令须由下游按实际环境确认可用性并串行前台执行；若超过 30 秒则拆分相关用例组，不删除断言。本阶段没有运行该命令，没有测试通过、官方费率确认、模型生产精度或运行时权限证据。\n\n### 5.3 交付裁决\n\n本规范达到“可交接的静态设计”阈值：六个必需决策指标、重量/体积命名消歧、旁路事实闭包、严格契约与失效背压均已定义。仍待工程与业务确认的事项是目标依赖版本、策略阈值、真实校准样本、物流报价、评论采样及来源审计；这些缺口不阻止提案交付，但阻止生产选品绿灯。\n\n没有发现可绑定的本地活动计划、项目事实基线或已接受 ADR 入口；根目录回执仅列出资料目录，因此本任务不恢复历史、不覆盖旧计划，也不把资料中的提案视为已生效决策。\n"}}