docs: 更新 README 与 CLAUDE.md 反映 P1 三层架构

- README.md：重写功能概述、完整目录结构（routes/services/utils + container）、三层架构图、快速开始、部署流程、环境变量表、技能清单、本地开发注意、 P0/P1 重构记录 - CLAUDE.md：重写为 Claude Code 项目指令，含目录结构、分层约定（单例走 container、路径走 utils/paths）、勿改接口模块、异常规范、常用命令、6 条避坑、当前 P1 完成状态 - 两份文档均从过时的旧结构更新到 P1-3 重构后的真实架构 Co-Authored-By: Claude <noreply@anthropic.com>

docs: 更新 README 与 CLAUDE.md 反映 P1 三层架构
- README.md：重写功能概述、完整目录结构（routes/services/utils + container）、三层架构图、快速开始、部署流程、环境变量表、技能清单、本地开发注意、 P0/P1 重构记录 - CLAUDE.md：重写为 Claude Code 项目指令，含目录结构、分层约定（单例走 container、路径走 utils/paths）、勿改接口模块、异常规范、常用命令、6 条避坑、当前 P1 完成状态 - 两份文档均从过时的旧结构更新到 P1-3 重构后的真实架构 Co-Authored-By: Claude <noreply@anthropic.com>
b7d51dd1 · 陈泽健 · 3caf6a0a · b7d51dd1 · b7d51dd1
--- a/CLAUDE.md
+++ b/CLAUDE.md
 # Troubleshoot AI Assistant
-问题排查分析助手项目。
+问题排查分析助手项目。Flask Web 服务，TF-IDF 搜索 + Claude AI 分析，知识库 357 条记录，跑在 `192.168.5.60:8088`。
-## 项目结构
+## 项目结构（P1-3 三层架构）
 ```
-skill/              # Claude Skills 源代码
+skill/code/web/              # Web 服务（唯一开发源）
-├── code/web/       # Web 服务代码
+├── server.py                # 入口：create_app() 应用工厂 + 启动（~146 行）
-└── **/SKILL.md     # 技能定义文件
+├── container.py             # 依赖容器：单例 + config 集中（get_search_engine 等）
+├── auth.py                  # UserManager 认证
+├── decorators.py            # login_required / admin_required / page_login_required
+├── search_engine.py         # 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 等）
+│   ├── audit.py             #   log_audit
+│   ├── record_utils.py      #   入库纯函数
+│   ├── logger.py            #   通用日志（控制台+文件双输出）
+│   ├── error_codes.py       #   统一错误码
+│   └── response.py          #   success/error 响应封装
+├── templates/               # index.html / login.html
+├── config.json              # 运行配置
+└── users.json               # 用户数据
-deploy/             # 部署相关文件
+skill/code/tests/            # 单元测试（pytest，94 用例）
-docs/               # 文档
+├── conftest.py              # sys.path 注入 web/ + 索引路径 autouse fixture
-config/             # 配置文件
+├── test_safety_filter.py    # 41 用例
+├── test_cache_manager.py    # 19 用例
+└── test_search_engine.py    # 34 用例
+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` - 代码提交辅助
+- `/git-commit` - 代码提交辅助（审查 + Conventional Commits + 推送分支安全确认）
 - `/CreateCMD` - 创建 CMD 窗口
- `/prd-code` - PRD 代码生成
+- `/prd-plan` - 解析 PRD 需求文档生成执行计划
- `/prd-plan` - PRD 计划执行
+- `/prd-code` - 解析执行计划文档生成/更新代码
- `/handoff` - 会话交接文档生成
+- `/handoff` - 会话交接文档生成（写入 HANDOFF.md）
+## 常用命令
+```bash
+# 单元测试（94 用例，应全绿）
+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`，否则部署会缺文件。
+5. **Blueprint 端点名**：Blueprint 路由端点是 `<bp>.<func>`，`url_for` 要用全名（如 `url_for('auth.login')`）。
+6. **Windows 中文乱码**：控制台显示乱码是 GBK 解码 UTF-8 的正常现象，不影响功能，不要去"修编码"。
 ## 环境配置
-见 `.env.example` 文件，使用环境变量管理敏感信息。
+见 `.env.example`。关键变量：`SECRET_KEY`、`CLAUDE_API_BASE`、`CLAUDE_API_KEY`、`SSH_PASSWORD`。
+## 当前状态（2026-07-13）
+P1 级代码质量优化已全部完成并部署到 5.60：
+- **P1-1** 异常处理规范化 ✅
+- **P1-2** 单元测试（94 用例，覆盖率 85%~99%）✅
+- **P1-3** 架构分层重构（server.py 1443→146 行，三层 + container）✅
+详见 `HANDOFF.md` 与 `Docs/PRD_计划执行_P1级代码质量优化.md`。
--- a/README.md
+++ b/README.md
 # 问题排查分析助手 (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/                          # Claude Skill 源代码
 │   ├── SKILL.md                    # Skill 定义文件
