# PRD_需求文档_项目优化方向

## 基本信息

| 项目 | 内容 |
|------|------|
| 文档类型 | 优化规划 |
| 创建日期 | 2026-07-12 |
| 最后更新 | 2026-07-12 |
| 负责人 | 研发组 |
| 状态 | 持续跟踪 |

---

## 一、项目现状

### 1.1 已完成功能（v1.2.0）

| 功能模块 | 状态 | 说明 |
|---------|------|------|
| Web 排查服务 | ✅ 完成 | Flask 后端，端口 8088 |
| 智能搜索引擎 | ✅ 完成 | TF-IDF + 余弦相似度，357 条记录 |
| AI 分析集成 | ✅ 完成 | GLM-4-flash/5.1/4-plus 多模型支持 |
| 流式返回 (SSE) | ✅ 完成 | 实时输出排查结果 |
| 安全过滤器 | ✅ 完成 | 75+ 危险命令模式，敏感信息脱敏 |
| 登录认证 | ✅ 完成 | 用户/管理员角色，暴力破解保护 |
| 缓存管理 | ✅ 完成 | JSON 文件缓存，24 小时过期 |
| Word 导出 | ✅ 完成 | python-docx 生成报告 |
| 问题入库 | ✅ 完成 | 提交新问题到知识库 |
| Claude Skills | ✅ 完成 | 5 个技能集成 |

### 1.2 已修复问题

| 问题 | 优先级 | 修复日期 |
|------|--------|----------|
| 硬编码密码泄露 | P0 | 2026-07-12 |
| server.py 重复赋值 Bug | P0 | 2026-07-12 |
| skill/ 与 deploy/ 代码重复 | P0 | 2026-07-12 |
| 登录页泄露默认账号密码 | P1 | 2026-07-12 |

---

## 二、待优化方向

### 2.1 🔴 高优先级（P1）

#### 2.1.1 异常处理规范化

| 项目 | 说明 |
|------|------|
| **问题** | 空异常捕获 `except: pass`，过宽异常捕获 |
| **位置** | `cache_manager.py:126-128`，`server.py` 多处 |
| **风险** | 静默失败隐藏 Bug，调试困难 |
| **方案** | 细化异常类型，添加日志记录 |
| **工时** | 0.5 天 |

#### 2.1.2 添加单元测试

| 项目 | 说明 |
|------|------|
| **现状** | 无本地单元测试，仅有远程 SSH 测试 |
| **方案** | 引入 pytest 框架，覆盖核心模块 |
| **覆盖目标** | 搜索引擎、安全过滤器、缓存管理 |
| **工时** | 1 天 |

#### 2.1.3 架构分层重构

| 项目 | 说明 |
|------|------|
| **现状** | `server.py` 单文件 1415 行，无分层设计 |
| **问题** | 维护困难，职责不清 |
| **方案** | 拆分为 Controller/Service/Repository 三层 |
| **工时** | 2-3 天 |

---

### 2.2 🟠 功能增强（P2）

#### 2.2.1 语义搜索升级

| 项目 | 说明 |
|------|------|
| **现状** | TF-IDF + 关键词匹配 |
| **方案** | 引入 Embedding 向量搜索（如 text-embedding-3-small） |
| **收益** | 匹配准确率提升 20%+，理解语义相似问题 |
| **工时** | 2 天 |

#### 2.2.2 移动端适配

| 项目 | 说明 |
|------|------|
| **现状** | 仅支持桌面端 |
| **方案** | 响应式布局优化，支持手机浏览器访问 |
| **收益** | 扩大使用场景，支持现场移动办公 |
| **工时** | 1 天 |

#### 2.2.3 问题趋势分析

| 项目 | 说明 |
|------|------|
| **功能** | 按项目/时间/类型统计问题分布 |
| **输出** | 可视化图表（问题热力图、趋势折线图） |
| **收益** | 发现高频问题模式，提前预防 |
| **工时** | 2 天 |

