chore: prepare yanting monorepo handoff

report-notebooklm-api/NOTES.md

@@ -0,0 +1,56 @@
+# 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.