159 lines
3.2 KiB
Markdown
159 lines
3.2 KiB
Markdown
# 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.
|