chore: prepare yanting monorepo handoff
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user