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

快速开始

后端

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

前端

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 有效且配额充足。