ben
/
liurenchaxin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
liurenchaxin/docs/requirements.md

4.9 KiB
Raw Blame History

炼妖壶项目清理与重构需求文档

介绍

炼妖壶项目经过长期开发，积累了大量代码和配置文件，但项目结构变得混乱，存在安全隐患（密钥泄露）和维护困难。本规范旨在系统性地清理和重构项目，建立清晰的架构和安全的开发流程。

需求

需求1：项目结构清理

用户故事： 作为开发者，我希望项目有清晰的目录结构和文件组织，以便快速理解和维护代码。

验收标准

  1. WHEN 查看项目根目录 THEN 应该只包含必要的核心文件和目录
  2. WHEN 查看任何目录 THEN 应该有清晰的README说明其用途
  3. WHEN 寻找特定功能代码 THEN 应该能在预期的目录中找到
  4. WHEN 删除无用文件后 THEN 项目仍能正常运行
  5. IF 文件超过6个月未使用 THEN 应该被归档或删除

需求2：安全配置管理

用户故事： 作为开发者，我希望所有密钥和敏感配置都安全管理，不会意外泄露到代码库中。

验收标准

  1. WHEN 扫描代码库 THEN 不应该发现任何硬编码的密钥或敏感信息
  2. WHEN 开发者需要密钥 THEN 应该从环境变量或Doppler获取
  3. WHEN 提交代码 THEN 应该自动检查是否包含敏感信息
  4. WHEN 新开发者加入 THEN 应该有清晰的密钥管理指南
  5. IF 发现密钥泄露 THEN 应该有自动化的处理流程

需求3：核心功能保留

用户故事： 作为用户，我希望在项目重构后，所有核心功能（AI辩论、数据分析、Streamlit界面）仍然可用。

验收标准

  1. WHEN 启动Streamlit应用 THEN 应该能正常访问所有功能页面
  2. WHEN 运行AI辩论 THEN 应该能正常生成辩论内容
  3. WHEN 连接数据库 THEN 应该能正常读写数据
  4. WHEN 调用外部API THEN 应该能正常获取响应
  5. WHEN 运行测试 THEN 所有核心功能测试应该通过

需求4：开发体验优化

用户故事： 作为开发者，我希望有良好的开发体验，包括清晰的文档、简单的启动流程和有效的调试工具。

验收标准

  1. WHEN 新开发者克隆项目 THEN 应该能在10分钟内启动应用
  2. WHEN 查看文档 THEN 应该能找到所有必要的设置和使用说明
  3. WHEN 遇到问题 THEN 应该有清晰的故障排除指南
  4. WHEN 添加新功能 THEN 应该有明确的开发规范可遵循
  5. WHEN 部署应用 THEN 应该有自动化的部署流程

需求5：技术债务清理

用户故事： 作为维护者，我希望清理技术债务，移除过时的代码和依赖，提高代码质量。

验收标准

  1. WHEN 检查依赖 THEN 不应该有未使用或过时的包
  2. WHEN 运行代码分析 THEN 不应该有严重的代码质量问题
  3. WHEN 查看代码 THEN 应该有一致的编码风格和注释
  4. WHEN 运行性能测试 THEN 应用响应时间应该在可接受范围内
  5. IF 发现重复代码 THEN 应该被重构为可复用的模块

需求6：部署和运维简化

用户故事： 作为运维人员，我希望部署和监控应用变得简单可靠。

验收标准

  1. WHEN 部署到生产环境 THEN 应该使用一键部署脚本
  2. WHEN 应用运行异常 THEN 应该有清晰的日志和监控信息
  3. WHEN 需要扩展 THEN 应该支持水平扩展
  4. WHEN 备份数据 THEN 应该有自动化的备份策略
  5. WHEN 回滚版本 THEN 应该能快速回滚到稳定版本

优先级

  1. P0 (紧急): 安全配置管理 - 立即解决密钥泄露问题
  2. P1 (高): 项目结构清理 - 建立清晰的项目架构
  3. P2 (中): 核心功能保留 - 确保重构不影响核心功能
  4. P3 (中): 开发体验优化 - 改善开发流程
  5. P4 (低): 技术债务清理 - 长期代码质量改进
  6. P5 (低): 部署和运维简化 - 运维流程优化

迁移策略

鉴于当前项目状态混乱，采用全新开始的策略：

  1. 文档先行 - 完善所有需求和设计文档
  2. 干净迁移 - 在新目录 /home/ben/liurenchaxin 重新开始
  3. 选择性迁移 - 只迁移核心功能代码，抛弃历史包袱
  4. 安全优先 - 从一开始就建立安全的配置管理

核心功能清单（需要保留）

必须迁移的功能

  • 🤖 稷下学宫AI辩论系统 (八仙辩论)
  • 📊 Streamlit主界面
  • 🔗 Doppler配置管理
  • 💾 数据库连接 (PostgreSQL, MongoDB, Zilliz)
  • 🔌 外部API集成 (OpenRouter, Anthropic等)

可选迁移的功能

  • 📈 金融数据分析
  • 🔄 N8N工作流
  • 📱 MCP服务器
  • 🧪 实验性功能

成功标准

项目重构成功的标志：

  • ✅ 通过GitGuardian安全扫描，无密钥泄露
  • ✅ 项目目录结构清晰，符合最佳实践
  • ✅ 所有核心功能正常工作
  • ✅ 新开发者能在10分钟内启动项目
  • ✅ 代码质量评分达到B级以上
  • ✅ 部署时间缩短到5分钟以内
  • ✅ 完全摆脱历史技术债务