chore: prepare yanting monorepo handoff

report-notebooklm-api/docs/API_AND_DATA.md

@@ -0,0 +1,185 @@
+# API and Data Handoff
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+## Current Implementation Status
+
+Implemented in this repository:
+
+- FastAPI app under `/api/report-notebooklm/v1`.
+- SQLAlchemy model layer for the Phase 1 table set.
+- Alembic initial migration.
+- Seed import script with institutions, reports, modules, audio assets, users, favorites, and playback-progress fixtures.
+- Public read endpoints for health, feeds, reports, modules, institutions, and listen list.
+- Tests covering seed counts, public response shape, module visibility, gray-source handling, and listen behavior.
+
+Not implemented yet:
+
+- Auth APIs.
+- Personal state APIs.
+- Audio stream signing endpoint.
+- Outbound events endpoint.
+- Internal management APIs.
+- Real Redis cache invalidation policy.
+- Real object-storage signed URL policy.
+- Production pagination/cursor behavior beyond seed-scale responses.
+
+## Data Tables
+
+| Table | Purpose | Current model |
+|---|---|---|
+| `institutions` | Institution profile, source tier, website, topics, credibility notes. | Implemented |
+| `reports` | Report master record, source, topics, publication state, cache version. | Implemented |
+| `raw_artifacts` | NotebookLM artifact metadata and object-storage references. | Implemented as metadata only |
+| `display_artifacts` | Reviewed display version metadata for App consumption. | Implemented |
+| `display_modules` | Detail-page modules, sort order, visibility, content or content reference. | Implemented |
+| `audio_assets` | Audio metadata and object-storage key. | Implemented |
+| `related_news` | Related-source candidates and reviewed related items. | Implemented |
+| `users` | User account records. | Implemented as seed model, no auth routes |
+| `favorites` | User report favorites. | Implemented as seed model, no API routes |
+| `reading_history` | User reading/history events. | Implemented as model, no API routes |
+| `saved_listens` | User saved-listen records. | Implemented as model, no API routes |
+| `playback_progress` | Playback progress sync records. | Implemented as seed model, no API routes |
+| `outbound_events` | External attribution events. | Implemented as model, no API route |
+
+## Public API Implemented
+
+Prefix: `/api/report-notebooklm/v1`
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/health` | Service health. |
+| `GET` | `/feed/recommended` | Published report cards for recommendation feed. |
+| `GET` | `/reports` | Published report cards with basic filters. |
+| `GET` | `/reports/{report_id}` | Report detail skeleton and published modules. |
+| `GET` | `/reports/{report_id}/modules/{module_id}` | Full content for a visible module. |
+| `GET` | `/institutions` | Active institution list. |
+| `GET` | `/institutions/{institution_id}` | Institution detail with latest/recent reports. |
+| `GET` | `/listen` | Published audio-backed report list. |
+
+Current filters:
+
+- `/reports`: `topic`, `institution_id`, `has_audio`, `source_tier`, `q`, `page_size`.
+- `/institutions`: `topic`, `source_tier`, `page_size`.
+- `/feed/recommended` and `/listen`: `page_size`.
+
+Current pagination is seed-scale. Responses return `next_cursor: null` and `has_more: false`.
+
+## Planned Public API
+
+The Phase 1 contract also expects:
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/audio/{audio_id}/stream` | Return short-lived playable URL. |
+| `POST` | `/outbound/events` | Persist external attribution click event. |
+
+Audio stream must not return a permanent object-storage URL. The planned behavior is backend-signed short-lived playback URL with no download URL.
+
+## Planned Auth and Personal State API
+
+Auth:
+
+- `POST /auth/phone/start`
+- `POST /auth/phone/verify`
+- `POST /auth/wechat`
+- `POST /auth/apple`
+
+Personal state:
+
+- `GET /me`
+- `GET /me/favorites`
+- `POST /me/favorites`
+- `DELETE /me/favorites/{report_id}`
+- `GET /me/history`
+- `POST /me/history`
+- `GET /me/listens/saved`
+- `POST /me/listens/saved`
+- `DELETE /me/listens/saved/{audio_id}`
+- `POST /me/playback-progress`
+- `GET /me/playback-progress/{audio_id}`
+
+These endpoints are contract-level requirements but are not implemented in this scaffold.
+
+## Planned Internal API
+
+Internal APIs should require service token and network allowlist. They must never be exposed to the App.
+
+- `POST /internal/reports`
+- `POST /internal/reports/{report_id}/raw-artifacts`
+- `GET /internal/reports/{report_id}/raw-artifacts`
+- `POST /internal/reports/{report_id}/display-artifacts`
+- `PATCH /internal/modules/{module_id}`
+- `POST /internal/reports/{report_id}/publish`
+- `POST /internal/reports/{report_id}/hide`
+- `POST /internal/related-news/candidates`
+
+Publishing should update report display status, update `has_audio`, bump `cache_version`, and clear related cache keys.
+
+## Public vs Internal Fields
+
+Public responses may expose:
+
+- Report identity, title, subtitle, one-liner, topics, institution card, release time, source tier, interpretation label, `has_audio`, and `cache_version`.
+- Detail source note, source URL where allowed, risk disclaimer, and published display modules.
+- Module metadata needed by the client: `module_id`, `type`, `layer`, `render_mode`, `has_detail_page`, `is_publish_blocking`, `requires_human_review`, `sort_order`, `title_cn`, `content`, `preview`, `content_ref`, `content_etag`.
+
+Public responses must not expose:
+
+- Raw artifact payload.
+- Object-storage private paths for raw artifacts.
+- NotebookLM notebook IDs, source IDs, conversation IDs, or local account information.
+- Local filesystem paths.
+- `display_version` or `module.version`.
+- User phone hash, WeChat OpenID, Apple user ID, or auth internals.
+
+The public cache contract is a single `cache_version` string. `display_version` and module `version` are server-internal fields only.
+
+## Seed Data
+
+The seed importer currently creates:
+
+- 18 institutions.
+- 27 reports, including one NotebookLM sample report and multiple boundary cases.
+- 15 audio assets.
+- More than 120 display modules.
+- Test users, favorites, and playback progress.
+
+Seed boundary cases intentionally cover:
+
+- Reports with audio and reports without audio.
+- Hidden/unpublished report behavior.
+- Gray broker source with restricted source URL behavior.
+- Published modules vs review-only modules.
+- `study_guide` module replacing legacy `faq`.
+- Heavy modules using `card_plus_page` preview plus full-module endpoint.
+
+Do not treat seed content as production content. It exists to exercise app/API behavior and edge cases.
+
+## Detail Module Model
+
+The detail page uses a skeleton plus module model:
+
+- Inline modules include small `content` directly in the detail response.
+- Heavy modules use `render_mode=card_plus_page`, return `preview` in detail, and load full content from `/reports/{report_id}/modules/{module_id}`.
+- Unknown future module types should not break the App; they should fall back to hidden or generic rendering.
+
+Core module types:
+
+- `basic_info`
+- `executive_overview`
+- `core_insights`
+- `key_data`
+- `source_compliance`
+- `institution`
+- `differentiated_view`
+- `weaknesses`
+- `timeline`
+- `study_guide`
+- `structure_graph`
+- `related_sources`
+- `infographic`
+- `audio`
+- `research_discovery`

