dreamweaver/backend/docs/refactoring_plan.md

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_schemas.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 供应商的成本与成功率。

3.4 Phase 3 最小可执行任务清单 (MVP)

目标：在不大改业务代码的前提下，于一个迭代内完成高可用基础设施闭环。

• PostgreSQL 主从：新增 docker-compose.ha.yml，包含 1 主 1 从与健康检查。
• PostgreSQL 备份：新增每日备份任务（pg_dump）与 7 天保留策略。
• Redis Sentinel：新增 1 主 2 哨兵最小拓扑，并验证故障切换。
• Celery 连接：更新 Celery broker/result backend 配置，支持 Sentinel 连接串。
• 回归验证：执行一次故事生成 + 异步任务链路（worker/beat）冒烟测试。
• 运行手册：补充故障切换与恢复步骤文档（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 监控大盘上线，关键指标报警配置完毕。