# PRD — 平台版本号与操作日志子模块

> 版本：1.0 ｜ 日期：2026-07-29 ｜ 作者：czj

---

## 1. 背景

当前运行维护平台已完成 Vue 前端迁移，包含三个功能模块：
- **问题排查助手**：问题搜索、AI 分析
- **服务监测**：目标管理、巡检执行、报告查看、定时任务、通知配置
- **服务管理**：服务授权、服务升级、服务信息

平台存在以下缺失：
1. **无版本号显示**：用户无法直观了解当前系统版本
2. **操作日志分散**：后端已有 `log_audit()` 记录操作，但前端无可视化界面查看各模块的操作历史

## 2. 需求目标

### 2.1 平台版本号

- 在平台导航栏右侧显示当前版本号
- 版本号来源：前端 `package.json` 的 `version` 字段
- 支持版本号点击跳转到更新日志（可选）

### 2.2 操作日志子模块

为三个模块各自增加「操作日志」页面：

| 模块 | 路由 | 记录的操作 |
|------|------|------------|
| 问题排查 | `/troubleshoot/logs` | 搜索、分析、导出、入库 |
| 服务监测 | `/service-monitor/logs` | 目标创建/编辑/删除、巡检执行、报告导出、定时任务配置、通知配置变更 |
| 服务管理 | `/service-manage/logs` | 授权变更、升级操作、信息查询 |

**操作日志字段**：
- 操作时间
- 操作用户
- 操作类型（搜索/分析/导出/入库/创建/编辑/删除/执行等）
- 操作对象（目标名称/报告ID/关键字等）
- 操作详情（JSON 展开，可选）
- IP 地址

## 3. 功能规格

### 3.1 版本号显示

**位置**：导航栏右侧，用户名左侧

**样式**：
```
运行维护平台                    v0.1.0    admin  [退出]
```

**交互**：
- 版本号以小标签形式显示（类似 GitHub release tag）
- 鼠标悬停显示完整版本信息（如构建时间）
- 点击跳转到 `/changelog` 页面或弹出更新日志对话框（P2 优先级）

### 3.2 操作日志页面

**通用布局**（三个模块一致）：
```
┌─────────────────────────────────────────────────────────────┐
│ 操作日志                                        [筛选] [刷新] │
├─────────────────────────────────────────────────────────────┤
│ 时间范围: [今天 ▼]  操作类型: [全部 ▼]  用户: [全部 ▼]       │
├─────────────────────────────────────────────────────────────┤
│ 操作时间          │ 用户   │ 操作类型 │ 操作对象  │ IP       │
├─────────────────────────────────────────────────────────────┤
│ 2026-07-29 10:30 │ admin  │ 搜索    │ 数据库连接 │ 192...  │
│ 2026-07-29 10:25 │ admin  │ 分析    │ 服务启动慢 │ 192...  │
│ ...                                                       │
├─────────────────────────────────────────────────────────────┤
│                                   < 1 2 3 4 5 ... 10 >     │
└─────────────────────────────────────────────────────────────┘
```

**筛选条件**：
- 时间范围：今天 / 最近7天 / 最近30天 / 自定义
- 操作类型：下拉选择（根据模块动态显示）
- 操作用户：下拉选择（从用户列表获取）

**表格列**：
| 列名 | 说明 | 宽度 |
|------|------|------|
| 操作时间 | `YYYY-MM-DD HH:mm` 格式 | 150px |
| 用户 | 操作人用户名 | 100px |
| 操作类型 | 搜索/分析/导出/入库/创建/编辑/删除/执行 | 100px |
| 操作对象 | 简短描述（可点击展开详情） | 自适应 |
| IP | 客户端 IP 地址 | 120px |
| 操作 | 查看详情按钮 | 80px |

**详情弹窗**：
点击「查看详情」按钮，弹出对话框展示完整操作记录（JSON 格式化显示）。

### 3.3 后端 API

#### 新增接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/version` | GET | 获取平台版本号 |
| `/api/audit/logs` | GET | 分页查询操作日志 |
| `/api/audit/users` | GET | 获取有操作记录的用户列表 |

