# report-notebooklm-api Notes

This file keeps short engineering notes for this repository. The durable handoff is in `docs/`.

## 2026-06-03 Phase 1 Scaffold

- Started the Phase 1 backend scaffold from `phase1-build-brief.md`.
- Technical identifiers use `report-notebooklm` / `rnb`; user-facing product name is `研听`.
- Implemented FastAPI config, database, cache helper, routers, SQLAlchemy models, Alembic migration, seed importer, and public read API.
- Public API prefix is `/api/report-notebooklm/v1`.
- Implemented public routes:
  - `/health`
  - `/feed/recommended`
  - `/reports`
  - `/reports/{id}`
  - `/reports/{id}/modules/{module_id}`
  - `/institutions`
  - `/institutions/{id}`
  - `/listen`
- Seed importer covers institutions, reports, display artifacts, display modules, audio assets, users, favorites, and playback progress.
- Heavy modules store preview/full content in a JSON envelope. Public detail responses expose previews for `card_plus_page`; the module endpoint exposes full content.
- Review-only modules do not appear in public responses.
- Public responses expose `cache_version`; `display_version` and module `version` remain internal.

## Verification Snapshot

- Backend tests: `pytest -q` passed.
- Local API smoke checks passed for `/health`, `/feed/recommended`, and `/reports/rep_ssga_gold`.
- Companion App analyze/test/build checks passed when using a Flutter SDK compatible with Dart 3.12.1.
- Android debug validation was completed during local handoff. Build artifacts and screenshots are transient and should not be committed.

## Resolved Product Decisions

- Public responses expose only `cache_version`.
- Heavy module access keeps both `content_ref` and `GET /reports/{id}/modules/{module_id}` available.
- Public published content may use direct content references; restricted sources should use backend short-lived signed URLs.
- FAQ, Study Guide, and Glossary are represented as a single `study_guide` module type.
- `faq` stays deprecated; legacy seed `faq` should map to `study_guide`.
- Gray-source full-text audio is allowed by product decision but still needs operations/compliance review before production release.
- App prototype feedback decisions from 2026-06-03 are durable in mall-docs `docs/2026-06-03-app-prototype-feedback-decisions.md`.
- Seed/display module order is: 报告概览 / 报告摘要 / 听研报 / 报告要点 / 报告中的关键数据 / 观点差异 / 局限与疑问 / 时间线 / 术语与问答 / 结构梳理 / 延伸阅读 / 报告来源.
- Do not seed a separate `institution` display module for public Detail. Publisher information belongs inside the source/compliance surface rendered as `报告来源`.
- The real BIS sample should be the top report, but public UI copy must not expose internal labels such as NotebookLM sample, query artifact, or artifact mapping.
- `basic_info` and `executive_overview` must not repeat the same text: overview is factual scope/metadata; summary is a few-sentence report-level description.
- All public modules returned for Detail should expose `has_detail_page=True`; tests assert this to prevent accidental regression.

## Remaining Backend Gaps

- Auth routes.
- Personal-state routes.
- Audio stream signed URL route.
- Outbound events route.
- Internal management routes.
- Production object storage integration.
- Production cache invalidation and pagination.
- Deployment environment configuration.