Yanting / report-notebooklm

研听 is a Phase 1 app and backend for turning global institutional research reports into structured Chinese reading and listening experiences.

This repository is prepared as a single Gitea handoff repository for product and engineering teams.

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.

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.

Read First

For human readers:

docs/PROJECT_OVERVIEW.md
docs/DECISIONS.md
docs/DEVELOPMENT_HISTORY.md
report-notebooklm-api/docs/HANDOFF.md
report-notebooklm-app/docs/HANDOFF.md

For agents:

AGENTS.md
docs/DECISIONS.md
Target subsystem README and runbook.

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.

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.

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.

Backend Quick Start

cd report-notebooklm-api
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# edit .env for your MySQL and Redis
alembic upgrade head
python scripts/import_seed_content.py
uvicorn app.main:app --reload --host <bind-host> --port <port>

Smoke checks:

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"

App Quick Start

cd report-notebooklm-app
flutter analyze
flutter test
flutter run -d chrome --dart-define=RNB_API_BASE=<api-base-url>

Android emulator:

flutter run -d <emulator-id> --dart-define=RNB_API_BASE=<emulator-api-base-url>

Verification

Backend:

cd report-notebooklm-api
source .venv/bin/activate
pytest -q

App:

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>

Documentation Boundary

This repository contains a code handoff snapshot. It does not replace the product source of truth.

Product SSOT: mall-docs report-notebooklm docs, snapshot date: 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.

4.1 KiB Raw Blame History