Refactor Phase 2: Split stories.py into Schema/Service/Controller, add missing endpoints, fix async bug

backend/docs/memory_system_prd.md

@@ -1,93 +0,0 @@
-# 梦语织机 (DreamWeaver) 记忆系统升级 PRD
-> 版本: v1.0 | 状态: 规划中 | 优先级: High
-
-## 1. 核心愿景 (Vision)
-
-将当前的"数据存储"升级为有温度的**"情感连接系统"**。
-我们不只是在记住数据，而是在**维护孩子与故事世界的关系**。让每一个故事不再是孤立的碎片，而是构建孩子专属"故事宇宙"的砖瓦。
-
----
-
-## 2. 产品痛点与解决方案
-
-| 用户角色 | 核心痛点 | 解决方案 | 预期价值 |
-|---------|---------|---------|---------|
-| **孩子** | "上次的小兔子怎么不认识我了？" <br> 故事之间缺乏连续性，只有单次体验。 | **角色一致性与记忆注入** <br> 故事开头主动提及往事，角色性格延续。 | 建立情感依恋，提升沉浸感。 |
-| **家长** | "这App除了生成故事还能干嘛？" <br> 无法感知产品的长期教育价值。 | **显性化成长轨迹** <br> 词汇量统计、主题变化、成就徽章可视化。 | 提高付费意愿，提供社交货币。 |
-| **平台** | 用户用完即走，缺乏留存壁垒。 | **沉没成本与情感资产** <br> 积累的记忆越多，越舍不得离开。 | 提升长期留存率 (LTV)。 |
-
----
-
-## 3. 功能架构：记忆分层模型
-
-### 3.1 层级 1: 核心档案 (Identity Layer)
-*性质：永久、静态、显性*
-*   **数据**: 姓名、年龄、性别。
-*   **输入**: 家长在 Onboarding 阶段手动输入。
-*   **作用**: 决定故事的基础适龄性和称呼。
-
-### 3.2 层级 2: 故事宇宙 (Universe Layer)
-*性质：长期、动态积累、半显性*
-*   **主角设定**: 姓名、性格特征（勇敢/害羞）、外貌特征（戴眼镜/卷发）。
-*   **常驻配角**: 从随机故事中涌现出的固定伙伴（如"爱吃胡萝卜的松鼠奇奇"）。
-*   **世界观**: 故事发生的背景（魔法森林、未来城市、海底世界）。
-*   **成就系统**: 孩子获得的虚拟奖励（勇气勋章、小小探险家）。
-
-### 3.3 层级 3: 工作记忆 (Working Memory)
-*性质：短期、自动衰减、隐性*
-*   **关键情节**: 最近 3 个故事的结局和核心冲突。
-*   **情感标记**: 孩子对特定内容的反应（根据“重播”、“跳过”推断）。
-*   **新学词汇**: 故事中出现的高级词汇。
-
----
-
-## 4. 关键功能特性 (Feature Specs)
-
-### 4.1 智能开场白 (Memory Injection)
-在生成新故事时，Prompt 必须包含一段"记忆唤醒"指令。
-*   **示例**: "小明，还记得上周我们帮小松鼠找回了松果吗？今天，小松鼠带来了一位新朋友..."
-*   **策略**: 提取权重最高的 Top 3 记忆注入 Prompt。
-
-### 4.2 成长时间轴 (Growth Timeline)
-一个可视化的 H5 页面或 App 模块，以时间轴形式展示里程碑。
-*   **节点类型**:
-    *   🌟 **初次相遇**: 创建角色的第一天。
-    *   📖 **阅读打卡**: 累计阅读 10/50/100 本。
-    *   🏅 **获得成就**: 获得"诚实勋章"。
-    *   🧠 **能力解锁**: 第一次阅读"科幻"题材。
-
-### 4.3 成就仪式感 (Achievement Ceremony)
-*   **触发**: 故事生成并分析后，如果获得新成就。
-*   **表现**: 弹窗动画 + 音效 + "恭喜获得 [勇气] 徽章"。
-*   **分享**:允许生成带二维码的成就海报。
-
----
-
-## 5. 记忆类型扩展 (Memory Types)
-
-| 类型 Key | 描述 | 来源 | 过期策略 |
-|---------|------|------|---------|
-| `recent_story` | 最近读过的故事梗概 | 阅读事件 | 30天衰减 |
-| `favorite_character` | 孩子喜欢的角色 | 重播/高评分 | 长期有效 |
-| `scary_element` | 孩子害怕/不喜欢的元素 | 跳过/负反馈 | 长期有效 (避雷) |
-| `vocabulary_growth` | 新掌握的词汇 | 故事分析 | 90天衰减 |
-| `emotional_highlight` | 高光时刻 (如: 特别开心的情节) | 互动数据 | 60天衰减 |
-
----
-
-## 6. 实施路线图 (Roadmap)
-
-### Phase 1: 基础建设 (v0.3.0)
-*   [x] 数据库 `MemoryItem` 表 (已存在)。
-*   [ ] 扩展 `MemoryItem` 类型字段，支持更多维度。
-*   [ ] 优化 `_build_memory_context`，支持更自然的 Prompt 注入。
-*   [ ] 前端：简单的"近期回忆"展示列表。
-
-### Phase 2: 可视化与成就 (v0.4.0)
-*   [ ] 实现"成就提取器" (Achievement Extractor) 的闭环通知。
-*   [ ] 前端：开发"我的成就"和"成长时间轴"页面。
-*   [ ] 增加故事开场白的动态生成逻辑。
-
-### Phase 3: 深度智能 (v0.5.0+)
-*   [ ] 引入向量数据库，实现基于语义的记忆检索 (不仅是时间最近)。
-*   [ ] 情感分析模型：分析用户行为推断情感倾向。

