# Troubleshoot AI Assistant

问题排查分析助手项目。Flask Web 服务，Embedding 向量搜索（TF-IDF 降级兜底）+ Claude AI 分析，知识库 357 条记录，跑在 `192.168.5.60:8088`。

## 项目结构（P1-3 三层架构）

```
skill/code/web/              # Web 服务（唯一开发源）
├── server.py                # 入口：create_app() 应用工厂 + 启动（~146 行）
├── container.py             # 依赖容器：单例 + config 集中（get_search_engine 等）
├── auth.py                  # UserManager 认证
├── decorators.py            # login_required / admin_required / page_login_required
├── search_engine.py         # Embedding 向量搜索引擎（TF-IDF 降级兜底，被测模块，勿改公开接口）
├── safety_filter.py         # 安全过滤器（函数式模块，被测，勿改公开接口）
├── cache_manager.py         # 缓存管理器（被测模块，勿改公开接口）
├── routes/                  # 路由层（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             #   路径常量（SCRIPT_DIR/PROJECT_ROOT/RECORDS_DIR/VECTOR_INDEX_FILENAME 等）
│   ├── audit.py             #   log_audit
│   ├── record_utils.py      #   入库纯函数
│   ├── vector_builder.py    #   向量预计算脚本（P2-1，生成 搜索向量.json）
│   ├── logger.py            #   通用日志（控制台+文件双输出）
│   ├── error_codes.py       #   统一错误码
│   └── response.py          #   success/error 响应封装
├── templates/               # index.html / login.html
├── config.json              # 运行配置
└── users.json               # 用户数据

skill/code/tests/            # 单元测试（pytest，143 用例）
├── conftest.py              # sys.path 注入 web/ + 索引路径 autouse fixture + 向量 fixture
├── test_safety_filter.py    # 41 用例
├── test_cache_manager.py    # 19 用例
└── test_search_engine.py    # 46 用例（34 TF-IDF + 12 向量搜索）

deploy/                      # 部署脚本（upload_to_server.py / verify_deployment.py）
Docs/                        # PRD 与技术文档
config/                      # systemd 服务定义
.claude/skills/              # Claude Code 技能定义
```

## 关键约定（务必遵守）

### 代码分层
- **新功能按 routes/services/utils 分层**：路由放 `routes/`，业务逻辑放 `services/`，纯工具放 `utils/`
- **单例与 config 统一走 `container.py`**：不要在各模块重建模块级全局单例。取搜索引擎用 `container.get_search_engine()`，重置用 `container.reset_search_engine()`
- **依赖方向单向**：routes/services → container → utils，禁止反向依赖或循环导入
- **路径常量从 `utils/paths.py` 取**：不要在各文件重算 `Path(__file__).parent`，会偏移

### 勿改公开接口的模块
`search_engine.py` / `safety_filter.py` / `cache_manager.py` 三个模块的类与函数签名**不要改**——P1-2 的 94 个单元测试依赖它们。改了要同步更新测试。

### 异常处理（P1-1 规范）
- 禁止空异常捕获 `except:`
- 异常必须记录日志（用 `utils/logger.get_logger`）
- 路由层保留 `except Exception` 兜底是合理设计（避免漏捕），但工具/业务层要细化异常类型

### 敏感信息
- 密码/密钥**禁止硬编码**，用环境变量（见 `.env.example`）
- SSH 密码从 `SSH_PASSWORD` 环境变量读

## 可用技能

- `/git-commit` - 代码提交辅助（审查 + Conventional Commits + 推送分支安全确认）
- `/CreateCMD` - 创建 CMD 窗口
- `/prd-plan` - 解析 PRD 需求文档生成执行计划
- `/prd-code` - 解析执行计划文档生成/更新代码
- `/handoff` - 会话交接文档生成（写入 HANDOFF.md）

## 常用命令

```bash
# 单元测试（143 用例，应全绿）
cd skill/code && python -m pytest -v

# 覆盖率（三核心模块 > 80%）
cd skill/code && python -m pytest --cov=web --cov-report=term

# 本地启动服务
python skill/code/web/server.py    # 监听 0.0.0.0:8088

# 部署到 5.60（用 ! 前缀在会话内执行，避免环境变量读不到）
! cd deploy && SSH_PASSWORD='***' python upload_to_server.py

# 权威验证部署（走 HTTP）
cd deploy && python verify_deployment.py
```

## 避坑（踩过，不要再踩）

1. **环境变量隔离**：Claude 的 Bash 是独立子进程，读不到用户交互 shell 后来 export 的变量。涉及 `SSH_PASSWORD` 等的命令，让用户用 `!` 前缀在会话内执行。
2. **索引文件**：`SearchEngine()` 初始化需 `搜索索引.json`，本地开发默认路径可能不存在。pytest 靠 `tests/conftest.py` 注入 `deploy/搜索索引.json` 副本；本地手动启动需临时注入路径。
3. **部署后健康检查误报**：`upload_to_server.py` 结尾的 `[FAIL]` 是误报（sleep 3 秒不够，加载 357 条索引要更久）。权威验证用 `verify_deployment.py`。
4. **上传清单同步**：新增代码文件/目录后，必须同步更新 `deploy/upload_to_server.py` 的 `FILES_TO_UPLOAD` / `DIRS_TO_UPLOAD` / `DEPLOY_FILES_TO_UPLOAD`，否则部署会缺文件。
5. **Blueprint 端点名**：Blueprint 路由端点是 `<bp>.<func>`，`url_for` 要用全名（如 `url_for('auth.login')`）。
6. **Windows 中文乱码**：控制台显示乱码是 GBK 解码 UTF-8 的正常现象，不影响功能，不要去"修编码"。
7. **向量文件降级静默**：`搜索向量.json` 缺失时 SearchEngine 静默降级 TF-IDF 不报错，只有 `/api/health` 的 `search.mode` 能看出。部署后务必检查 health 响应确认是 `vector` 模式。
8. **向量预计算需联网**：`vector_builder.py` 调 `/v1/embeddings` API，需 `CLAUDE_API_BASE` / `CLAUDE_API_KEY` 配置正确且网络可达。357 条分 20 批调用，约 2 分钟。

## 环境配置

见 `.env.example`。关键变量：`SECRET_KEY`、`CLAUDE_API_BASE`、`CLAUDE_API_KEY`、`SSH_PASSWORD`。

## 当前状态（2026-07-14）

P1 级代码质量优化已全部完成并部署到 5.60：
- **P1-1** 异常处理规范化 ✅
- **P1-2** 单元测试（94 用例，覆盖率 85%~99%）✅
- **P1-3** 架构分层重构（server.py 1443→146 行，三层 + container）✅

P2 级功能增强进行中：
- **P2-1** 语义搜索升级（Embedding 向量搜索 + TF-IDF 降级兜底）✅ 代码完成
- **P2-2** 移动端响应式适配 ✅ 代码完成
- 待部署到 5.60 + 生成向量文件

详见 `HANDOFF.md` 与 `Docs/PRD_计划执行_P2级功能增强.md`。
