wip: snapshot full local workspace state

AGENTS.md

@@ -0,0 +1,134 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DreamWeaver (梦语织机) - AI-powered children's story generation app for ages 3-8. Features story generation from keywords, story enhancement, AI-generated cover images, and text-to-speech narration.
+
+**Language:** Chinese (Simplified) for UI and comments.
+
+## Tech Stack
+
+- **Backend:** FastAPI + PostgreSQL (Neon) + SQLAlchemy (async) + Celery/Redis | **Python 3.11+**
+- **Frontend:** Vue 3 + TypeScript + Pinia + Tailwind CSS + vue-i18n
+- **Auth:** OAuth 2.0 (GitHub/Google) with JWT in httpOnly cookie
+- **AI Services:** Text generation, image generation, TTS (pluggable adapters)
+
+## Commands
+
+```bash
+# Backend
+cd backend
+pip install -e .                              # Install dependencies
+pip install -e ".[dev]"                       # With dev tools (pytest, ruff)
+uvicorn app.main:app --reload --port 8000     # Start dev server
+
+# Celery worker (requires Redis)
+celery -A app.tasks worker --loglevel=info
+
+# Database migrations
+alembic upgrade head                          # Run migrations
+alembic revision -m "message" --autogenerate  # Generate new migration
+
+# Linting
+ruff check app/                               # Check code
+ruff check app/ --fix                         # Auto-fix
+
+# Testing
+pytest                                        # Run all tests
+pytest tests/test_auth.py -v                  # Single test file
+pytest -k "test_name"                         # Match pattern
+
+# Frontend
+cd frontend
+npm install
+npm run dev                                   # Start dev server (port 5173)
+npm run build                                 # Type-check + build
+```
+
+## Architecture
+
+```
+backend/app/
+├── main.py                    # FastAPI app entry, routes registration
+├── api/
+│   ├── auth.py                # OAuth routes (GitHub/Google)
+│   ├── stories.py             # Story CRUD and AI generation endpoints
+│   ├── profiles.py            # User profile management
+│   ├── universes.py           # Story universe/world management
+│   ├── reading_events.py      # Reading progress tracking
+│   ├── push_configs.py        # Push notification settings
+│   ├── admin_providers.py     # Provider CRUD (admin)
+│   └── admin_reload.py        # Hot-reload providers (admin)
+├── core/
+│   ├── config.py              # Pydantic settings from env
+│   ├── deps.py                # Dependency injection (auth, db session)
+│   ├── security.py            # JWT token create/verify
+│   ├── prompts.py             # AI prompt templates
+│   └── admin_auth.py          # Basic Auth for admin routes
+├── db/
+│   ├── database.py            # SQLAlchemy async engine + session
+│   ├── models.py              # User, Story models
+│   └── admin_models.py        # Provider model
+├── services/
+│   ├── adapters/              # Capability adapters (text, image, tts)
+│   ├── provider_router.py     # Failover routing across providers
+│   ├── provider_cache.py      # In-memory provider config cache
+│   ├── provider_metrics.py    # Provider performance metrics
+│   └── achievement_extractor.py  # Extract achievements from stories
+└── tasks/
+    ├── achievements.py        # Celery task: achievement processing
+    └── push_notifications.py  # Celery task: push notifications
+
+frontend/src/
+├── api/client.ts              # Axios wrapper with auth interceptors
+├── stores/user.ts             # Pinia user state
+├── router.ts                  # Vue Router config
+├── i18n.ts + locales/         # vue-i18n setup
+├── components/                # Reusable Vue components
+└── views/                     # Page components
+```
+
+## Key Patterns
+
+- **Async everywhere:** All database and API calls use async/await
+- **Dependency injection:** FastAPI `Depends()` for auth and db session
+- **JWT auth:** Stored in httpOnly cookie, validated via `get_current_user` dependency
+- **Provider routing:** `provider_router.py` tries providers in order, auto-failover on error
+- **Background tasks:** Celery workers handle achievements and push notifications
+- **Proxy in dev:** Vite proxies `/api`, `/auth`, `/admin` to backend (see `vite.config.ts`)
+
+## Provider System
+
+AI providers are configured via env vars (`TEXT_PROVIDERS`, `IMAGE_PROVIDERS`, `TTS_PROVIDERS`) as JSON arrays. The router tries each in order and fails over automatically.
+
+Admin console (disabled by default): Set `ENABLE_ADMIN_CONSOLE=true` to enable `/admin/providers` CRUD endpoints with Basic Auth (`ADMIN_USERNAME`/`ADMIN_PASSWORD`).
+
+## Environment Variables
+
+See `backend/.env.example` for required variables:
+
+- `DATABASE_URL`, `SECRET_KEY` (required)
+- OAuth: `GITHUB_CLIENT_ID/SECRET`, `GOOGLE_CLIENT_ID/SECRET`
+- AI: `TEXT_API_KEY`, `TTS_API_BASE`, `TTS_API_KEY`, `IMAGE_API_KEY`
+- Providers: `TEXT_PROVIDERS`, `IMAGE_PROVIDERS`, `TTS_PROVIDERS` (JSON arrays)
+- Celery: `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND` (Redis URLs)
+- Admin: `ENABLE_ADMIN_CONSOLE`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`
+
+## API Endpoints
+
+| Method              | Route                      | Description                 |
+| ------------------- | -------------------------- | --------------------------- |
+| GET                 | `/auth/{provider}/signin`  | OAuth login                 |
+| GET                 | `/auth/session`            | Get current user            |
+| POST                | `/api/generate`            | Generate/enhance story      |
+| POST                | `/api/image/generate/{id}` | Generate cover image        |
+| GET                 | `/api/audio/{id}`          | Get TTS audio               |
+| GET                 | `/api/stories`             | List stories (paginated)    |
+| GET/DELETE          | `/api/stories/{id}`        | Story CRUD                  |
+| CRUD                | `/api/profiles`            | User profiles               |
+| CRUD                | `/api/universes`           | Story universes             |
+| CRUD                | `/api/reading-events`      | Reading progress            |
+| CRUD                | `/api/push-configs`        | Push notification settings  |
+| GET/POST/PUT/DELETE | `/admin/providers`         | Provider management (admin) |