yanting/docs/DATA_SOURCE_FLOW.md

数据源流转说明 / Data Source Flow

这是一份交接快照，不是产品唯一真源（SSOT）。

产品 SSOT：mall-docs 的 report-notebooklm 文档，快照日期：2026-06-03。

本文把"研报从哪里来 → 怎么解读 → 存在哪里 → 怎么进 APP"这条链路一次讲清楚，并把之前文档里分散或缺失的部分（尤其是数据源清单与更新频率）补齐。涉及的具体实现细节请回到各子系统文档与 SSOT 核对。

---

1. 一图看懂：四层数据模型 + 端到端流转

研听的数据分四层。前两层是内部证据，对 APP 不可见；后两层是审核后的展示物，对 APP 可见。

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 1  报告源 Report Source                                        │
│  机构研报 PDF / 来源 URL / 机构元数据                                  │
│  └─ 来自公开官方源 / 授权伙伴源 / 灰色券商公开源                       │
└───────────────────────────────┬─────────────────────────────────────┘
                                 │  上传到 NotebookLM，源驱动解读
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 2  原始产物 Raw Artifact（内部，App 不可见）                    │
│  NotebookLM 原生 + 定向查询产物，全量保留                              │
│  └─ payload 存对象存储；DB 只存 metadata + payload_ref + sha256        │
└───────────────────────────────┬─────────────────────────────────────┘
                                 │  确定性组装 / 清洗 / 字段映射 + 人工审核
                                 │  （禁止本地 LLM 重写原文）
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 3  展示产物 Display Artifact（审核后，App 可见）                │
│  display_artifacts + display_modules（按 P0/P1/P2 分层的详情模块）     │
│  └─ 状态机：missing → raw_ready → review → approved → published        │
└───────────────────────────────┬─────────────────────────────────────┘
                                 │  只读公开 API
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 4  App 响应 App Response                                        │
│  列表 / 详情骨架 / 模块懒加载 / 音频签名 URL / 机构卡片                │
└─────────────────────────────────────────────────────────────────────┘

核心原则：APP 永远只消费 Layer 3/4 的"审核后展示物"，从不直接读 Layer 1/2 的原始 PDF 或 NotebookLM 原始产物。误请求原始产物应返回 RAW_ARTIFACT_NOT_EXPOSED（403）。

---

2. 数据源（Layer 1）

2.1 三类来源 / 三个可信层级

来源类别	可信层级	处理规则
官方公开源（监管机构、国际组织、行业组织）	tier_1	标准流程。
卖方研究 / 资管（投行、资管公司、数据商）	tier_2	标准流程。
灰色券商公开源	tier_3	更严格审核；来源 URL 展示受限，需走后端短期签名 URL；发布前必须合规/运营复核。
自家 / 授权合作源	按约定	暂空，后续接期货公司 / 券商内部研报时新增。

来源可作参考的历史经验来自 Vision 的源清单与源健康数据，但生产数据不得依赖本地 Vision 运行时、本地路径、本地缓存或本地账号状态。

2.2 研报 PDF 源清单与发布频率（补齐）

以下为 SSOT（vision-research-sources）中已启用的研报 PDF 源，按主题分组，含天然发布频率——这正是此前文档缺失的"PDF 更新频率"基线。频率列指源站自身的研报发布周期，不等于研听的解读 / 复读节奏（见第 6 节）。

贵金属专门机构

机构	代表报告	发布频率
World Gold Council（世界黄金协会）	Weekly Markets Monitor / Silver Lining	周
WPIC（世界铂金投资协会）	铂金季报	季
State Street（道富）	贵金属月度	月
ING	贵金属 / 外汇研究	不定期
Silver Institute（白银协会）	白银市场	年 / 不定期
HDFC Securities / Sharekhan	印度市场视角	不定期
Emirates NBD	中东 / 央行购金	不定期

跨资产 / 大宗宏观（卖方主力）

机构	代表报告	发布频率
Goldman Sachs（高盛研究）	大宗 / 宏观展望	年 / 不定期
J.P. Morgan（AM + PWM）	资产配置展望	年 / 不定期
Bloomberg Intelligence	跨资产	不定期
WisdomTree（EU + US）	大宗商品展望	不定期
Invesco（景顺）	ETF / 资产配置	年
World Bank（世界银行）	Commodity Markets Outlook / Pink Sheet	半年 / 双周（频率最高）

能源

机构	代表报告	发布频率
EIA（美国能源信息署）	Short-Term Energy Outlook	月
IEA（国际能源署）	Oil Market Report / Gas Market Report	月 / 季
OPEC（欧佩克）	年度展望	年
IEEJ（日本能源经济研究所）	能源经济	不定期
Policy Center（摩洛哥）	能源政策	不定期

矿企 / 工业金属 / 农产品

机构	代表报告	发布频率
USGS（美国地质调查局）	Mineral Commodity Summaries	年
USDA	WASDE 农产品供需	月（PDF 链接月度轮换）
Eldorado Gold / Pan American Silver	矿企季报	季

