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

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 监控大盘上线，关键指标报警配置完毕。 |