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

## 介绍

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

## 需求

### 需求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分钟以内
- ✅ 完全摆脱历史技术债务