report-notebooklm-api/docs/CONTENT_PIPELINE.md

@@ -0,0 +1,142 @@
+# Content Pipeline Handoff
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+## Content Principle
+
+Use NotebookLM as a source-driven research engine, not as a generic rewriting model.
+
+The pipeline may orchestrate, clean, validate, map, and review NotebookLM-native artifacts. It must not silently replace missing NotebookLM artifacts with locally rewritten publishable content.
+
+## Source Inputs
+
+Phase 1 content is based on public or authorized institutional research reports. Priority source categories:
+
+- Official public sources.
+- Authorized partner sources.
+- Gray broker public sources, with stricter review and source display handling.
+
+Vision source lists, tiering, and historical source-health experience may be used as reference material. Production data must not depend on a local Vision runtime, local path, local cache, or local account state.
+
+## NotebookLM Workflow
+
+Recommended report run order:
+
+1. Inspect the source PDF: title, institution, date, page count, size, and report type.
+2. Create or reuse one notebook for one report source unless a multi-report synthesis is explicitly planned.
+3. Upload the report source.
+4. Generate the P0 text package:
+   - source description
+   - native Briefing Doc
+   - native Blog Post
+   - data table
+   - query dimensions
+   - query key data
+   - query divergence
+   - query weaknesses
+5. Generate useful P1 artifacts:
+   - query timeline
+   - query related sources
+   - Study Guide
+   - mind map, if download succeeds
+6. Generate P2 artifacts asynchronously:
+   - infographic candidate
+   - audio brief
+   - research discovery
+7. Persist every artifact status in a manifest.
+8. Deterministically assemble display modules from reviewed artifacts.
+9. Run human review before publishing.
+
+## Artifact Types
+
+The Phase 1 schema supports these NotebookLM artifact types:
+
+| Artifact type | Purpose | Publish blocking | Human review |
+|---|---|---:|---:|
+| `source_summary` | Source-level summary. | No | No |
+| `notebook_summary` | Notebook-level summary. | No | No |
+| `native_briefing_doc` | Native briefing document. | Yes | No |
+| `native_blog_post` | Native blog post. | Yes | No |
+| `native_study_guide` | FAQ, study guide, glossary. | No | No |
+| `data_table` | Structured table data. | Yes | No |
+| `mind_map` | Mind map or graph source. | No | No |
+| `query_dimensions` | Analysis dimensions. | Yes | No |
+| `query_key_data` | Key data points. | Yes | No |
+| `query_divergence` | Views that diverge from consensus. | No | No |
+| `query_weaknesses` | Weaknesses and open questions. | No | No |
+| `query_timeline` | Timeline and turning points. | No | No |
+| `query_related_sources` | Related source candidates. | No | Yes |
+| `research_discovery` | Enrichment queue. | No | Yes |
+| `infographic` | Candidate public image. | No | Yes |
+| `audio_brief` | Listening preview or audio source. | No | No |
+
+Artifact records should keep status, object reference, format, size, hash, generated time, error, and review flags. Raw payloads should stay in object storage and remain internal.
+
+## Module Mapping
+
+| Product module | Primary artifact sources | Notes |
+|---|---|---|
+| `basic_info` | Source metadata and source summary. | P0, inline. |
+| `executive_overview` | Briefing Doc and Blog Post. | P0, heavy card plus page. |
+| `core_insights` | Briefing Doc and query dimensions. | P0, inline with optional detail page. |
+| `key_data` | Data table and query key data. | P0, heavy card plus page. |
+| `source_compliance` | Source metadata and review notes. | P0, inline, must include disclaimer. |
+| `institution` | Institution record. | P0, inline. |
+| `differentiated_view` | Query divergence. | P1, optional. |
+| `weaknesses` | Query weaknesses. | P1, optional, avoid investment-advice wording. |
+| `timeline` | Query timeline. | P1, optional. |
+| `study_guide` | Native Study Guide. | P1, optional, replaces legacy `faq`. |
+| `structure_graph` | Mind map or deterministic fallback. | P1, optional. |
+| `related_sources` | Related-source query and review queue. | P1, review required before display. |
+| `infographic` | Infographic candidate. | P2, review required before display. |
+| `audio` | Audio brief or reviewed audio asset. | P2, not required for text publish. |
+| `research_discovery` | Research discovery queue. | P2, internal or reviewed only. |
+
+## Publish Gates
+
+Blocking before public release:
+
+- Source upload succeeded and is traceable.
+- Required P0 text artifacts exist and have usable content.
+- `basic_info`, `executive_overview`, `core_insights`, `key_data`, and `source_compliance` are present unless a product decision allows a partial report.
+- Display artifact is reviewed and approved.
+- Source attribution and risk disclaimer are present.
+- No raw artifact payload, local path, private notebook ID, or account information appears in public responses.
+
+Non-blocking:
+
+- Mind map.
+- Study guide.
+- Timeline.
+- Related-source candidates.
+- Research discovery.
+- Infographic.
+- Audio.
+
+If optional artifacts fail, record the failure and continue without inventing fallback public copy. Deterministic fallback is allowed for structure graph from already available artifacts.
+
+## Cadence Notes
+
+NotebookLM operations should be conservative by default:
+
+- One active NotebookLM operation per account.
+- Text artifacts first.
+- Media artifacts after text success.
+- Heavy media should not block publishable text.
+- On transient failure, retry once; if an optional artifact fails again, mark it failed and continue.
+
+The seed importer is not a production runner. A production runner should persist manifests after every operation and support resumable review/import.
+
+## Human Review
+
+Review is mandatory for:
+
+- Gray broker sources.
+- Related-source candidate display.
+- Infographic or generated media.
+- Any content where citations/page labels are ambiguous.
+- Any copy that could be interpreted as investment advice.
+
+Do not display raw NotebookLM page labels until they are normalized against verifiable source pages or sections.

