# DreamWeaver

AI 驱动的儿童故事生成应用，面向 3-8 岁儿童提供个性化童话创作。

## 技术栈
- 后端：FastAPI、SQLAlchemy (async)、PostgreSQL，OAuth (GitHub/Google)
- AI：文本生成、图像生成、语音合成（可替换适配器）
- 前端：Vue 3、TypeScript、Pinia、Vue Router、Vite

## 仓库结构
```
backend/
  app/               # 后端代码
  alembic/           # 数据库迁移
  pyproject.toml
  .env.example
frontend/
  src/               # 前端代码
  package.json
```

## 快速开始
### 后端
```bash
cd backend
python -m venv .venv
.\.venv\Scripts\activate  # Linux/Mac: source .venv/bin/activate
pip install -e .

cp .env.example .env      # 填写 SECRET_KEY、DATABASE_URL、各 API Key

# 运行数据库迁移（先配置好 DATABASE_URL）
alembic upgrade head

# 启动
uvicorn app.main:app --reload --port 8000
```

### 前端
```bash
cd frontend
npm install
npm run dev
```
前端常用环境变量（可放 `.env.development`）：
- `VITE_API_BASE`：后端地址，例如 `http://localhost:8000`
- `VITE_ADMIN_USER` / `VITE_ADMIN_PASS`：管理后台 Basic Auth 账号（仅后台开启时需要）

### 访问
- 前端：http://localhost:5173
- 后端 API：http://localhost:8000
- Swagger 文档：http://localhost:8000/docs

## 供应商路由与管理后台
- 路由按配置顺序尝试：`TEXT_PROVIDERS`（默认 `text_primary`）、`IMAGE_PROVIDERS`（默认 `image_primary`）、`TTS_PROVIDERS`（默认 `tts_primary`）。失败会自动切换下一个。
- 管理后台（默认关闭）：`ENABLE_ADMIN_CONSOLE=true` 时启用，接口在 `/admin/providers`（CRUD）和 `/admin/providers/reload`。鉴权使用 Basic Auth，账号密码由 `ADMIN_USERNAME`/`ADMIN_PASSWORD` 设置（请覆盖默认值）。
- 建议后台放在受保护子域并在反代层加 Basic Auth/IP 白名单；生产环境默认关闭。
- 前端最小管理页：`/admin/providers`，仅后台开启时可用，使用上面的 Basic Auth 调用。

## 数据库迁移（Alembic）
- 运行迁移：`alembic upgrade head`
- 生成新迁移：`alembic revision -m "message" --autogenerate`
迁移脚本位于 `backend/alembic/versions/`，包含 `providers` 表和 `stories.mode` 字段。

## 主要 API
| 方法 | 路径 | 说明 |
| ---- | ---- | ---- |
| GET | `/auth/github/signin` | GitHub 登录 |
| GET | `/auth/google/signin` | Google 登录 |
| GET | `/auth/session` | 当前会话 |
| POST | `/api/generate` | 生成/润色故事 |
| POST | `/api/image/generate/{id}` | 生成封面图 |
| GET | `/api/audio/{id}` | 获取 TTS 音频 |
| GET | `/api/stories` | 获取故事列表（分页） |
| GET | `/api/stories/{id}` | 获取故事详情 |
| DELETE | `/api/stories/{id}` | 删除故事 |
| GET | `/admin/providers` | Provider 列表（需后台开启 + 管理员） |

## 环境变量
常用项（详见 `backend/.env.example`）：
- `SECRET_KEY`（必填）：JWT 签名密钥
- `DATABASE_URL`（必填）：PostgreSQL 连接串
- OAuth：`GITHUB_CLIENT_ID/SECRET`，`GOOGLE_CLIENT_ID/SECRET`
- AI Keys：`TEXT_API_KEY`，`TTS_API_BASE`，`TTS_API_KEY`，`IMAGE_API_KEY`
- Provider 列表：`TEXT_PROVIDERS`，`IMAGE_PROVIDERS`，`TTS_PROVIDERS`
- 管理后台：`ENABLE_ADMIN_CONSOLE`，`ADMIN_USERNAME`，`ADMIN_PASSWORD`

## 注意
- 生产务必使用强随机 `SECRET_KEY`，并关闭 `ENABLE_ADMIN_CONSOLE`（或放在受保护子域/内网）。
- 路由会按配置/DB 顺序尝试供应商并失败切换，请确保各 Key 有效且配额充足。