DreamWeaver/dreamweaver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: simplify project entrypoints

Browse Source
This commit is contained in:
Yuyan
2026-04-18 12:23:41 +08:00
parent 44405ff7ac
commit bb575a7fe9
76 changed files with 282 additions and 10399 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
docs/README.md
View File

@@ -1,166 +1,29 @@
# Documentation Index
# 文档索引
This repository now uses a simple documentation taxonomy so you can quickly tell:
当前文档只保留对求职演示和短期迭代有用的内容，避免旧方案、临时交接和原型素材混在主线里。
- what is current and actionable
- what is product-facing vs. technical
- what is historical and should not be treated as source of truth
## Product
---
- `product/job-search-relaunch-prd.md`
求职版产品重启 PRD。用于说明产品定位、用户价值、MVP 范围和面试表达主线。
## Folder Structure
- `product/unified-generation-workflow-prd.md`
统一生成工作流 PRD。用于说明故事、绘本、封面、语音如何收敛成一条清晰体验。
### `docs/product/`
## Planning
Current product documents. These are the best starting point when you want to understand:
- `planning/week-1-execution-backlog.md`
当前短期执行 backlog。用于决定下一步先做什么，以及如何拆成可交付任务。
- product positioning
- MVP scope
- feature requirements
- portfolio/presentation story
## Technical
Files:
- `technical/memory-system-dev.md`
记忆系统技术说明。用于后续继续做孩子档案、故事宇宙和个性化生成。
- `job-search-relaunch-prd.md`
Status: Active
Type: Product strategy / reboot PRD
Use when: you want the current product direction and prioritization.
## 维护规则
- `unified-generation-workflow-prd.md`
Status: Active
Type: Feature-level PRD
Use when: you want the target design for the core generation workflow.
### `docs/planning/`
Execution-oriented documents. These are for sprint planning, backlog breakdown, and short-term delivery.
Files:
- `document-status-inventory.md`
Status: Active
Type: Documentation audit / implementation mapping
Use when: you want to know which docs are current, which capabilities are really implemented, and where coding should restart.
- `week-1-execution-backlog.md`
Status: Active
Type: Sprint / execution planning
Use when: you want to know what to do first and how to break work into tasks.
- `weekend-handoff-2026-04-17.md`
Status: Active
Type: Progress handoff / execution snapshot
Use when: you want to continue work from another machine without reconstructing the latest checkpoint from chat history.
### `docs/technical/`
Technical reference documents. These are implementation-oriented and may include design guidance or development notes.
Files:
- `memory-system-dev.md`
Status: Reference
Type: Technical design / development guide
Use when: you work on the memory system or want to study one style of technical design note.
Note: parts of this document are forward-looking and should be validated against the current codebase before implementation.
### `docs/operations/`
Runbooks and environment/operations documentation.
Files:
- `ha-runbook.md`
Status: Reference
Type: Operations runbook
Use when: you work on Docker-based HA deployment, Redis Sentinel, PostgreSQL replication, or backup verification.
### `docs/archive/`
Historical documents. Keep these for learning or project history, but do not treat them as the current source of truth.
Files:
- `provider-system-legacy.md`
Status: Archived
Type: Historical technical plan
Why archived: partially outdated; references earlier provider architecture and older app entry naming.
- `refactoring-plan-legacy.md`
Status: Archived
Type: Historical implementation plan
Why archived: reflects an earlier refactor phase; some items are completed, some are no longer current priorities.
- `stories-split-analysis-legacy.md`
Status: Archived
Type: Historical code analysis
Why archived: tied to a past `stories.py` split effort and no longer represents the current structure.
---
## Deleted Document
The following document was removed instead of archived:
- `backend/docs/code_review_report.md`
Reason: it was a one-off review artifact, not a durable project document, and its main issue was already resolved by the later `0002_add_api_key_to_providers.py` migration.
---
## Recommended Reading Order
If you want to understand the project as a product manager:
1. `docs/product/job-search-relaunch-prd.md`
2. `docs/product/unified-generation-workflow-prd.md`
3. `docs/planning/document-status-inventory.md`
4. `docs/planning/week-1-execution-backlog.md`
5. `docs/planning/weekend-handoff-2026-04-17.md`
6. `docs/technical/memory-system-dev.md`
7. `docs/operations/ha-runbook.md`
If you want to understand the project as an engineer:
1. `docs/planning/document-status-inventory.md`
2. `docs/product/unified-generation-workflow-prd.md`
3. `docs/technical/memory-system-dev.md`
4. `docs/operations/ha-runbook.md`
5. `docs/archive/*` only when you need historical context
---
## Documentation Rules Going Forward
When adding a new document, place it using these rules:
- Put it in `docs/product/` if it explains what should be built and why.
- Put it in `docs/planning/` if it explains when or in what order work should happen.
- Put it in `docs/technical/` if it explains how something works or should be implemented.
- Put it in `docs/operations/` if it is about deployment, environments, runbooks, or maintenance.
- Put it in `docs/archive/` if it is historically useful but no longer current.
Delete a document only when all three are true:
- it is a one-off artifact
- it is not a reusable reference
- its key information is either obsolete or already captured elsewhere
Archive instead of deleting when:
- the document shows project history
- the document may still help future debugging or learning
- you are not fully sure whether it is still valuable
---
## PM Learning Note
A good documentation system helps you think clearly:
- `product` tells you what problem you are solving
- `planning` tells you what to do next
- `technical` tells you how the system works
- `operations` tells you how to run it
- `archive` tells you what used to be true
That separation is useful not only for this repo, but also as a general PM habit. Many product documents become confusing because they mix all five at once.
- 新 PRD 放到 `docs/product/`
- 新执行计划放到 `docs/planning/`
- 新技术说明放到 `docs/technical/`
- 一次性记录、过期交接、旧原型、未验证部署实验不再放进主仓库
- 如果某份文档不能帮助“演示产品、解释决策、指导下一步编码”，优先删除而不是继续堆叠