#### `/api/version` 响应

```json
{
  "version": "0.1.0",
  "buildTime": "2026-07-28T15:30:00Z",
  "name": "troubleshoot-frontend"
}
```

#### `/api/audit/logs` 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| module | string | 是 | 模块名：troubleshoot/monitor/manage |
| page | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页条数，默认 20 |
| startTime | string | 否 | 开始时间 ISO 格式 |
| endTime | string | 否 | 结束时间 ISO 格式 |
| actionType | string | 否 | 操作类型筛选 |
| user | string | 否 | 用户筛选 |

#### `/api/audit/logs` 响应

```json
{
  "success": true,
  "data": {
    "total": 150,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": 1,
        "timestamp": "2026-07-29T10:30:00Z",
        "user": "admin",
        "module": "troubleshoot",
        "action": "search",
        "target": "数据库连接失败",
        "ip": "192.168.5.100",
        "details": {"query": "数据库连接", "results": 5}
      }
    ]
  }
}
```

## 4. 数据模型

### 4.1 审计日志存储

**现有方式**：追加写入 `web/audit.log` 文件，每行一条 JSON 记录。

**优化方案**：
- 保持文件追加方式（简单可靠）
- 新增模块字段 `module` 用于区分
- 新增字段：`id`（自增）、`target`（操作对象摘要）

**日志记录示例**：

```json
{
  "id": 1001,
  "timestamp": "2026-07-29T10:30:00Z",
  "user": "admin",
  "module": "troubleshoot",
  "action": "search",
  "target": "数据库连接失败",
  "ip": "192.168.5.100",
  "details": {...}
}
```

### 4.2 模块操作类型定义

| 模块 | 操作类型 | action 值 |
|------|----------|-----------|
| troubleshoot | 搜索 | search |
| troubleshoot | 分析 | analyze |
| troubleshoot | 导出 | export |
| troubleshoot | 入库 | submit |
| monitor | 创建目标 | create_target |
| monitor | 编辑目标 | edit_target |
| monitor | 删除目标 | delete_target |
| monitor | 执行巡检 | run_check |
| monitor | 导出报告 | export_report |
| monitor | 创建定时任务 | create_schedule |
| monitor | 编辑定时任务 | edit_schedule |
| monitor | 删除定时任务 | delete_schedule |
| monitor | 配置通知 | config_notification |
| manage | 授权变更 | auth_change |
| manage | 升级操作 | upgrade |
| manage | 信息查询 | query_info |

## 5. 非功能需求

| 项目 | 要求 |
|------|------|
| 性能 | 日志查询响应时间 < 500ms（10000 条以内） |
| 兼容性 | Chrome 90+、Edge 90+、Firefox 88+、移动端响应式 |
| 安全 | 仅登录用户可查看日志，管理员可查看所有用户日志 |
| 存储 | 日志文件按月归档，保留 6 个月 |

## 6. 实现优先级

### P0（核心功能）

- [ ] 版本号显示
- [ ] 操作日志 API（`/api/audit/logs`）
- [ ] 问题排查模块操作日志页面

### P1（完整功能）

- [ ] 服务监测模块操作日志页面
- [ ] 服务管理模块操作日志页面
- [ ] 日志详情弹窗
- [ ] 筛选功能

### P2（增强功能）

- [ ] 版本号点击显示更新日志
- [ ] 日志导出功能
- [ ] 日志统计图表

## 7. 验收标准

1. 导航栏正确显示版本号（与 package.json 一致）
2. 三个模块均能访问操作日志页面
3. 操作日志实时记录用户操作（搜索、分析、导出等）
4. 日志筛选功能正常工作
5. 详情弹窗正确展示完整日志记录
6. 移动端响应式布局正常

## 8. 风险与依赖

| 风险 | 缓解措施 |
|------|----------|
| 日志文件过大影响性能 | 按月归档 + 分页查询 |
| 版本号更新遗漏 | 构建脚本自动注入 |
| 操作类型遗漏 | 后端统一常量定义 |