report-notebooklm-api/docs/HANDOFF.md

@@ -0,0 +1,84 @@
+# Backend Handoff
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+## Current State
+
+The backend is a runnable Phase 1 scaffold for the public read surface. It is not production-ready yet.
+
+Implemented:
+
+- FastAPI app and API prefix.
+- SQLAlchemy models for the Phase 1 table set.
+- Alembic initial migration.
+- Seed import script.
+- Public read API for feed, reports, module detail, institutions, and listen list.
+- Tests for current seed behavior and public response boundaries.
+
+Not implemented:
+
+- Authentication.
+- User personal-state routes.
+- Audio stream signing.
+- Outbound attribution route.
+- Internal management routes.
+- Production object storage integration.
+- Real Redis cache invalidation.
+- Production deployment config.
+
+## Repository Map
+
+| Path | Purpose |
+|---|---|
+| `app/main.py` | FastAPI app, CORS, router registration. |
+| `app/config.py` | Environment-driven settings. |
+| `app/db.py` | Async SQLAlchemy engine and session dependency. |
+| `app/cache.py` | Redis client helper and key prefixing. |
+| `app/models/entities.py` | SQLAlchemy table models. |
+| `app/routers/` | HTTP route handlers. |
+| `app/services/catalog.py` | Public catalog response assembly. |
+| `migrations/` | Alembic environment and migration files. |
+| `scripts/import_seed_content.py` | Seed data importer and module fixture builder. |
+| `tests/test_public_api.py` | Current API and seed behavior tests. |
+| `docs/` | Engineering handoff documentation. |
+
+## Solved Decisions
+
+- Technical identifiers stay `report-notebooklm` / `rnb`; display name is `研听`.
+- Public API responses expose `cache_version`, not `display_version` or module `version`.
+- `study_guide` replaces legacy `faq`.
+- Heavy modules use preview cards plus full-module endpoint.
+- Raw artifacts stay internal; App consumes reviewed display artifacts only.
+- Gray broker sources may be audio-ized only after the latest product decision and compliance review.
+- Phase 1 has no interpretation-content download feature.
+
+## Known Gaps
+
+- `GET /audio/{audio_id}/stream` needs signed playback URL behavior.
+- Auth and personal state APIs need implementation.
+- `POST /outbound/events` needs implementation and validation for `click_id` / `tracking_id`.
+- Internal publish/hide/import management endpoints need implementation.
+- Cursor pagination and cache invalidation are seed-scale placeholders.
+- Object storage policy needs a production decision for public vs signed module content.
+- Release/deploy settings need staging and production environment values.
+- Compliance must re-review gray-source audio and generated media rules before launch.
+
+## Suggested Handoff Order
+
+1. Read `docs/PROJECT_BRIEF.md`.
+2. Read `docs/API_AND_DATA.md`.
+3. Run the backend locally with seed data using `docs/RUNBOOK.md`.
+4. Run `pytest -q` and smoke the three core public endpoints.
+5. Pair with `report-notebooklm-app/` and verify `RNB_API_BASE` points to this service.
+6. Choose the next work item from `docs/ROADMAP_AND_OPEN_ISSUES.md`.
+
+## Definition of Done for Next Backend Work
+
+- New API behavior has tests.
+- Public responses do not expose internal/raw fields.
+- Migrations include downgrade.
+- New config is environment-driven.
+- Seed data remains useful for App development.
+- Documentation is updated when contract behavior changes.

