Initial commit: clean project structure
- Backend: FastAPI + SQLAlchemy + Celery (Python 3.11+) - Frontend: Vue 3 + TypeScript + Pinia + Tailwind - Admin Frontend: separate Vue 3 app for management - Docker Compose: 9 services orchestration - Specs: design prototypes, memory system PRD, product roadmap Cleanup performed: - Removed temporary debug scripts from backend root - Removed deprecated admin_app.py (embedded UI) - Removed duplicate docs from admin-frontend - Updated .gitignore for Vite cache and egg-info
This commit is contained in:
zhangtuo
134
CLAUDE.md
Normal file
134
CLAUDE.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.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) |
|
||||
Reference in New Issue
Block a user