yanting/report-notebooklm-api/docs/HANDOFF.md

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.