report-notebooklm-api/docs/PROJECT_BRIEF.md

@@ -0,0 +1,71 @@
+# Project Brief Snapshot
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+## Product
+
+`研听` is a Chinese research-report interpretation app for users who want to understand global institutional research with lower language and time barriers. It turns hard-to-read English research reports into structured Chinese reading and listening experiences.
+
+Technical identifiers remain `report-notebooklm` and `rnb`. Do not use the product display name in code identifiers, database schema names, Redis keys, object storage paths, or API prefixes.
+
+## Phase 1 Goals
+
+- Validate whether Chinese users will repeatedly consume global institutional research-report interpretations.
+- Ship a complete first app experience for discovery, reading, listening, saving, and returning to reports.
+- Establish a minimum loop from report sources to selection, NotebookLM-assisted interpretation, review, storage, API distribution, and app display.
+- Keep source attribution and compliance clear: this is report interpretation and annotation, not investment advice.
+- Keep the commercial app independent from any local-only Vision runtime.
+
+## Target Users
+
+- General Chinese users interested in macro, precious metals, commodities, energy, central banks, and cross-asset research.
+- Light professional users who want overseas institutional views and original-source traceability, without trading advice.
+- Commuting or fragmented-time users who want reports transformed into listenable content.
+
+Non-target users: professional terminal users, real-time trading-signal users, UGC/community users, and users expecting original investment recommendations.
+
+## Main Tabs
+
+| Tab | Phase 1 scope | Explicitly out of scope |
+|---|---|---|
+| 推荐 | Latest and curated report interpretations. | Ads, hard trading CTAs, real-time news flashes. |
+| 研报 | All published report interpretations with basic filters. | Advanced investment terminal search. |
+| 机构 | Institution list and institution report entry points. | Commercial institution ranking or onboarding backend. |
+| 听单 | Reports that have audio form. | User-created podcasts, downloads, offline packages. |
+| 我的 | Guest/login state, favorites, history, saved listening entry points. | Comments, UGC, paid membership, points. |
+
+## Phase 1 Must Do
+
+- Public browsing for recommended reports, report list, institutions, and listen list.
+- Report detail pages with title, institution, publication/release data, source type, topics, summary, structured modules, source/compliance information, and favorite entry.
+- Guest users can browse public content and fully listen to at least one episode.
+- Logged-in users can synchronize favorites, reading history, saved listens, and playback progress.
+- Published app responses must expose only reviewed display artifacts, not raw NotebookLM artifacts.
+- Every report detail must preserve source attribution and risk disclaimer wording.
+
+## Phase 1 Must Not Do
+
+- No commercialization: no ads, paid unlock, membership, task wall, or points.
+- No comments, community, UGC, or user-generated report interpretations.
+- No investment advice, trading signals, buy/sell points, return promises, or portfolio recommendations.
+- No original financial news, real-time reporting, or commentary positioned as original market views.
+- No in-product downloads for interpretation content, audio packages, or PDFs.
+- No long-term production dependency on a local Vision runtime, local SQLite, local scripts, local paths, or local account state.
+- No App or server-side LLM rewriting of NotebookLM-native content into unsupported original copy.
+
+## Compliance Boundary
+
+- Positioning: research-report interpretation and annotation service.
+- Content: Chinese interpretation of public or authorized institutional reports.
+- Detail pages, agreements, and store metadata must state that content is not investment advice.
+- Each item must show institution, source, publication time, and interpretation/source labels.
+- Gray broker sources require special handling and human review before public release.
+- Phase 1 does not open user content surfaces.
+
+## Vision Decoupling
+
+Vision source experience can be reused as reference material: source lists, source tiers, source-health lessons, NotebookLM experience, and prior pitfalls.
+
+The app must not depend on local Vision runtime state in production. Any short-term Vision consumption must be read-only transition input, must not write back to Vision, and must not leak local file paths into production data.

