yanting/report-notebooklm-api/NOTES.md

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.