123 lines
4.9 KiB
Markdown
123 lines
4.9 KiB
Markdown
# 炼妖壶项目清理与重构需求文档
|
||
|
||
## 介绍
|
||
|
||
炼妖壶项目经过长期开发，积累了大量代码和配置文件，但项目结构变得混乱，存在安全隐患（密钥泄露）和维护困难。本规范旨在系统性地清理和重构项目，建立清晰的架构和安全的开发流程。
|
||
|
||
## 需求
|
||
|
||
### 需求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分钟以内
|
||
- ✅ 完全摆脱历史技术债务 |