246
docs/archive/provider-system-legacy.md
View File

@@ -1,246 +0,0 @@
# Provider 系统开发文档
## 当前版本功能 (v0.2.0)
### 已完成功能
1. **CQTAI nano 图像适配器** (`app/services/adapters/image/cqtai.py`)
- 异步生成 + 轮询获取结果
- 支持 nano-banana / nano-banana-pro 模型
- 支持多种分辨率和画面比例
- 支持图生图 (filesUrl)
2. **密钥加密存储** (`app/services/secret_service.py`)
- Fernet 对称加密，密钥从 SECRET_KEY 派生
- Provider API Key 自动加密存储
- 密钥管理 API (CRUD)
3. **指标收集系统** (`app/services/provider_metrics.py`)
- 调用成功率、延迟、成本统计
- 时间窗口聚合查询
- 已集成到 provider_router
4. **熔断器功能** (`app/services/provider_metrics.py`)
- 连续失败 3 次触发熔断
- 60 秒后自动恢复尝试
- 健康状态持久化到数据库
5. **管理后台前端** (`app/admin_app.py`)
- 独立端口部署 (8001)
- Vue 3 + Tailwind CSS 单页应用
- Provider CRUD 管理
- 密钥管理界面
- Basic Auth 认证
### 配置说明
```bash
# 启动主应用
uvicorn app.main:app --port 8000
# 启动管理后台 (独立端口)
uvicorn app.admin_app:app --port 8001
```
环境变量:
```
CQTAI_API_KEY=your-cqtai-api-key
ENABLE_ADMIN_CONSOLE=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password
```
---
## 下一版本优化计划 (v0.3.0)
### 高优先级
#### 1. 智能负载分流 (方案 B)
**目标**: 主渠道压力大时自动分流到后备渠道
**实现方案**:
- 监控指标: 并发数、响应延迟、错误率
- 分流阈值配置:
```python
class LoadBalanceConfig:
max_concurrent: int = 10 # 并发超过此值时分流
max_latency_ms: int = 5000 # 延迟超过此值时分流
max_error_rate: float = 0.1 # 错误率超过 10% 时分流
```
- 分流策略: 加权轮询，根据健康度动态调整权重
**涉及文件**:
- `app/services/provider_router.py` - 添加负载均衡逻辑
- `app/services/provider_metrics.py` - 添加并发计数器
- `app/db/admin_models.py` - 添加 LoadBalanceConfig 模型
#### 2. Storybook 适配器
**目标**: 生成可翻页的分页故事书
**实现方案**:
- 参考 Gemini AI Story Generator 格式
- 输出结构:
```python
class StorybookPage:
page_number: int
text: str
image_prompt: str
image_url: str | None
class Storybook:
title: str
pages: list[StorybookPage]
cover_url: str | None
```
- 集成文本 + 图像生成流水线
**涉及文件**:
- `app/services/adapters/storybook/` - 新建目录
- `app/api/stories.py` - 添加 storybook 生成端点
### 中优先级
#### 3. 成本追踪系统
**目标**: 记录实际消费，支持预算控制
**实现方案**:
- 成本记录表:
```python
class CostRecord:
user_id: str
provider_id: str
capability: str # text/image/tts
estimated_cost: Decimal
actual_cost: Decimal | None
timestamp: datetime
```
- 预算配置:
```python
class BudgetConfig:
user_id: str
daily_limit: Decimal
monthly_limit: Decimal
alert_threshold: float = 0.8 # 80% 时告警
```
- 超预算处理: 拒绝请求 / 降级到低成本 provider
**涉及文件**:
- `app/db/admin_models.py` - 添加 CostRecord, BudgetConfig
- `app/services/cost_tracker.py` - 新建
- `app/api/admin_providers.py` - 添加成本查询 API
#### 4. 指标可视化
**目标**: 管理后台展示供应商指标图表
**实现方案**:
- 添加指标查询 API:
- GET /admin/metrics/summary - 汇总统计
- GET /admin/metrics/timeline - 时间线数据
- GET /admin/metrics/providers/{id} - 单个供应商详情
- 前端使用 Chart.js 或 ECharts 展示
### 低优先级
#### 5. 多租户 Provider 配置
**目标**: 每个租户可配置独立 provider 列表和 API Key
**实现方案**:
- 租户配置表:
```python
class TenantProviderConfig:
tenant_id: str
provider_type: str
provider_ids: list[str] # 按优先级排序
api_key_override: str | None # 加密存储
```
- 路由时优先使用租户配置，回退到全局配置
#### 6. Provider 健康检查调度器
**目标**: 定期主动检查 provider 健康状态
**实现方案**:
- Celery Beat 定时任务
- 每 5 分钟检查一次所有启用的 provider
- 更新 ProviderHealth 表
#### 7. 适配器热加载
**目标**: 支持运行时动态加载新适配器
**实现方案**:
- 适配器插件目录: `app/services/adapters/plugins/`
- 启动时扫描并注册
- 提供 API 触发重新扫描
---
## API 变更记录
### v0.2.0 新增
| Method | Route | Description |
|--------|-------|-------------|
| GET | `/admin/secrets` | 列出所有密钥名称 |
| POST | `/admin/secrets` | 创建/更新密钥 |
| DELETE | `/admin/secrets/{name}` | 删除密钥 |
| GET | `/admin/secrets/{name}/verify` | 验证密钥有效性 |
### 计划中 (v0.3.0)
| Method | Route | Description |
|--------|-------|-------------|
| GET | `/admin/metrics/summary` | 指标汇总 |
| GET | `/admin/metrics/timeline` | 时间线数据 |
| POST | `/api/storybook/generate` | 生成分页故事书 |
| GET | `/admin/costs` | 成本统计 |
| POST | `/admin/budgets` | 设置预算 |
---
## 适配器开发指南
### 添加新适配器
1. 创建适配器文件:
```python
# app/services/adapters/image/new_provider.py
from app.services.adapters.base import AdapterConfig, BaseAdapter
from app.services.adapters.registry import AdapterRegistry
@AdapterRegistry.register("image", "new_provider")
class NewProviderAdapter(BaseAdapter[str]):
adapter_type = "image"
adapter_name = "new_provider"
async def execute(self, prompt: str, **kwargs) -> str:
# 实现生成逻辑
pass
async def health_check(self) -> bool:
# 实现健康检查
pass
@property
def estimated_cost(self) -> float:
return 0.01 # USD
```
2. 在 `__init__.py` 中导入:
```python
# app/services/adapters/__init__.py
from app.services.adapters.image import new_provider as _new_provider # noqa: F401
```
3. 添加配置:
```python
# app/core/config.py
new_provider_api_key: str = ""
# app/services/provider_router.py
API_KEY_MAP["new_provider"] = "new_provider_api_key"
```
4. 更新 `.env.example`:
```
NEW_PROVIDER_API_KEY=
```

