# Troubleshoot助手登录认证需求文档

## 代码路径
- 前端代码：[.claude/skills/Troubleshoot/code/web/templates/index.html]
- 后端代码：[.claude/skills/Troubleshoot/code/web/server.py]
- 配置文件：[.claude/skills/Troubleshoot/code/web/config.json]

## 功能需求

### 功能目标
**目标：** 为问题排查助手添加登录认证功能，防止项目敏感信息泄露，同时区分管理员与普通用户权限，实现差异化管理。

### 背景问题

**当前痛点：**
1. **信息安全隐患**：任何人都可以访问 http://192.168.5.60:8088，查看所有项目的问题排查记录，存在信息泄露风险
2. **缺乏权限控制**：缓存管理、问题入库等功能没有权限限制，普通用户误操作可能影响其他人
3. **无法追溯操作**：缺乏用户身份标识，无法追溯谁提交了哪些问题记录
4. **审计需求**：企业安全合规要求对系统访问进行身份认证和操作审计

**应用场景：**
- 现场实施同事登录后使用问题排查功能
- 管理员可查看缓存统计、清空缓存、导出问题库
- 所有操作可追溯，记录操作人员信息

---

## 需求描述

### 需求一：登录页面与身份认证（1 天）

#### 功能说明

**登录页面：**
- 访问系统时，未登录用户自动跳转到登录页
- 登录页包含：用户名、密码输入框、登录按钮
- 支持记住登录状态（localStorage 或 Cookie）
- 登录失败时显示错误提示

**身份认证方式：**
- 方式一：**本地账号认证（优先实现）**
  - 用户名密码存储在服务器配置文件中（加密存储）
  - 支持管理员和普通用户两种角色
  - 配置文件：`config.json` 或独立的 `users.json`

- 方式二：LDAP/AD 域认证（可选，企业环境）
  - 对接企业 LDAP 服务器
  - 域账号直接登录，无需单独配置

**登录流程：**
1. 用户访问 http://192.168.5.60:8088
2. 后端检查 Session/Token
3. 未登录则重定向到 `/login`
4. 用户输入用户名密码
5. 后端验证通过后生成 Session/Token
6. 重定向到主页，显示用户信息和角色

#### 技术实现

**后端实现：**
- 使用 Flask-Login 管理用户会话
- Session 存储在服务器端（内存或 Redis）
- 密码使用 `werkzeug.security` 进行哈希加密
- 登录成功后返回 Session Cookie

**前端实现：**
- 独立的登录页面 `login.html`
- 登录成功后保存 Token 到 localStorage
- 每次请求携带 Token（Header 或 Cookie）

#### 用户角色与权限

| 角色 | 权限 |
|------|------|
| **管理员** | - 问题排查（全部功能）<br>- 缓存管理（查看统计、清除缓存）<br>- 问题入库<br>- 导出功能<br>- 查看审计日志 |
| **普通用户** | - 问题排查（基础功能）<br>- 导出功能<br>- 提交问题记录（需填写记录人）<br>- 无缓存管理权限 |

#### 验收标准

- [x] 未登录用户访问系统自动跳转到登录页
- [x] 输入正确用户名密码可成功登录
- [x] 输入错误密码显示"用户名或密码错误"
- [x] 登录后显示当前用户信息（用户名、角色）
- [x] 关闭浏览器后重新打开仍保持登录状态（记住登录）
- [x] 管理员可以看到"缓存管理"按钮，普通用户看不到
- [x] 点击"退出"按钮可注销登录

---

### 需求二：权限控制与审计日志（0.5 天）

#### 功能说明

**权限控制：**
- 后端接口根据用户角色进行权限验证
- 无权限访问时返回 403 Forbidden
- 前端根据用户角色显示/隐藏功能按钮

**权限控制清单：**

| 接口 | 管理员 | 普通用户 |
|------|--------|----------|
| `/api/troubleshoot` | ✅ 允许 | ✅ 允许 |
| `/api/search` | ✅ 允许 | ✅ 允许 |
| `/api/analyze` | ✅ 允许 | ✅ 允许 |
| `/api/export` | ✅ 允许 | ✅ 允许 |
| `/api/submit` | ✅ 允许 | ✅ 允许（需记录人） |
| `/api/cache/stats` | ✅ 允许 | ❌ 禁止 |
| `/api/cache/clear` | ✅ 允许 | ❌ 禁止 |
| `/api/audit/logs` | ✅ 允许 | ❌ 禁止 |

