torin
b8d3cb4644
Some checks are pending
Build and Push Docker Images / changes (push) Waiting to run
Build and Push Docker Images / build-backend (push) Blocked by required conditions
Build and Push Docker Images / build-frontend (push) Blocked by required conditions
Build and Push Docker Images / build-admin-frontend (push) Blocked by required conditions
135 lines
6.3 KiB
Markdown
135 lines
6.3 KiB
Markdown
# 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) |
|