From 6c72b7d048e560ec5d5579afe53b80858e26b357 Mon Sep 17 00:00:00 2001 From: JIMME Date: Wed, 3 Jun 2026 13:30:53 +0900 Subject: [PATCH] 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 --- README.md | 119 +++++++------- docs/DATA_SOURCE_FLOW.md | 269 ++++++++++++++++++++++++++++++++ docs/PROJECT_OVERVIEW.md | 1 + report-notebooklm-api/README.md | 40 ++--- report-notebooklm-app/README.md | 72 ++++----- 5 files changed, 386 insertions(+), 115 deletions(-) create mode 100644 docs/DATA_SOURCE_FLOW.md diff --git a/README.md b/README.md index d80a3c6..2c8ac1e 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,79 @@ -# Yanting / report-notebooklm +# 研听 / report-notebooklm -`研听` is a Phase 1 app and backend for turning global institutional research reports into structured Chinese reading and listening experiences. +`研听` 是一个第一阶段（Phase 1）的应用和后端，用来把全球机构研报转化成结构化的中文阅读与收听体验。 -This repository is prepared as a single Gitea handoff repository for product and engineering teams. +这个仓库被整理成单个 Gitea 交接仓库，供产品和工程团队接手使用。 -## What Is In This Repository +## 仓库里有什么 -| Area | Path | Description | +| 区域 | 路径 | 说明 | |---|---|---| -| Backend API | `report-notebooklm-api/` | FastAPI service, MySQL models, Alembic migration, seed importer, public read API. | -| Flutter App | `report-notebooklm-app/` | Flutter client with five main tabs, report detail modules, Android/web scaffolds. | -| Repo docs | `docs/` | Project-level overview, decisions, development history, and handoff guidance. | -| Backend docs | `report-notebooklm-api/docs/` | API/data/content-pipeline/runbook details. | -| App docs | `report-notebooklm-app/docs/` | App runbook, project map, and API consumption notes. | +| 后端 API | `report-notebooklm-api/` | FastAPI 服务、MySQL 模型、Alembic 迁移、种子数据导入、对外只读 API。 | +| Flutter 应用 | `report-notebooklm-app/` | Flutter 客户端，包含五个主标签页、研报详情模块、Android/Web 脚手架。 | +| 仓库文档 | `docs/` | 项目级概览、决策记录、开发历程和交接指南。 | +| 后端文档 | `report-notebooklm-api/docs/` | API、数据、内容流水线、运维手册的细节。 | +| 应用文档 | `report-notebooklm-app/docs/` | 应用运维手册、项目地图、API 调用说明。 | -## Product Snapshot +## 产品速览 -`研听` helps Chinese users understand global institutional research reports across macro, precious metals, commodities, energy, central banks, and cross-asset topics. +`研听` 帮助中文用户读懂全球机构研报，覆盖宏观、贵金属、大宗商品、能源、央行、跨资产等主题。 -Phase 1 focuses on: +第一阶段聚焦在： -- 推荐: curated/latest report interpretations. -- 研报: report list and basic filtering. -- 机构: institution list and institution detail. -- 听单: reports that have audio. -- 我的: guest/login state and shallow personal-state entries. +- 推荐：精选 / 最新的研报解读。 +- 研报：研报列表和基础筛选。 +- 机构：机构列表和机构详情。 +- 听单：带音频的研报。 +- 我的：游客 / 登录状态，以及浅层的个人状态入口。 -Phase 1 explicitly does not include comments, UGC, paid unlocks, membership, ads, trading signals, investment advice, or report-interpretation downloads. +第一阶段明确**不包含**：评论、UGC、付费解锁、会员、广告、交易信号、投资建议、研报解读下载。 -## Read First +## 先读这些 -For human readers: +给人类读者： 1. `docs/PROJECT_OVERVIEW.md` 2. `docs/DECISIONS.md` -3. `docs/DEVELOPMENT_HISTORY.md` -4. `report-notebooklm-api/docs/HANDOFF.md` -5. `report-notebooklm-app/docs/HANDOFF.md` +3. `docs/DATA_SOURCE_FLOW.md` +4. `docs/DEVELOPMENT_HISTORY.md` +5. `report-notebooklm-api/docs/HANDOFF.md` +6. `report-notebooklm-app/docs/HANDOFF.md` -For agents: +给 AI agent： 1. `AGENTS.md` 2. `docs/DECISIONS.md` -3. Target subsystem README and runbook. +3. 对应子系统的 README 和运维手册。 -## Current Implementation Status +## 当前实现状态 -Backend implemented: +后端已实现： -- FastAPI app under `/api/report-notebooklm/v1`. -- SQLAlchemy model layer for Phase 1 tables. -- Alembic initial migration. -- Seed import script. -- Public read endpoints for health, feed, reports, report modules, institutions, and listen list. -- Tests for seed and public API behavior. +- 挂在 `/api/report-notebooklm/v1` 下的 FastAPI 应用。 +- 第一阶段数据表的 SQLAlchemy 模型层。 +- Alembic 初始迁移。 +- 种子数据导入脚本。 +- 健康检查、信息流、研报、研报模块、机构、听单的对外只读接口。 +- 针对种子数据和对外 API 行为的测试。 -App implemented: +应用已实现： -- Five bottom tabs: 推荐, 研报, 机构, 听单, 我的. -- API-backed list/detail views using `RNB_API_BASE`. -- Report detail module renderer registry. -- Local placeholders for login, favorites, outbound confirmation, and playback progress. -- Android and web build scaffolds. +- 五个底部标签页：推荐、研报、机构、听单、我的。 +- 基于 `RNB_API_BASE` 的列表 / 详情视图。 +- 研报详情的模块渲染器注册表。 +- 登录、收藏、外链跳转确认、播放进度的本地占位实现。 +- Android 和 Web 构建脚手架。 -Not production-ready yet: +尚未达到生产可用： -- Auth and personal state. -- Real audio stream signing. -- Outbound event writing. -- Internal content management API. -- Production object storage and cache invalidation. -- Production API domain, release signing, final app icon, and store metadata. +- 鉴权和个人状态。 +- 真实的音频流签名。 +- 外链事件写入。 +- 内部内容管理 API。 +- 生产环境对象存储和缓存失效。 +- 生产 API 域名、发布签名、最终应用图标、应用商店元信息。 -## Backend Quick Start +## 后端快速上手 ```bash cd report-notebooklm-api @@ -80,13 +81,13 @@ python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" cp .env.example .env -# edit .env for your MySQL and Redis +# 按你的 MySQL 和 Redis 编辑 .env alembic upgrade head python scripts/import_seed_content.py uvicorn app.main:app --reload --host --port ``` -Smoke checks: +冒烟检查： ```bash API_BASE_URL=http://:/api/report-notebooklm/v1 @@ -95,7 +96,7 @@ curl "$API_BASE_URL/feed/recommended" curl "$API_BASE_URL/reports/rep_ssga_gold" ``` -## App Quick Start +## 应用快速上手 ```bash cd report-notebooklm-app @@ -104,15 +105,15 @@ flutter test flutter run -d chrome --dart-define=RNB_API_BASE= ``` -Android emulator: +Android 模拟器： ```bash flutter run -d --dart-define=RNB_API_BASE= ``` -## Verification +## 验证 -Backend: +后端： ```bash cd report-notebooklm-api @@ -120,7 +121,7 @@ source .venv/bin/activate pytest -q ``` -App: +应用： ```bash cd report-notebooklm-app @@ -130,10 +131,10 @@ flutter build web --dart-define=RNB_API_BASE= flutter build apk --debug --dart-define=RNB_API_BASE= ``` -## Documentation Boundary +## 文档边界 -This repository contains a code handoff snapshot. It does not replace the product source of truth. +这个仓库是一份代码交接快照，不能替代产品的唯一真源（SSOT）。 -Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03. +产品 SSOT：mall-docs 里的 report-notebooklm 文档，快照日期：2026-06-03。 -Local-only notes, private paths, raw session pointers, and personal agent workflow belong in ignored `docs.jimme.local/` and `AGENTS.local.md`. +仅限本机的笔记、私有路径、原始会话指针、个人 agent 工作流，都应放在被忽略的 `docs.jimme.local/` 和 `AGENTS.local.md` 里。 diff --git a/docs/DATA_SOURCE_FLOW.md b/docs/DATA_SOURCE_FLOW.md new file mode 100644 index 0000000..f4755d9 --- /dev/null +++ b/docs/DATA_SOURCE_FLOW.md @@ -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 能力实验报告）。 diff --git a/docs/PROJECT_OVERVIEW.md b/docs/PROJECT_OVERVIEW.md index 05ee53d..7594c4b 100644 --- a/docs/PROJECT_OVERVIEW.md +++ b/docs/PROJECT_OVERVIEW.md @@ -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. diff --git a/report-notebooklm-api/README.md b/report-notebooklm-api/README.md index 041f127..958e0a6 100644 --- a/report-notebooklm-api/README.md +++ b/report-notebooklm-api/README.md @@ -1,30 +1,30 @@ # report-notebooklm-api -FastAPI service for the report-notebooklm Phase 1 public read surface. +report-notebooklm 第一阶段对外只读接口的 FastAPI 服务。 -This directory is the main engineering handoff entry for API, data model, seed import, and the NotebookLM-backed content pipeline. The companion Flutter app lives in `../report-notebooklm-app/` in the same monorepo. +这个目录是 API、数据模型、种子数据导入，以及由 NotebookLM 支撑的内容流水线的主要工程交接入口。配套的 Flutter 应用在同一个 monorepo 的 `../report-notebooklm-app/` 里。 -## Read First +## 先读这些 -- [docs/HANDOFF.md](docs/HANDOFF.md): current progress, solved issues, open issues, and handoff order. -- [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md): product and Phase 1 scope snapshot. -- [docs/API_AND_DATA.md](docs/API_AND_DATA.md): data tables, endpoints, implemented vs planned API. -- [docs/CONTENT_PIPELINE.md](docs/CONTENT_PIPELINE.md): report source and NotebookLM artifact flow. -- [docs/RUNBOOK.md](docs/RUNBOOK.md): local setup, seed import, smoke checks, and deployment checks. -- [docs/ROADMAP_AND_OPEN_ISSUES.md](docs/ROADMAP_AND_OPEN_ISSUES.md): next engineering work. -- [docs/SOURCE_INDEX.md](docs/SOURCE_INDEX.md): source document names used for this handoff snapshot. +- [docs/HANDOFF.md](docs/HANDOFF.md)：当前进度、已解决的问题、待解决的问题，以及交接顺序。 +- [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md)：产品和第一阶段范围速览。 +- [docs/API_AND_DATA.md](docs/API_AND_DATA.md)：数据表、接口，以及已实现 / 计划中的 API。 +- [docs/CONTENT_PIPELINE.md](docs/CONTENT_PIPELINE.md)：研报来源和 NotebookLM 产物的流转。 +- [docs/RUNBOOK.md](docs/RUNBOOK.md)：本地搭建、种子数据导入、冒烟检查和部署检查。 +- [docs/ROADMAP_AND_OPEN_ISSUES.md](docs/ROADMAP_AND_OPEN_ISSUES.md)：下一步的工程工作。 +- [docs/SOURCE_INDEX.md](docs/SOURCE_INDEX.md)：本次交接快照所用到的源文档名称。 -## Product Boundary +## 产品边界 -This repo contains code and an engineering handoff snapshot. It is not the product source of truth. +这个仓库装的是代码和一份工程交接快照，不是产品的唯一真源。 -Product SSOT: mall-docs report-notebooklm docs. Snapshot date: 2026-06-03. +产品 SSOT：mall-docs 里的 report-notebooklm 文档。快照日期：2026-06-03。 -Use `report-notebooklm` and `rnb` for technical identifiers. The user-facing product name is `研听`. +技术标识符用 `report-notebooklm` 和 `rnb`，面向用户的产品名是 `研听`。 -## Local Quick Start +## 本地快速上手 -Create a `.env` file with the backend services available to your environment: +按你环境里可用的后端服务，创建一个 `.env` 文件： ```bash RNB_DATABASE_URL=mysql+asyncmy://:@:/report_notebooklm @@ -32,7 +32,7 @@ RNB_REDIS_URL=redis://:/0 RNB_REDIS_KEY_PREFIX=rnb: ``` -Then run: +然后运行： ```bash python -m venv .venv @@ -43,16 +43,16 @@ python scripts/import_seed_content.py uvicorn app.main:app --reload --host --port ``` -API prefix: `/api/report-notebooklm/v1` +API 前缀：`/api/report-notebooklm/v1` -## Verify +## 验证 ```bash source .venv/bin/activate pytest -q ``` -Recommended smoke checks after the service starts: +服务启动后，建议做这些冒烟检查： ```bash API_BASE_URL=http://:/api/report-notebooklm/v1 diff --git a/report-notebooklm-app/README.md b/report-notebooklm-app/README.md index 2a92677..78f0cda 100644 --- a/report-notebooklm-app/README.md +++ b/report-notebooklm-app/README.md @@ -1,54 +1,54 @@ # report-notebooklm-app -Flutter client for the report-notebooklm Phase 1 app shell. +report-notebooklm 第一阶段应用外壳的 Flutter 客户端。 -The backend API lives in `../report-notebooklm-api/` in the same monorepo. API/data/content-pipeline details are documented there; this directory focuses on App handoff, UI state, build commands, and integration notes. +后端 API 在同一个 monorepo 的 `../report-notebooklm-api/` 里。API、数据、内容流水线的细节都记在那边；这个目录专注于应用交接、UI 状态、构建命令和对接说明。 -## Read First +## 先读这些 -- [docs/HANDOFF.md](docs/HANDOFF.md): current App state, implemented screens, placeholders, and next work. -- [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md): product and Phase 1 scope snapshot. -- [docs/APP_RUNBOOK.md](docs/APP_RUNBOOK.md): Flutter version, local run, web build, Android debug build, and verification. -- [docs/API_CONTRACT_NOTES.md](docs/API_CONTRACT_NOTES.md): endpoints and fields consumed by the App. -- [docs/PROJECT_MAP.md](docs/PROJECT_MAP.md): source tree map. +- [docs/HANDOFF.md](docs/HANDOFF.md)：当前应用状态、已实现的页面、占位项，以及下一步工作。 +- [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md)：产品和第一阶段范围速览。 +- [docs/APP_RUNBOOK.md](docs/APP_RUNBOOK.md)：Flutter 版本、本地运行、Web 构建、Android 调试构建和验证。 +- [docs/API_CONTRACT_NOTES.md](docs/API_CONTRACT_NOTES.md)：应用所消费的接口和字段。 +- [docs/PROJECT_MAP.md](docs/PROJECT_MAP.md)：源码目录地图。 -## Product Boundary +## 产品边界 -This repo contains App code and an engineering handoff snapshot. It is not the product source of truth. +这个仓库装的是应用代码和一份工程交接快照，不是产品的唯一真源。 -Product SSOT: mall-docs report-notebooklm docs. Snapshot date: 2026-06-03. +产品 SSOT：mall-docs 里的 report-notebooklm 文档。快照日期：2026-06-03。 -Use `report-notebooklm` and `rnb` for technical identifiers. The user-facing product name is `研听`. +技术标识符用 `report-notebooklm` 和 `rnb`，面向用户的产品名是 `研听`。 -## Requirements +## 环境要求 -- Flutter 3.44.1 / Dart 3.12.1 or compatible newer versions. -- A running backend that serves `/api/report-notebooklm/v1`. -- For Android builds: Android SDK, accepted licenses, and an emulator or device. +- Flutter 3.44.1 / Dart 3.12.1，或兼容的更新版本。 +- 一个正在运行、提供 `/api/report-notebooklm/v1` 的后端。 +- 做 Android 构建还需要：Android SDK、已接受的许可协议，以及一台模拟器或真机。 -## API Base URL +## API 基础地址 -The App intentionally has no built-in live API default. Pass the backend base URL explicitly: +应用刻意不内置任何线上 API 默认值。请显式传入后端基础地址： ```bash flutter run -d chrome --dart-define=RNB_API_BASE= ``` -Android emulator: +Android 模拟器： ```bash flutter run -d --dart-define=RNB_API_BASE= ``` -Same-network Android device: +同一局域网内的 Android 真机： ```bash flutter run -d --dart-define=RNB_API_BASE=http://:/api/report-notebooklm/v1 ``` -Only use cleartext HTTP for debug builds. Release builds must use HTTPS. +明文 HTTP 只能用于调试构建。发布构建必须使用 HTTPS。 -## Verify +## 验证 ```bash flutter analyze @@ -57,21 +57,21 @@ flutter build web --dart-define=RNB_API_BASE= flutter build apk --debug --dart-define=RNB_API_BASE= ``` -## Current App Scope +## 当前应用范围 -Implemented: +已实现： -- Five bottom tabs: 推荐, 研报, 机构, 听单, 我的. -- API-backed feed, report list, institution list, listen list, institution detail, and report detail. -- Module renderer registry for inline and card-plus-page modules. -- Product display name `研听`. -- Local UI placeholders for login, favorite, outbound confirmation, and playback progress. +- 五个底部标签页：推荐、研报、机构、听单、我的。 +- 基于 API 的信息流、研报列表、机构列表、听单、机构详情和研报详情。 +- 用于内联模块和「卡片 + 页面」模块的模块渲染器注册表。 +- 产品显示名 `研听`。 +- 登录、收藏、外链跳转确认、播放进度的本地 UI 占位。 -Not implemented yet: +尚未实现： -- Real auth. -- Real favorite/history/saved-listen sync. -- Real playable audio stream. -- Real outbound event write. -- Production API domain. -- Release signing, final icon, and final store metadata. +- 真实鉴权。 +- 真实的收藏 / 历史 / 收听记录同步。 +- 真正可播放的音频流。 +- 真实的外链事件写入。 +- 生产 API 域名。 +- 发布签名、最终图标和最终应用商店元信息。