maobo/yanting
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: prepare yanting monorepo handoff

Browse Source
This commit is contained in:
JIMME
2026-06-03 10:39:03 +09:00
commit 634ae98dec
65 changed files with 5144 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API_CONTRACT_NOTES.md
+158
View File
@@ -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.
docs/APP_RUNBOOK.md
+81
View File
@@ -0,0 +1,81 @@
# App Runbook
This is a handoff snapshot, not the product SSOT.
Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
## Requirements
- Flutter 3.44.1 / Dart 3.12.1 or compatible newer versions.
- A backend API serving `/api/report-notebooklm/v1`.
- Android SDK and accepted licenses for Android builds.
- Chrome for web debug.
Check tool versions:
```bash
flutter --version
dart --version
flutter doctor -v
```
If dependency solving reports that Dart is older than required, switch to a Flutter SDK that includes Dart 3.12.1 or newer.
## API Base URL
The App requires an explicit API base URL:
```bash
--dart-define=RNB_API_BASE=<api-base-url>
```
Examples:
```bash
RNB_API_BASE=http://<debug-api-host>:<port>/api/report-notebooklm/v1
RNB_API_BASE=https://<api-domain>/api/report-notebooklm/v1
```
Use cleartext HTTP only for local debug builds. Release builds must use HTTPS.
## Web Run
```bash
flutter run -d chrome --dart-define=RNB_API_BASE=<api-base-url>
```
## Android Emulator Run
Start the backend on the host, then:
```bash
flutter devices
flutter run -d <emulator-id> --dart-define=RNB_API_BASE=<emulator-api-base-url>
```
## Same-Network Android Device
Start the backend on a host/port reachable from the device, then:
```bash
flutter run -d <device-id> --dart-define=RNB_API_BASE=http://<host-lan-ip>:<port>/api/report-notebooklm/v1
```
Use this only for debug. Do not hardcode LAN IPs in source code.
## Verify
```bash
flutter analyze
flutter test
flutter build web --dart-define=RNB_API_BASE=<api-base-url>
flutter build apk --debug --dart-define=RNB_API_BASE=<emulator-api-base-url>
```
## Release Notes
- Release builds must not allow cleartext traffic.
- Production API base must be passed explicitly.
- Release signing is not finalized in this scaffold.
- Final app icon and store metadata are not finalized.
- Do not commit build outputs, APKs, screenshots, `.dart_tool/`, or local IDE caches.
docs/HANDOFF.md
+79
View File
@@ -0,0 +1,79 @@
# App Handoff
This is a handoff snapshot, not the product SSOT.
Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
## Current State
The App is a runnable Phase 1 Flutter shell connected to the backend public seed API. It is not production-ready yet.
Implemented:
- Five bottom tabs: 推荐, 研报, 机构, 听单, 我的.
- API client configured by `RNB_API_BASE`.
- API-backed recommended feed, report list, institution list, institution detail, listen list, report detail, and module detail.
- Report detail module renderer registry.
- Inline module rendering and card-plus-page module preview/detail flow.
- Local mini-player UI and player controls.
- Login, favorite, outbound, and playback placeholders that make blocked Phase 1 flows visible without pretending they are complete.
- Android platform scaffold and debug/release build compatibility.
Not implemented:
- Auth and real login state.
- Server-synced favorites, reading history, saved listens, and playback progress.
- Real audio stream from `/audio/{audio_id}/stream`.
- Outbound event write before external navigation.
- Production API domain.
- Release signing.
- Final app icon, final brand visuals, privacy copy, and store metadata.
## Important Product Decisions Reflected in App
- User-facing product name is `研听`.
- Technical identifiers stay `report-notebooklm` / `rnb`.
- Phase 1 has no download feature for report interpretation content, audio packages, or PDFs.
- Source access is through source/compliance or outbound surfaces, not in-product downloads.
- Guest users can browse public content and listen; login is only required for synchronized personal state.
- App must not call NotebookLM or any LLM to generate report content.
## Source Tree Map
| Path | Purpose |
|---|---|
| `lib/main.dart` | App entry point and API data source construction. |
| `lib/app.dart` | Material app and theme hookup. |
| `lib/data/api/` | Backend API client. |
| `lib/data/models/` | Typed response models. |
| `lib/features/shell_page.dart` | Bottom-tab shell and mini-player state. |
| `lib/features/feed/` | Recommended feed. |
| `lib/features/reports/` | Report list. |
| `lib/features/institutions/` | Institution list and detail. |
| `lib/features/listen/` | Listen list. |
| `lib/features/profile/` | Guest/login placeholder and personal-state entry points. |
| `lib/features/detail/` | Report detail. |
| `lib/features/detail/modules/` | Module renderer registry and module detail page. |
| `lib/widgets/` | Reusable UI components. |
| `lib/theme/` | Design tokens and Flutter theme. |
| `android/` | Android platform scaffold. |
| `test/` | Widget tests. |
## Suggested Handoff Order
1. Read `docs/PROJECT_BRIEF.md`.
2. Run the backend seed API from `report-notebooklm-api/`.
3. Read `docs/API_CONTRACT_NOTES.md`.
4. Run `flutter analyze` and `flutter test`.
5. Run the App against the backend with `RNB_API_BASE`.
6. Choose the next App/API integration item from the open gaps.
## Next App Work
- Wire real auth once backend auth exists.
- Replace favorite/history/saved-listen placeholders with API-backed state.
- Use backend audio stream endpoint for actual playback URL.
- Persist playback progress for logged-in users.
- Write outbound event before external navigation.
- Add production API config and release signing.
- Finalize app icon, privacy wording, store copy, and risk-disclaimer surfaces.
docs/PROJECT_BRIEF.md
+65
View File
@@ -0,0 +1,65 @@
# Project Brief Snapshot
This is a handoff snapshot, not the product SSOT.
Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
## Product
`研听` is a Chinese research-report interpretation app for users who want to understand global institutional research with lower language and time barriers. It turns hard-to-read English research reports into structured Chinese reading and listening experiences.
Technical identifiers remain `report-notebooklm` and `rnb`. Do not use the product display name in code identifiers, database schema names, Redis keys, object storage paths, or API prefixes.
## Phase 1 Goals
- Validate whether Chinese users will repeatedly consume global institutional research-report interpretations.
- Ship a complete first app experience for discovery, reading, listening, saving, and returning to reports.
- Establish a minimum loop from report sources to selection, NotebookLM-assisted interpretation, review, storage, API distribution, and app display.
- Keep source attribution and compliance clear: this is report interpretation and annotation, not investment advice.
- Keep the commercial app independent from any local-only Vision runtime.
## Target Users
- General Chinese users interested in macro, precious metals, commodities, energy, central banks, and cross-asset research.
- Light professional users who want overseas institutional views and original-source traceability, without trading advice.
- Commuting or fragmented-time users who want reports transformed into listenable content.
Non-target users: professional terminal users, real-time trading-signal users, UGC/community users, and users expecting original investment recommendations.
## Main Tabs
| Tab | Phase 1 scope | Explicitly out of scope |
|---|---|---|
| 推荐 | Latest and curated report interpretations. | Ads, hard trading CTAs, real-time news flashes. |
| 研报 | All published report interpretations with basic filters. | Advanced investment terminal search. |
| 机构 | Institution list and institution report entry points. | Commercial institution ranking or onboarding backend. |
| 听单 | Reports that have audio form. | User-created podcasts, downloads, offline packages. |
| 我的 | Guest/login state, favorites, history, saved listening entry points. | Comments, UGC, paid membership, points. |
## Phase 1 Must Do
- Public browsing for recommended reports, report list, institutions, and listen list.
- Report detail pages with title, institution, publication/release data, source type, topics, summary, structured modules, source/compliance information, and favorite entry.
- Guest users can browse public content and fully listen to at least one episode.
- Logged-in users can synchronize favorites, reading history, saved listens, and playback progress.
- Published app responses must expose only reviewed display artifacts, not raw NotebookLM artifacts.
- Every report detail must preserve source attribution and risk disclaimer wording.
## Phase 1 Must Not Do
- No commercialization: no ads, paid unlock, membership, task wall, or points.
- No comments, community, UGC, or user-generated report interpretations.
- No investment advice, trading signals, buy/sell points, return promises, or portfolio recommendations.
- No original financial news, real-time reporting, or commentary positioned as original market views.
- No in-product downloads for interpretation content, audio packages, or PDFs.
- No long-term production dependency on a local Vision runtime, local path, local cache, or local account state.
- No App or server-side LLM rewriting of NotebookLM-native content into unsupported original copy.
## Compliance Boundary
- Positioning: research-report interpretation and annotation service.
- Content: Chinese interpretation of public or authorized institutional reports.
- Detail pages, agreements, and store metadata must state that content is not investment advice.
- Each item must show institution, source, publication time, and interpretation/source labels.
- Gray broker sources require special handling and human review before public release.
- Phase 1 does not open user content surfaces.
docs/PROJECT_MAP.md
+75
View File
@@ -0,0 +1,75 @@
# App Project Map
This is a handoff snapshot, not the product SSOT.
Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
## Entry Points
| Path | Purpose |
|---|---|
| `lib/main.dart` | Creates `RnbApiDataSource` and starts the App. |
| `lib/app.dart` | Defines `MaterialApp`, app title, theme, and shell page. |
| `lib/features/shell_page.dart` | Owns bottom navigation and mini-player state. |
## Data Layer
| Path | Purpose |
|---|---|
| `lib/data/api/report_data_source.dart` | API client interface and HTTP implementation. |
| `lib/data/models/models.dart` | Data models, JSON parsing helpers, and formatting helpers. |
The data source currently performs GET requests only. Mutating APIs for auth, favorites, playback progress, and outbound events are not implemented.
## Feature Pages
| Path | Purpose |
|---|---|
| `lib/features/feed/feed_page.dart` | Recommended feed. |
| `lib/features/reports/reports_page.dart` | Report list and simple filters. |
| `lib/features/institutions/institutions_page.dart` | Institution list. |
| `lib/features/institutions/institution_detail_page.dart` | Institution detail and recent reports. |
| `lib/features/listen/listen_page.dart` | Listen list. |
| `lib/features/profile/profile_page.dart` | Guest/login placeholder and personal-state entries. |
| `lib/features/detail/report_detail_page.dart` | Report detail shell and source/compliance display. |
| `lib/features/detail/modules/renderer_registry.dart` | Module card rendering and module detail page rendering. |
| `lib/features/shared/report_card_widget.dart` | Shared report card. |
## Shared UI
| Path | Purpose |
|---|---|
| `lib/widgets/app_buttons.dart` | Buttons. |
| `lib/widgets/app_card.dart` | Cards. |
| `lib/widgets/badges.dart` | Badges and chips. |
| `lib/widgets/mini_player.dart` | Mini-player and placeholder player UI. |
| `lib/widgets/sheets.dart` | Login/outbound sheets and toasts. |
| `lib/widgets/states.dart` | Loading, skeleton, empty, and error states. |
| `lib/theme/app_theme.dart` | Flutter `ThemeData`. |
| `lib/theme/wise_tokens.dart` | Color, spacing, radius, motion, and shadow tokens. |
## Platform
| Path | Purpose |
|---|---|
| `android/` | Android scaffold. |
| `android/app/src/debug/AndroidManifest.xml` | Debug-only cleartext allowance. |
| `android/app/src/main/AndroidManifest.xml` | Main manifest; release should remain HTTPS-only. |
| `web/` | Flutter web scaffold. |
## Tests
| Path | Purpose |
|---|---|
| `test/widget_test.dart` | Smoke widget test with fake data source. |
## Generated or Local Files
Do not commit:
- `build/`
- `.dart_tool/`
- APKs
- screenshots
- local IDE caches
- local environment files