**审计日志：**
- 记录所有敏感操作：登录、缓存清除、问题入库、导出
- 日志字段：时间、用户、操作类型、操作对象、IP 地址、结果
- 管理员可查看审计日志（Web 界面或日志文件）

#### 审计日志格式

```json
{
  "timestamp": "2026-07-12T15:30:00",
  "user": "zhangsan",
  "role": "admin",
  "action": "clear_cache",
  "detail": "清除所有缓存",
  "ip": "192.168.5.100",
  "result": "success",
  "cleared_count": 15
}
```

#### 验收标准

- [x] 普通用户访问 `/api/cache/*` 接口返回 403 错误
- [x] 管理员访问 `/api/cache/*` 接口正常返回数据
- [x] 前端根据角色显示/隐藏"缓存管理"按钮
- [x] 所有敏感操作记录到审计日志
- [x] 审计日志包含用户信息、操作类型、时间、IP 地址

---

### 需求三：用户管理界面（0.5 天）

#### 功能说明

**管理员功能：**
- 查看当前所有用户列表
- 添加新用户（用户名、密码、角色）
- 修改用户密码
- 禁用/启用用户账号
- 查看用户登录历史

**用户管理页面：**
- 访问路径：`/admin/users`（仅管理员可访问）
- 显示用户列表：用户名、角色、创建时间、最后登录时间、状态
- 提供添加用户、修改密码、禁用账号的操作按钮

#### 验收标准

- [x] 管理员可访问用户管理页面
- [x] 可添加新用户并指定角色
- [x] 可修改用户密码
- [x] 可禁用用户账号（禁用后无法登录）
- [x] 普通用户无法访问用户管理页面

---

## 技术方案

### 认证方案对比

| 方案 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
| **Session Cookie** | 简单、成熟、服务器端控制 | 需要服务器存储 Session | 小型系统，用户数少（推荐） |
| **JWT Token** | 无状态、跨域支持好 | Token 泄露风险、续期复杂 | 微服务、移动端 |
| **LDAP/AD** | 企业统一认证、安全 | 依赖外部系统、配置复杂 | 企业内部系统 |

**推荐方案：** Session Cookie（优先），后续可扩展支持 LDAP

---

## 默认账号配置

### 初始管理员账号

| 字段 | 值 |
|------|------|
| 用户名 | admin |
| 密码 | Admin@2026 |
| 角色 | admin |
| 说明 | 首次部署后建议立即修改密码 |

### 配置文件格式

**users.json（加密存储）：**
```json
{
  "users": [
    {
      "username": "admin",
      "password_hash": "pbkdf2:sha256:...",
      "role": "admin",
      "created_at": "2026-07-12T15:00:00",
      "last_login": "2026-07-12T15:30:00",
      "active": true
    },
    {
      "username": "zhangsan",
      "password_hash": "pbkdf2:sha256:...",
      "role": "user",
      "created_at": "2026-07-12T16:00:00",
      "last_login": null,
      "active": true
    }
  ]
}
```

---

## 安全要求

1. **密码加密存储**：使用 `pbkdf2:sha256` 算法，迭代次数 ≥ 260000
2. **防止暴力破解**：登录失败 5 次后锁定账号 15 分钟
3. **Session 过期**：Session 有效期 24 小时，超时自动注销
4. **HTTPS**：建议部署到 HTTPS 环境（可选，生产环境推荐）
5. **审计日志保护**：审计日志文件权限设为仅管理员可读写

---

## 用户界面设计

### 登录页面布局

```
┌─────────────────────────────────────┐
│        🔐 问题排查助手登录          │
│                                     │
│  用户名：[___________________]      │
│                                     │
│  密  码：[___________________]      │
│                                     │
│  □ 记住登录状态                     │
│                                     │
│        [ 🔑 登  录 ]                │
│                                     │
│  提示：默认账号 admin/Admin@2026    │
└─────────────────────────────────────┘
```

### 主页用户信息区域

```
┌─────────────────────────────────────┐
│ 用户：admin（管理员）  [退出]       │
└─────────────────────────────────────┘
```

---

## 规范文档
- 代码规范: `Docs/PRD/01规范文档/_PRD_规范文档_代码规范.md`
- 文档规范: `Docs/PRD/01规范文档/_PRD_规范文档_文档规范.md`

## 优化功能回填
- [ ] 支持 LDAP/AD 域认证
- [ ] 双因素认证（2FA）
- [ ] 登录验证码（防止机器人）
- [ ] 密码强度检测
- [ ] 用户自助修改密码功能
- [ ] 登录历史查看（用户侧）