diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5a3b957 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,166 @@ +# 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 + +--- + +## Folder Structure + +### `docs/product/` + +Current product documents. These are the best starting point when you want to understand: + +- product positioning +- MVP scope +- feature requirements +- portfolio/presentation story + +Files: + +- `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. diff --git a/docs/archive/provider-system-legacy.md b/docs/archive/provider-system-legacy.md new file mode 100644 index 0000000..0e11fe0 --- /dev/null +++ b/docs/archive/provider-system-legacy.md @@ -0,0 +1,246 @@ +# 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= +``` diff --git a/docs/archive/refactoring-plan-legacy.md b/docs/archive/refactoring-plan-legacy.md new file mode 100644 index 0000000..4859ceb --- /dev/null +++ b/docs/archive/refactoring-plan-legacy.md @@ -0,0 +1,109 @@ +# 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 监控大盘上线，关键指标报警配置完毕。 | diff --git a/docs/archive/stories-split-analysis-legacy.md b/docs/archive/stories-split-analysis-legacy.md new file mode 100644 index 0000000..eb1179b --- /dev/null +++ b/docs/archive/stories-split-analysis-legacy.md @@ -0,0 +1,52 @@ +# `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 行 diff --git a/docs/operations/ha-runbook.md b/docs/operations/ha-runbook.md new file mode 100644 index 0000000..12893f4 --- /dev/null +++ b/docs/operations/ha-runbook.md @@ -0,0 +1,89 @@ +# 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/路由）待后续迭代。 diff --git a/docs/planning/document-status-inventory.md b/docs/planning/document-status-inventory.md new file mode 100644 index 0000000..2fae192 --- /dev/null +++ b/docs/planning/document-status-inventory.md @@ -0,0 +1,450 @@ +# 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 问题说明项目还没完成最后一轮收尾。 + +因此，文档已经足够清晰，可以进入下一阶段：按优先级开始改代码，而不是继续扩写更多概念文档。 diff --git a/docs/planning/week-1-execution-backlog.md b/docs/planning/week-1-execution-backlog.md new file mode 100644 index 0000000..a915696 --- /dev/null +++ b/docs/planning/week-1-execution-backlog.md @@ -0,0 +1,344 @@ +# DreamWeaver 求职版重启：Week 1 执行 Backlog + +**Version**: 1.0 +**Date**: 2026-04-17 +**Author**: Sarah (Product Owner) +**Sprint Length**: 5 个工作日 +**Sprint Theme**: 产品聚焦与核心生成链路收敛 + +--- + +## 1. Sprint Executive Summary + +本周的核心任务不是“继续加功能”，而是为 DreamWeaver 的求职版重启建立一个稳定、可解释、可执行的基础版本。Week 1 的目标是完成三件事： + +1. 明确 DreamWeaver 求职版的核心产品主线。 +2. 明确统一生成工作流的目标状态与系统边界。 +3. 识别并解决阻碍演示与后续开发的关键基础问题。 + +这意味着本周的重点是“收敛、抽象、对齐”，而不是“冲刺做完所有体验”。如果 Week 1 做得对，Week 2 的前端状态、音频体验和闭环演示才会顺。 + +--- + +## 2. Sprint Goal + +### Sprint Goal + +在 5 个工作日内，将 DreamWeaver 从“功能分散的 AI 项目”推进为“围绕个性化亲子故事体验的清晰产品方案”，并完成统一生成工作流的设计对齐与关键技术阻塞清单。 + +### Sprint Success Definition + +本周结束时，团队应满足以下状态： + +- 已统一项目对外叙事：DreamWeaver 是“个性化 AI 绘本与陪伴式讲述产品”。 +- 已形成统一生成工作流的需求说明、状态模型和系统边界。 +- 已确认 admin 端、Storybook 恢复能力、Provider 重构边界的处理方案。 +- 已产出 Week 2 可直接进入开发的任务清单。 + +## 2.1 Current Progress Snapshot + +**Updated**: 2026-04-17 evening + +### What Has Been Completed + +- 已完成求职版产品方向收敛，并形成 `docs/product/job-search-relaunch-prd.md` 与 `docs/product/unified-generation-workflow-prd.md` +- 已在代码中补齐 Storybook 按 ID 恢复，不再只依赖前端内存态 +- 已在后端和前端落地统一状态字段与状态文案： + - `generation_status` + - `image_status` + - `audio_status` + - `last_error` +- 已补齐故事列表、故事详情、绘本阅读页的状态展示 +- 已为故事音频增加首次生成后落盘缓存与后续复用 +- 已新增数据库迁移： + - `0009_add_story_generation_statuses.py` + - `0010_add_story_audio_cache_path.py` +- 已完成一轮后端回归验证：`backend/` 下 `pytest -q` 结果为 `53 passed` + +### What Is In Progress + +- 统一状态模型已落地，但统一 service workflow 仍未真正收束成单一路径 +- 普通故事、完整生成、绘本生成仍存在多条 service / API 路径 +- 资产补全虽然已经支持图片与音频状态，但“统一重试入口”尚未实现 + +### What Is Still Pending + +- admin-frontend 的处理决策与演示范围收敛 +- Provider 的 Capability / Provider / Routing Policy 边界整理 +- Week 2 可直接执行的开发任务表 +- 演示 checklist 与最终收尾策略 + +### Remote Checkpoint Scope + +当前远端已同步一个阶段性 checkpoint： + +- Commit: `a97a2fe` +- Message: `feat: persist story generation states and cache audio` + +这个 checkpoint **不是今天下午所有本地修改的全集**。它只覆盖以下主线： + +- 统一生成状态模型 +- Storybook 按 ID 恢复 +- 故事列表/详情/绘本页状态展示 +- 音频缓存与状态语义修正 + +当前工作区里仍存在其他未提交、本机独有的改动，周末换电脑后不会自动带过去。 + +--- + +## 3. Scope + +### In Scope + +- 产品主线收敛 +- 统一生成工作流的需求定义 +- Provider 概念重构边界梳理 +- Storybook 恢复路径方案确认 +- Admin 前端处理策略确认 +- Week 2 开发前准备 + +### Out of Scope + +- 大规模前端视觉重构 +- 新增更多 AI 供应商 +- 复杂监控大盘与成本后台 +- 多租户、商业化支付、会员系统 +- 全量高可用部署优化 + +--- + +## 4. Sprint Priorities + +| Priority | Item | Why It Matters | +|------|------|------| +| P0 | 收敛产品定位 | 决定后续所有产品与技术选择 | +| P0 | 统一生成工作流定义 | 决定故事、绘本、音频、封面如何整合 | +| P0 | Storybook 恢复方案 | 当前是演示稳定性的关键缺口 | +| P0 | Admin 端处理决策 | 当前会影响完整构建与部署 | +| P1 | Provider 分层整理 | 为后续系统重构和面试讲解打底 | +| P1 | Week 2 任务准备 | 保证下周可直接进入执行 | + +--- + +## 5. Week 1 User Stories + +### Story A: 明确求职版产品主线 + +**As a** 项目拥有者 +**I want to** 明确 DreamWeaver 求职版只讲一个清晰的产品故事 +**So that** 我在面试和开发中都能聚焦重点 + +**Acceptance Criteria** + +- [ ] 输出一句话产品定位 +- [ ] 输出 3 条核心价值主张 +- [ ] 明确哪些功能是本轮保留，哪些是延后 + +### Story B: 明确统一生成工作流 + +**As a** 产品负责人 +**I want to** 用统一工作流来定义故事、绘本、封面和语音生成 +**So that** 系统可以持续演进，而不是继续分裂 + +**Acceptance Criteria** + +- [x] 定义统一状态模型 +- [x] 明确故事与绘本的共同链路和差异 +- [ ] 明确失败降级与重试原则 + +### Story C: 识别并拆解关键阻塞项 + +**As a** 求职项目维护者 +**I want to** 找出影响演示和开发推进的关键阻塞 +**So that** 后续投入能集中在最高价值项上 + +**Acceptance Criteria** + +- [ ] 明确 admin-frontend 的处理方案 +- [x] 明确 Storybook 恢复方案 +- [ ] 明确 Provider 重构边界 + +--- + +## 6. Task Backlog + +| ID | Workstream | Task | Output | Priority | Estimate | Status | +|------|------|------|------|------|------|------| +| W1-01 | Product | 确认求职版产品定位与展示口径 | 一句话定位 + 3 条价值主张 | P0 | 0.5d | Done | +| W1-02 | Product | 梳理本轮 In Scope / Out of Scope | 范围清单 | P0 | 0.5d | Done | +| W1-03 | Product / System | 盘点现有生成路径：普通故事、完整生成、绘本生成 | 现状流程图或对照表 | P0 | 0.5d | Done | +| W1-04 | Product / System | 定义统一 Generation Workflow 状态模型 | 状态流转说明 | P0 | 1.0d | Done | +| W1-05 | Product / Backend | 定义统一工作流下的 API / 数据结构影响 | 接口与模型变更清单 | P0 | 0.5d | In Progress | +| W1-06 | Product / Backend | 梳理 Provider 概念层：Capability / Provider / Routing Policy | 分层图与术语表 | P1 | 0.5d | Pending | +| W1-07 | Product / Frontend | 梳理 Storybook 当前问题与恢复方案 | 恢复方案说明 | P0 | 0.5d | Done | +| W1-08 | Product / Frontend | 确认 admin 前端是修复、裁剪还是暂时降级 | 决策记录 | P0 | 0.5d | Pending | +| W1-09 | Planning | 产出 Week 2 开发任务清单 | 下周 backlog | P1 | 0.5d | In Progress | +| W1-10 | Review | 形成求职演示版检查清单 | 演示清单 | P1 | 0.5d | Pending | + +--- + +## 7. Recommended Execution Sequence + +### Day 1: 产品聚焦 + +- 完成求职版产品定位 +- 确认本轮保留功能与延后功能 +- 输出一句话产品口径和核心价值主张 + +**Expected Output** + +- 产品定位 statement +- MVP 范围清单 +- 非本轮范围说明 + +### Day 2: 现状拆解 + +- 盘点当前三类生成路径 +- 对比普通故事、完整故事、绘本生成的共同点与差异 +- 找出重复步骤与缺失状态 + +**Expected Output** + +- 现状流程对照表 +- 问题清单 +- 工作流统一方向初稿 + +### Day 3: 统一工作流定义 + +- 确定 Generation Workflow 的状态模型 +- 明确文本、封面、语音、绘本页的生成关系 +- 明确哪些步骤同步、哪些异步 + +**Expected Output** + +- 统一工作流草案 +- 状态流转图 +- 失败降级规则 + +### Day 4: 关键阻塞项决策 + +- 明确 Storybook 恢复方案 +- 明确 admin 端处理策略 +- 明确 Provider 重构边界和迁移原则 + +**Expected Output** + +- 技术决策记录 +- Week 2 实施前置条件 + +### Day 5: Sprint Wrap-up + +- 整理 Week 2 可执行任务 +- 形成演示清单与风险清单 +- 输出周总结 + +**Expected Output** + +- Week 2 backlog +- 演示 checklist +- Sprint review summary + +--- + +## 8. Deliverables + +本周必须交付的成果如下： + +1. 求职版产品定位文档 +2. 统一生成工作流功能级 PRD +3. Storybook 恢复方案说明 +4. Admin 端处理决策 +5. Week 2 开发 Backlog +6. 演示检查清单 + +## 8.1 Weekend Handoff Guidance + +如果周末在另一台电脑继续推进，建议按以下顺序接手： + +1. 先拉取远端 `main`，确认已经包含 commit `a97a2fe` +2. 先阅读： + - `docs/product/job-search-relaunch-prd.md` + - `docs/product/unified-generation-workflow-prd.md` + - 当前这份 backlog +3. 运行数据库迁移：`alembic upgrade head` +4. 从“统一资产补全”和“统一 service workflow”继续，而不是重新发散到新功能 + +建议周末接续时的第一优先级： + +- 抽出图片/音频统一资产补全过程 +- 设计并实现统一的重试入口 +- 继续收敛普通故事、完整生成、绘本生成三条路径 + +--- + +## 9. Definition of Done + +只有满足以下条件，Week 1 才视为完成： + +- [ ] 产品定位能用 30 秒讲清楚 +- [ ] 统一生成工作流的状态模型已明确 +- [ ] 关键阻塞项均有明确处理方案，不处于“再看看” +- [ ] Week 2 有可直接执行的任务表 +- [ ] 所有本周产出都已沉淀为书面文档 + +--- + +## 10. Risks + +| Risk | Likelihood | Impact | Mitigation | +|------|------|------|------| +| 本周又回到“继续加功能” | High | High | 每天检查任务是否服务于核心闭环 | +| Provider 讨论过深，脱离产品目标 | Medium | High | 保持“求职版可解释性”优先，不做过度设计 | +| 前端细节打断主线梳理 | High | Medium | Week 1 不做大量视觉细化，只做策略与任务定义 | +| Storybook 恢复方案定义不清 | Medium | High | 必须把“按 ID 恢复”作为明确目标，不接受模糊状态 | + +--- + +## 11. Dependencies + +- 已有 PRD: `docs/product/job-search-relaunch-prd.md` +- 当前生成接口与数据结构 +- Storybook Viewer 与 Store 实现 +- Provider Router 当前实现 + +--- + +## 12. Suggested Daily Rituals + +为了帮助你模仿真实产品经理工作方式，建议你在执行本周任务时保持以下节奏： + +- **每日开始前**：先写今天要解决的 1 个核心问题。 +- **每日结束时**：用 3 句话回答： + - 今天明确了什么？ + - 还有什么不确定？ + - 明天最重要的一件事是什么？ + +这会帮助你从“想到什么做什么”转向“围绕目标做判断”。 + +--- + +## 13. How to Reuse This Format + +以后你自己写 Sprint Backlog 或执行计划时，可以直接套用这套结构： + +1. Executive Summary +2. Sprint Goal +3. Scope +4. Priorities +5. User Stories +6. Task Backlog +7. Recommended Execution Sequence +8. Deliverables +9. Definition of Done +10. Risks / Dependencies + +和 PRD 不同，Backlog 文档更偏执行，不需要写太多业务背景，但一定要写清楚： + +- 这周为什么做 +- 这周不做什么 +- 每天要推进什么 +- 什么状态算完成 + +--- + +*This document is intended as a PM-style execution backlog for Week 1 of the DreamWeaver portfolio relaunch.* diff --git a/docs/planning/weekend-handoff-2026-04-17.md b/docs/planning/weekend-handoff-2026-04-17.md new file mode 100644 index 0000000..d4c33b4 --- /dev/null +++ b/docs/planning/weekend-handoff-2026-04-17.md @@ -0,0 +1,125 @@ +# DreamWeaver Weekend Handoff - 2026-04-17 + +## Purpose + +这份文档用于周末在另一台电脑上继续推进 DreamWeaver 时快速接手，不需要先重新阅读大量聊天记录或从工作区猜测上下文。 + +--- + +## What Is Already On Remote + +当前远端已经包含一个阶段性 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` 已和错误展示保持一致 + +--- + +## What Is Not Yet On Remote + +当前这台机器的工作区里仍存在大量未提交改动，它们 **不属于上面的 checkpoint**，也不会自动出现在另一台电脑上。 + +因此，周末接手时应该默认： + +- 远端 `main` 只包含“统一状态模型 + Storybook 恢复 + 音频缓存”这一条主线 +- 其他本机未提交内容需要后续再整理，不应假设它们已经同步 + +--- + +## 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/Scripts/python.exe -m pytest -q` +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 `a97a2fe` 为准 +- 产品目标：以 `docs/product/job-search-relaunch-prd.md` 为准 +- 当前执行主线：以 `docs/product/unified-generation-workflow-prd.md` 与 `docs/planning/week-1-execution-backlog.md` 为准 diff --git a/docs/product/job-search-relaunch-prd.md b/docs/product/job-search-relaunch-prd.md new file mode 100644 index 0000000..bc9402f --- /dev/null +++ b/docs/product/job-search-relaunch-prd.md @@ -0,0 +1,474 @@ +# Product Requirements Document: DreamWeaver 求职版产品重启与重构 + +**Version**: 1.0 +**Date**: 2026-04-17 +**Author**: Sarah (Product Owner) +**Quality Score**: 91/100 + +--- + +## Executive Summary + +DreamWeaver 当前已经具备一个 AI 儿童故事产品的基础能力，包括故事生成、绘本生成、封面图生成、语音合成、孩子档案、故事宇宙、记忆系统与供应商路由能力。从“功能数量”上看，这个项目并不空，但从“产品完成度”上看，当前版本的核心问题是价值主线分散、工作流不统一、供应商体系复杂度过高，导致产品体验不够聚焦，项目故事也不够适合面试场景快速讲清楚。 + +本次重启不以“继续堆功能”为目标，而以“构建一个求职可展示、逻辑可讲述、体验可闭环的 AI 产品版本”为目标。求职版 DreamWeaver 将聚焦为一个“面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品”，突出三个核心价值：个性化连续性、稳定的生成工作流、可感知的声音体验。 + +本 PRD 旨在为后续 2 周至 4 周的产品重构提供明确的目标、范围、优先级与阶段计划。文档同时兼具两个用途：一是作为当前项目的重启执行依据；二是作为转型 AI 产品经理时可模仿的标准化产品文档样本。 + +--- + +## Problem Statement + +**Current Situation** +DreamWeaver 目前存在以下产品层与系统层问题： + +1. 产品主线不清晰。系统同时在讲“儿童故事产品”“成长记忆产品”“多供应商 AI 编排平台”三个故事，但没有一个故事被打磨到足够完整。 +2. 关键工作流分裂。普通故事生成、完整生成、绘本生成分别走不同实现，验证、上下文、保存、资产生成与后处理逻辑重复，难以稳定演进。 +3. 供应商体系职责混杂。Provider 路由层同时承担默认配置、Key 映射、路由策略、熔断、成本统计、执行入口等多项职责，维护成本高，后续扩展风险大。 +4. 演示链路不够稳。Storybook 阅读器依赖内存状态，刷新后无法恢复；音频未做缓存；管理端构建失败会阻碍全量部署。 +5. 工程观感不统一。后端测试可通过，但 lint 历史债务较多，前后端重复代码较多，项目成熟度展示受影响。 + +**Proposed Solution** +将项目收敛为“求职版 DreamWeaver MVP”，围绕一个可讲清楚的核心闭环进行重构： + +`选择孩子档案 -> 输入主题/教育目标 -> 生成故事或绘本 -> 生成封面/语音 -> 保存进入故事库与成长时间线` + +系统层同步推进两项重构： + +1. 将故事/绘本/资产生成统一到一套 Generation Workflow 中。 +2. 将供应商体系重构为清晰的 Capability / Provider / Routing Policy 分层结构。 + +**Business Impact** +本轮重构完成后，项目在求职场景中的价值将从“会调用多个模型的功能集合”提升为“有明确价值主张、闭环体验和系统设计取舍的 AI 产品案例”，更适合作为 AI 产品经理岗位的核心项目展示。 + +--- + +## Current Product Diagnosis + +| 诊断项 | 当前表现 | 对产品的影响 | 判断 | +|------|------|------|------| +| 核心价值主张 | 功能较多，但主线分散 | 面试官难以快速理解产品价值 | P0 问题 | +| 生成工作流 | 故事、完整生成、绘本三套路径并存 | 需求扩展成本高，失败处理不一致 | P0 问题 | +| Provider 架构 | 路由、配置、凭证、监控耦合 | 后续优化与说明成本过高 | P0 问题 | +| Storybook 体验 | 依赖前端内存状态，无法按 ID 恢复 | 阅读体验中断，演示不稳 | P0 问题 | +| 音频体验 | 支持实时生成，但无缓存与复用 | 性能与成本不可控 | P1 问题 | +| Admin 前端 | 构建失败，影响完整部署链路 | 一键启动和展示受阻 | P0 问题 | +| 代码质量信号 | 后端测试通过，但 lint 债务明显 | 降低项目成熟度感知 | P1 问题 | +| 前端表现力 | 可用但较轻，缺少状态设计与产品表达 | 难以承载“生成中/失败/降级成功”等体验 | P1 问题 | + +--- + +## Product Positioning + +### 产品定位 + +DreamWeaver 是一款面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品，通过孩子档案、成长主题和故事宇宙上下文，为家庭生成连续、可回看、可聆听的儿童故事体验。 + +### 求职版定位 + +求职版 DreamWeaver 不是“最全功能版本”，而是“最能体现产品思考与系统设计能力的版本”。 +该版本重点体现以下能力： + +- 能围绕明确用户价值做产品收敛，而不是单纯堆功能。 +- 能把多模型、多供应商能力整理成稳定、可解释的 AI 工作流。 +- 能把声音体验、个性化连续性和失败降级机制变成真正的产品能力。 + +### 核心价值主张 + +1. **个性化连续性**：故事不是一次性生成，而是围绕孩子档案与世界观不断积累。 +2. **陪伴式体验**：文本、绘本和语音不是孤立能力，而是一套完整的亲子阅读体验。 +3. **生成稳定性**：用户不需要理解底层模型，只需要感受到“能稳定出结果，失败也可恢复”。 + +--- + +## Success Metrics + +**Primary KPIs** + +- **故事生成成功率**：核心生成链路成功完成率 >= 90% + 测量方式：生成请求中完成文本输出并成功保存主记录的比例。 +- **首个结果可见时长**：用户发起生成后，首个可见结果出现时间 <= 15 秒 + 测量方式：文本结果或“部分完成”状态首次返回时间。 +- **完整体验完成率**：文本、封面、语音至少完成其二的比例 >= 80% + 测量方式：故事生成后资产完成状态统计。 +- **个性化命中率**：在内部评审样本中，>= 80% 的故事能明显体现孩子档案/宇宙上下文 + 测量方式：人工评估打分表。 +- **演示可用率**：求职演示关键链路 10 次连续演示成功率 = 100% + 测量方式：内部演示脚本回归。 + +**Validation** + +- 第 1 阶段验证：以“是否能完成端到端故事闭环”为准。 +- 第 2 阶段验证：以“是否能稳定支持绘本与语音回放体验”为准。 +- 对外验证：以面试演示反馈和项目讲解清晰度为准。 + +--- + +## User Personas + +### Primary Persona: 家长 / 监护人 + +- **Role**: 3-8 岁儿童的家长或监护人 +- **Goals**: + - 为孩子快速生成有趣、温暖、可教育的故事 + - 让孩子成为故事主角，形成陪伴感 + - 在睡前、亲子共读等场景中使用语音或绘本 +- **Pain Points**: + - 一次性生成内容容易同质化 + - 缺少与孩子长期成长相关的连续性 + - 语音与插图往往不是同一套体验的一部分 +- **Technical Level**: 初中级 + +### Secondary Persona: 产品拥有者 / 运营管理员 + +- **Role**: 产品负责人、创作者或系统维护者 +- **Goals**: + - 稳定控制模型调用效果、成本和失败降级 + - 保持产品演示链路稳定 + - 对系统结构有解释力，便于招聘场景展示 +- **Pain Points**: + - Provider 配置复杂，难以讲清楚 + - 多条工作流重复演化，维护成本高 + - 工程质量与展示价值不匹配 +- **Technical Level**: 中高级 + +--- + +## User Stories & Acceptance Criteria + +### Story 1: 快速生成个性化故事 + +**As a** 家长 +**I want to** 基于孩子档案和教育主题生成一个故事 +**So that** 我能快速得到适合孩子的阅读内容 + +**Acceptance Criteria** + +- [ ] 用户可以选择孩子档案并输入主题或教育目标 +- [ ] 系统能结合档案与宇宙上下文生成故事文本 +- [ ] 故事保存后可在故事库中查看 +- [ ] 当图片或语音生成失败时，故事文本仍可正常保留并查看 + +### Story 2: 生成并阅读绘本 + +**As a** 家长 +**I want to** 生成一个多页绘本并在前端顺畅阅读 +**So that** 我能获得更强的陪伴和共读体验 + +**Acceptance Criteria** + +- [ ] 系统支持多页绘本生成 +- [ ] 绘本可通过唯一 ID 被再次打开，而不是只依赖前端内存状态 +- [ ] 页面刷新或重新进入时，绘本内容仍能恢复 +- [ ] 若部分页面插图失败，文本页仍可正常展示 + +### Story 3: 听故事 + +**As a** 家长 +**I want to** 播放故事语音 +**So that** 我可以在睡前或陪伴场景下使用 + +**Acceptance Criteria** + +- [ ] 故事详情页支持加载和播放语音 +- [ ] 同一故事音频应支持缓存或复用，避免重复生成 +- [ ] 音频生成失败时，页面应给出明确状态与重试方式 + +### Story 4: 管理模型供应与成本风险 + +**As a** 产品拥有者 +**I want to** 以清晰的方式管理不同能力对应的供应商 +**So that** 我能解释系统架构，并稳定控制成本与故障 + +**Acceptance Criteria** + +- [ ] Provider 配置以能力、供应商、模型配置的方式组织 +- [ ] 路由策略与凭证管理职责分离 +- [ ] 系统能清楚展示失败降级逻辑 +- [ ] 管理端或配置文档能说明当前有效供应链路 + +--- + +## Functional Requirements + +### Core Feature 1: 统一的生成工作流 + +- **Description**: 将普通故事、完整故事、绘本生成统一到一套生成任务模型中。 +- **User Flow**: + 1. 用户发起生成 + 2. 系统校验档案与宇宙关系 + 3. 系统构建 memory/context + 4. 系统生成文本或绘本结构 + 5. 系统保存主记录 + 6. 系统异步生成封面与语音 + 7. 系统回写状态 +- **Edge Cases**: + - 用户未选择孩子档案 + - 故事宇宙与孩子档案不匹配 + - 部分资产生成失败 +- **Error Handling**: + - 文本失败：返回明确错误，不保存空故事 + - 图片失败：标记为部分完成，可后续重试 + - 音频失败：不阻塞文本阅读 + +### Core Feature 2: 个性化上下文注入 + +- **Description**: 将孩子档案、成长主题、故事宇宙和记忆系统统一视为内容上下文，而不是附属配置。 +- **User Flow**: + 1. 用户选择档案 + 2. 系统聚合角色、兴趣、成长主题、宇宙设定、记忆 + 3. 生成结果体现上下文 +- **Edge Cases**: + - 没有档案时，允许通用生成 + - 没有宇宙时，允许使用基础档案 +- **Error Handling**: + - 某类上下文缺失不应阻塞生成，只进行降级 + +### Core Feature 3: 绘本与语音的可恢复体验 + +- **Description**: 阅读器和音频播放应支持重新进入、状态恢复与降级处理。 +- **User Flow**: + 1. 用户打开故事详情或绘本详情 + 2. 系统按 ID 拉取内容 + 3. 页面展示当前已完成资产 + 4. 用户按需触发图片或音频补全 +- **Edge Cases**: + - 页面刷新 + - 资产未生成完成 + - 资产生成失败 +- **Error Handling**: + - 以状态展示替代“空白失败” + - 保留重试入口 + +### Core Feature 4: 简化后的 Provider Orchestration + +- **Description**: 供应商系统应服务于“稳定生成”，而不是暴露为产品主角。 +- **User Flow**: + 1. 系统根据能力类型加载 provider 列表 + 2. 根据 routing policy 选择执行顺序 + 3. 调用成功即返回结果，失败则自动切换 + 4. 记录成本、耗时与错误 +- **Edge Cases**: + - 没有可用 provider + - provider 凭证缺失 + - 同类 provider 全部失败 +- **Error Handling**: + - 返回聚合错误 + - 支持 degraded completion + +### Core Feature 5: 演示级前端关键体验 + +- **Description**: 前端优先完成关键状态设计，而不是先追求大规模视觉升级。 +- **Required States**: + - 初始化 + - 生成中 + - 文本已完成、资产处理中 + - 部分完成 + - 全部完成 + - 失败与重试 +- **UI Principles**: + - 用户始终知道系统当前在做什么 + - 用户始终知道下一步能做什么 + - 页面刷新后体验不中断 + +### Out of Scope + +- 新增大量供应商类型或复杂负载均衡策略 +- 多租户 Provider 管理 +- 复杂高可用部署优化作为本轮核心目标 +- 高保真商业化支付、会员与订阅系统 +- 花大量时间做纯视觉层重做 + +--- + +## Technical Constraints + +### Performance + +- 文本生成应在 15 秒内给出首个可用结果或明确状态 +- 图片/语音资产生成可异步完成，但前端必须有可见状态 +- 绘本详情和故事详情需支持按 ID 快速恢复 + +### Security + +- 继续使用现有 JWT + httpOnly Cookie 认证方案 +- Provider 密钥应保持加密管理，不在前端暴露 +- 管理端仅保留必要入口，默认不作为求职版核心展示对象 + +### Integration + +- **Text Providers**: Gemini / OpenAI 作为文本能力候选 +- **Image Providers**: CQTAI / Antigravity 作为图片能力候选 +- **TTS Providers**: MiniMax / ElevenLabs / Edge TTS 作为语音能力候选 +- **Background Jobs**: Celery + Redis 负责后处理与异步任务 + +### Technology Stack + +- **Backend**: FastAPI + SQLAlchemy Async + PostgreSQL + Celery/Redis +- **Frontend**: Vue 3 + TypeScript + Pinia + Tailwind CSS +- **Design Principle**: 先完成状态与流程设计，再做界面强化 + +--- + +## MVP Scope & Phasing + +### Phase 1: MVP (2 周) + +**目标**: 做出一个求职可演示、逻辑清晰、体验闭环的 AI 故事产品版本 + +**MVP Scope** + +- 统一故事 / 完整生成 / 绘本生成的工作流抽象 +- 将 Storybook 页面改为支持按 ID 恢复 +- 修复管理端构建问题，或明确降级为非核心链路 +- 清理 Provider 概念层，去掉历史别名与混杂职责 +- 为图片/音频生成增加明确状态与重试入口 +- 清理关键 lint 与工程观感问题 + +**MVP Definition** + +用户可以稳定完成一次“选择孩子档案 -> 生成故事/绘本 -> 获取封面/语音 -> 回看或继续阅读”的完整体验，且系统结构可以被清晰讲述。 + +### Phase 2: Enhancements (4 周) + +- 音频缓存与复用 +- 记忆系统与时间线联动优化 +- Provider 健康状态与成本摘要 +- 演示级前端优化，包括结果页、状态页和阅读页体验 +- 补齐缺失测试，提升工程可信度 + +### Future Considerations + +- 更细粒度的叙事风格与音色策略 +- 睡前模式 / 陪伴模式 +- 教师场景或课程场景扩展 +- 更复杂的成本路由与多租户配置 + +--- + +## Prioritization Matrix + +| Priority | 事项 | 目标 | 原因 | +|------|------|------|------| +| P0 | 收敛产品主线 | 明确“个性化 AI 绘本与陪伴讲述”定位 | 决定后续所有范围 | +| P0 | 统一生成工作流 | 消除故事/绘本/资产生成的分裂实现 | 是系统稳定性的核心 | +| P0 | Provider 概念重构 | 拆清 Capability / Provider / Routing Policy | 是系统可解释性的核心 | +| P0 | Storybook 可恢复体验 | 支持按 ID 加载与刷新恢复 | 是演示稳定性的核心 | +| P0 | 修复 admin-frontend 构建或明确降级 | 保证一键启动或明确非核心范围 | 避免部署阻塞 | +| P1 | 音频缓存与重试 | 强化声音体验和成本控制 | 与你的背景强相关 | +| P1 | 前端状态设计 | 让生成中、失败、部分完成可感知 | 提升产品成熟度 | +| P1 | 补测试与 lint 清理 | 提升工程可信度 | 有助于面试展示 | +| P2 | 增加更多 Provider | 扩展覆盖面 | 当前不是关键短板 | +| P2 | 管理后台复杂可视化 | 增强运维能力 | 不是求职版核心 | +| P2 | 大规模视觉升级 | 提升表层观感 | 应晚于闭环与稳定性 | + +--- + +## Delivery Plan + +### 第 1 阶段：2 周执行清单 + +#### Week 1 + +- 完成产品主线和展示口径收敛 +- 定义统一的 Generation Job 状态模型 +- 拆分 Provider 层职责，输出新概念模型 +- 决定 admin 端保留范围 +- 修复 Storybook 依赖内存状态的问题 + +#### Week 2 + +- 将前端关键页面补齐状态与重试 +- 打通故事生成与绘本生成的统一流程 +- 输出一版稳定演示脚本 +- 清理关键 lint 问题 +- 完成一轮端到端回归测试 + +### 第 2 阶段：4 周执行清单 + +#### Week 3 + +- 上线音频缓存与复用 +- 让时间线、记忆、故事结果之间形成更清晰关联 +- 增加失败降级与资产补全机制 + +#### Week 4 + +- 完善前端结果体验与语音体验 +- 补齐缺失测试 +- 输出项目说明文档、架构图和演示话术 +- 完成求职版 Demo 包装 + +--- + +## Risk Assessment + +| Risk | Probability | Impact | Mitigation Strategy | +|------|------------|--------|---------------------| +| 重构范围失控 | High | High | 严格限制本轮只服务一个核心闭环，不新增大功能 | +| Provider 重构导致兼容性问题 | Medium | High | 先保留兼容层，再逐步迁移配置 | +| Storybook/音频链路改动引入回归 | Medium | High | 补关键回归测试与演示脚本 | +| 前端优化挤占后端重构时间 | High | Medium | 前端只做状态和关键体验，不做全量视觉翻新 | +| 求职展示与真实产品目标冲突 | Medium | Medium | 将“求职版”定义为独立阶段目标，不追求商业化全量能力 | + +--- + +## Dependencies & Blockers + +**Dependencies** + +- 现有后端数据库模型和迁移能力 +- 现有 Provider Adapter 体系 +- Vue 前端页面与 Pinia 状态管理 +- 可用的测试与构建环境 + +**Known Blockers** + +- 管理端前端当前构建失败 +- Storybook 阅读器缺少按 ID 恢复能力 +- 音频未缓存，体验和成本不可控 +- Provider Router 耦合度高，任何修改都容易牵动多处逻辑 + +--- + +## Appendix + +### Assumptions + +- 本轮目标以求职展示为第一优先级，而非商业化上线。 +- 目标用户仍然是 3-8 岁儿童家庭场景。 +- 当前技术栈保持不变，不进行大规模框架迁移。 +- 管理后台是辅助能力，不作为本轮展示主角。 + +### Glossary + +- **Generation Workflow**: 从用户输入到文本、图片、语音完成的一整套生成流程。 +- **Capability**: 底层 AI 能力分类，如文本、图片、语音。 +- **Provider**: 具体供应商，如 Gemini、OpenAI、MiniMax。 +- **Routing Policy**: 供应商选择与降级策略。 +- **Degraded Completion**: 资产部分失败但主结果可用的完成状态。 + +### 如何模仿本类文档 + +当你以后写自己的 PRD 或产品方案时，可以复用这套骨架： + +1. 先写 Executive Summary，说明产品现在为什么要做这件事。 +2. 再写 Problem Statement，拆清当前问题、方案与业务影响。 +3. 给出 Success Metrics，避免文档只有想法没有验证标准。 +4. 用 Persona 和 User Story 把“用户价值”写实，而不是只写功能点。 +5. 在 Functional Requirements 里同时写 happy path、edge case 和 error handling。 +6. 用明确的 Out of Scope 防止范围不断膨胀。 +7. 用 P0/P1/P2 或阶段计划体现产品判断，而不是罗列任务。 +8. 最后补风险、依赖和假设，让文档更像真正可执行的产品方案。 + +### References + +- `backend/app/services/provider_router.py` +- `backend/app/services/story_service.py` +- `frontend/src/views/StorybookViewer.vue` +- `frontend/src/stores/storybook.ts` +- `backend/tests/` + +--- + +*This PRD was created as a job-search-oriented product reboot plan, with emphasis on product focus, AI workflow clarity, and portfolio-ready execution quality.* diff --git a/docs/product/unified-generation-workflow-prd.md b/docs/product/unified-generation-workflow-prd.md new file mode 100644 index 0000000..58c5b35 --- /dev/null +++ b/docs/product/unified-generation-workflow-prd.md @@ -0,0 +1,510 @@ +# Product Requirements Document: 统一生成工作流 + +**Version**: 1.0 +**Date**: 2026-04-17 +**Author**: Sarah (Product Owner) +**Quality Score**: 93/100 + +--- + +## Executive Summary + +DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本生成，但这三类能力在系统中以不同接口、不同服务路径和不同前端消费方式存在，已经开始阻碍产品迭代。当前实现能工作，但不利于功能演化，也不利于在求职场景中讲清楚产品系统逻辑。 + +统一生成工作流的目标，是将“文本生成、封面生成、语音生成、绘本页生成、后处理（记忆/成就）”纳入一套统一的产品与系统模型中。对于用户，统一工作流意味着结果更稳定、失败更可解释、页面状态更清晰；对于产品和工程，统一工作流意味着需求不会在多个分叉路径中重复实现。 + +本 PRD 面向 DreamWeaver 求职版 MVP，重点定义统一生成工作流的目标用户、状态模型、功能边界、数据结构演进方向、前后端行为以及发布优先级。 + +## Implementation Snapshot + +**Updated**: 2026-04-17 evening + +当前代码已经从“纯目标态设计”进入“部分落地”阶段，主要进展如下： + +### Already Landed + +- `Story` 主记录已持久化以下统一状态相关字段： + - `generation_status` + - `image_status` + - `audio_status` + - `last_error` + - `audio_path` +- Storybook 阅读器已支持按 ID 恢复，不再只依赖 Pinia 内存态 +- 故事列表页、故事详情页、绘本阅读页已接入统一状态展示 +- 故事音频已支持首次生成后缓存复用 +- `degraded_completed` 已在服务层和前端语义中落地 + +### Still Missing + +- 统一的 `POST /api/generations` 风格入口尚未建立 +- 普通故事、完整生成、绘本生成仍通过多条 service 路径实现 +- “统一资产重试入口”尚未落地 +- `partial_ready`、`retryable_assets` 等更细粒度状态仍停留在目标态 + +### What This Means + +这份 PRD 仍然是目标态文档，但它对应的主干方向已经不是纸面方案。当前最适合的继续方式，不是重写文档，而是继续把 service workflow 和资产补全过程收拢成统一实现。 + +--- + +## Problem Statement + +**Current Situation** + +DreamWeaver 当前存在以下工作流层面问题： + +1. **生成入口不统一** + 普通故事走 `/api/stories/generate`，完整故事走 `/api/stories/generate/full`，绘本走 `/api/storybook/generate`，前端对结果的处理也不同。 + +2. **保存与资产补全过程不统一** + 有的流程先存文本再补图，有的流程只返回绘本对象并依赖前端 store，有的流程不考虑音频状态。 + +3. **状态表达不统一** + 系统缺少标准的“生成中、部分完成、已完成、失败、可重试”等状态定义，导致前端难以做出成熟体验。 + +4. **失败处理策略不统一** + 图片、音频、绘本页生成失败时，系统没有统一的降级定义，用户体验和技术行为都不够稳定。 + +5. **恢复能力不足** + 尤其是绘本路径，依赖前端内存态，页面刷新或重进后无法恢复。 + +**Proposed Solution** + +引入统一的 Generation Workflow，将不同内容模式视为同一工作流下的不同配置，而不是完全不同的产品流程。系统将围绕一个统一对象进行组织： + +- 请求输入 +- 上下文准备 +- 文本或绘本结构生成 +- 主记录保存 +- 资产异步补全 +- 状态回写 +- 后处理任务 + +**Business Impact** + +统一生成工作流将带来以下影响： + +- 用户更容易理解生成过程与失败反馈 +- 前端可构建成熟状态体验 +- 后续扩展语音缓存、绘本恢复、记忆提取等能力更顺畅 +- 面试场景中可清楚展示 AI 产品的工作流设计能力 + +--- + +## Success Metrics + +**Primary KPIs** + +- **工作流覆盖率**：普通故事、完整故事、绘本生成全部迁移到统一工作流 >= 100% +- **部分完成可用率**：当图片或音频失败时，文本仍能可读的比例 >= 95% +- **可恢复率**：绘本和故事结果按 ID 重新打开成功率 >= 100% +- **前端状态完整度**：关键生成状态在前端均有可见反馈 >= 100% +- **新增需求复用率**：新生成能力接入时复用统一工作流步骤的比例 >= 80% + +**Validation** + +- 技术验证：端到端测试与手动演示 +- 产品验证：能否用一张流程图清楚说明 DreamWeaver 的生成机制 + +--- + +## User Personas + +### Primary Persona: 家长 / 监护人 + +- **Role**: 使用 DreamWeaver 为孩子生成故事内容的人 +- **Goals**: + - 快速得到稳定的故事或绘本结果 + - 看到清晰的生成状态 + - 即使部分资产失败，仍能继续阅读 +- **Pain Points**: + - 不知道系统是否仍在生成中 + - 结果部分丢失后体验中断 + - 页面刷新后无法找回内容 +- **Technical Level**: 初中级 + +### Secondary Persona: 产品负责人 / 开发者 + +- **Role**: 维护 DreamWeaver 的产品与系统设计者 +- **Goals**: + - 降低流程分裂造成的重复实现 + - 统一失败处理与状态管理 + - 能向他人清楚解释系统设计 +- **Pain Points**: + - 同一需求在多个生成路径里改动 + - 状态定义不清，难以推进前端体验 + - 架构复杂度高，影响项目表达 +- **Technical Level**: 中高级 + +--- + +## User Stories & Acceptance Criteria + +### Story 1: 统一发起生成 + +**As a** 家长 +**I want to** 从一个统一的创建入口发起普通故事或绘本生成 +**So that** 我不需要理解系统内部差异 + +**Acceptance Criteria** + +- [ ] 创建入口支持选择输出类型：普通故事或绘本 +- [ ] 系统能根据输入类型走统一流程，而不是完全独立逻辑 +- [ ] 用户提交后立即看到生成状态 + +### Story 2: 获得可用结果 + +**As a** 家长 +**I want to** 在生成过程中尽快看到第一个可用结果 +**So that** 我不会因等待过久而中断使用 + +**Acceptance Criteria** + +- [ ] 文本生成完成后，主记录应被保存 +- [ ] 图片、音频、绘本页可后续补全 +- [ ] 即使部分资产失败，用户仍可查看文本结果 + +### Story 3: 恢复历史结果 + +**As a** 家长 +**I want to** 通过故事或绘本 ID 再次打开内容 +**So that** 我可以回看、继续阅读或重新播放 + +**Acceptance Criteria** + +- [ ] 故事详情页支持按 ID 加载 +- [ ] 绘本阅读器支持按 ID 加载 +- [ ] 刷新页面不会导致内容丢失 + +### Story 4: 理解系统状态 + +**As a** 家长 +**I want to** 知道系统目前是在生成文本、生成图片还是失败可重试 +**So that** 我不会困惑或误以为系统卡住 + +**Acceptance Criteria** + +- [ ] 前端展示统一状态模型 +- [ ] 失败原因对用户可解释 +- [ ] 可补全资产应有独立重试入口 + +### Story 5: 以统一方式扩展能力 + +**As a** 产品负责人 +**I want to** 未来新增音频缓存、更多绘本模式或新资产时复用统一工作流 +**So that** 系统能持续扩展而不继续分叉 + +**Acceptance Criteria** + +- [ ] 工作流步骤具备清晰边界 +- [x] 新能力接入时能挂入现有状态模型 +- [ ] 不需要再新增完全平行的一套生成接口 + +--- + +## Functional Requirements + +### Feature 1: 统一工作流模型 + +**Description** +所有内容生成行为必须映射到同一套工作流中，不再按“故事模式/绘本模式”分别设计完全独立的业务流程。 + +**Standard Workflow Steps** + +1. Request Accepted +2. Context Prepared +3. Narrative Generated +4. Story Saved +5. Assets Generating +6. Partial Ready / Completed +7. Post-processing Completed + +**Requirements** + +- 系统需定义统一工作流状态 +- 故事与绘本共享前四步 +- 资产生成与后处理作为后续步骤处理 + +### Feature 2: 状态模型 + +**Description** +系统必须拥有统一且可面向前端呈现的状态模型。 + +**Proposed Status Set** + +- `pending` +- `context_ready` +- `narrative_ready` +- `assets_generating` +- `partial_ready` +- `completed` +- `failed` +- `degraded_completed` + +**Requirements** + +- 每个状态必须有明确进入条件 +- 前端可根据状态做 UI 展示 +- `degraded_completed` 必须代表“主结果可用，部分资产失败” + +### Feature 3: 统一主记录保存 + +**Description** +不论输出为普通故事还是绘本，系统都应有统一的主记录保存策略。 + +**Requirements** + +- 文本或绘本结构生成完成后，应立即保存主记录 +- 主记录至少保存： + - 用户 ID + - 档案 ID + - 宇宙 ID + - 标题 + - 模式 + - 文本或分页结构 + - 封面 prompt + - 资产状态 +- 保存后即可供前端按 ID 加载 + +### Feature 4: 资产异步补全 + +**Description** +图片、音频等资产不应阻塞主结果可用性。 + +**Requirements** + +- 封面、绘本页插图、音频均支持异步补全 +- 各资产需独立记录状态 +- 资产失败不应导致主故事记录失效 +- 用户应可单独重试未完成资产 + +### Feature 5: 恢复与回看能力 + +**Description** +结果页与绘本页应按持久化数据恢复，而不是仅依赖 Pinia 内存状态。 + +**Requirements** + +- 故事详情页支持按 ID 读取主记录 +- 绘本阅读器支持按 ID 读取 `pages` +- 前端 store 可以作为缓存层，但不是唯一数据来源 + +### Feature 6: 统一后处理钩子 + +**Description** +成就提取、记忆提取、阅读时间线更新等能力应挂在统一后处理节点中。 + +**Requirements** + +- 后处理任务应在主记录保存后触发 +- 后处理失败不应影响主内容可读 +- 后处理可被日志和状态观测 + +### Out of Scope + +- 引入复杂工作流引擎 +- 设计多租户任务编排 +- 在本轮中彻底重做数据库结构 +- 把所有历史接口一次性废弃 + +--- + +## UX Requirements + +### Core UX Principles + +- 用户始终知道当前生成到哪一步 +- 用户始终能在部分成功时继续阅读 +- 用户始终能在失败后看到下一步动作 + +### Required UI States + +- 提交中 +- 正在分析输入 +- 正在生成文本 +- 文本已完成，图片/音频处理中 +- 部分完成 +- 全部完成 +- 失败 +- 可重试 + +### Recovery UX + +- 刷新页面后，故事结果应直接恢复 +- 绘本页刷新后，应恢复到默认首页或上次阅读位置 +- 若某资产失败，应明确显示“稍后重试”而非空白区域 + +--- + +## Technical Constraints + +### Backend Constraints + +- 现有后端基于 FastAPI + SQLAlchemy Async + Celery +- 应优先在当前架构内重组服务边界，而非大规模重写 +- 现有 `Story` 表已支持 `story_text`、`pages`、`image_url` 等字段，可作为统一主记录基础 + +### Frontend Constraints + +- 当前前端使用 Vue 3 + Pinia +- 已有创建弹窗、故事详情页、绘本阅读页 +- 需尽量在现有组件结构内推进，不做过度重写 + +### Integration Constraints + +- 文本、图片、语音能力由 Provider Router 提供 +- 工作流应与 Provider 路由解耦，避免把模型策略写进业务流程 + +--- + +## Proposed Data Model Evolution + +### Existing Base + +当前 `Story` 模型已经可承载： + +- `story_text` +- `pages` +- `cover_prompt` +- `image_url` +- `mode` + +### Recommended Additions + +建议新增以下字段或概念层（可为数据库字段，也可先为服务层状态）： + +- `generation_status` +- `text_status` +- `image_status` +- `audio_status` +- `last_error` +- `retryable_assets` + +### Why This Matters + +这些字段可以帮助： + +- 前端显示精确状态 +- 后端区分主结果和资产结果 +- 支持“部分完成”和“可重试”能力 + +--- + +## API Impact + +### Current APIs + +- `POST /api/stories/generate` +- `POST /api/stories/generate/full` +- `POST /api/storybook/generate` +- `GET /api/stories/{id}` +- `GET /api/audio/{id}` + +### Recommended Direction + +第一阶段不必强行一次性废弃旧接口，但建议向统一入口演进。 + +**Recommended Target** + +- `POST /api/generations` +- `GET /api/generations/{id}` +- `POST /api/generations/{id}/retry-assets` + +如果短期不改 API 命名，也至少应做到： + +- 内部统一走同一个 service workflow +- 外部不同接口只是兼容层 + +--- + +## MVP Scope & Phasing + +### Phase 1: MVP + +- 统一 service 层生成流程 +- 支持统一状态模型 +- 支持故事和绘本按 ID 恢复 +- 支持部分完成与失败降级 +- 支持图片和音频独立重试入口 + +### Phase 2: Enhancements + +- 更进一步的音频缓存策略（如过期、清理与复用治理） +- 更细粒度资产状态 +- 阅读位置恢复 +- 工作流相关日志与监控 + +### Future Considerations + +- 长任务通知 +- 流式生成 UI +- 多阶段生成策略 +- 高级 narrative plan + +--- + +## Risk Assessment + +| Risk | Probability | Impact | Mitigation Strategy | +|------|------------|--------|---------------------| +| 工作流抽象过度 | Medium | High | 先围绕现有故事/绘本/音频场景做最小抽象 | +| 历史接口兼容性问题 | Medium | Medium | 保留兼容入口，内部统一服务实现 | +| 前后端状态模型理解不一致 | High | High | 先写清统一状态表，再进入实现 | +| Storybook 恢复实现不彻底 | Medium | High | 把“按 ID 加载”作为硬性验收项 | +| 资产状态字段新增引发迁移成本 | Medium | Medium | 允许先在服务层实现，再视需要落库 | + +--- + +## Dependencies & Blockers + +**Dependencies** + +- 现有 `Story` 数据模型 +- 现有 `story_service.py` 能力 +- 现有前端创建入口与详情页 +- Provider Router 可继续提供文本、图片、音频能力 + +**Known Blockers** + +- 统一入口尚未建立 +- 多条生成链路重复实现 + +--- + +## Appendix + +### Recommended State Definition Table + +| State | Meaning | User-facing Message | +|------|------|------| +| `pending` | 请求已提交 | 正在准备生成 | +| `context_ready` | 上下文已完成 | 正在分析孩子档案和主题 | +| `narrative_ready` | 文本或绘本结构已生成 | 故事已生成，正在补充插图/语音 | +| `assets_generating` | 资产处理中 | 正在绘制封面或生成语音 | +| `partial_ready` | 主结果可用，资产未全部完成 | 可以先阅读，稍后补全更多内容 | +| `completed` | 全部核心资产完成 | 故事已准备完成 | +| `failed` | 主流程失败 | 生成失败，请重试 | +| `degraded_completed` | 主流程成功但部分资产失败 | 故事已可阅读，部分内容稍后重试 | + +### How to Learn from This PRD + +如果你想模仿写功能级 PRD，可以重点学习这几个动作： + +1. 不要直接写功能，要先写“为什么当前方式有问题”。 +2. 一定要把“当前实现”和“目标实现”分开写。 +3. 用状态模型、边界和恢复能力来体现你对 AI 产品的不确定性理解。 +4. 用户故事不要只写 happy path，要覆盖失败、降级和恢复。 +5. 对系统型需求，要写清 API 影响和数据模型影响。 + +### References + +- `backend/app/services/story_service.py` +- `backend/app/api/stories.py` +- `backend/app/schemas/story_schemas.py` +- `backend/app/db/models.py` +- `frontend/src/components/CreateStoryModal.vue` +- `frontend/src/views/StorybookViewer.vue` + +--- + +*This PRD defines the target-state product and system behavior for unifying DreamWeaver's content generation workflow.* diff --git a/docs/technical/memory-system-dev.md b/docs/technical/memory-system-dev.md new file mode 100644 index 0000000..0eea23e --- /dev/null +++ b/docs/technical/memory-system-dev.md @@ -0,0 +1,147 @@ +# 记忆系统开发指南 (Development Guide) + +本文档详细说明了 PRD 中定义的记忆系统的技术实现细节。 + +## 1. 数据库架构变更 (Schema Changes) + +目前的 `MemoryItem` 表结构尚可，但需要增强字段以支持丰富的情感和元数据。 + +### 1.1 `MemoryItem` 表优化 +建议使用 Alembic 进行迁移，增加以下字段或在 `value` JSON 中规范化以下结构： + +```python +# 建议在 models.py 中明确这些字段，或者严格定义 value 字段的 Schema +class MemoryItem(Base): + # ... 现有字段 ... + + # 新增/规范化字段建议 + # value 字段的 JSON 结构规范： + # { + # "content": "小兔子战胜了大灰狼", # 记忆的核心文本 + # "keywords": ["勇敢", "森林"], # 用于检索的关键词 + # "emotion": "positive", # 情感倾向: positive/negative/neutral + # "source_story_id": 123, # 来源故事 ID + # "confidence": 0.85 # 记忆置信度 (如果是 AI 自动提取) + # } +``` + +### 1.2 `StoryUniverse` 表优化 (成就系统) +目前的成就存储在 `achievements` JSON 字段中。为了支持更复杂的查询（如"获得勇气勋章的所有用户"），建议将其重构为独立关联表，或保持 JSON 但规范化结构。 + +**当前 JSON 结构规范**: +```json +[ + { + "id": "badge_courage_01", + "type": "勇气", + "name": "小小勇士", + "description": "第一次在故事中独自面对困难", + "icon_url": "badges/courage.png", + "obtained_at": "2023-10-27T10:00:00Z", + "source_story_id": 45 + } +] +``` + +--- + +## 2. 核心逻辑实现 + +### 2.1 记忆注入逻辑 (Prompt Engineering) + +修改 `backend/app/api/stories.py` 中的 `_build_memory_context` 函数。 + +**目标**: 生成一段自然的、不仅是罗列数据的 Prompt。 + +**伪代码逻辑**: +```python +def format_memory_for_prompt(memories: list[MemoryItem]) -> str: + """ + 将记忆项转换为自然语言 Prompt 片段。 + """ + context_parts = [] + + # 1. 角色记忆 + chars = [m for m in memories if m.type == 'favorite_character'] + if chars: + names = ", ".join([c.value['name'] for c in chars]) + context_parts.append(f"孩子特别喜欢的角色有：{names}。请尝试让他们客串出场。") + + # 2. 近期情节 + recent_stories = [m for m in memories if m.type == 'recent_story'][:2] + if recent_stories: + for story in recent_stories: + context_parts.append(f"最近发生过：{story.value['summary']}。可以在对话中不经意地提及此事。") + + # 3. 避雷区 (负面记忆) + scary = [m for m in memories if m.type == 'scary_element'] + if scary: + items = ", ".join([s.value['keyword'] for s in scary]) + context_parts.append(f"【绝对禁止】不要出现以下让孩子害怕的元素：{items}。") + + return "\n".join(context_parts) +``` + +### 2.2 成就提取与通知流程 + +当前流程在 `app/tasks/achievements.py`。需要完善闭环。 + +**改进后的流程**: +1. **Story Generation**: 故事生成成功，存入数据库。 +2. **Async Task**: 触发 Celery 任务 `extract_story_achievements`。 +3. **LLM Analysis**: 调用 Gemini 分析故事，提取成就。 +4. **Update DB**: 更新 `StoryUniverse.achievements`。 +5. **Notification (新增)**: + * 创建一个 `Notification` 或 `UserMessage` 记录（需要新建表或使用 Redis Pub/Sub）。 + * 前端轮询或通过 SSE (Server-Sent Events) 接收通知："🎉 恭喜！在这个故事里，小明获得了[诚实勋章]！" + +### 2.3 记忆清理与衰减 (Maintenance) + +需要一个后台定时任务（Cron Job），清理无效记忆，避免 Prompt 过长。 + +* **频率**: 每天一次。 +* **逻辑**: + * 删除 `ttl_days` 已过期的记录。 + * 对 `recent_story` 类型的 `base_weight` 进行每日衰减 update（或者只在读取时计算，数据库存静态值，推荐读取时动态计算以减少写操作）。 + * 当 `MemoryItem` 总数超过 100 条时，触发"记忆总结"任务，将多条旧记忆合并为一条"长期印象" (Long-term Impression)。 + +--- + +## 3. API 接口规划 + +### 3.1 获取成长时间轴 +`GET /api/profiles/{id}/timeline` + +**Response**: +```json +{ + "events": [ + { + "date": "2023-10-01", + "type": "milestone", + "title": "初次相遇", + "description": "创建了角色 [小明]" + }, + { + "date": "2023-10-05", + "type": "story", + "title": "小明与魔法树", + "image_url": "..." + }, + { + "date": "2023-10-05", + "type": "achievement", + "badge": { + "name": "好奇宝宝", + "icon": "..." + } + } + ] +} +``` + +### 3.2 记忆反馈 (人工干预) +`POST /api/memories/{id}/feedback` + +允许家长手动删除或修正错误的记忆。 +* **Action**: `delete` | `reinforce` (强化，增加权重)