-│   └── code/              # 核心代码
+│   └── code/
-│       ├── web/           # Web服务代码（唯一源）
+│       ├── web/                    # Web 服务代码（唯一开发源）
-│       │   ├── server.py          # Flask服务器主程序
+│       │   ├── server.py           # 入口（app 工厂 create_app + 启动，~146 行）
-│       │   ├── search_engine.py   # 搜索引擎
+│       │   ├── container.py        # 依赖容器（单例 + config 集中管理）
-│       │   ├── cache_manager.py   # 缓存管理
+│       │   ├── auth.py             # UserManager 认证模块
-│       │   ├── auth.py            # 认证模块
+│       │   ├── decorators.py       # login_required / admin_required 装饰器
-│       │   ├── safety_filter.py   # 安全过滤
+│       │   ├── search_engine.py    # TF-IDF 搜索引擎
-│       │   └── templates/         # HTML模板
+│       │   ├── safety_filter.py    # 安全过滤器（函数式模块）
-│       ├── xlsx_to_md.py          # Excel转Markdown工具
+│       │   ├── cache_manager.py    # 缓存管理器
-│       ├── build_index.py         # 索引构建工具
+│       │   ├── routes/             # 路由层（5 个 Blueprint）
-│       ├── requirements.txt       # Python依赖
+│       │   │   ├── auth.py         #   /login /logout /api/user/info /
-│       └── start.bat              # Windows启动脚本
+│       │   │   ├── troubleshoot.py #   /api/troubleshoot /search /analyze /stream /health /projects /categories
-│
+│       │   │   ├── cache.py        #   /api/cache/stats /clear
-├── deploy/                # 部署相关文件
+│       │   │   ├── export.py       #   /api/export
-│   ├── deploy.sh          # Linux部署脚本（从 skill/code/web/ 复制）
+│       │   │   └── submit.py       #   /api/submit
-│   ├── 问题记录/          # 问题知识库（日常+项目）
+│       │   ├── services/           # 业务层
-│   ├── upload_to_server.py # 上传工具
+│       │   │   ├── ai_service.py   #   build_prompt / call_claude_api / 流式调用
-│   ├── check_service.py   # 服务检查脚本
+│       │   │   └── record_service.py # rebuild_search_index
-│   └── verify_deployment.py # 验证脚本
+│       │   ├── 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 启动脚本
 │
-├── docs/                  # PRD文档
+├── deploy/                         # 部署相关
-│   ├── PRD_需求文档_问题知识库智能排查助手.md
+│   ├── deploy.sh                   # Linux 部署脚本
-│   ├── PRD_需求文档_问题排查助手性能与功能优化.md
+│   ├── upload_to_server.py         # 上传更新文件到服务器
-│   ├── PRD_需求文档_问题排查助手流式返回优化.md
+│   ├── verify_deployment.py        # 部署后 HTTP 验证（权威）
-│   ├── _PRD_Troubleshoot助手登录认证_需求文档.md
+│   ├── check_service.py            # 服务检查
-│   ├── _PRD_Troubleshoot助手功能优化_需求文档.md
+│   ├── build_index.py              # 索引构建（部署版）
-│   ├── 技术实现文档_问题排查助手Web服务.md
+│   └── 搜索索引.json               # 知识库索引副本
-│   ├── 部署指南_问题排查助手Web服务.md
-│   └── 用户使用手册_问题排查助手.md
-│
-├── config/                # 配置文件
-│   ├── troubleshoot.service  # systemd服务定义
-│   └── troubleshoot-data.zip # 数据压缩包（如有）
 │
+├── Docs/                           # PRD 与技术文档（24 个 md）
+├── config/                         # 系统配置
+│   ├── troubleshoot.service        # systemd 服务定义
+│   └── troubleshoot-data.zip       # 数据压缩包
+├── .claude/skills/                 # Claude Code 技能定义
 ├── .env.example                    # 环境变量模板
