# PRD_需求文档_P0级问题修复

## 基本信息

| 项目 | 内容 |
|------|------|
| 文档类型 | 需求文档 |
| 创建日期 | 2026-07-12 |
| 负责人 | 研发组 |
| 优先级 | P0（最高优先级） |
| 状态 | 待实施 |

---

## 一、背景与目标

### 1.1 问题背景

经过代码质量分析，发现项目中存在 3 个 P0 级别的严重问题，需要立即修复：

| 问题编号 | 问题描述 | 风险等级 |
|----------|----------|----------|
| P0-1 | 硬编码密码泄露 | 🔴 严重 |
| P0-2 | server.py 重复赋值 Bug | 🔴 严重 |
| P0-3 | skill/ 与 deploy/ 代码重复 | 🟠 高 |

### 1.2 修复目标

1. **消除安全隐患**：移除所有硬编码密码，使用环境变量管理敏感信息
2. **修复代码缺陷**：解决重复赋值 Bug，确保逻辑正确
3. **提升代码质量**：消除代码重复，建立单一数据源，便于维护

---

## 二、需求详情

### 2.1 P0-1：移除硬编码密码

#### 问题描述

以下文件中存在硬编码密码，存在严重安全风险：

| 文件路径 | 行号 | 硬编码内容 |
|----------|------|------------|
| deploy/check_service.py | 10 | PASSWORD = 'Ubains@123' |
| deploy/upload_to_server.py | 14 | PASSWORD = 'Ubains@123' |
| skill/code/test_login_auth.py | 14 | ssh.connect(..., password='Ubains@123') |
| skill/code/test_normal_user.py | 12 | ssh.connect(..., password='Ubains@123') |
| skill/code/web/server.py | 86 | app.secret_key = 'troubleshoot-secret-key-2026-secure' |

#### 需求规格

| 需求项 | 规格 |
|--------|------|
| 密码存储 | 使用 .env 文件或环境变量 |
| 配置读取 | 通过 python-dotenv 或 os.environ.get() 读取 |
| 默认值处理 | 生产环境禁止使用默认密码，开发环境可使用占位符 |
| 文档说明 | 在 README 中说明如何配置环境变量 |

#### 验收标准

- [x] 所有硬编码密码已移除
- [x] 创建 .env.example 模板文件
- [x] .env 已添加到 .gitignore
- [x] 代码中使用环境变量读取敏感配置
- [x] README 中添加配置说明

---

### 2.2 P0-2：修复重复赋值 Bug

#### 问题描述

skill/code/web/server.py 第 796-797 行存在重复赋值：

```python
# 第 796 行
query = request.args.get('query', '').strip()
# 第 797 行（重复，会覆盖上面的值）
query = request.args.get('query', '').strip()
```

此 Bug 会导致：
- 变量被重复赋值，代码逻辑混乱
- 如果未来在第 796 行之后添加了对 query 的处理，第 797 行会覆盖处理结果

#### 需求规格

| 需求项 | 规格 |
|--------|------|
| 代码修复 | 删除第 797 行重复代码 |
| 逻辑验证 | 确认 analyze_stream 函数参数读取逻辑正确 |
| 测试验证 | 手动测试流式 API 功能正常 |

#### 验收标准

- [x] 重复赋值代码已删除
- [x] 流式 API 功能测试通过
- [x] 代码逻辑清晰，无冗余

---

### 2.3 P0-3：消除代码重复

#### 问题描述

skill/code/web/ 与 deploy/web/ 目录下存在大量重复代码：

| 文件 | 相似度 | 说明 |
|------|--------|------|
| server.py | ~95% | 几乎相同 |
| search_engine.py | ~95% | 几乎相同 |
| cache_manager.py | 100% | 完全相同 |
| safety_filter.py | 100% | 完全相同 |
| auth.py | ~95% | 几乎相同 |
| decorators.py | 100% | 完全相同 |

#### 问题影响

1. **维护困难**：修改一处代码需要同步修改另一处，容易遗漏
2. **版本混乱**：两份代码可能存在细微差异，导致行为不一致
3. **存储浪费**：重复代码占用额外空间

#### 需求规格

| 需求项 | 规格 |
|--------|------|
| 目标架构 | 保留 skill/code/web/ 作为开发目录，deploy/ 仅保留部署配置 |
| 共享模块 | 提取公共模块到 skill/code/web/shared/ 或使用符号链接 |
| 部署脚本 | 更新部署脚本，从 skill/code/web/ 复制文件 |
| 文档更新 | 更新 README 说明目录结构 |

#### 验收标准

- [x] 重复代码已消除
- [x] 部署脚本可正确复制源代码
- [x] 部署后服务功能正常
- [x] README 目录结构说明已更新

---

## 三、影响范围

### 3.1 涉及文件

| 文件 | 变更类型 |
|------|----------|
| deploy/check_service.py | 修改 |
| deploy/upload_to_server.py | 修改 |
| skill/code/test_login_auth.py | 修改 |
| skill/code/test_normal_user.py | 修改 |
| skill/code/web/server.py | 修改 |
| .env.example | 新增 |
| .gitignore | 修改 |
| README.md | 修改 |
| deploy/web/ | 删除（使用符号链接或部署脚本复制） |
| deploy/deploy.sh | 修改 |

### 3.2 风险评估

| 风险项 | 等级 | 缓解措施 |
|--------|------|----------|
| 环境变量未配置导致服务启动失败 | 中 | 提供默认值 + 启动检查 |
| 部署脚本复制失败 | 低 | 部署前验证文件存在 |
| 测试文件修改后无法运行 | 低 | 更新测试配置 |

---

## 四、非功能需求

| 需求项 | 说明 |
|--------|------|
| 向后兼容 | 环境变量未配置时使用默认值（开发环境） |
| 文档完善 | README 添加环境变量配置说明 |
| 安全合规 | 敏感信息不得提交到版本控制 |

---

## 五、验收清单

### P0-1 验收

- [x] 所有硬编码密码已移除
- [x] 创建 .env.example 模板
- [x] .env 已添加到 .gitignore
- [x] 服务启动正常，环境变量读取正确

### P0-2 验收

- [x] 重复赋值代码已删除
- [x] 流式 API 功能测试通过

### P0-3 验收

- [x] 重复代码已消除
- [x] 部署脚本正常工作
- [x] 服务部署后功能正常

---

## 六、时间估算

| 任务 | 预计工时 |
|------|----------|
| P0-1：移除硬编码密码 | 0.5 天 |
| P0-2：修复重复赋值 Bug | 0.1 天 |
| P0-3：消除代码重复 | 0.4 天 |
| 测试验证与文档更新 | 0.2 天 |
| **总计** | **1.2 天** |
