# 问题排查分析助手 (Troubleshoot AI Assistant)

> 基于 TF-IDF 搜索 + AI 分析的现场问题排查助手，帮研发快速定位现场故障根因。
> 知识库 357 条问题记录，跑在 Flask Web 服务上。

---

## 功能概述

1. **智能搜索** — TF-IDF 相似度从问题知识库检索历史案例（支持项目/分类过滤）
2. **AI 分析** — 调用 Claude API 生成只读排查步骤 + 根因概率分析
3. **流式返回** — SSE 实时流式输出分析结果（打字效果）
4. **安全过滤** — 三层过滤机制：危险命令黑名单 / 白名单验证 / 敏感信息脱敏，确保输出绝对安全
5. **登录认证** — 用户认证 + 角色权限（admin/普通用户）
6. **缓存管理** — JSON 文件缓存 AI 分析结果，支持过期清理与超限清理
7. **报告导出** — 导出 Word 排查报告
8. **问题入库** — 现场新问题写入知识库并自动重建索引

---

## 目录结构

```
troubleshoot-ai-assistant/
├── skill/                          # Claude Skill 源代码
│   ├── SKILL.md                    # Skill 定义文件
│   └── code/
│       ├── web/                    # Web 服务代码（唯一开发源）
│       │   ├── server.py           # 入口（app 工厂 create_app + 启动，~146 行）
│       │   ├── container.py        # 依赖容器（单例 + config 集中管理）
│       │   ├── auth.py             # UserManager 认证模块
│       │   ├── decorators.py       # login_required / admin_required 装饰器
│       │   ├── search_engine.py    # TF-IDF 搜索引擎
│       │   ├── safety_filter.py    # 安全过滤器（函数式模块）
│       │   ├── cache_manager.py    # 缓存管理器
│       │   ├── routes/             # 路由层（5 个 Blueprint）
│       │   │   ├── auth.py         #   /login /logout /api/user/info /
│       │   │   ├── troubleshoot.py #   /api/troubleshoot /search /analyze /stream /health /projects /categories
│       │   │   ├── cache.py        #   /api/cache/stats /clear
│       │   │   ├── export.py       #   /api/export
│       │   │   └── submit.py       #   /api/submit
│       │   ├── services/           # 业务层
│       │   │   ├── ai_service.py   #   build_prompt / call_claude_api / 流式调用
│       │   │   └── record_service.py # rebuild_search_index
│       │   ├── utils/              # 工具层
│       │   │   ├── paths.py        #   路径常量集中
│       │   │   ├── audit.py        #   log_audit 审计日志
│       │   │   ├── record_utils.py #   入库纯函数
│       │   │   ├── logger.py       #   通用日志（控制台+文件双输出）
│       │   │   ├── error_codes.py  #   统一错误码
│       │   │   └── response.py     #   success/error 响应封装
│       │   ├── templates/          # HTML 模板（index.html / login.html）
│       │   ├── config.json         # 服务运行配置
│       │   └── users.json          # 用户数据
│       ├── tests/                  # 单元测试（pytest，94 用例）
│       │   ├── conftest.py         #   公共 fixture（索引路径注入）
│       │   ├── test_safety_filter.py
│       │   ├── test_cache_manager.py
│       │   └── test_search_engine.py
│       ├── pytest.ini              # pytest 配置
│       ├── build_index.py          # 搜索索引构建工具
│       ├── xlsx_to_md.py           # Excel 转 Markdown 工具
│       ├── requirements.txt        # Python 依赖
│       └── start.bat               # Windows 启动脚本
│
├── deploy/                         # 部署相关
│   ├── deploy.sh                   # Linux 部署脚本
│   ├── upload_to_server.py         # 上传更新文件到服务器
│   ├── verify_deployment.py        # 部署后 HTTP 验证（权威）
│   ├── check_service.py            # 服务检查
│   ├── build_index.py              # 索引构建（部署版）
│   └── 搜索索引.json               # 知识库索引副本
│
├── Docs/                           # PRD 与技术文档（24 个 md）
├── config/                         # 系统配置
│   ├── troubleshoot.service        # systemd 服务定义
│   └── troubleshoot-data.zip       # 数据压缩包
├── .claude/skills/                 # Claude Code 技能定义
├── .env.example                    # 环境变量模板
└── CLAUDE.md                       # Claude Code 项目指令
```

---

## 架构（P1-3 重构后：三层 + 依赖容器）

```
请求 → routes/ (Blueprint) → services/ (业务) → container (单例) → search_engine/cache_manager
                          ↓
                     utils/ (工具：日志/审计/路径/错误码)
```