report-notebooklm-api/docs/ROADMAP_AND_OPEN_ISSUES.md

@@ -0,0 +1,57 @@
+# Roadmap and Open Issues
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+## P0 Before Production Handoff
+
+- Add environment examples and production-safe defaults for all deploy-time settings.
+- Decide staging and production API domains.
+- Implement `GET /audio/{audio_id}/stream` with short-lived signed playback URL.
+- Implement auth start/verify flow and token handling.
+- Implement `/me` personal-state APIs for favorites, history, saved listens, and playback progress.
+- Implement `POST /outbound/events` with required `click_id` and `tracking_id`.
+- Implement production cursor pagination.
+- Implement cache invalidation on publish/hide/module/audio changes.
+- Add smoke scripts for health, feed, detail, listen, audio stream, favorite, and outbound event.
+
+## P1 Content and Admin
+
+- Implement internal APIs for report import, raw artifacts, display artifacts, module patching, publish, hide, and related-source candidates.
+- Implement production content importer from a manifest-based NotebookLM runner.
+- Add validation for module JSON schemas.
+- Add object storage integration for raw payloads, heavy module content, audio, images, and source references.
+- Add publish blocking validation for P0 modules.
+- Add gray-source review flags and operational reporting.
+
+## P1 App/API Contract
+
+- Align App with real auth state and return-to-action behavior.
+- Add playable audio stream integration once backend stream endpoint exists.
+- Replace local playback placeholders with API-backed progress.
+- Add real outbound event write before external navigation.
+- Decide whether heavy P1 modules stay as separate pages or merge into one deep-dive page.
+
+## P2 Production Operations
+
+- Add structured logs and request IDs.
+- Add application metrics for feed/detail/listen/audio/outbound.
+- Add backup and restore runbook for database and content objects.
+- Add staging seed or reviewed staging content set.
+- Add CI checks for lint, tests, migrations, and public response snapshots.
+
+## Product and Compliance Open Issues
+
+- Re-review gray-source audio policy before public release.
+- Define AI-generated-content labeling requirements in App detail and store metadata.
+- Define infographic watermark, QA, and factual-check process.
+- Define source citation display rules after citation/page-label normalization.
+- Confirm login channels and external approvals: phone SMS, WeChat, Apple.
+- Confirm store listing wording and risk disclaimers.
+
+## Gitea Handoff Blockers
+
+- Use the single Gitea remote for the monorepo.
+- Decide whether the initial push goes directly to `main` or to a review branch.
+- Confirm the team has access to the product SSOT or accepts the code-repo snapshot as the development handoff.