频率总览：周（WGC）→ 双周（WB Pink Sheet）→ 月（EIA / IEA OMR / USDA / State Street）→ 季（WPIC / IEA Gas / 矿企）→ 半年（WB CMO）→ 年（高盛 / JPM / Invesco / USGS / OPEC）。

口径优先级：实际入库表 > Vision config/research_report_sources.json 与 config/sources.yaml > 本文。本文是研听消费视角的聚合视图，会定期 stale，使用前请回源核对。

2.3 与种子数据的差异（重要）

后端 import_seed_content.py 里的 18 家机构是种子数据，不是生产清单。生产权威清单是 §2.2 的 ~31 家 PDF 源。此外：

• 种子里出现的 BIS / Fed / IMF 等，以及早期设计稿设想的 ECB / BOJ，不在已启用的研报源清单内——它们是设计设想或实验样本（如 NotebookLM 能力实验用的 BIS 季报），落地时以已启用清单为准。
• 上线前接入新源，应在 Vision 源配置（或后续研听自有源配置）里新增 source，并同步本文。

---

3. 机构信息（institutions 表）

字段	说明	App 可见	现状
name_cn / name_en	中英文名	是	已填
institution_type	7 类枚举：official / international_org / industry_org / bank_research / asset_manager / data_provider / partner	是	已填
source_tier	tier_1/2/3	是	已填
website_url	官网	是	已填
covered_topics	覆盖主题	是	已填
intro_cn	机构详情页简介	是	⚠️ 字段存在，逐家文本基本未写
credibility_note	可信度说明	是	⚠️ 仅有 WGC 一条样例

机构介绍现状：schema 完全支持 intro_cn + credibility_note，但 SSOT 中目前只有一条实际样例——WGC 的可信度说明："全球黄金行业组织，公开发布黄金需求与市场研究。" §2.2 各机构的"代表报告 / 主题"可作为撰写逐家简介的素材，但31 家逐家成段介绍文本仍是待补内容。

---

4. PDF → NotebookLM：解读与抓取内容结构（Layer 2）

4.1 解读工作流（推荐顺序）

1. 检查源 PDF：标题、机构、日期、页数、大小、报告类型。
2. 为一份报告源创建（或复用）一个 notebook；除非明确做多报告综述，否则一报告一 notebook。
3. 上传报告源。
4. 生成 P0 文本包：source description、原生 Briefing Doc、原生 Blog Post、data table、query dimensions、query key data、query divergence、query weaknesses。
5. 生成 P1 产物：query timeline、query related sources、Study Guide、mind map（若导出成功）。
6. 异步生成 P2 产物：infographic 候选、audio brief、research discovery。
7. 每步操作后写入 manifest，持久化每个产物状态。
8. 从已审核产物确定性组装展示模块。
9. 发布前人工审核。

工具链：NotebookLM CLI（nlm）创建 notebook、上传 source、生成并导出 artifacts；生产 worker 把 PDF 生产为 raw artifacts 并入库。

4.2 产物类型（16 类）与实测结构

一次实测（106 页机构季报样本）产出 16 类 artifact，15 成功、1 失败（mind map 导出失败），体量从 ~1KB 文本到 5.4MB 信息图、~75 秒音频不等。各类用途与发布约束：

Artifact 类型	用途	阻断发布	需人审
source_summary / notebook_summary	源 / notebook 级摘要	否	否
native_briefing_doc	原生简报文档	是	否
native_blog_post	原生博文	是	否
native_study_guide	FAQ / 学习指南 / 术语表	否	否
data_table	结构化表格（CSV）	是	否
mind_map	思维导图 / 图结构源	否	否
query_dimensions	分析维度	是	否
query_key_data	关键数据点	是	否
query_divergence	与共识的分歧	否	否
query_weaknesses	弱点与开放问题	否	否
query_timeline	时间线与转折点	否	否
query_related_sources	相关源候选	否	是
research_discovery	拓展队列	否	是
infographic	公开候选图	否	是
audio_brief	音频预览 / 音频源	否	否

最高价值层是 query 系产物（dimensions / key_data / divergence / weaknesses / timeline），体量最大、信息最密。

4.3 raw artifact 元数据结构（manifest → 数据库 raw_artifacts）

每条 artifact 记录持久化的字段：artifact_type、provider（默认 notebooklm）、payload_format、payload_ref（对象存储引用）、sha256、size_bytes、status（pending/ok/failed）、error、generated_at / ingested_at、is_publish_blocking、requires_human_review、quality_flags、retention_status，以及内部关联 ID（notebook / source / conversation——仅内部，绝不进 App 响应）。

4.4 抓取的两条硬规则

• 禁止本地 LLM 重写 NotebookLM 原文。流水线只能编排、清洗、校验、字段映射、确定性组装、人工裁剪；不得用本地改写凭空生成可发布内容。
• 引用页码需二次规范化：NotebookLM 引用可能给出研报印刷页码（≠ PDF 物理页码），UI 不暴露 raw page label，未规范化前不展示页标；保留 citation 作内部证据。

