e9d7f8832a
- 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
91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# 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 有效且配额充足。
|