report-notebooklm-api/docs/RUNBOOK.md

@@ -0,0 +1,112 @@
+# Backend Runbook
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+## Requirements
+
+- Python 3.12 or compatible with the configured project dependencies.
+- MySQL 8 for local/staging/prod-like runs.
+- Redis 7 for cache-compatible local/staging/prod-like runs.
+- A shell environment that can create a Python virtual environment.
+
+SQLite is used by the automated tests through `RNB_DATABASE_URL`; production-like local runs should use MySQL.
+
+## Environment Variables
+
+Create `.env` in the repository root:
+
+```bash
+RNB_DATABASE_URL=mysql+asyncmy://<db-user>:<db-pass>@<db-host>:<db-port>/report_notebooklm
+RNB_REDIS_URL=redis://<redis-host>:<redis-port>/0
+RNB_REDIS_KEY_PREFIX=rnb:
+```
+
+Do not commit `.env`.
+
+## Install
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Migrate and Seed
+
+```bash
+source .venv/bin/activate
+alembic upgrade head
+python scripts/import_seed_content.py
+```
+
+Seed import is destructive for seed tables. Use it only in local or disposable test data environments unless a production-safe importer is written.
+
+## Run API
+
+```bash
+source .venv/bin/activate
+uvicorn app.main:app --reload --host <bind-host> --port <port>
+```
+
+API prefix:
+
+```text
+/api/report-notebooklm/v1
+```
+
+## 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"
+```
+
+Expected:
+
+- Health returns `{"status":"ok"}`.
+- Feed returns non-empty `items`.
+- Report detail returns modules and does not include `display_version`.
+
+## Test
+
+```bash
+source .venv/bin/activate
+pytest -q
+```
+
+## App Integration
+
+Start this backend first, then run the App with:
+
+```bash
+flutter run -d chrome --dart-define=RNB_API_BASE=<api-base-url>
+```
+
+For Android emulator, use an API base URL reachable from that emulator:
+
+```bash
+flutter run -d <emulator-id> --dart-define=RNB_API_BASE=<emulator-api-base-url>
+```
+
+Only use cleartext HTTP for local debug builds. Release builds must use HTTPS.
+
+## Deployment Checks
+
+Before staging or production:
+
+- Use environment variables for all database, Redis, object storage, auth, and signing settings.
+- Configure HTTPS at the gateway.
+- Confirm migrations can run forward and downgrade in staging.
+- Import reviewed content, not raw/unreviewed NotebookLM artifacts.
+- Smoke `/health`, `/feed/recommended`, report detail, audio stream, favorites, and outbound event once those APIs exist.
+- Confirm public responses do not expose local paths, raw payloads, notebook IDs, source IDs, conversation IDs, or secrets.
+
+## Operational Notes
+
+- Redis keys must use the `rnb:` prefix or a compatible namespace.
+- Object storage keys should use `rnb/raw/`, `rnb/modules/`, `rnb/audio/`, and `rnb/images/` style prefixes.
+- Long NotebookLM operations should live in a resumable runner, not inside HTTP request handlers.

report-notebooklm-api/docs/SOURCE_INDEX.md

@@ -0,0 +1,35 @@
+# Source Index
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+## Snapshot Sources
+
+The handoff documents in this repository were distilled from these logical product-document sources:
+
+| Logical source | Used for |
+|---|---|
+| `phase1-scope.md` | Product positioning, target users, tabs, Phase 1 scope, non-goals, compliance boundary, Vision decoupling. |
+| `phase1-build-brief.md` | Data tables, endpoint list, display module model, artifact enum, seed mapping, open questions. |
+| `phase1-development-plan.md` | Technology choices, architecture, Redis/object-storage strategy, phases, deployment assumptions, external dependencies. |
+| `data-model-api-contract-v0.1.md` | API/data object intent and response boundaries. |
+| `user-flows.md` | Guest vs logged-in behavior, shallow interaction expectations, no-download clarification. |
+| `app-prd-v0.1.md` | App-side behavior and page-level expectations. |
+| `vision-research-sources.md` | Source-reference context and Vision decoupling principle. |
+
+## Drift Rule
+
+Do not treat this repository snapshot as the product SSOT. When product requirements change:
+
+1. Update the product SSOT first.
+2. Update this code-repo snapshot only for information needed by engineers.
+3. Bump the snapshot date or add a short changelog entry.
+
+## What Was Not Copied
+
+- Historical drafts.
+- Full experiment reports.
+- Local-only evidence paths.
+- Private local notes.
+- Raw NotebookLM notebook IDs, source IDs, conversation IDs, account identifiers, or payloads.