docs: add data source flow guide and localize handoff READMEs

- Add docs/DATA_SOURCE_FLOW.md: end-to-end source -> NotebookLM -> storage -> App flow, source list with publish frequency, institution intro status, ingestion artifact structure, and known cadence gaps - Link the new doc from README and PROJECT_OVERVIEW indexes - Localize top-level and subproject READMEs to Chinese for handoff (pre-existing working-tree changes) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-03 13:30:53 +09:00
parent 556f366894
commit 6c72b7d048
5 changed files with 386 additions and 115 deletions
@@ -0,0 +1,269 @@
+# 数据源流转说明 / 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 能力实验报告）。
@@ -40,5 +40,6 @@ NotebookLM-native content may be cleaned, mapped, reviewed, and assembled determ
 - `AGENTS.md`: public agent instructions.
 - `docs/DECISIONS.md`: durable decisions.
 - `docs/DEVELOPMENT_HISTORY.md`: major change history.
+- `docs/DATA_SOURCE_FLOW.md`: end-to-end data source flow, source list with publish frequency, and storage/ingestion path.
 - `report-notebooklm-api/docs/`: backend, data, API, and content pipeline details.
 - `report-notebooklm-app/docs/`: App runbook and API consumption notes.