9.1 KiB
Flask Prompt Master 项目重构方案
上下文和目标
项目概况：D:/aaa/aitsc 是一个 Flask 应用程序，提供多种 AI 驱动的功能（提示词模板、饭菜规划、旅行攻略、会议 纪要、简历优化等）。项目采用蓝图架构，但随着功能增加出现了代码质量问题。
当前问题：
- 安全漏洞：多个路由文件中存在硬编码的 API 密钥和数据库密码
- 代码结构：routes.py 文件过大（1300+ 行），职责不单一
- API 设计不一致：多种响应格式和错误处理方式
- 认证系统碎片化：同时使用会话、令牌和微信认证
- 配置管理混乱：新旧配置系统并存
- 代码重复：相似功能间存在重复代码
重构目标：
- 消除安全漏洞，移除所有硬编码的敏感信息
- 提高代码可维护性，优化项目结构
- 标准化 API 设计和错误处理
- 集中化认证和授权系统
- 实现关注点分离（业务逻辑与表现层分离）
重构方案概述
目标架构
flask_prompt_master/ ├── app/ # 应用层（API/Web 路由） ├── core/ # 核心业务逻辑（服务层） ├── infrastructure/ # 基础设施（配置、数据库、外部服务） ├── shared/ # 共享组件（工具类、数据模型、常量） ├── tests/ # 测试套件 └── docs/ # 文档
核心改进
- 安全加固：环境变量管理，JWT 认证，安全头部
- API 标准化：统一响应格式，版本控制，OpenAPI 文档
- 代码重组：服务层提取，仓库模式，依赖注入
- 质量提升：测试覆盖率，CI/CD，代码质量工具
详细实施计划
阶段 1：安全加固与基础建设（第 1-2 周）
任务 1.1：消除硬编码敏感信息
- 优先级：高
- 文件：
- flask_prompt_master/routes.py:115 - 移除硬编码数据库密码
- config.py - 移除已弃用的硬编码配置
- 所有包含 sk-fdf7cc1c73504e628ec0119b7e11b8cc 的文件
- 方法： a. 创建 .env.template 文件，列出所有需要的环境变量 b. 更新配置系统，从环境变量读取所有敏感信息 c. 添加配置验证，确保关键配置在启动时已设置
任务 1.2：实现统一认证中间件
- 优先级：高
- 方法： a. 创建 auth/middleware.py 实现 JWT 认证中间件 b. 统一所有 API 的认证方式，逐步替换现有的多种认证系统 c. 添加角色和权限管理系统 d. 实现刷新令牌机制
任务 1.3：添加安全头部和请求验证
- 优先级：中
- 方法： a. 实现安全中间件，添加 CSP、HSTS、XSS 防护等头部 b. 使用 Pydantic 创建请求数据验证模型 c. 实现全局请求验证中间件
阶段 2：API 标准化与文档（第 3-4 周）
任务 2.1：创建标准 API 响应格式
- 优先级：高
- 方法： a. 创建 shared/api/responses.py 定义标准响应类 b. 实现成功响应：{success: true, data: {...}, meta: {...}} c. 实现错误响应：{success: false, error: {...}, error_code: string} d. 创建响应工具函数，统一所有路由的响应格式
任务 2.2：实现 API 版本控制
- 优先级：中
- 方法： a. 创建 /api/v1/ 命名空间，所有新 API 使用此版本 b. 保留现有 /api/ 路由作为 v0 版本，逐步迁移 c. 实现版本路由中间件，支持通过 URL 或头部指定版本 d. 添加 API 弃用警告机制
任务 2.3：添加 OpenAPI 文档
- 优先级：中
- 方法： a. 使用 Flask-Swagger 或 FastAPI-style 注解 b. 自动生成 API 文档，支持在线测试 c. 添加 API 使用示例和错误代码说明
阶段 3：代码重组与服务层提取（第 5-6 周）
任务 3.1：分解大型路由文件
- 优先级：高
- 文件：flask_prompt_master/routes.py（1300+ 行）
- 方法：
a. 按功能模块拆分：
- routes/prompt_routes.py - 提示词相关路由
- routes/auth_routes.py - 认证相关路由
- routes/history_routes.py - 历史记录路由
- routes/feature_routes.py - 各 AI 功能路由 b. 每个文件不超过 300 行，保持单一职责 c. 使用蓝图组织相关路由
任务 3.2：提取业务逻辑到服务层
- 优先级：高
- 方法： a. 创建 services/ 目录，按领域划分服务类 b. 将路由中的业务逻辑移动到对应服务类 c. 服务类负责：业务规则验证、外部 API 调用、复杂数据处理 d. 路由只负责：请求解析、响应格式化、错误处理
任务 3.3：实现仓库模式
- 优先级：中
- 方法： a. 创建 repositories/ 目录，按实体划分仓库类 b. 仓库类封装数据库操作，提供高层抽象接口 c. 路由和服务通过仓库访问数据，不直接使用 SQLAlchemy d. 便于单元测试和数据库切换
阶段 4：测试与质量提升（第 7-8 周）
任务 4.1：提升测试覆盖率
- 优先级：中
- 方法： a. 实现单元测试：服务层、仓库层、工具类 b. 实现集成测试：API 端点测试 c. 实现端到端测试：关键用户流程测试 d. 目标：测试覆盖率从 ~40% 提升到 80%+
任务 4.2：实现 CI/CD 流水线
- 优先级：中
- 方法： a. 设置 GitHub Actions 或 GitLab CI b. 自动化：代码检查、测试、构建、部署 c. 添加质量门禁：测试覆盖率、代码复杂度、安全扫描
任务 4.3：代码质量工具集成
- 优先级：低
- 方法： a. 集成 black、isort、flake8 代码格式化 b. 添加 mypy 类型检查 c. 集成 pre-commit hooks 自动执行代码检查
阶段 5：部署优化与文档（第 9-10 周）
任务 5.1：优化 Docker 部署
- 优先级：低
- 方法： a. 优化 Dockerfile，减少镜像大小 b. 实现多阶段构建 c. 添加健康检查端点 d. 优化生产环境配置
任务 5.2：实现监控和可观测性
- 优先级：中
- 方法： a. 添加 Prometheus 指标收集 b. 实现结构化日志记录 c. 添加错误追踪和告警 d. 实现性能监控
任务 5.3：完善文档
- 优先级：低
- 方法： a. 架构设计文档 b. API 使用文档 c. 部署和维护指南 d. 开发环境设置指南
风险缓解策略
技术风险
数据库迁移风险：
- 使用 Alembic 生成迁移脚本
- 在测试环境充分验证
- 准备回滚方案 API 兼容性风险：
- 使用功能开关控制新功能
- 保持向后兼容性至少一个版本周期
- 提供详细的迁移指南 性能回归风险：
- 重构前后进行性能基准测试
- 实施监控和告警
- 准备快速回滚机制
实施风险
团队知识差距：
- 结对编程和代码审查
- 详细的架构文档
- 定期知识分享会议 时间安排风险：
- 采用敏捷方法，每两周评估进度
- 优先处理高价值任务
- 保持灵活性，根据进展调整计划
关键文件路径
需要立即处理的安全问题
- D:/aaa/aitsc/src/flask_prompt_master/routes/routes.py:115 - 硬编码数据库密码
- D:/aaa/aitsc/config.py - 已弃用的硬编码配置
- 所有包含硬编码 API 密钥的文件（搜索 sk-fdf7cc1c73504e628ec0119b7e11b8cc）
大型文件需要拆分
- D:/aaa/aitsc/src/flask_prompt_master/routes/routes.py（1300+ 行）
- D:/aaa/aitsc/src/flask_prompt_master/models/models.py（500+ 行）
新目录结构
- src/flask_prompt_master/services/ - 服务层
- src/flask_prompt_master/repositories/ - 仓库层
- src/flask_prompt_master/shared/ - 共享组件
- src/flask_prompt_master/api/ - API 相关组件
验证和测试策略
验证步骤
- 安全验证：确保无硬编码敏感信息，所有配置通过环境变量管理
- 功能验证：所有现有功能测试通过，API 响应格式一致
- 性能验证：关键 API 端点响应时间无显著下降
- 部署验证：生产环境部署成功，监控系统正常运行
测试计划
- 单元测试：服务层、仓库层、工具类
- 集成测试：API 端点、数据库操作
- 端到端测试：关键用户流程（注册、登录、使用功能）
- 性能测试：负载测试、压力测试
成功指标
量化指标
- 零硬编码敏感信息
- 测试覆盖率 80%+
- 代码复杂度降低 30%
- API 平均响应时间改善 20%
- 缺陷修复时间减少 50%
质化指标
- 新开发者上手时间减少 50%
- 完整的架构和 API 文档
- 开发者满意度提升
- 部署信心增强
资源需求
团队配置
- 2-3 名高级开发工程师
- 兼职 QA 工程师
- 技术负责人（架构决策和代码审查）
时间安排
- 总时长：10 周（2.5 个月）
- 开发工作量：约 400-500 人时
- 每周进度评审和调整
工具和环境
- CI/CD 流水线
- 测试环境（开发、测试、预生产）
- 监控和告警系统
- 文档管理系统
注意：本重构计划采用渐进式方法，每个阶段都有明确的可交付成果和验证标准。建议从阶段 1 开始，确保安全基础稳固后再进行架构优化。