109
docs/archive/refactoring-plan-legacy.md
View File

@@ -1,109 +0,0 @@
# DreamWeaver 重构实施计划
## 1. 概述
本文档基于对当前架构的深入分析，制定了从稳定性、可维护性到可扩展性的分阶段重构计划。
**目标**：
- **短期**：解决单点故障风险，优化开发体验，清理关键技术债。
- **中期**：提升系统高可用能力，增强监控与可观测性。
- **长期**：架构演进，支持大规模并发与复杂业务场景。
---
## 2. 短期优化计划 (1-2周)
**重点**：消除即时风险，提升部署效率。
### 2.1 统一镜像构建 (High Priority)
目前 `backend`, `backend-admin`, `worker`, `celery-beat` 重复构建 4 次，浪费资源且镜像版本可能不一致。
- **Action Items**:
- [x] 修改 `backend/Dockerfile` 为通用基础镜像。
- [x] 更新 `docker-compose.yml`，定义 `backend-base` 服务或使用 `image` 标签共享镜像。
- [x] 确保所有 Python 服务共用同一构建产物，仅启动命令不同。
### 2.2 修复 Provider 缓存与限流 (High Priority)
内存缓存 (`TTLCache`, `_latency_cache`) 在多进程/多实例下失效。
- **Action Items**:
- [x] 引入 Redis 作为共享缓存后端。
- [x] 重构 `_load_provider_cache`，将 Provider 配置缓存至 Redis。
- [x] 重构 `stories.py` 中的限流逻辑，使用 `redis-cell` 或简单的 Redis 计数器替代 `TTLCache`。
### 2.3 拆分 `stories.py` (Medium Priority)
`app/api/stories.py` 超过 600 行，包含 API 定义、业务逻辑、验证逻辑，维护困难。
- **Action Items**:
- [x] 创建 `app/services/story_service.py`，迁移生成、润色、PDF生成等核心逻辑。
- [x] 创建 `app/schemas/story_schemas.py`，迁移 Pydantic 模型（`GenerateRequest`, `StoryResponse` 等）。
- [x] API 层 `stories.py` 仅保留路由定义和依赖注入，调用 Service 层。
---
## 3. 中期优化计划 (1-2月)
**重点**：高可用 (HA) 与系统韧性。
### 3.1 数据库高可用 (Critical)
当前 PostgreSQL 为单点，且 Admin/User 混合使用。
- **Action Items**:
- [ ] 部署 PostgreSQL 主从复制 (Master-Slave)。
- [ ] 配置 `PgBouncer` 或 SQLAlchemy 读写分离，减轻主库压力。
- [ ] 实施数据库自动备份策略 (如 `pg_dump` 定时上传 S3)。
### 3.2 消息队列高可用 (Critical)
Redis 单点故障将导致 Celery 任务全盘停摆。
- **Action Items**:
- [ ] 迁移至 Redis Sentinel 或 Redis Cluster 模式。
- [ ] 更新 Celery 配置以支持 Sentinel/Cluster 连接串。
### 3.3 增强可观测性 (Important)
目前仅有简单的日志，缺乏系统级指标。
- **Action Items**:
- [ ] 集成 Prometheus Client，暴露 `/metrics` 端点。
- [ ] 部署 Grafana + Prometheus，监控 API 延迟、QPS、Celery 队列积压情况。
- [ ] 完善 `ProviderMetrics`，增加可视化大盘，实时监控 AI 供应商的成本与成功率。
### 3.4 Phase 3 最小可执行任务清单 (MVP)
目标：在不大改业务代码的前提下，于一个迭代内完成高可用基础设施闭环。
- [x] PostgreSQL 主从：新增 `docker-compose.ha.yml`，包含 1 主 1 从与健康检查。
- [x] PostgreSQL 备份：新增每日备份任务（`pg_dump`）与 7 天保留策略。
- [x] Redis Sentinel：新增 1 主 2 哨兵最小拓扑，并验证故障切换。
- [x] Celery 连接：更新 Celery broker/result backend 配置，支持 Sentinel 连接串。
- [x] 回归验证：执行一次故事生成 + 异步任务链路（worker/beat）冒烟测试。
- [x] 运行手册：补充故障切换与恢复步骤文档（PostgreSQL/Redis/Celery）。
---
## 4. 长期架构演进 (季度规划)
**重点**：业务解耦与规模化。
### 4.1 统一 API 网关
- **当前**：前端直连后端端口，CORS 配置分散。
- **演进**：引入 Traefik 或 Nginx 作为统一网关，管理路由、SSL、全局限流、统一鉴权。
### 4.2 前端工程合并
- **当前**：User App 和 Admin Console 是完全独立的两个项目，但在组件和工具链上高度重复。
- **演进**：使用一种 Monorepo 策略或基于路由的单一应用策略，共享组件库和类型定义，减少维护成本。
### 4.3 事件驱动架构完善
- **当前**：部分业务逻辑耦合在 API 中。
- **演进**：扩展事件总线，将“阅读记录”、“成就解锁”、“通知推送”等非核心链路完全异步化，通过 Domain Events 解耦。
---
## 5. 实施路线图
| 阶段 | 时间估算 | 关键里程碑 |
| :--- | :--- | :--- |
| **Phase 1: 基础夯实** | Week 1-2 | Docker 构建优化上线，Redis 替代内存缓存。 |
| **Phase 2: 代码重构** | Week 3-4 | `stories.py` 拆分完成，Service 层建立。 |
| **Phase 3: 高可用建设** | Month 2 | 数据库与 Redis 实现主备/集群模式。 |
| **Phase 4: 监控体系** | Month 2 | Grafana 监控大盘上线，关键指标报警配置完毕。 |

