kangshifu-board/docs/workshop-decision-quality-20261109/before/references/research-library/data-contract.md

数据结构、分类与证据合同

规则：ksf.agent-data-rules.20261106.v1；数据库 ksf.voc-library.v2，检索 ksf.voc-retrieval.v2。现有结构沿用，不要求重建已入库资料。实际字段、字典、计数以当前 contract 为准。全部物理表及字段用 schema [--table 表名] 读取；离线完整字典为 research-data-dictionary.json，Agent入库见 full-schema-and-intake.md。

按研究对象分表

对象	实体 / 实表	关键维度与关联
商品链接	products / products	marketplace、brand_code、category_code、shop_id 独立；唯一键为接口族＋商品ID
包装与SKU规格	specs / specs	product_id、上游SKU、规格原文、克重、件数、核对依据；SKU未知不造ID
历史观察价	prices / prices、price_sources	product_id、人民币分、价格口径、来源观察时间；多次观察不覆盖旧价
电商评价	reviews / reviews	接口族＋商品ID＋评价ID唯一；product_id 精确关联，正文、追加、评分体系、购买规格、时间分列
社媒内容	social / social_posts、social_brand_mentions	平台＋内容ID；品牌只是提及关系，不是商品归属
政策和膳食文件	documents / policy_documents	文档ID、声明状态及截至日、生效日期、官方URL、可用正文
条款与应用	clauses / policy_clauses	document_id、条款位置、摘录、摘录类型、应用建议；建议不当法规原话
榜单线索	rankings / ranking_signals	商品＋榜单标识、排名、来源时间与覆盖口径；标识不证明完整榜单或增长趋势
采集覆盖	coverage / coverage_observations	商品、成功/受阻等状态、可用评价数、上游报告数量、历史是否完整

报告、项目、机会卡、配方方案与审核证据仍由 ksf-workshop-runtime 查业务库；底料和报告不是同一种实体。库之间用实际来源/证据引用关联，不能把SQLite编号冒充Parse对象编号。

分类要能解释，未知值保留

• 渠道和接口族分开：taobao 接口族可能含天猫或渠道未核商品，只有已确认 tmall 才满足天猫条件。数字ID均以字符串保存。
• 品牌先看来源明确属性，再用已登记的保守标题规则；不因店铺名称、采集关键词或同时提到某品牌就归属该品牌。分类依据保存在 classification_assertions，带来源、字段、方法和规则版本，不等于人工核验。
• 品类采用稳定code与字典定义，拌面为 banmian；热干面、面皮、炒面、汤面、挂面、拌面酱单列。用户明确包含相关类时分别查询并注明。杯/桶/袋是包装，非油炸是工艺/宣称，不代替食用方式分类。
• 用户限定的维度必须有值且精确满足。未限定的维度允许未知，不为了提高“准确率”把仍相关的数据全局丢弃。冲突或未知留 pending，Agent不改字典或原分类。
• 新批次复用同一字典和唯一键，先校验字段、外键、关联与质量，再生成新代际和索引；分类变更留依据与旧版，不边查边改。新数据类型首次接入需维护映射，不能强塞到商品表。

评价进入分析的条件

1. 必须按同接口族＋商品ID准确关联商品，昵称、相似标题、同店、单独itemId不够。
2. quality=analysis 排除默认文本、身份未核/错配及购买规格冲突。用户限定品类时，购买规格也须为 category_state=consistent；整条混合商品链接下的全部评价不能冒称该品类评价。
3. 链接下规格不明或冲突的记录用同样范围单独 quality=audit 查看，不掺进有效观点。购买规格缺失不能从商品标题补造。
4. 评论条数、去重文本数、关联商品数各自统计；均不是独立消费者数或销量。“三篇说量少”不能写“多数消费者认为量少”。同文不同ID保留原记录，可另报去重文本数。

结论必须能回到原件

追溯链：结论 → 实体与记录ID → source_record_id → source_records → assets / source_links → collection_requests / 原始ZIP。

分析引用至少保留实体、记录ID、商品或文档ID、source_record_id、原句、来源观察/发表/评价时间及未知标记、可得URL、generation。关键证据用 get 回读完整实体，再用 source 回读出处；列表最多带3条上游引用，source 才展开完整路径。

后台来源保留：原文件与1起始行号（旧SQLite用表＋行ID）、原载荷、记录/文件/ZIP SHA256、上游接口和请求追踪。不可得URL留空，以文件定位，不能生成看似真实的链接。技术指纹用于追溯，不必塞给员工看板正文。无关作者身份不输出。

时间分开：来源观察/发表/评价时间、采集请求时间、入库时间。没有时区不猜UTC，没有日期不拿入库日补。“时效未知”不等于过期。价格为历史观察，标题克重为候选，未核净重不算每100g价格。

快速查询与后续更新

• 字段先缩小范围：实体＋平台/品牌/品类/店铺/商品/时间；索引覆盖组合范围、品牌、品类、商品、店铺、文档及日期。
• 问题主题在上述范围内用中文FTS和有限同义组找候选，再核原句。政策用文件全文和条款，不把商品关键词套进政策条件。
• 总量与分布用 aggregate，字段可选值用 facets；不把第一页当全库。关键证据才展开 get/source 大载荷。分组结果 truncated=true 需说明统计展示不完整。
• 一次分析固定 generation，游标还绑定实体、条件和排序；当前库更新则报错重建受影响查询，不能拼接不同代际。运维绑定 KSF_LIBRARY_REGISTRY 后，下次新分析读同一 current.json，无需每次更新Skill。只有新增字段/类型/分类定义或查询能力时更新合同与Skill。