-├── .gitignore             # Git忽略配置
+└── CLAUDE.md                       # Claude Code 项目指令
-└── README.md              # 本说明文件
 ```
-## 功能概述
+---
+## 架构（P1-3 重构后：三层 + 依赖容器）
-问题排查分析助手是一个基于AI的智能问题分析工具，主要功能包括：
+```
+请求 → routes/ (Blueprint) → services/ (业务) → container (单例) → search_engine/cache_manager
+                          ↓
+                     utils/ (工具：日志/审计/路径/错误码)
+```
-1. **智能搜索** - 通过关键词搜索问题知识库
+**分层职责**：
-2. **AI分析** - 使用Claude API进行问题分析和解决方案推荐
+- **routes/** — Flask Blueprint，仅处理 HTTP 请求/响应、参数校验、审计日志
-3. **流式返回** - 支持实时流式输出分析结果
+- **services/** — 业务逻辑（AI 调用、记录入库、索引重建）
-4. **登录认证** - 用户认证和权限管理
+- **container.py** — 依赖容器，集中管理单例（搜索引擎/缓存/安全过滤器）与 config，解决跨模块全局副作用
-5. **缓存管理** - 搜索结果缓存优化性能
+- **utils/** — 纯工具（路径常量、审计、日志、错误码、响应封装、入库纯函数）
-## 快速使用
+**依赖方向**：routes/services → container → utils（单向，无循环依赖）
-### Claude Skill调用
+---
-在Claude Code中使用 `/Troubleshoot` 命令调用此助手。
+## 快速开始
-### Web服务部署
+### 1. 环境配置
 ```bash
-# 1. 配置环境变量
 cp .env.example .env
-# 编辑 .env 文件，填写实际配置
+# 编辑 .env 填写实际配置
+```
+### 2. 安装依赖
-# 2. 安装依赖
+```bash
 pip install -r skill/code/requirements.txt
+```
+### 3. 本地启动
-# 3. 启动服务
+```bash
 python skill/code/web/server.py
+# 服务监听 http://localhost:8088
+```
+> ⚠️ 本地启动需索引文件，见下方"本地开发注意"。
+### 4. 运行单元测试
-# Linux systemd部署
+```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`。
+---
+## 环境变量
 | 变量名 | 说明 | 必填 |
 |--------|------|------|
-| `SSH_HOST` | SSH服务器地址 | 否（测试用） |
+| `SECRET_KEY` | Flask Session 密钥（生产必须，至少 32 字符） | 是 |
-| `SSH_USER` | SSH用户名 | 否（测试用） |
+| `CLAUDE_API_BASE` | Claude API 地址 | 是 |
-| `SSH_PASSWORD` | SSH密码 | 否（测试用） |
+| `CLAUDE_API_KEY` | Claude API 密钥 | 是 |
-| `SECRET_KEY` | Flask Session密钥 | 是（生产环境） |
+| `TROUBLESHOOT_ROOT` | 项目根目录覆盖（可选） | 否 |
-| `CLAUDE_API_BASE` | Claude API地址 | 是 |
+| `FLASK_DEBUG` | debug 模式（`1` 开 / `0` 关，默认 `1`） | 否 |
-| `CLAUDE_API_KEY` | Claude API密钥 | 是 |
+| `SSH_HOST` | SSH 服务器地址（部署用） | 否 |
+| `SSH_USER` | SSH 用户名（部署用） | 否 |
+| `SSH_PASSWORD` | SSH 密码（部署用） | 否 |
-## 相关链接
+---
- [技术实现文档](docs/技术实现文档_问题排查助手Web服务.md)
+## 可用 Claude Code 技能
- [部署指南](docs/部署指南_问题排查助手Web服务.md)
- [用户使用手册](docs/用户使用手册_问题排查助手.md)
-## 迁移记录
+| 命令 | 用途 |
+|------|------|
+| `/git-commit` | 代码提交辅助（审查 + Conventional Commits + 分支安全确认） |
+| `/CreateCMD` | 在当前目录打开 CMD 窗口 |
+| `/prd-plan` | 解析 PRD 需求文档生成执行计划 |
+| `/prd-code` | 解析执行计划文档生成/更新代码 |
+| `/handoff` | 会话交接文档生成（写入 HANDOFF.md） |
-本目录于 2026-07-12 从原仓库分散位置迁移至此统一目录结构：
+---
- 原位置: `.claude/skills/Troubleshoot/` → 新位置: `skill/`
+## 本地开发注意
- 原位置: `Troubleshoot-deploy/` → 新位置: `deploy/`
- 原位置: `Docs/PRD/问题知识库/` → 新位置: `docs/`
+1. **索引文件**：`SearchEngine()` 初始化需 `搜索索引.json`，本地开发环境的三条默认路径可能都不存在。
- 原位置: `troubleshoot.service` → 新位置: `config/`
+   - 跑 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/` 已删除
+- **单一数据源**：`skill/code/web/` 是唯一开发目录，`deploy/web/` 已删除（P0-3）
- **部署方式**: 通过 `deploy/deploy.sh` 从 `skill/code/web/` 复制文件
+- **敏感信息**：使用环境变量，禁止硬编码密码/密钥
- **敏感信息**: 使用环境变量，禁止硬编码密码
+- **异常处理**：禁止空异常捕获 `except:`，异常必须记录日志（P1-1 规范）
\ No newline at end of file
+- **测试覆盖**：核心纯逻辑模块（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 依赖容器