chore: prepare yanting monorepo handoff

2026-06-03 10:39:03 +09:00
commit fde51468c6
106 changed files with 8171 additions and 0 deletions
@@ -0,0 +1,158 @@
+# App API Contract Notes
+
+This is a handoff snapshot, not the product SSOT.
+
+Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
+
+For full API/data details, read `../report-notebooklm-api/docs/API_AND_DATA.md` from the monorepo root.
+
+## Configuration
+
+The App reads the API base URL from:
+
+```text
+RNB_API_BASE
+```
+
+If `RNB_API_BASE` is missing, live API requests throw an error. This is intentional to avoid silently pointing production builds at a debug backend.
+
+## Endpoints Currently Consumed
+
+| Method | Path | App use |
+|---|---|---|
+| `GET` | `/feed/recommended` | Recommended feed cards. |
+| `GET` | `/reports` | Report list. |
+| `GET` | `/reports/{report_id}` | Report detail skeleton and modules. |
+| `GET` | `/reports/{report_id}/modules/{module_id}` | Module detail page content. |
+| `GET` | `/institutions` | Institution list. |
+| `GET` | `/institutions/{institution_id}` | Institution detail and recent reports. |
+| `GET` | `/listen` | Listen list and mini-player entry. |
+
+## Response Fields Currently Used
+
+Report cards:
+
+- `report_id`
+- `title_cn`
+- `subtitle_cn`
+- `one_liner`
+- `institution`
+- `topics`
+- `released_at`
+- `has_audio`
+- `interpretation_label`
+- `source_tier`
+- `cache_version`
+
+Report detail:
+
+- `report_id`
+- `title_cn`
+- `subtitle_cn`
+- `original_title`
+- `one_liner`
+- `institution`
+- `source`
+- `topics`
+- `has_audio`
+- `interpretation_label`
+- `risk_disclaimer`
+- `released_at`
+- `cache_version`
+- `modules`
+
+Display modules:
+
+- `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`
+
+Listen items:
+
+- `audio_id`
+- `title_cn`
+- `duration_sec`
+- `report_id`
+- `report_title_cn`
+- `institution`
+- `released_at`
+- `cache_version`
+
+Institution:
+
+- `institution_id`
+- `name_cn`
+- `name_en`
+- `institution_type`
+- `source_tier`
+- `website_url`
+- `covered_topics`
+- `report_count`
+- `latest_report_at`
+- `credibility_note`
+- `intro_cn`
+- `latest_report`
+- `recent_reports`
+
+## Module Rendering Behavior
+
+- `render_mode=inline`: App renders `content` on the report detail page.
+- `render_mode=card_plus_page`: App renders `preview` on the report detail page and opens module detail for full content.
+- Unknown module `type` should not crash the App; it should fall back to a generic or hidden renderer.
+
+Current renderer coverage includes:
+
+- `basic_info`
+- `executive_overview`
+- `core_insights`
+- `key_data`
+- `source_compliance`
+- `audio`
+- `institution`
+- `timeline`
+- `study_guide`
+- `structure_graph`
+- `related_sources`
+- `differentiated_view`
+- `weaknesses`
+
+## Endpoints Not Yet Consumed
+
+- `GET /audio/{audio_id}/stream`
+- Auth endpoints.
+- `/me` personal-state endpoints.
+- `POST /outbound/events`
+
+The UI currently uses placeholders for these blocked flows:
+
+- Login prompt.
+- Favorite action.
+- Browse/history sync.
+- Saved listen.
+- Playback progress.
+- Outbound confirmation.
+- Real audio playback.
+
+## Public Field Boundary
+
+The App must not rely on or display:
+
+- `display_version`
+- module `version`
+- raw artifact payload
+- raw NotebookLM IDs
+- private object-storage references
+- local paths
+- auth internals
+
+The App should use `cache_version` as the public cache/version signal.