52
docs/archive/stories-split-analysis-legacy.md
View File

@@ -1,52 +0,0 @@
# `stories.py` 拆分分析 (Phase 2 准备)
## 当前职责
`app/api/stories.py` (591 行) 承担了以下职责：
| 职责 | 行数 | 描述 |
|---|---|---|
| Pydantic 模型 | ~50 行 | `GenerateRequest`, `StoryResponse`, `FullStoryResponse` 等 |
| 验证逻辑 | ~40 行 | `_validate_profile_and_universe` |
| 路由 + 业务 | ~300 行 | `generate_story`, `generate_story_full`, `generate_story_stream` |
| 绘本逻辑 | ~170 行 | `generate_storybook_api` (含并行图片生成) |
| 成就查询 | ~30 行 | `get_story_achievements` |
## 缺失端点
测试中引用但 **未实现** 的端点（这些应在拆分时一并补充）：
- `GET /api/stories` — 故事列表 (分页)
- `GET /api/stories/{id}` — 故事详情
- `DELETE /api/stories/{id}` — 故事删除
- `POST /api/image/generate/{id}` — 封面图片生成
- `GET /api/audio/{id}` — 语音朗读
## 建议拆分结构
```
app/
├── schemas/
│ └── story_schemas.py # [NEW] Pydantic 模型
├── services/
│ └── story_service.py # [NEW] 核心业务逻辑
└── api/
├── stories.py # [SLIM] 路由定义 + 依赖注入
└── stories_storybook.py # [NEW] 绘本相关端点 (可选)
```
### `story_schemas.py`
- 迁移所有 Pydantic 模型
- 包括 `GenerateRequest`, `StoryResponse`, `FullStoryResponse`, `StorybookRequest`, `StorybookResponse` 等
### `story_service.py`
- `validate_profile_and_universe()` — 验证逻辑
- `create_story()` — 故事入库
- `generate_and_save_story()` — 生成 + 保存联合操作
- `generate_storybook_with_images()` — 绘本并行图片生成
- 补充: `list_stories()`, `get_story()`, `delete_story()`
### `stories.py` (瘦路由层)
- 仅保留 `@router` 装饰器和依赖注入
- 调用 service 层完成业务逻辑
- 预计 150-200 行

89
docs/operations/ha-runbook.md
View File

@@ -1,89 +0,0 @@
# HA 部署与验证 Runbook（Phase 3 MVP）
本文档对应 `docker-compose.ha.yml`，用于本地/测试环境验证高可用基础能力。
## 1. 启动方式
```bash
docker compose -f docker-compose.yml -f docker-compose.ha.yml up -d
```
说明：
- 基础业务服务仍来自 `docker-compose.yml`。
- `docker-compose.ha.yml` 覆盖了 `db`、`redis`，并新增 `db-replica`、`postgres-backup`、`redis-replica`、`redis-sentinel-*`。
## 2. 核心环境变量建议
在 `backend/.env`（或 shell 环境）中至少配置：
```env
# PostgreSQL
POSTGRES_USER=dreamweaver
POSTGRES_PASSWORD=dreamweaver_password
POSTGRES_DB=dreamweaver_db
POSTGRES_REPMGR_PASSWORD=repmgr_password
# Redis Sentinel
REDIS_SENTINEL_ENABLED=true
REDIS_SENTINEL_NODES=redis-sentinel-1:26379,redis-sentinel-2:26379,redis-sentinel-3:26379
REDIS_SENTINEL_MASTER_NAME=mymaster
REDIS_SENTINEL_DB=0
REDIS_SENTINEL_SOCKET_TIMEOUT=0.5
# 可选：若 Sentinel/Redis 设置了密码
REDIS_SENTINEL_PASSWORD=
# 备份周期，默认 86400 秒（1 天）
BACKUP_INTERVAL_SECONDS=86400
```
## 3. 健康检查
### 3.1 PostgreSQL 主从
```bash
docker compose -f docker-compose.yml -f docker-compose.ha.yml ps
docker exec -it dreamweaver_db_primary psql -U dreamweaver -d dreamweaver_db -c "select now();"
docker exec -it dreamweaver_db_replica psql -U dreamweaver -d dreamweaver_db -c "select pg_is_in_recovery();"
```
期望：
- 主库可读写；
- 从库 `pg_is_in_recovery()` 返回 `t`。
### 3.2 Redis Sentinel
```bash
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel masters
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel replicas mymaster
```
期望：
- `mymaster` 存在；
- 至少 1 个 replica 被发现。
### 3.3 备份任务
```bash
docker exec -it dreamweaver_postgres_backup sh -c "ls -lh /backups"
```
期望：
- `/backups` 下出现 `.dump` 文件；
- 旧于 7 天的备份会被自动清理。
## 4. 故障切换演练（最小）
```bash
# 模拟 Redis 主节点故障
docker stop dreamweaver_redis_master
# 等待 Sentinel 选主后查看
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel get-master-addr-by-name mymaster
```
提示：应用与 Celery 已支持 Sentinel 配置。若未启用 Sentinel，仍可回退到 `REDIS_URL` / `CELERY_BROKER_URL` / `CELERY_RESULT_BACKEND` 直连模式。
## 5. 当前已知限制（下一步）
- PostgreSQL 侧当前仅完成主从拓扑，读写分离（PgBouncer/路由）待后续迭代。