---

5. 存储与流转落点（Layer 2 → 3）

5.1 对象存储（阿里云 OSS）

原始 payload、音频、图片、超大模块内容都存 OSS，DB 只存引用键。约定前缀：

前缀	内容
rnb/raw/	NotebookLM 原始产物 payload
rnb/modules/	展示模块内容（大模块 content_ref）
rnb/audio/	音频资产
rnb/images/	信息图 / 图片

• raw payload 存 OSS，MySQL 仅存 payload_ref + metadata + sha256（内部）。
• 音频对象键 audio_assets.oss_key 内部不可见；播放 stream_url 由后端即时签发短期签名 URL（计划有效期 ~2 小时），不落库、无下载 URL。
• 大模块内容（如 mind map / infographic / 长表，>100KB）存 OSS，display_modules.content 只存 content_ref + content_etag。

⚠️ 当前实现状态：真实 OSS 签名与失效策略仍为 planned，本仓库 scaffold 未落地生产对象存储。

5.2 数据库表（schema = report_notebooklm，MySQL 8）

共 13 张表：institutions、reports、raw_artifacts、display_artifacts、display_modules、audio_assets、related_news、users、favorites、reading_history、saved_listens、playback_progress、outbound_events。

• 内容侧（已实现模型）：前 7 张。
• 用户态侧（已实现模型、API 多为 planned）：后 6 张。

5.3 raw → display 审核状态机

missing → raw_ready → review → approved → published
                                   ↑↓
                                 hidden

发布门槛：所有 is_publish_blocking=True 的 P0 模块均已 published，且来源署名与风险免责声明齐备、公开响应不含原始 payload / 本地路径 / NotebookLM 内部 ID / 账号信息。

---

6. 流转节奏（cadence）与已知缺口

把"频率"分成三个层次看，避免混淆：

层次	现状
A. 各源天然发布频率	✅ 已明确，见 §2.2（周 / 双周 / 月 / 季 / 半年 / 年）。
B. 单次 NotebookLM 生产压力策略	✅ 已实测：单账号串行（parallelism=1）、限速（~48 ops/小时量级）、按产物重量 60–150 秒冷却、不跑 slides/video、research discovery 不自动导入；一篇报告图文层约 20–30 分钟。
C. 研听自身的解读 / 复读 / 排产 cadence	❌ 未冻结——产品契约层没有定义"每篇研报多久复读一次""每天/每周解读多少篇""生产 runner 的 cron/触发节奏"。

内容量门槛（非频率，但相关）：

• 开发期种子：10–20 条 Report / 5–8 个 Institution / 3–5 条带音频。
• 上线前首批：30–50 条已审核研报解读，≥10 条带音频。

仍待补的缺口（建议下一步处理）：

1. 研听生产 cadence（C 层）：每篇研报的复读周期、每天/每周产量、生产 runner 调度节奏。Phase 1 的定位是"上线前批量跑一次最小内容集，不阻塞 App 开发"，持续 cadence 留给后续阶段（G5 服务端生产链迁移），目前仅"每周检查可发布数量"。
2. 机构逐家介绍文本：§3 的 intro_cn / credibility_note 31 家逐家内容。
3. 种子清单 vs 生产清单对齐：把 §2.2 的生产源清单沉淀为正式机构主数据，替换 18 家种子。

---

7. 进入 APP 的出口（Layer 4）

是的，最终是"进数据库 + 进对象存储"的双层落地，APP 通过只读 API 消费：

• 元数据与结构化模块内容 → MySQL（13 张表）。
• 原始 PDF、原始产物、音频、图片、超大模块 → 对象存储，DB 存引用键。
• 缓存 → Redis（feed/detail 缓存、播放进度去抖、限流）。

公开 API（前缀 /api/report-notebooklm/v1）：/feed/recommended、/reports、/reports/{id}（详情骨架）、/reports/{id}/modules/{module_id}（重模块全文懒加载）、/institutions、/institutions/{id}、/listen，以及计划中的 /audio/{id}/stream（短期签名 URL）。

详情页取数模型：骨架 + 模块懒加载——轻模块内联返回 content；重模块返回 preview，全文走二级端点或 content_ref，客户端用 content_etag 校验缓存。公开已发布内容可直读 content_ref；受限（灰色）来源走后端短期签名 URL。

内部生产链 API（service token + 网络白名单，绝不对 App 暴露）：POST /internal/reports/{id}/raw-artifacts、/display-artifacts、/publish、/hide 等。发布动作更新展示状态、刷新 has_audio、bump cache_version、清相关缓存键。

---

8. 相关文档

• 内容流水线细节：report-notebooklm-api/docs/CONTENT_PIPELINE.md
• API 与数据模型：report-notebooklm-api/docs/API_AND_DATA.md
• 运维与存储约定：report-notebooklm-api/docs/RUNBOOK.md
• 决策记录：docs/DECISIONS.md
• 产品 SSOT：mall-docs report-notebooklm 文档（数据源清单、构建 brief、数据模型契约、NotebookLM 能力实验报告）。