# HANDOFF — P2 级功能增强 + 平台化改造（已部署，待提交 + 密码修改）

> 最后更新：2026-07-14 16:00 ｜ 分支：troubleshoot-ai-assistant ｜ 负责人：研发组（Claude 协助）

---

## 1. 我们在做什么

这个项目是「运维辅助平台」（原"问题排查 AI 助手"），Flask Web 服务跑在 `192.168.5.60:8088`。

本会话完成了三项主要工作：

1. **P2-1 语义搜索升级**：SearchEngine 加 Embedding 向量搜索能力（代码就绪，用户因担心 API 扣费暂关闭 `embedding_enabled: false`，搜索走 TF-IDF）
2. **P2-2 移动端响应式适配**：三档断点 + 触控热区 + 弹窗适配 + SSE 滚动跟随
3. **平台化改造**：新增平台首页 `/`（模块卡片），问题排查助手降级为 `/troubleshoot` 模块，预留"服务监控"模块

还完成了两个额外需求：
- **普通用户项目名称输入限制**：`/api/projects` 角色鉴权，普通用户返回空列表防泄露
- **架构文档**：根目录新建 `ARCHITECTURE.md`，说明技术栈、部署方式、模块注册机制

**关键决策**：
- Embedding 向量搜索**暂停使用**（用户决定），启用只需改 `config.json` 的 `embedding_enabled: true` + 生成向量文件
- 平台化用**同服务不同路由**（非微服务），共用 Flask + 认证，各模块独立 Blueprint
- 模块注册用声明式 `modules.py`，新增模块只需追加声明 + 注册 Blueprint

---

## 2. 已经完成了什么

### ✅ 2.1 P2-1 语义搜索升级（代码完成，功能关闭）

- `search_engine.py` 加向量加载/查询/降级，**公开接口零变更**（`search()` 签名不变）
- 新增 `utils/vector_builder.py` 预计算脚本
- `config.json` 新增 `embedding_enabled: false` / `embedding_model` / `embedding_api_timeout`
- `/api/health` 暴露 `search.mode: tfidf` + 版本升至 1.3.0
- **验证**：`/api/health` 确认 `search.mode=tfidf, vector_loaded=false`

### ✅ 2.2 P2-2 移动端响应式适配（已部署）

- `templates/index.html`：viewport + 三档断点 + 触控热区 ≥44px + 弹窗/代码块适配 + SSE 滚动
- `templates/login.html`：viewport + 移动端断点
- **验证**：Chrome DevTools iPhone 模拟，登录→搜索→AI 分析全流程正常

### ✅ 2.3 普通用户项目名称输入限制（已部署）

- `routes/troubleshoot.py` 的 `/api/projects` 角色鉴权：普通用户返回 `[]`，管理员返回 120 项
- **验证**：`verify_deployment.py` 全通过，未登录调 `/api/projects` 返回 0 项

### ✅ 2.4 平台化改造（已部署）

- `utils/modules.py` **新建**：模块清单声明 + `get_modules(role)`，预留"服务监控"模块（`enabled: false`）
- `routes/platform.py` **新建**：平台首页路由 `/`，登录后显示模块卡片
- `templates/platform.html` **新建**：平台首页模板（渐变背景 + 卡片网格 + 响应式）
- `routes/auth.py`：删除原 `/` 路由（由 platform 接管）
- `routes/troubleshoot.py`：新增 `/troubleshoot` 页面路由 + `page_login_required`
- `templates/index.html`：顶部用户信息栏加"🏠 返回首页"链接
- `server.py`：注册 `platform` Blueprint
- **验证**：Chrome DevTools 确认 `/` 显示"运维辅助平台"首页，点击"问题排查助手"卡片进入 `/troubleshoot`，返回首页正常

### ✅ 2.5 架构文档

- 根目录 `ARCHITECTURE.md`：技术栈、项目结构、架构图、服务器部署、systemd 配置、环境变量、新增模块步骤

### ✅ 2.6 P2 级功能增强已提交推送（`b4fad0c1`）

### ✅ 2.7 全部部署到 5.60 并验证

- 145 用例全绿（2.77s）
- `verify_deployment.py` 全通过
- Chrome DevTools 手动验证：首页 → 排查助手 → 返回首页

---

## 3. 当前卡在哪

**有一个未完成项**：用户要求修改密码，**尚未执行**：
- admin 密码改为 `Ubains@1357`
- 普通用户 user 密码改为 `Ubains@123`

需要用 `auth.py` 的 `UserManager.update_password()` 生成 scrypt 哈希后更新 `users.json`，然后重新部署。

**平台化改造代码已部署但未提交 git**（6 个修改文件 + 5 个新文件）。

---

## 4. 下一步计划

1. **修改用户密码**：更新 `users.json` 中 admin 和 user 的 `password_hash`，然后部署到 5.60
2. **提交 git 并推送**：平台化改造 6 个修改文件 + 5 个新文件（含 ARCHITECTURE.md + modules.py + platform.py/html + PRD 文档），用 `/git-commit`
3. **启用向量搜索（可选）**：将 `config.json` 的 `embedding_enabled` 改为 `true` + 执行 `python -m utils.vector_builder` 生成 `搜索向量.json` + 部署
4. **接入"服务监控"模块**：在 `modules.py` 中将 `service-monitor` 的 `enabled` 改为 `true` + 创建对应的 Blueprint 和模板

---

## 5. 踩过的坑（绝对不要再踩）

### 🚨 坑 1：删除 auth.py 的 `/` 路由时多删了 `render_template` 导入
- **现象**：删 `page_login_required` 导入时把 `render_template` 也删了，导致 `/login` GET 请求 500
- **原因**：`login()` 函数仍用 `render_template('login.html')`，但导入被一起删掉
- **避免**：删除导入前 grep 确认函数体内无引用

