Flask Prompt Master 项目重构方案 上下文和目标 项目概况：D:/aaa/aitsc 是一个 Flask 应用程序，提供多种 AI 驱动的功能（提示词模板、饭菜规划、旅行攻略、会议 纪要、简历优化等）。项目采用蓝图架构，但随着功能增加出现了代码质量问题。 当前问题： 1. 安全漏洞：多个路由文件中存在硬编码的 API 密钥和数据库密码 2. 代码结构：routes.py 文件过大（1300+ 行），职责不单一 3. API 设计不一致：多种响应格式和错误处理方式 4. 认证系统碎片化：同时使用会话、令牌和微信认证 5. 配置管理混乱：新旧配置系统并存 6. 代码重复：相似功能间存在重复代码 重构目标： 1. 消除安全漏洞，移除所有硬编码的敏感信息 2. 提高代码可维护性，优化项目结构 3. 标准化 API 设计和错误处理 4. 集中化认证和授权系统 5. 实现关注点分离（业务逻辑与表现层分离） 重构方案概述 目标架构 flask_prompt_master/ ├── app/ # 应用层（API/Web 路由） ├── core/ # 核心业务逻辑（服务层） ├── infrastructure/ # 基础设施（配置、数据库、外部服务） ├── shared/ # 共享组件（工具类、数据模型、常量） ├── tests/ # 测试套件 └── docs/ # 文档 核心改进 6. 安全加固：环境变量管理，JWT 认证，安全头部 7. API 标准化：统一响应格式，版本控制，OpenAPI 文档 8. 代码重组：服务层提取，仓库模式，依赖注入 9. 质量提升：测试覆盖率，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 兼容性风险： - 使用功能开关控制新功能 - 保持向后兼容性至少一个版本周期 - 提供详细的迁移指南 性能回归风险： - 重构前后进行性能基准测试 - 实施监控和告警 - 准备快速回滚机制 实施风险 团队知识差距： - 结对编程和代码审查 - 详细的架构文档 - 定期知识分享会议 时间安排风险： - 采用敏捷方法，每两周评估进度 - 优先处理高价值任务 - 保持灵活性，根据进展调整计划 关键文件路径 需要立即处理的安全问题 1. D:/aaa/aitsc/src/flask_prompt_master/routes/routes.py:115 - 硬编码数据库密码 2. D:/aaa/aitsc/config.py - 已弃用的硬编码配置 3. 所有包含硬编码 API 密钥的文件（搜索 sk-fdf7cc1c73504e628ec0119b7e11b8cc） 大型文件需要拆分 4. D:/aaa/aitsc/src/flask_prompt_master/routes/routes.py（1300+ 行） 5. D:/aaa/aitsc/src/flask_prompt_master/models/models.py（500+ 行） 新目录结构 6. src/flask_prompt_master/services/ - 服务层 7. src/flask_prompt_master/repositories/ - 仓库层 8. src/flask_prompt_master/shared/ - 共享组件 9. src/flask_prompt_master/api/ - API 相关组件 验证和测试策略 验证步骤 10. 安全验证：确保无硬编码敏感信息，所有配置通过环境变量管理 11. 功能验证：所有现有功能测试通过，API 响应格式一致 12. 性能验证：关键 API 端点响应时间无显著下降 13. 部署验证：生产环境部署成功，监控系统正常运行 测试计划 14. 单元测试：服务层、仓库层、工具类 15. 集成测试：API 端点、数据库操作 16. 端到端测试：关键用户流程（注册、登录、使用功能） 17. 性能测试：负载测试、压力测试 成功指标 量化指标 18. 零硬编码敏感信息 19. 测试覆盖率 80%+ 20. 代码复杂度降低 30% 21. API 平均响应时间改善 20% 22. 缺陷修复时间减少 50% 质化指标 23. 新开发者上手时间减少 50% 24. 完整的架构和 API 文档 25. 开发者满意度提升 26. 部署信心增强 资源需求 团队配置 - 2-3 名高级开发工程师 - 兼职 QA 工程师 - 技术负责人（架构决策和代码审查） 时间安排 - 总时长：10 周（2.5 个月） - 开发工作量：约 400-500 人时 - 每周进度评审和调整 工具和环境 - CI/CD 流水线 - 测试环境（开发、测试、预生产） - 监控和告警系统 - 文档管理系统 --- 注意：本重构计划采用渐进式方法，每个阶段都有明确的可交付成果和验证标准。建议从阶段 1 开始，确保安全基础稳固后再进行架构优化。