85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
# Backend 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 backend is a runnable Phase 1 scaffold for the public read surface. It is not production-ready yet.
|
|
|
|
Implemented:
|
|
|
|
- FastAPI app and API prefix.
|
|
- SQLAlchemy models for the Phase 1 table set.
|
|
- Alembic initial migration.
|
|
- Seed import script.
|
|
- Public read API for feed, reports, module detail, institutions, and listen list.
|
|
- Tests for current seed behavior and public response boundaries.
|
|
|
|
Not implemented:
|
|
|
|
- Authentication.
|
|
- User personal-state routes.
|
|
- Audio stream signing.
|
|
- Outbound attribution route.
|
|
- Internal management routes.
|
|
- Production object storage integration.
|
|
- Real Redis cache invalidation.
|
|
- Production deployment config.
|
|
|
|
## Repository Map
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `app/main.py` | FastAPI app, CORS, router registration. |
|
|
| `app/config.py` | Environment-driven settings. |
|
|
| `app/db.py` | Async SQLAlchemy engine and session dependency. |
|
|
| `app/cache.py` | Redis client helper and key prefixing. |
|
|
| `app/models/entities.py` | SQLAlchemy table models. |
|
|
| `app/routers/` | HTTP route handlers. |
|
|
| `app/services/catalog.py` | Public catalog response assembly. |
|
|
| `migrations/` | Alembic environment and migration files. |
|
|
| `scripts/import_seed_content.py` | Seed data importer and module fixture builder. |
|
|
| `tests/test_public_api.py` | Current API and seed behavior tests. |
|
|
| `docs/` | Engineering handoff documentation. |
|
|
|
|
## Solved Decisions
|
|
|
|
- Technical identifiers stay `report-notebooklm` / `rnb`; display name is `研听`.
|
|
- Public API responses expose `cache_version`, not `display_version` or module `version`.
|
|
- `study_guide` replaces legacy `faq`.
|
|
- Heavy modules use preview cards plus full-module endpoint.
|
|
- Raw artifacts stay internal; App consumes reviewed display artifacts only.
|
|
- Gray broker sources may be audio-ized only after the latest product decision and compliance review.
|
|
- Phase 1 has no interpretation-content download feature.
|
|
|
|
## Known Gaps
|
|
|
|
- `GET /audio/{audio_id}/stream` needs signed playback URL behavior.
|
|
- Auth and personal state APIs need implementation.
|
|
- `POST /outbound/events` needs implementation and validation for `click_id` / `tracking_id`.
|
|
- Internal publish/hide/import management endpoints need implementation.
|
|
- Cursor pagination and cache invalidation are seed-scale placeholders.
|
|
- Object storage policy needs a production decision for public vs signed module content.
|
|
- Release/deploy settings need staging and production environment values.
|
|
- Compliance must re-review gray-source audio and generated media rules before launch.
|
|
|
|
## Suggested Handoff Order
|
|
|
|
1. Read `docs/PROJECT_BRIEF.md`.
|
|
2. Read `docs/API_AND_DATA.md`.
|
|
3. Run the backend locally with seed data using `docs/RUNBOOK.md`.
|
|
4. Run `pytest -q` and smoke the three core public endpoints.
|
|
5. Pair with `report-notebooklm-app/` and verify `RNB_API_BASE` points to this service.
|
|
6. Choose the next work item from `docs/ROADMAP_AND_OPEN_ISSUES.md`.
|
|
|
|
## Definition of Done for Next Backend Work
|
|
|
|
- New API behavior has tests.
|
|
- Public responses do not expose internal/raw fields.
|
|
- Migrations include downgrade.
|
|
- New config is environment-driven.
|
|
- Seed data remains useful for App development.
|
|
- Documentation is updated when contract behavior changes.
|