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>

CLAUDE.md

 # Troubleshoot AI Assistant
 
-问题排查分析助手项目。
+问题排查分析助手项目。Flask Web 服务，TF-IDF 搜索 + Claude AI 分析，知识库 357 条记录，跑在 `192.168.5.60:8088`。
 
-## 项目结构
+## 项目结构（P1-3 三层架构）
 
 ```
-skill/              # Claude Skills 源代码
-├── code/web/       # Web 服务代码
-└── **/SKILL.md     # 技能定义文件
+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         # 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/             # 部署相关文件
-docs/               # 文档
-config/             # 配置文件
+skill/code/tests/            # 单元测试（pytest，94 用例）
+├── conftest.py              # sys.path 注入 web/ + 索引路径 autouse fixture
+├── 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 计划执行
-- `/handoff` - 会话交接文档生成
+- `/prd-plan` - 解析 PRD 需求文档生成执行计划
+- `/prd-code` - 解析执行计划文档生成/更新代码
+- `/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`。