450
docs/planning/document-status-inventory.md
View File

@@ -1,450 +0,0 @@
# DreamWeaver 文档状态盘点表
**Version**: 1.0
**Date**: 2026-04-17
**Author**: Sarah (Product Owner) / Codex
**Document Type**: Documentation Audit / Source-of-Truth Inventory
---
## 1. 盘点目的
这份文档不是新的 PRD，也不是新的技术方案，而是一份“项目资产盘点文档”。它解决三个问题：
1. 让团队快速分清楚 `docs/` 里哪些文件是当前有效文档，哪些只是历史材料。
2. 让产品文档与代码现实建立映射，避免“文档看起来很完整，但代码并没有落地”的错觉。
3. 在重新启动项目时，为后续改代码提供明确起点，减少无效重构和重复讨论。
对于求职版 DreamWeaver，这份盘点文档的价值在于：它帮助你把“会写需求文档”进一步提升为“会管理文档体系、会判断 source of truth、会做项目现状诊断”。
---
## 2. 盘点范围与判定口径
### 2.1 盘点范围
本次盘点覆盖以下对象：
- `docs/` 当前全部文档
- 后端核心实现：`backend/app/api/`、`backend/app/services/`、`backend/app/db/`
- 前端关键体验：`frontend/src/components/`、`frontend/src/views/`、`frontend/src/stores/`
- 运维相关配置：`docker-compose.ha.yml`、`backend/app/core/`
- 构建与验证结果：后端测试、后端 lint、主前端构建、管理端构建
### 2.2 文档状态定义
| 文档状态 | 含义 |
| --- | --- |
| Active | 当前有效，应作为近期工作的参考依据 |
| Reference | 有参考价值，但不能直接视为最新实现说明 |
| Archived | 保留历史价值，但不再作为现行 source of truth |
### 2.3 代码落地状态定义
| 落地状态 | 含义 |
| --- | --- |
| 非实现类文档 | 文档本身是产品/规划/治理文档，不直接对应“已实现/未实现” |
| 已实现 | 文档描述的主体能力已在代码中形成闭环，且验证结果基本通过 |
| 部分实现 | 已有主干能力，但关键路径、恢复能力、状态模型或工程质量仍未闭环 |
| 未实现 | 文档描述的主体仍是目标态，当前代码尚未形成有效落地 |
| 历史文档 | 文档描述对应的是过去的设计/阶段，部分内容已落地，但已不适合作为现行依据 |
### 2.4 本次验证快照
截至 2026-04-17 evening，本次盘点同步得到以下验证结果：
- 后端测试通过：`backend/` 下 `pytest -q` 结果为 `53 passed`
- 主前端类型检查通过：`frontend/` 下 `vue-tsc --noEmit` 成功
- 主前端完整构建在当前环境受 Rollup 可选原生包缺失影响，属于环境依赖问题，不是本轮状态模型改动直接引起
- 管理端范围仍未明确，不适合作为当前求职版稳定演示链路
- 后端 lint 仍有历史债务，尚未完成最后一轮收尾
这意味着：项目并不是“不能运行”，而是“核心主链路可用，但工程完备度和演示稳定性还没到求职成品状态”。
---
## 3. 文档状态总表
| 文档 | 分类 | 文档状态 | 代码落地状态 | 盘点结论 | 建议动作 |
| --- | --- | --- | --- | --- | --- |
| `docs/README.md` | 文档治理 | Active | 非实现类文档 | 当前 docs 分类规则清晰，已成为文档入口页 | 保留并持续维护 |
| `docs/product/job-search-relaunch-prd.md` | 产品 PRD | Active | 非实现类文档 | 是当前“求职版产品重启”的核心 source of truth | 保留，作为产品总纲 |
| `docs/product/unified-generation-workflow-prd.md` | 功能 PRD | Active | 部分实现 | 目标方向明确，但“统一工作流”目标态尚未真正落地 | 保留，作为改代码主依据 |
| `docs/planning/week-1-execution-backlog.md` | 执行规划 | Active | 非实现类文档 | 是执行计划，不应用它判断是否“已经做完” | 保留，并按完成情况更新 |
| `docs/planning/document-status-inventory.md` | 项目盘点 | Active | 非实现类文档 | 当前文档体系与代码现实的映射表 | 保留，后续按阶段更新 |
| `docs/technical/memory-system-dev.md` | 技术设计 | Reference | 部分实现 | 记忆系统主干已存在，但文档中不少内容仍是增强设计 | 保留，开发前逐条核验 |
| `docs/operations/ha-runbook.md` | 运维 Runbook | Reference | 部分实现 | Docker HA、Redis Sentinel、备份与 Celery Sentinel 支持已存在，但仍属基础版 | 保留，按真实环境演练继续校正 |
| `docs/archive/provider-system-legacy.md` | 历史技术文档 | Archived | 历史文档 | 部分设计已落地，但命名与架构描述已过时 | 继续归档，不再扩写 |
| `docs/archive/refactoring-plan-legacy.md` | 历史实施计划 | Archived | 历史文档 | 反映旧阶段重构过程，部分 checklist 已完成 | 继续归档，仅供回溯 |
| `docs/archive/stories-split-analysis-legacy.md` | 历史分析 | Archived | 历史文档 | 拆分分析对应的主要重构已发生 | 继续归档，仅供理解演进过程 |
---
## 4. 逐份文档判定说明
### 4.1 `docs/README.md`
**判定**
当前有效，属于“文档治理入口”。
**证据**
- 已明确区分 `product / planning / technical / operations / archive`
- 已写清删除与归档规则
- 已能帮助团队快速识别 source of truth
**结论**
这份文档不是实现说明，但它已经承担“文档信息架构”角色，应继续保留并作为 docs 首页。
### 4.2 `docs/product/job-search-relaunch-prd.md`
**判定**
当前有效，属于产品总纲文档。
**证据**
- 文档明确提出求职版产品定位、成功指标、P0/P1/P2 取舍
- 文档中的问题诊断与当前代码现实一致，包括：
- Storybook 恢复能力不足
- Provider 体系职责混杂
- Admin 构建问题影响演示
- 前端状态设计薄弱
**结论**
这份 PRD 不用于判断“是否已实现”，而用于回答“现在应该把项目做成什么样”。它是当前最重要的产品 source of truth。
### 4.3 `docs/product/unified-generation-workflow-prd.md`
**判定**
当前有效，但对应能力仅部分实现。
**证据**
- 当前后端仍保留多条生成路径：
- `POST /api/stories/generate`
- `POST /api/stories/generate/full`
- `POST /api/storybook/generate`
- 相关实现仍分别落在 `backend/app/api/stories.py` 与 `backend/app/services/story_service.py`
- 当前 `Story` 模型已具备统一主记录的基础字段：
- `story_text`
- `pages`
- `cover_prompt`
- `image_url`
- `mode`
- 当前已经落地的统一状态模型包括：
- `generation_status`
- `image_status`
- `audio_status`
- `last_error`
- `degraded_completed`
- 但更完整的工作流目标仍未完全实现，例如：
- `partial_ready`
- `retryable_assets`
- 统一资产重试入口
- 单一 generation service workflow
**结论**
这份文档对应的是“当前核心改造主线”。它已经不再只是方向性文档，因为统一状态模型和恢复能力已经开始落地；但它仍不是“已完成实现说明”，因为统一工作流入口和统一资产补全过程还未真正收束。
### 4.4 `docs/planning/week-1-execution-backlog.md`
**判定**
当前有效，属于执行计划文档。
**证据**
- 文档将工作拆成产品聚焦、工作流定义、Storybook 恢复、Admin 处理、Provider 边界梳理等任务
- 这些任务与盘点出的真实缺口一致
- 但多数事项仍未被代码完成，因此不能把这份文档当作“实现说明”
**结论**
这是一份“该做什么”的文档，不是“已经做了什么”的文档。后续应在每个任务完成后更新状态，而不是继续长期停留在初始 backlog。
### 4.5 `docs/technical/memory-system-dev.md`
**判定**
技术参考文档，部分实现。
**已落地部分证据**
- `backend/app/db/models.py` 中存在 `MemoryItem`、`ChildProfile`、`StoryUniverse`
- `backend/app/services/memory_service.py` 中已实现：
- 记忆类型定义
- 时效衰减评分
- Prompt 注入格式化
- TTL 清理
- recent story / favorite character / scary element 创建
- `backend/app/api/memories.py` 已提供记忆查询、创建、删除相关接口
- `backend/app/api/profiles.py` 已提供 `GET /profiles/{profile_id}/timeline`
- `backend/app/tasks/memory.py` 和 `backend/app/core/celery_app.py` 已接入每日清理任务
**未完全落地部分**
- 文档规划的反馈接口 `POST /api/memories/{id}/feedback` 当前不存在
- 更复杂的“长期印象总结”“通知机制”“更丰富的结构化 schema”尚未形成闭环
- 时间线目前主要由档案创建、故事记录、宇宙成就拼装而成，还不是完整的成长操作系统
**结论**
记忆系统不是“没做”，而是“已经有主干，但还停在可用原型阶段”。这份文档应该被保留为技术参考，但开发时必须逐条核验，不可直接按文档默认其已落地。
### 4.6 `docs/operations/ha-runbook.md`
**判定**
运维参考文档，部分实现。
**已落地部分证据**
- `docker-compose.ha.yml` 已提供：
- PostgreSQL 主库
- PostgreSQL 从库
- 定时备份容器
- Redis 主从
- 3 个 Sentinel 节点
- `backend/app/core/config.py` 已支持 Sentinel 相关配置解析
- `backend/app/core/redis.py` 已支持通过 Sentinel 获取 Redis master
- `backend/app/core/celery_app.py` 已支持 Celery broker/result backend 走 Sentinel
**未完全落地部分**
- 仍停留在 Docker Compose 层的基础 HA 演练，不是成熟生产级方案
- 尚未看到读写分离、连接池代理、监控告警等更完整设施
- 这份 runbook 更适合作为“基础 HA 实验手册”，而不是正式生产运维规范
**结论**
该文档不应删除，因为它对应的基础设施确实存在；但也不能对外表述成“完整 HA 能力已成熟上线”。
### 4.7 `docs/archive/provider-system-legacy.md`
**判定**
历史文档，部分内容已落地，但整体已过时。
**证据**
- 文档提到的 provider failover、metrics、secret management、admin console 等能力，在代码中能找到对应实现：
- `backend/app/services/provider_router.py`
- `backend/app/services/provider_metrics.py`
- `backend/app/services/secret_service.py`
- `backend/app/api/admin_providers.py`
- 但文档中的部分命名与现状不一致，例如仍提到 `app/admin_app.py`，而当前入口为 `backend/app/admin_main.py`
- 当前 provider router 同时承担默认配置、凭据映射、路由策略、熔断、成本记录等多项职责，说明体系已继续演化，不再等同于这份旧文档
**结论**
这份文档值得保留用于理解历史，但不能作为现行 provider 体系说明书。
### 4.8 `docs/archive/refactoring-plan-legacy.md`
**判定**
历史计划文档，部分任务已完成。
**证据**
- 文档中提到的 `stories.py` 拆分，目前已经有明显落地：
- `backend/app/services/story_service.py`
- `backend/app/schemas/story_schemas.py`
- `backend/app/api/stories.py`
- 文档中提到的 Redis / HA 方向也已有基础实现
- 但它描述的是更早阶段的改造路线，与当前“求职版重启”的产品目标已不是同一语境
**结论**
保留在 `archive/` 是合理的。它是“项目曾经怎么想”的材料，不是“现在应该怎么做”的材料。
### 4.9 `docs/archive/stories-split-analysis-legacy.md`
**判定**
历史分析文档，核心分析目的已经完成。
**证据**
- 文档聚焦 `stories.py` 过重的问题
- 当前已形成更合理的拆分：
- API 层保留路由
- schema 独立
- service 独立
- 说明它的主要使命已经完成
**结论**
应继续归档，用于未来解释“为什么会有现在的结构”，但不再参与当前需求决策。
---
## 5. 当前已落地的核心能力
以下能力已经具备“代码存在且主链路可验证”的基础：
### 5.1 内容生成基础能力
- 普通故事生成、完整故事生成、绘本生成均存在可调用接口
- `Story` 模型已能同时承载文本故事与分页绘本
- 封面图生成与成就提取已接入后处理链路
### 5.2 个性化上下文基础能力
- 孩子档案、故事宇宙、记忆系统、成长时间线均已有基础模型和接口
- Prompt 侧已接入记忆上下文构建
- 成就可回写到 `StoryUniverse.achievements`
### 5.3 Provider 管理基础能力
- Provider Router 已支持 failover
- Provider 管理、密钥管理、成本汇总等管理 API 已存在
- 默认 provider 列表与数据库 provider 配置可共存
### 5.4 运维与异步基础能力
- Celery + Redis 已接入
- Redis Sentinel 与 Celery Sentinel 配置已实现
- PostgreSQL 主从与备份的 Compose 级实验环境已存在
### 5.5 工程可运行性
- 后端测试通过：`53 passed`
- 主前端构建通过
---
## 6. 当前“部分实现 / 未实现”的关键缺口
这些缺口正是接下来改代码最应该优先处理的地方。
### 6.1 统一生成工作流尚未真正落地
虽然 PRD 已经明确目标，但当前系统仍是多入口、多响应模型、多处理路径并存。它们共享了一些底层能力，但还没有收束为统一 workflow。
### 6.2 Storybook 恢复能力不完整
当前前端仍依赖 `frontend/src/stores/storybook.ts` 暂存数据，`frontend/src/views/StorybookViewer.vue` 在刷新或直接访问时无法按 ID 恢复。这是最明显的“演示链路不稳”问题之一。
### 6.3 音频体验未形成闭环
当前 `GET /api/audio/{id}` 会在请求时即时生成音频，但没有持久化缓存与复用策略，既影响用户体验，也影响成本控制。
### 6.4 Provider 体系职责边界仍然混杂
当前 `provider_router.py` 既负责默认 provider、凭据映射、策略排序，又承担 metrics、熔断、成本记录等职责。功能虽强，但不利于后续持续演进，也不利于你在面试中清晰讲解。
### 6.5 管理端尚未达到“可展示成品”标准
`admin-frontend` 当前构建失败，说明管理端虽然概念上存在，但还不适合作为稳定演示链路的一部分。
### 6.6 工程质量信号还不统一
后端测试是加分项，但 lint 未通过会削弱成熟度观感。对于求职版项目，测试通过但 lint 大量报错，会让项目显得“能跑，但还没收尾”。
---
## 7. 推荐下一步编码切入点
如果目标是“尽快把项目恢复到可演示、可讲清、可继续迭代”的状态，建议按以下顺序推进。
### 7.1 第一优先级：补齐 Storybook 按 ID 恢复
**为什么先做**
- 改动范围相对可控
- 用户价值直观
- 修完后演示稳定性立刻提升
- 很适合作为“重新启动项目后的第一场胜仗”
**目标**
- `StorybookViewer` 不再只依赖 Pinia
- 支持通过 `story_id` 拉取 `Story.pages`
- 刷新页面后仍能继续阅读
### 7.2 第二优先级：抽出统一生成状态模型
**为什么第二个做**
- 这是“统一工作流”真正开始落地的最小切口
- 它能先统一语言，再统一代码
- 前端状态设计、后端任务编排、部分完成/降级完成，都会以它为中心展开
**目标**
- 先在服务层定义统一状态
- 再决定是否扩展数据库字段
- 让故事、绘本、图片、音频都能共享一套状态表达
### 7.3 第三优先级：清理 Provider 边界并决定 Admin 范围
**为什么第三个做**
- 这是系统长期可解释性的关键
- 但它比 Storybook 恢复和状态模型更抽象，适合在主链路稳定后推进
**目标**
- 先梳理 Capability / Provider / Routing Policy 三层概念
- 再判断管理端是修复、降级，还是缩小到只保留必要接口
---
## 8. 建议保留、更新、删除动作汇总
### 8.1 建议保留
- `docs/README.md`
- `docs/product/job-search-relaunch-prd.md`
- `docs/product/unified-generation-workflow-prd.md`
- `docs/planning/week-1-execution-backlog.md`
- `docs/technical/memory-system-dev.md`
- `docs/operations/ha-runbook.md`
- `docs/archive/*`
### 8.2 建议更新
- `docs/planning/week-1-execution-backlog.md`
- 需要随着任务推进更新完成状态，不应长期停留在纯规划状态
- `docs/technical/memory-system-dev.md`
- 后续开发时应补充“已实现”和“待实现”标记，减少误读
- `docs/operations/ha-runbook.md`
- 后续若做真实演练，应把演练结果写回文档
### 8.3 当前不建议再删除
本轮分类整理后，`docs/` 目录中没有新的“应该直接删除”的文档。剩余历史文件都具备学习价值或项目演进价值，适合继续保留在 `archive/`。
---
## 9. PM 学习笔记：为什么要写这种盘点文档
很多初级产品文档只会写“要做什么”，但不会回答：
- 现在手里的文档哪些是真的有效
- 哪些是目标态，哪些是现状
- 哪些能力已经能演示，哪些只是概念
- 哪些问题适合现在改，哪些问题应该晚一点改
“文档状态盘点表”就是用来解决这些问题的。它本质上是产品管理中的三项能力训练：
1. **Source of Truth 管理**
你要知道团队现在到底该信哪份文档。
2. **现状诊断能力**
你要把 PRD、代码、构建结果、运维配置放在一起看，而不是只看其中一边。
3. **优先级判断能力**
你要判断什么是“现在最值得做的第一件事”。
以后你在写自己的项目盘点时，可以直接复用这套结构：
1. 盘点目的
2. 判定口径
3. 状态总表
4. 逐项证据
5. 已落地能力
6. 关键缺口
7. 下一步建议
---
## 10. 本次盘点结论
DreamWeaver 当前不是“半成品废案”，而是“有明显实现基础、但还缺一轮产品收束与关键链路补完”的项目。
更准确地说：
- 产品层面，方向已经比以前清楚，现有 PRD 可以继续作为重启依据。
- 技术层面，后端主能力、记忆系统、Provider 管理、异步任务和基础 HA 都不是空白。
- 体验层面，Storybook 恢复、音频闭环、前端状态设计已明显推进，但统一工作流与统一重试入口仍是关键缺口。
- 工程层面，主前端与后端可用，但 admin-frontend 与 lint 问题说明项目还没完成最后一轮收尾。
因此，文档已经足够清晰，可以进入下一阶段：按优先级开始改代码，而不是继续扩写更多概念文档。