#### 2.2.4 批量导入功能

| 项目 | 说明 |
|------|------|
| **功能** | 支持从 Excel/CSV 批量导入历史问题 |
| **收益** | 知识库扩充效率大幅提升 |
| **工时** | 1 天 |

---

### 2.3 🟢 技术优化（P3）

#### 2.3.1 添加类型注解

| 项目 | 说明 |
|------|------|
| **现状** | 所有 Python 文件缺少类型提示 |
| **方案** | 添加 Python 类型注解（Type Hints） |
| **收益** | IDE 支持更好，早期错误检测 |
| **工时** | 2 天 |

#### 2.3.2 API 文档

| 项目 | 说明 |
|------|------|
| **现状** | 仅有代码注释 |
| **方案** | 引入 Swagger/OpenAPI 自动生成文档 |
| **收益** | 接口文档标准化，便于对接 |
| **工时** | 1 天 |

#### 2.3.3 Docker 部署

| 项目 | 说明 |
|------|------|
| **现状** | 手动部署，依赖 shell 脚本 |
| **方案** | Docker Compose 一键部署 |
| **收益** | 部署标准化，环境一致性 |
| **工时** | 1 天 |

#### 2.3.4 监控告警

| 项目 | 说明 |
|------|------|
| **现状** | 仅日志输出 |
| **方案** | Prometheus + Grafana 监控面板 |
| **收益** | 实时监控服务状态，异常告警 |
| **工时** | 2 天 |

---

## 三、实施路线图

### 3.1 短期（本周）

| 任务 | 优先级 | 工时 | 状态 |
|------|--------|------|------|
| 异常处理规范化 | P1 | 0.5天 | ✅ 完成（2026-07-13） |
| 提交代码规范检查配置 | P3 | 0.2天 | 待开始 |

### 3.2 中期（下周）

| 任务 | 优先级 | 工时 | 状态 |
|------|--------|------|------|
| 添加 pytest 单元测试 | P1 | 1天 | ✅ 完成（2026-07-13，94 用例） |
| 移动端响应式适配 | P2 | 1天 | 待开始 |
| 统一错误响应 + 路由层测试 | P1 | 1.5天 | ✅ 完成（2026-07-14，131 用例） |

### 3.3 长期（本月）

| 任务 | 优先级 | 工时 | 状态 |
|------|--------|------|------|
| 语义搜索升级 | P2 | 2天 | 待开始 |
| 架构分层重构 | P1 | 2天 | ✅ 完成（2026-07-13，server.py 1443→146 行） |
| Docker 部署方案 | P3 | 1天 | 待开始 |

---

## 四、技术栈规划

### 4.1 当前技术栈

| 层级 | 技术 |
|------|------|
| 前端 | 原生 HTML/CSS/JavaScript |
| 后端 | Python 3.10 + Flask |
| 搜索 | TF-IDF + 余弦相似度 |
| AI | GLM API |
| 存储 | Markdown + JSON |
| 认证 | Session + users.json |

### 4.2 规划升级

| 层级 | 当前 | 升级方向 |
|------|------|----------|
| 搜索 | TF-IDF | Embedding 向量搜索 |
| 认证 | Session | JWT Token（可选） |
| 存储 | JSON | SQLite/PostgreSQL（可选） |
| 部署 | Shell | Docker Compose |
| 监控 | 日志 | Prometheus + Grafana |

---

## 五、维护记录

| 日期 | 更新内容 | 更新人 |
|------|----------|--------|
| 2026-07-12 | 初始版本，记录已完成和待优化项 | Claude |
| 2026-07-13 | P1-1/P1-2/P1-3 三项全部完成（异常处理 + 单测 + 架构重构） | Claude |
| 2026-07-14 | P1 收尾三项完成（统一错误响应 + 路由层测试 + submit/export 鉴权），131 用例全绿 | Claude |
