# HANDOFF 服务管理模块交接文档

> 文档生成时间：2026-07-22
> 分支：troubleshoot-ai-assistant
> 状态：静态页面开发完成

---

## 一、任务概述

开发"服务管理"模块静态页面，参考 `https://192.168.5.44` 统一管理平台的设计风格，实现服务授权、服务升级、服务信息三个子页面。

---

## 二、已完成项

### 2.1 PRD 文档

| 文档 | 路径 | 状态 |
|------|------|------|
| 需求文档 | `Docs/需求文档/服务管理/PRD_需求文档_服务管理模块.md` | ✅ 完成 |
| 执行计划 | `Docs/需求文档/服务管理/PRD_计划执行_服务管理模块.md` | ✅ 完成 |

### 2.2 代码文件

| 文件 | 路径 | 说明 |
|------|------|------|
| 路由文件 | `skill/code/web/routes/service_manage.py` | 三个子页面路由 + 管理员权限校验 |
| 基础模板 | `skill/code/web/templates/service_manage/base.html` | 侧边栏导航 + 顶部栏 + 响应式布局 |
| 服务授权页 | `skill/code/web/templates/service_manage/authorization.html` | 4步骤流程卡片 + 项目信息表单 |
| 服务升级页 | `skill/code/web/templates/service_manage/upgrade.html` | Tab切换 + 服务列表表格 + 批量操作 |
| 服务信息页 | `skill/code/web/templates/service_manage/info.html` | 监控类型筛选 + CPU/内存/硬盘使用率卡片 |

### 2.3 路由测试

```
GET /service-manage/authorization → 200 ✅
GET /service-manage/upgrade       → 200 ✅
GET /service-manage/info          → 200 ✅
```

- 未登录访问：重定向到 `/login`
- 管理员登录后访问：正常渲染页面

---

## 三、页面结构

### 3.1 服务授权 (authorization.html)

**布局**：4个步骤卡片，Grid 响应式排列

| 步骤 | 功能 | 组件 |
|------|------|------|
| 1 | 申请服务授权 | 下载激活文件按钮 + 上传授权文件 |
| 2 | 填写项目信息 | 5字段表单（项目销售、部署人员、下单时间、服务器密码、项目概述） |
| 3 | 填写并提交部署视图 | 下载部署视图 + 上传 |
| 4 | 填写并提交自检文档 | 下载自检文档 + 上传 |

### 3.2 服务升级 (upgrade.html)

**布局**：Tab 切换 + 工具栏 + 服务列表表格

| Tab | 内容 |
|-----|------|
| 服务重启 | 服务列表（服务名称、类型、升级路径、重启脚本路径、操作） |
| 服务回滚 | 服务列表（服务名称、类型、当前版本、回滚版本、操作） |

**工具栏按钮**：
- 下载配置、备份数据库文件、上传更新服务
- 重启已选服务（批量）、下载日志（批量）

### 3.3 服务信息 (info.html)

**布局**：筛选栏 + 3个信息卡片

| 卡片 | 内容 |
|------|------|
| CPU 使用率 | 数值 + 进度条 + 核心数/负载 |
| 内存使用率 | 数值 + 进度条 + 已用/总计 |
| 硬盘使用率 | 数值 + 进度条 + 已用/总计 |

---

## 四、隔离设计

与 `service_monitor` 模块完全隔离：

| 隔离项 | 实现 |
|--------|------|
| 代码隔离 | `routes/service_manage.py` 独立文件，不导入 service_monitor |
| 模板隔离 | `templates/service_manage/` 独立目录 |
| 数据隔离 | 暂无数据存储需求 |

---

## 五、下一步

### 5.1 功能开发（后续迭代）

| 页面 | 待开发功能 |
|------|------------|
| 服务授权 | 下载激活文件、上传授权文件、保存项目信息、上传部署视图、上传自检文档 |
| 服务升级 | 下载配置、备份数据库、上传更新服务、服务重启/回滚、下载日志 |
| 服务信息 | 监控类型筛选、实时数据获取 |

### 5.2 后端服务层

需要创建 `skill/code/web/services/service_manage_service.py`：
- 授权文件处理
- 项目信息存储
- 服务重启/回滚 API 调用
- 监控数据获取

### 5.3 数据存储

可能需要：
- 项目信息存储（JSON 或数据库）
- 服务配置缓存

---

## 六、踩坑警示

### 6.1 模板继承

- 子模板必须使用 `{% extends "service_manage/base.html" %}`（注意路径）
- `base.html` 已定义 `{% block title %}`、`{% block breadcrumb %}`、`{% block content %}`、`{% block extra_css %}`、`{% block extra_js %}`

### 6.2 权限控制

- 所有页面路由使用 `@page_login_required` 装饰器
- 内部检查 `_is_admin()`，非管理员重定向到首页

### 6.3 静态资源

- 当前页面内联 CSS，复用 `service_monitor` 的颜色变量
- 如需添加 JS/CSS 文件，放入 `static/` 目录

---

## 七、相关文档

- [[PRD_需求文档_服务管理模块]]
- [[PRD_计划执行_服务管理模块]]
- [[PRD_需求文档_服务监测模块]]（参考模板结构）