113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
# Backend Runbook
|
|
|
|
This is a handoff snapshot, not the product SSOT.
|
|
|
|
Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.12 or compatible with the configured project dependencies.
|
|
- MySQL 8 for local/staging/prod-like runs.
|
|
- Redis 7 for cache-compatible local/staging/prod-like runs.
|
|
- A shell environment that can create a Python virtual environment.
|
|
|
|
SQLite is used by the automated tests through `RNB_DATABASE_URL`; production-like local runs should use MySQL.
|
|
|
|
## Environment Variables
|
|
|
|
Create `.env` in the repository root:
|
|
|
|
```bash
|
|
RNB_DATABASE_URL=mysql+asyncmy://<db-user>:<db-pass>@<db-host>:<db-port>/report_notebooklm
|
|
RNB_REDIS_URL=redis://<redis-host>:<redis-port>/0
|
|
RNB_REDIS_KEY_PREFIX=rnb:
|
|
```
|
|
|
|
Do not commit `.env`.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
## Migrate and Seed
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
alembic upgrade head
|
|
python scripts/import_seed_content.py
|
|
```
|
|
|
|
Seed import is destructive for seed tables. Use it only in local or disposable test data environments unless a production-safe importer is written.
|
|
|
|
## Run API
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
uvicorn app.main:app --reload --host <bind-host> --port <port>
|
|
```
|
|
|
|
API prefix:
|
|
|
|
```text
|
|
/api/report-notebooklm/v1
|
|
```
|
|
|
|
## Smoke Checks
|
|
|
|
```bash
|
|
API_BASE_URL=http://<api-host>:<port>/api/report-notebooklm/v1
|
|
curl "$API_BASE_URL/health"
|
|
curl "$API_BASE_URL/feed/recommended"
|
|
curl "$API_BASE_URL/reports/rep_ssga_gold"
|
|
```
|
|
|
|
Expected:
|
|
|
|
- Health returns `{"status":"ok"}`.
|
|
- Feed returns non-empty `items`.
|
|
- Report detail returns modules and does not include `display_version`.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
pytest -q
|
|
```
|
|
|
|
## App Integration
|
|
|
|
Start this backend first, then run the App with:
|
|
|
|
```bash
|
|
flutter run -d chrome --dart-define=RNB_API_BASE=<api-base-url>
|
|
```
|
|
|
|
For Android emulator, use an API base URL reachable from that emulator:
|
|
|
|
```bash
|
|
flutter run -d <emulator-id> --dart-define=RNB_API_BASE=<emulator-api-base-url>
|
|
```
|
|
|
|
Only use cleartext HTTP for local debug builds. Release builds must use HTTPS.
|
|
|
|
## Deployment Checks
|
|
|
|
Before staging or production:
|
|
|
|
- Use environment variables for all database, Redis, object storage, auth, and signing settings.
|
|
- Configure HTTPS at the gateway.
|
|
- Confirm migrations can run forward and downgrade in staging.
|
|
- Import reviewed content, not raw/unreviewed NotebookLM artifacts.
|
|
- Smoke `/health`, `/feed/recommended`, report detail, audio stream, favorites, and outbound event once those APIs exist.
|
|
- Confirm public responses do not expose local paths, raw payloads, notebook IDs, source IDs, conversation IDs, or secrets.
|
|
|
|
## Operational Notes
|
|
|
|
- Redis keys must use the `rnb:` prefix or a compatible namespace.
|
|
- Object storage keys should use `rnb/raw/`, `rnb/modules/`, `rnb/audio/`, and `rnb/images/` style prefixes.
|
|
- Long NotebookLM operations should live in a resumable runner, not inside HTTP request handlers.
|