chore: prepare yanting monorepo handoff

2026-06-03 10:39:03 +09:00
commit fde51468c6
106 changed files with 8171 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 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.