backend/docs/refactoring_plan.md

@@ -0,0 +1,98 @@
+# DreamWeaver 重构实施计划
+
+## 1. 概述
+
+本文档基于对当前架构的深入分析，制定了从稳定性、可维护性到可扩展性的分阶段重构计划。
+
+**目标**：
+- **短期**：解决单点故障风险，优化开发体验，清理关键技术债。
+- **中期**：提升系统高可用能力，增强监控与可观测性。
+- **长期**：架构演进，支持大规模并发与复杂业务场景。
+
+---
+
+## 2. 短期优化计划 (1-2周)
+
+**重点**：消除即时风险，提升部署效率。
+
+### 2.1 统一镜像构建 (High Priority)
+目前 `backend`, `backend-admin`, `worker`, `celery-beat` 重复构建 4 次，浪费资源且镜像版本可能不一致。
+
+- **Action Items**:
+  - [ ] 修改 `backend/Dockerfile` 为通用基础镜像。
+  - [ ] 更新 `docker-compose.yml`，定义 `backend-base` 服务或使用 `image` 标签共享镜像。
+  - [ ] 确保所有 Python 服务共用同一构建产物，仅启动命令不同。
+
+### 2.2 修复 Provider 缓存与限流 (High Priority)
+内存缓存 (`TTLCache`, `_latency_cache`) 在多进程/多实例下失效。
+
+- **Action Items**:
+  - [ ] 引入 Redis 作为共享缓存后端。
+  - [ ] 重构 `_load_provider_cache`，将 Provider 配置缓存至 Redis。
+  - [ ] 重构 `stories.py` 中的限流逻辑，使用 `redis-cell` 或简单的 Redis 计数器替代 `TTLCache`。
+
+### 2.3 拆分 `stories.py` (Medium Priority)
+`app/api/stories.py` 超过 600 行，包含 API 定义、业务逻辑、验证逻辑，维护困难。
+
+- **Action Items**:
+  - [ ] 创建 `app/services/story_service.py`，迁移生成、润色、PDF生成等核心逻辑。
+  - [ ] 创建 `app/schemas/story_schema.py`，迁移 Pydantic 模型（`GenerateRequest`, `StoryResponse` 等）。
+  - [ ] 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 供应商的成本与成功率。
+
+---
+
+## 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 监控大盘上线，关键指标报警配置完毕。 |