145 lines
3.7 KiB
Markdown
145 lines
3.7 KiB
Markdown
# DreamWeaver 梦语织机
|
||
|
||
AI 儿童故事生成应用，面向 3-8 岁儿童与家长，支持关键词生成故事、绘本页生成、封面图生成、语音朗读、孩子档案、故事宇宙与 Provider 管理。
|
||
|
||
当前仓库优先服务一个目标：本地 Docker 环境中稳定跑通完整产品闭环，便于求职演示和后续迭代。
|
||
|
||
## 技术栈
|
||
|
||
- 后端：FastAPI、SQLAlchemy async、PostgreSQL、Celery、Redis
|
||
- 前端：Vue 3、TypeScript、Pinia、Vue Router、Tailwind CSS、Vite
|
||
- 认证：OAuth 2.0 + JWT httpOnly cookie，本地演示支持 dev login
|
||
- AI：文本、图片、TTS、绘本结构生成均通过 adapter/provider router 接入
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
backend/ FastAPI 后端、Celery 任务、数据库迁移
|
||
frontend/ 用户端 Vue 应用
|
||
admin-frontend/ 管理端 Vue 应用
|
||
docs/ 当前产品、规划与技术文档
|
||
docker-compose.yml
|
||
```
|
||
|
||
## 本地 Docker 演示
|
||
|
||
1. 准备环境文件：
|
||
|
||
```bash
|
||
cp backend/.env.example backend/.env
|
||
```
|
||
|
||
本地求职演示建议在 `backend/.env` 中使用：
|
||
|
||
```env
|
||
DEBUG=true
|
||
ENABLE_DEMO_PROVIDERS=true
|
||
TEXT_PROVIDERS=["demo", "gemini", "openai"]
|
||
IMAGE_PROVIDERS=["demo", "cqtai"]
|
||
TTS_PROVIDERS=["edge_tts", "minimax", "elevenlabs"]
|
||
STORYBOOK_PROVIDERS=["demo", "storybook_primary"]
|
||
```
|
||
|
||
`SECRET_KEY` 必须设置为强随机值。`backend/.env` 已被 git 忽略，不要提交真实密钥。
|
||
|
||
2. 启动完整本地栈：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
3. 访问入口：
|
||
|
||
- 用户端：http://localhost:52080
|
||
- 本地开发登录：http://localhost:52080/auth/dev/signin
|
||
- 管理端：http://localhost:52888
|
||
- 后端健康检查：http://localhost:52000/health
|
||
- 管理后端健康检查：http://localhost:52800/health
|
||
|
||
4. 常用命令：
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose logs -f backend
|
||
docker compose down
|
||
docker compose down -v
|
||
```
|
||
|
||
## 手动开发
|
||
|
||
后端：
|
||
|
||
```bash
|
||
cd backend
|
||
pip install -e ".[dev]"
|
||
alembic upgrade head
|
||
uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
Celery：
|
||
|
||
```bash
|
||
cd backend
|
||
celery -A app.core.celery_app worker --loglevel=info
|
||
celery -A app.core.celery_app beat --loglevel=info
|
||
```
|
||
|
||
用户前端：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
管理前端：
|
||
|
||
```bash
|
||
cd admin-frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 质量检查
|
||
|
||
```bash
|
||
cd backend
|
||
pytest
|
||
ruff check app tests
|
||
|
||
cd ../frontend
|
||
npm run build
|
||
|
||
cd ../admin-frontend
|
||
npm run build
|
||
```
|
||
|
||
当前已知情况：完整后端测试可通过；全量 ruff 仍有少量历史 lint 债，优先处理核心演示链路与新增代码。
|
||
|
||
## 核心接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/auth/dev/signin` | 本地开发登录，仅 `DEBUG=true` 可用 |
|
||
| GET | `/auth/github/signin` | GitHub OAuth 登录 |
|
||
| GET | `/auth/google/signin` | Google OAuth 登录 |
|
||
| GET | `/auth/session` | 当前会话 |
|
||
| POST | `/api/stories/generate/full` | 生成故事并尝试生成封面 |
|
||
| POST | `/api/storybook/generate` | 生成绘本 |
|
||
| POST | `/api/stories/{story_id}/assets/retry` | 统一重试封面/语音资源 |
|
||
| GET | `/api/stories` | 故事列表 |
|
||
| GET | `/api/stories/{story_id}` | 故事详情 |
|
||
| DELETE | `/api/stories/{story_id}` | 删除故事 |
|
||
| GET/POST/PUT/DELETE | `/admin/providers` | Provider 管理，需开启管理后台 |
|
||
|
||
## 文档入口
|
||
|
||
- `docs/product/job-search-relaunch-prd.md`：求职版产品重启 PRD
|
||
- `docs/product/unified-generation-workflow-prd.md`：统一生成工作流 PRD
|
||
- `docs/planning/week-1-execution-backlog.md`：短期执行 backlog
|
||
- `docs/technical/memory-system-dev.md`：记忆系统技术说明
|
||
|
||
## 当前取舍
|
||
|
||
仓库只保留一个 Docker Compose 入口：`docker-compose.yml`。生产部署、HA 演练、旧 Claude 原型和历史归档已从主仓库移除，避免干扰当前求职演示主线。
|