chore: simplify project entrypoints

2026-04-18 12:23:41 +08:00
parent 44405ff7ac
commit bb575a7fe9
76 changed files with 282 additions and 10399 deletions
--- a/README.md
+++ b/README.md
@@ -1,208 +1,144 @@
-# DreamWeaver
+# DreamWeaver 梦语织机

-AI 驱动的儿童故事生成应用，面向 3-8 岁儿童提供个性化童话创作。
+AI 儿童故事生成应用，面向 3-8 岁儿童与家长，支持关键词生成故事、绘本页生成、封面图生成、语音朗读、孩子档案、故事宇宙与 Provider 管理。
+
+当前仓库优先服务一个目标：本地 Docker 环境中稳定跑通完整产品闭环，便于求职演示和后续迭代。

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

 ## 仓库结构
-```
-backend/
-  app/               # 后端代码
-  alembic/           # 数据库迁移
-  pyproject.toml
-  .env.example
-frontend/
-  src/               # 前端代码
-  package.json
+
+```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
-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）
+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
 ```
-前端常用环境变量（可放 `.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
+管理前端：

-## Docker Compose 使用说明
-本项目包含 3 个 compose 文件：
-
- `docker-compose.yml`：开发基线，包含本地构建（`build`）配置，适合日常开发调试。
- `docker-compose.prod.yml`：生产基线，使用预构建镜像（不本地构建），适合部署环境。
- `docker-compose.ha.yml`：HA 覆盖层，提供 PostgreSQL 主从、Redis 主从 + Sentinel、备份任务。
-
-### 使用选择
- 本地开发：使用 `docker-compose.yml`
- 生产部署：使用 `docker-compose.prod.yml`
- 需要高可用：在上面任一基线上叠加 `docker-compose.ha.yml`
-
-> 注意：`docker-compose.ha.yml` 是覆盖文件，不能单独使用。
-
-### 常用命令
-
-#### 开发模式（单机）
 ```bash
-docker compose -f docker-compose.yml up -d
+cd admin-frontend
+npm install
+npm run dev
 ```

-#### 开发 + HA（主从/哨兵演练）
+## 质量检查
+
 ```bash
-docker compose -f docker-compose.yml -f docker-compose.ha.yml up -d
+cd backend
+pytest
+ruff check app tests
+
+cd ../frontend
+npm run build
+
+cd ../admin-frontend
+npm run build
 ```

-#### 生产模式（预构建镜像）
-```bash
-docker compose -f docker-compose.prod.yml up -d
-```
+当前已知情况：完整后端测试可通过；全量 ruff 仍有少量历史 lint 债，优先处理核心演示链路与新增代码。

-#### 生产 + HA
-```bash
-docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml up -d
-```
+## 核心接口

-#### 查看状态 / 日志
-```bash
-docker compose -f docker-compose.yml -f docker-compose.ha.yml ps
-docker compose -f docker-compose.yml -f docker-compose.ha.yml logs -f backend
-```
-
-#### 停止并清理（含卷）
-```bash
-docker compose -f docker-compose.yml -f docker-compose.ha.yml down -v
-```
-
-### `docker-compose.prod.yml` 镜像标签
-`docker-compose.prod.yml` 使用以下镜像格式：
- `${REGISTRY:-}dreamweaver-backend:${TAG:-latest}`
- `${REGISTRY:-}dreamweaver-frontend:${TAG:-latest}`
- `${REGISTRY:-}dreamweaver-admin-frontend:${TAG:-latest}`
-
-Linux 部署示例（推荐）：
-```bash
-export REGISTRY=my-registry.example.com/
-export TAG=2026.02.12
-docker compose -f docker-compose.prod.yml up -d
-```
-
-Windows PowerShell 示例：
-```powershell
-$env:REGISTRY="my-registry.example.com/"
-$env:TAG="2026.02.12"
-docker compose -f docker-compose.prod.yml up -d
-```
-
-### Linux 服务器部署流程（推荐）
-以下流程适用于 Ubuntu/CentOS 等 Linux 服务器：
-
-#### 1) 准备配置
-```bash
-cp backend/.env.example backend/.env
-# 编辑 backend/.env，至少配置 SECRET_KEY、OAuth/API Key 等
-```
-
-#### 2) 启动（非 HA）
-```bash
-export REGISTRY=my-registry.example.com/
-export TAG=2026.02.12
-docker compose -f docker-compose.prod.yml pull
-docker compose -f docker-compose.prod.yml up -d
-```
-
-#### 3) 启动（HA）
-```bash
-export REGISTRY=my-registry.example.com/
-export TAG=2026.02.12
-docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml pull
-docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml up -d
-```
-
-#### 4) 运行状态检查
-```bash
-docker compose -f docker-compose.prod.yml ps
-docker compose -f docker-compose.prod.yml logs -f backend
-```
-HA 场景使用：
-```bash
-docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml ps
-docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml logs -f backend
-```
-
-#### 5) 版本升级
-```bash
-export TAG=2026.02.13
-docker compose -f docker-compose.prod.yml pull
-docker compose -f docker-compose.prod.yml up -d
-```
-HA 场景同理，在命令中额外叠加 `-f docker-compose.ha.yml`。
-
-#### 6) 版本回滚
-```bash
-export TAG=2026.02.12
-docker compose -f docker-compose.prod.yml pull
-docker compose -f docker-compose.prod.yml up -d
-```
-
-## 供应商路由与管理后台
- 路由按配置顺序尝试：`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/dev/signin` | 本地开发登录，仅 `DEBUG=true` 可用 |
+| GET | `/auth/github/signin` | GitHub OAuth 登录 |
+| GET | `/auth/google/signin` | Google OAuth 登录 |
 | 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 列表（需后台开启 + 管理员） |
+| 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 管理，需开启管理后台 |

-## 环境变量
-常用项（详见 `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 有效且配额充足。
+- `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 原型和历史归档已从主仓库移除，避免干扰当前求职演示主线。