### 🚨 坑 2：平台首页 `/` 与 auth 的 `/` 路由冲突
- **现象**：Flask 注册两个 Blueprint 都有 `/` 路由会报 `AssertionError: duplicate route`
- **避免**：平台化后 `/` 只由 `platform.py` 定义，`auth.py` 的 `/` 必须删除

### 🚨 坑 3：向量功能关闭后测试 `test_vector_load_success` 失败
- **现象**：`config.json` 的 `embedding_enabled: false` 导致 `_load_vectors` 跳过加载
- **避免**：向量测试类加 `autouse` fixture 注入临时配置 `embedding_enabled: True`

### 🚨 坑 4：conftest autouse 注入向量文件路径会干扰降级测试
- **避免**：autouse fixture 默认 `VECTOR_INDEX_PATHS=[]`，需要向量的测试单独注入路径

### ⚠️ 坑 5：修改 `/api/projects` 返回值破坏现有测试
- **避免**：改后端 API 返回值时，必须同步检查并按角色拆分测试用例

### ⚠️ 坑 6：平台首页 `/` 未登录时的重定向行为
- **注意**：`platform.py` 用 `session.get('user')` 手动判断，不用 `@page_login_required`（因为未登录应重定向而非返回 401），与 `auth.py` 原 `/` 行为一致

---

## 6. 关键文件与命令速查

### 本次新增/修改的核心文件

| 文件 | 状态 | 说明 |
|------|------|------|
| `skill/code/web/utils/modules.py` | **新增** | 模块清单声明 + `get_modules(role)` |
| `skill/code/web/routes/platform.py` | **新增** | 平台首页路由 `/` |
| `skill/code/web/templates/platform.html` | **新增** | 平台首页模板 |
| `skill/code/web/utils/vector_builder.py` | **新增**（P2-1） | 向量预计算脚本 |
| `skill/code/web/search_engine.py` | 修改 | 向量加载/查询/降级 + `get_search_mode()` |
| `skill/code/web/routes/auth.py` | 修改 | 删除 `/` 路由 |
| `skill/code/web/routes/troubleshoot.py` | 修改 | 新增 `/troubleshoot` 页面 + health 搜索模式 + projects 鉴权 |
| `skill/code/web/server.py` | 修改 | 注册 platform Blueprint |
| `skill/code/web/templates/index.html` | 修改 | 移动端适配 + 返回首页导航 |
| `skill/code/web/templates/login.html` | 修改 | 移动端适配 |
| `skill/code/web/config.json` | 修改 | `embedding_enabled: false` |
| `skill/code/web/container.py` | 修改 | `load_config` 补 embedding 默认值 |
| `skill/code/web/services/record_service.py` | 修改 | 同步重建向量 |
| `skill/code/web/utils/paths.py` | 修改 | `VECTOR_INDEX_FILENAME` |
| `deploy/upload_to_server.py` | 修改 | 补 search_engine.py + DEPLOY_FILES + 更新注释 |
| `skill/code/tests/conftest.py` | 修改 | 向量 fixture + mock |
| `skill/code/tests/test_search_engine.py` | 修改 | +12 向量用例 |
| `skill/code/tests/test_routes_auth.py` | 修改 | TestIndex 适配平台首页 |
| `skill/code/tests/test_routes_troubleshoot.py` | 修改 | projects 拆 3 角色用例 |
| `ARCHITECTURE.md` | **新增** | 技术架构与部署说明 |
| `Docs/PRD_需求文档_P2级功能增强.md` | **新增** | — |
| `Docs/PRD_计划执行_P2级功能增强.md` | **新增** | — |
| `Docs/PRD_需求文档_普通用户项目名称输入限制.md` | **新增** | — |
| `Docs/PRD_计划执行_普通用户项目名称输入限制.md` | **新增** | — |
| `Docs/PRD_需求文档_平台化改造与模块切换.md` | **新增** | — |
| `Docs/PRD_计划执行_平台化改造与模块切换.md` | **新增** | — |

### 常用命令

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

# 部署到 5.60（用 ! 前缀在会话内执行）
! cd "E:/github/ubains-module-test/troubleshoot-ai-assistant/deploy" && SSH_PASSWORD='***' python upload_to_server.py

# 权威验证部署
cd deploy && python verify_deployment.py

# 检查搜索模式
curl -s http://192.168.5.60:8088/api/health | python -c "import sys,json; d=json.load(sys.stdin); print('mode:', d['search']['mode'])"

# 修改用户密码（在 web/ 目录下执行）
python -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('新密码'))"
# 然后替换 users.json 中的 password_hash 字段

# 生成向量文件（暂不执行，需 API 联网）
cd skill/code/web && python -m utils.vector_builder
```

### Git 状态（未提交 — 平台化改造部分）

```
 M deploy/upload_to_server.py
 M skill/code/tests/test_routes_auth.py
 M skill/code/web/routes/auth.py
 M skill/code/web/routes/troubleshoot.py
 M skill/code/web/server.py
 M skill/code/web/templates/index.html
?? ARCHITECTURE.md
?? Docs/PRD_需求文档_平台化改造与模块切换.md
?? Docs/PRD_计划执行_平台化改造与模块切换.md
?? skill/code/web/routes/platform.py
?? skill/code/web/templates/platform.html
?? skill/code/web/utils/modules.py
?? HANDOFF.md
```

### 用户密码信息（待修改）

- admin：当前密码 `Admin@2026` → **改为** `Ubains@1357`
- user：当前密码未知（哈希存储） → **改为** `Ubains@123`
