jimme
6c72b7d048
- 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>
141 lines
4.1 KiB
Markdown
141 lines
4.1 KiB
Markdown
# 研听 / report-notebooklm
|
||
|
||
`研听` 是一个第一阶段（Phase 1）的应用和后端，用来把全球机构研报转化成结构化的中文阅读与收听体验。
|
||
|
||
这个仓库被整理成单个 Gitea 交接仓库，供产品和工程团队接手使用。
|
||
|
||
## 仓库里有什么
|
||
|
||
| 区域 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| 后端 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 调用说明。 |
|
||
|
||
## 产品速览
|
||
|
||
`研听` 帮助中文用户读懂全球机构研报，覆盖宏观、贵金属、大宗商品、能源、央行、跨资产等主题。
|
||
|
||
第一阶段聚焦在：
|
||
|
||
- 推荐：精选 / 最新的研报解读。
|
||
- 研报：研报列表和基础筛选。
|
||
- 机构：机构列表和机构详情。
|
||
- 听单：带音频的研报。
|
||
- 我的：游客 / 登录状态，以及浅层的个人状态入口。
|
||
|
||
第一阶段明确**不包含**：评论、UGC、付费解锁、会员、广告、交易信号、投资建议、研报解读下载。
|
||
|
||
## 先读这些
|
||
|
||
给人类读者：
|
||
|
||
1. `docs/PROJECT_OVERVIEW.md`
|
||
2. `docs/DECISIONS.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`
|
||
|
||
给 AI agent：
|
||
|
||
1. `AGENTS.md`
|
||
2. `docs/DECISIONS.md`
|
||
3. 对应子系统的 README 和运维手册。
|
||
|
||
## 当前实现状态
|
||
|
||
后端已实现：
|
||
|
||
- 挂在 `/api/report-notebooklm/v1` 下的 FastAPI 应用。
|
||
- 第一阶段数据表的 SQLAlchemy 模型层。
|
||
- Alembic 初始迁移。
|
||
- 种子数据导入脚本。
|
||
- 健康检查、信息流、研报、研报模块、机构、听单的对外只读接口。
|
||
- 针对种子数据和对外 API 行为的测试。
|
||
|
||
应用已实现：
|
||
|
||
- 五个底部标签页：推荐、研报、机构、听单、我的。
|
||
- 基于 `RNB_API_BASE` 的列表 / 详情视图。
|
||
- 研报详情的模块渲染器注册表。
|
||
- 登录、收藏、外链跳转确认、播放进度的本地占位实现。
|
||
- Android 和 Web 构建脚手架。
|
||
|
||
尚未达到生产可用：
|
||
|
||
- 鉴权和个人状态。
|
||
- 真实的音频流签名。
|
||
- 外链事件写入。
|
||
- 内部内容管理 API。
|
||
- 生产环境对象存储和缓存失效。
|
||
- 生产 API 域名、发布签名、最终应用图标、应用商店元信息。
|
||
|
||
## 后端快速上手
|
||
|
||
```bash
|
||
cd report-notebooklm-api
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -e ".[dev]"
|
||
cp .env.example .env
|
||
# 按你的 MySQL 和 Redis 编辑 .env
|
||
alembic upgrade head
|
||
python scripts/import_seed_content.py
|
||
uvicorn app.main:app --reload --host <bind-host> --port <port>
|
||
```
|
||
|
||
冒烟检查：
|
||
|
||
```bash
|
||
API_BASE_URL=http://<api-host>:<port>/api/report-notebooklm/v1
|
||
curl "$API_BASE_URL/health"
|
||
curl "$API_BASE_URL/feed/recommended"
|
||
curl "$API_BASE_URL/reports/rep_ssga_gold"
|
||
```
|
||
|
||
## 应用快速上手
|
||
|
||
```bash
|
||
cd report-notebooklm-app
|
||
flutter analyze
|
||
flutter test
|
||
flutter run -d chrome --dart-define=RNB_API_BASE=<api-base-url>
|
||
```
|
||
|
||
Android 模拟器：
|
||
|
||
```bash
|
||
flutter run -d <emulator-id> --dart-define=RNB_API_BASE=<emulator-api-base-url>
|
||
```
|
||
|
||
## 验证
|
||
|
||
后端：
|
||
|
||
```bash
|
||
cd report-notebooklm-api
|
||
source .venv/bin/activate
|
||
pytest -q
|
||
```
|
||
|
||
应用：
|
||
|
||
```bash
|
||
cd report-notebooklm-app
|
||
flutter analyze
|
||
flutter test
|
||
flutter build web --dart-define=RNB_API_BASE=<api-base-url>
|
||
flutter build apk --debug --dart-define=RNB_API_BASE=<emulator-api-base-url>
|
||
```
|
||
|
||
## 文档边界
|
||
|
||
这个仓库是一份代码交接快照，不能替代产品的唯一真源（SSOT）。
|
||
|
||
产品 SSOT：mall-docs 里的 report-notebooklm 文档，快照日期：2026-06-03。
|
||
|
||
仅限本机的笔记、私有路径、原始会话指针、个人 agent 工作流，都应放在被忽略的 `docs.jimme.local/` 和 `AGENTS.local.md` 里。
|