# 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:

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`

For agents:

1. `AGENTS.md`
2. `docs/DECISIONS.md`
3. 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

```bash
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:

```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"
```

## App Quick Start

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

Android emulator:

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

## Verification

Backend:

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

App:

```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>
```

## 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`.