**分层职责**：
- **routes/** — Flask Blueprint，仅处理 HTTP 请求/响应、参数校验、审计日志
- **services/** — 业务逻辑（AI 调用、记录入库、索引重建）
- **container.py** — 依赖容器，集中管理单例（搜索引擎/缓存/安全过滤器）与 config，解决跨模块全局副作用
- **utils/** — 纯工具（路径常量、审计、日志、错误码、响应封装、入库纯函数）

**依赖方向**：routes/services → container → utils（单向，无循环依赖）

---

## 快速开始

### 1. 环境配置

```bash
cp .env.example .env
# 编辑 .env 填写实际配置
```

### 2. 安装依赖

```bash
pip install -r skill/code/requirements.txt
```

### 3. 本地启动

```bash
python skill/code/web/server.py
# 服务监听 http://localhost:8088
```

> ⚠️ 本地启动需索引文件，见下方"本地开发注意"。

### 4. 运行单元测试

```bash
cd skill/code
python -m pytest -v                          # 跑全部 94 用例
python -m pytest --cov=web --cov-report=term # 覆盖率（三核心模块 > 80%）
```

---

## 部署到生产（192.168.5.60）

```bash
# 上传代码（需 SSH_PASSWORD，建议用 ! 前缀在会话内执行）
! cd deploy && SSH_PASSWORD='***' python upload_to_server.py

# 权威验证（走 HTTP，无需 SSH）
cd deploy && python verify_deployment.py
```

**Linux systemd 部署**：

```bash
sudo cp config/troubleshoot.service /etc/systemd/system/
sudo systemctl enable troubleshoot
sudo systemctl start troubleshoot
```

生产路径：`/opt/troubleshoot/web/`，服务地址 `http://192.168.5.60:8088`。

---

## 环境变量

| 变量名 | 说明 | 必填 |
|--------|------|------|
| `SECRET_KEY` | Flask Session 密钥（生产必须，至少 32 字符） | 是 |
| `CLAUDE_API_BASE` | Claude API 地址 | 是 |
| `CLAUDE_API_KEY` | Claude API 密钥 | 是 |
| `TROUBLESHOOT_ROOT` | 项目根目录覆盖（可选） | 否 |
| `FLASK_DEBUG` | debug 模式（`1` 开 / `0` 关，默认 `1`） | 否 |
| `SSH_HOST` | SSH 服务器地址（部署用） | 否 |
| `SSH_USER` | SSH 用户名（部署用） | 否 |
| `SSH_PASSWORD` | SSH 密码（部署用） | 否 |

---

## 可用 Claude Code 技能

| 命令 | 用途 |
|------|------|
| `/git-commit` | 代码提交辅助（审查 + Conventional Commits + 分支安全确认） |
| `/CreateCMD` | 在当前目录打开 CMD 窗口 |
| `/prd-plan` | 解析 PRD 需求文档生成执行计划 |
| `/prd-code` | 解析执行计划文档生成/更新代码 |
| `/handoff` | 会话交接文档生成（写入 HANDOFF.md） |

---

## 本地开发注意

1. **索引文件**：`SearchEngine()` 初始化需 `搜索索引.json`，本地开发环境的三条默认路径可能都不存在。
   - 跑 pytest 时 `tests/conftest.py` 会自动注入仓库内 `deploy/搜索索引.json` 副本
   - 本地手动启动 server.py 需临时设置索引路径
   - 生产环境索引在 `/opt/troubleshoot/搜索索引.json`，已就位

2. **编码**：Windows 控制台显示中文乱码是正常现象（GBK 解码 UTF-8），不影响功能，日志文件本身是 UTF-8。

3. **部署后验证**：`upload_to_server.py` 结尾的 `[FAIL]` 健康检查是误报（sleep 时间不够），权威验证用 `verify_deployment.py`。

---

## 代码规范

- **单一数据源**：`skill/code/web/` 是唯一开发目录，`deploy/web/` 已删除（P0-3）
- **敏感信息**：使用环境变量，禁止硬编码密码/密钥
- **异常处理**：禁止空异常捕获 `except:`，异常必须记录日志（P1-1 规范）
- **测试覆盖**：核心纯逻辑模块（search_engine/safety_filter/cache_manager）覆盖率 > 80%（P1-2）
- **分层架构**：新功能按 routes/services/utils 分层，单例统一走 container（P1-3）

---

## 相关文档

- [P1 级代码质量优化 - 需求文档](Docs/PRD_需求文档_P1级代码质量优化.md)
- [P1 级代码质量优化 - 计划执行](Docs/PRD_计划执行_P1级代码质量优化.md)
- [项目优化方向](Docs/PRD_需求文档_项目优化方向.md)

---

## 迁移与重构记录

- **2026-07-12**：目录结构统一迁移（`skill/code/web/` 成唯一源，删除 `deploy/web/`）
- **2026-07-13 P0**：修复硬编码密码、server.py 重复赋值、代码重复
- **2026-07-13 P1-1**：异常处理规范化，新增 utils/ 日志/错误码/响应模块
- **2026-07-13 P1-2**：引入 pytest，94 用例覆盖三核心模块（覆盖率 85%~99%）
- **2026-07-13 P1-3**：server.py 拆分为 routes/services/utils 三层架构（1443→146 行）+ container 依赖容器