139
docs/planning/weekend-handoff-2026-04-17.md
View File

@@ -1,139 +0,0 @@
# DreamWeaver Weekend Handoff - 2026-04-17
## Purpose
这份文档用于周末在另一台电脑上继续推进 DreamWeaver 时快速接手，不需要先重新阅读大量聊天记录或从工作区猜测上下文。
---
## What Is Already On Remote
当前远端 `main` 已经包含两个连续 checkpoint：
- Commit: `a97a2fe`
- Message: `feat: persist story generation states and cache audio`
这个 checkpoint 覆盖的主线如下：
- 新增并落地统一生成状态字段：
- `generation_status`
- `image_status`
- `audio_status`
- `last_error`
- Storybook 阅读页支持按 ID 恢复
- 故事列表页、故事详情页、绘本阅读页接入统一状态展示
- 音频首次生成后缓存落盘并可复用
- 统一状态语义中 `degraded_completed` 已和错误展示保持一致
- Commit: `b8d3cb4`
- Message: `wip: snapshot full local workspace state`
这个 checkpoint 已把 2026-04-17 晚间的工作区快照同步到远端，包括：
- 新增 `AGENTS.md`
- 整理 `docs/` 文档信息架构
- 新增求职版 PRD、统一生成工作流 PRD、Week 1 backlog 与文档盘点
- 归档旧 backend docs 到 `docs/archive/`、`docs/technical/`、`docs/operations/`
- 补齐 Storybook 带 ID 路由恢复相关前端改动
注意：`b8d3cb4` 是一次 WIP 快照提交，原始 diff 中包含大量行尾/格式噪音。继续开发时应以当前 `main` 代码与 `docs/` 中 Active 文档为准，不需要再回到 `a97a2fe` 重新整理。
---
## Current Local Status On 2026-04-18
2026-04-18 在个人电脑接手后已确认：
- 本地 `main` 与 `origin/main` 对齐到 `b8d3cb4`
- 工作树起始状态干净
- 已配置 Gitea HTTPS 推送凭据，并通过 `git push --dry-run origin HEAD:main`
- 后端本地虚拟环境可用：`backend/.venv`
- 主前端与管理端依赖已安装到各自 `node_modules`
---
## Recommended Reading Order
周末继续前，建议先阅读：
1. `docs/product/job-search-relaunch-prd.md`
2. `docs/product/unified-generation-workflow-prd.md`
3. `docs/planning/week-1-execution-backlog.md`
4. `docs/planning/document-status-inventory.md`
---
## Environment Setup On The Next Machine
建议接手后先完成以下动作：
1. `git pull`
2. `cd backend && alembic upgrade head`
3. `cd backend && .venv/bin/python -m pytest -q`（macOS/Linux）
4. `cd frontend && npm install`
5. `cd frontend && ./node_modules/.bin/vue-tsc --noEmit`
如果主前端完整构建失败，优先检查 Rollup 可选原生包是否正常安装，而不是先怀疑本轮代码逻辑。
---
## Current Product / Engineering Position
当前阶段不是“继续加功能”，而是把 DreamWeaver 收敛成可讲述、可演示、可恢复的求职版产品。
已经完成的关键支点：
- 状态模型已落地，不再只是文档概念
- Storybook 恢复能力已补上
- 音频体验开始形成闭环
还没完成的关键工作：
- 普通故事、完整生成、绘本生成仍是多条 service 路径
- 缺少统一资产重试入口
- 缺少更清晰的统一 workflow 编排边界
- admin-frontend 范围和 Provider 边界仍未收束
---
## Best Next Step
周末最值得继续做的第一优先级：
### P0: 统一资产补全过程
目标：
- 抽出封面生成和音频生成的共同步骤
- 让图片 / 音频共享一套资产状态回写逻辑
- 为后续“统一重试入口”打基础
为什么先做：
- 它直接承接已经落地的状态模型
- 它比继续加页面更能体现系统设计能力
- 它能把当前三条生成路径往统一 workflow 再推近一步
### P1: 统一重试入口
目标：
- 至少设计出一个清晰的 retry API 方向
- 即使不一次性重命名为 `/api/generations/...`，也先做到内部统一
### P1: 收敛 service workflow
目标：
- 梳理普通故事 / 完整生成 / 绘本生成的共同步骤
- 把“验证上下文 -> 生成主内容 -> 保存主记录 -> 补全资产 -> 状态回写”整理成更明确的共享流程
---
## Important Reminder
如果周末是在另一台电脑上继续，不要默认“今天下午所有本地修改”都已经上远端。当前最可靠的 source of truth 是：
- 远端代码：以 commit `b8d3cb4` 为准
- 产品目标：以 `docs/product/job-search-relaunch-prd.md` 为准
- 当前执行主线：以 `docs/product/unified-generation-workflow-prd.md` 与 `docs/planning/week-1-execution-backlog.md` 为准