# PRD 需求文档 — 服务管理模块功能升级（服务授权 + 目标配置）

> 版本：1.0 ｜ 日期：2026-08-12 ｜ 分支：troubleshoot-ai-assistant

---

## 1. 需求背景

### 1.1 现状

当前「服务管理」模块仅有 Vue SPA 前端框架，页面内容均为占位符（"开发中，敬请期待"）：

| 页面 | 状态 |
|------|------|
| 服务授权（`/service-manage/authorization`） | 骨架页面，所有功能为空实现 |
| 服务升级（`/service-manage/upgrade`） | 空白页面 |
| 服务信息（`/service-manage/info`） | 空白页面 |
| 操作日志（`/service-manage/logs`） | 空白页面 |

后端 `routes/service_manage.py` 仅有一个空 Blueprint，无任何 API 实现。

### 1.2 目标

对标 5.44 统一管理平台的服务授权流程，在自研平台（5.60:8088）上实现完整的服务授权功能，并新增「目标配置」模块用于管理需要对接的目标服务器。

### 1.3 业务场景

| 场景 | 说明 |
|------|------|
| 服务授权 | 4 步流程：下载激活文件 → 上传授权文件 → 填写项目信息 → 下载部署视图/自检文档 |
| 目标配置 | 配置目标服务器（5.44 等）的连接信息，使授权操作可代理到目标服务器执行 |

---

## 2. 需求概述

### 2.1 服务授权（4 步流程）

整体对标 5.44 平台的授权流程，界面布局沿用当前 4 步卡片设计，但需对接自研后端代理 API。

**流程图：**

```
┌─────────────────────────────────────────────────────────────────┐
│  Step 1: 申请服务授权                                             │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  [📥 下载激活文件]  →  GET /api/service-manage/license/download │ │
│  │  [📤 上传授权文件]  →  POST /api/service-manage/license/upload │ │
│  │  拖拽/点击上传 .zip/.lic/.key 文件                           │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  Step 2: 填写项目信息                                             │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  项目销售 *  │  部署人员 *  │  下单时间 *  │  服务器密码 *  │ │
│  │  项目概述 *  │  [💾 保存]  →  POST /api/service-manage/project │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  Step 3: 填写并提交部署视图                                       │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  [📥 下载部署视图]  →  GET /api/service-manage/deploy-view/download │
│  │  [📤 上传部署视图]  →  POST /api/service-manage/deploy-view/upload │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  Step 4: 填写并提交自检文档                                       │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  [📥 下载自检文档]  →  GET /api/service-manage/self-check/download │
│  │  [📤 上传自检文档]  →  POST /api/service-manage/self-check/upload │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 目标配置（左侧栏新增模块）

在服务管理左侧导航栏新增「目标配置」入口，用于管理对接的目标服务器（如 5.44 统一管理平台）。

**功能：**

| 功能 | 说明 |
|------|------|
| 目标列表 | 展示已配置的目标服务器（名称、地址、端口、状态） |
| 新增目标 | 添加目标服务器 IP、端口、认证凭据 |
| 编辑目标 | 修改目标服务器配置 |
| 删除目标 | 移除目标服务器配置 |
| 连通性测试 | 测试与目标服务器的连接状态 |

**设计说明：** 目标配置复用服务监测模块已有的 `target_service.py` 能力（CRUD + Fernet 加密 + SSH 连接测试），在服务管理模块中新增针对 HTTP API 代理的目标配置类型，主要存储目标服务器的 URL/端口/Token 等连接信息，用于授权 API 代理转发。

---

## 3. API 接口设计

### 3.1 服务授权 API

#### 3.1.1 下载激活文件

```
GET /api/service-manage/license/download
响应：文件流（licences.zip）
```

#### 3.1.2 上传授权文件

```
POST /api/service-manage/license/upload
Content-Type: multipart/form-data
Body: file=license.zip, iszip=true
响应：
{
  "success": true,
  "taskId": "a141b345-xxx",
  "status": "pending"
}
```

#### 3.1.3 查询授权任务状态

```
GET /api/service-manage/license/task-status?taskId=xxx
响应：
{
  "success": true,
  "taskId": "xxx",
  "status": "processing" | "completed" | "failed",
  "message": "正在重新加载配置"
}
```

#### 3.1.4 保存项目信息

```
POST /api/service-manage/project
Body:
{
  "salesPeople": "销售测试",
  "deployer": "部署测试",
  "orderTime": "2026-08-21 00:00:00",
  "serverPassword": "Ubains@123",
  "projectOverview": "项目概述测试内容"
}
响应：
{
  "success": true,
  "message": "设置软件版本成功"
}
```

#### 3.1.5 下载部署视图

```
GET /api/service-manage/deploy-view/download
响应：文件流（deploymentView<timestamp>.xlsx）
```

#### 3.1.6 下载自检文档

```
GET /api/service-manage/self-check/download
响应：文件流（checkList<timestamp>.xlsx）
```

### 3.2 目标配置 API

#### 3.2.1 目标列表

```
GET /api/service-manage/targets
响应：
{
  "success": true,
  "targets": [
    {
      "id": "tgt-xxx",
      "name": "5.44 统一管理平台",
      "host": "192.168.5.44",
      "port": 443,
      "protocol": "https",
      "auth_type": "password",
      "username": "superadmin",
      "has_password": true,
      "connected": true,
      "created_at": "2026-08-12T00:00:00"
    }
  ]
}
```

#### 3.2.2 新增目标

```
POST /api/service-manage/targets
Body:
{
  "name": "5.44 统一管理平台",
  "host": "192.168.5.44",
  "port": 443,
  "protocol": "https",
  "auth_type": "password",
  "username": "superadmin",
  "password": "xxx"
}
响应：{ "success": true, "target": { ... } }
```

#### 3.2.3 更新目标

```
PUT /api/service-manage/targets/:id
响应：{ "success": true, "target": { ... } }
```

#### 3.2.4 删除目标

```
DELETE /api/service-manage/targets/:id
响应：{ "success": true }
```

#### 3.2.5 测试连接

```
POST /api/service-manage/targets/test
Body:
{
  "host": "192.168.5.44",
  "port": 443,
  "protocol": "https",
  "username": "superadmin",
  "password": "xxx"
}
响应：
{
  "success": true,
  "message": "连接成功"
}
```

---

## 4. 前端页面设计

### 4.1 服务授权页面（Authorization.vue）

**当前状态：** 4 步卡片布局已存在，功能为空实现

**需要变更：**

| 卡片 | 当前 | 目标 |
|------|------|------|
| Step 1 | 下载/上传按钮 + 上传区域（空实现） | 对接真实 API，下载激活文件、上传授权文件、轮询任务状态 |
| Step 2 | 表单 + 保存按钮（空实现） | 对接项目信息保存 API，显示成功/失败提示 |
| Step 3 | 下载/上传按钮 + 上传区域（空实现） | 对接部署视图下载/上传 API |
| Step 4 | 下载/上传按钮 + 上传区域（空实现） | 对接自检文档下载/上传 API |

**交互细节：**
- 上传授权文件后显示进度条/状态提示
- 任务处理中禁用其他操作按钮
- 表单字段验证（必填项）
- 下载文件时使用 Blob 处理

### 4.2 目标配置页面（TargetConfig.vue）— 新增

**布局：**
```
┌──────────────────────────────────────────────────────────────┐
│  🎯 目标配置                              [+ 新增目标]      │
├──────────────────────────────────────────────────────────────┤
│  ┌────────────────────────────────────────────────────────┐  │
│  │ 名称           │ 地址          │ 状态    │ 操作        │  │
│  ├────────────────────────────────────────────────────────┤  │
│  │ 5.44 管理平台  │ 192.168.5.44 │ ✅ 在线  │ ✏️ 🗑️ 🔗  │  │
│  │ 5.60 本机      │ 192.168.5.60 │ ✅ 在线  │ ✏️ 🗑️ 🔗  │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

🔗 = 测试连接
```

**新增目标对话框：**
```
┌─ 新增目标 ───────────────────────────────────┐
│  名称 *         [________________________]   │
│  地址 *         [________________________]   │
│  端口 *         [443_____]  协议 [HTTPS ▼]  │
│  认证方式       [密码 ▼]                    │
│  用户名 *       [________________________]   │
│  密码 *         [________________________]   │
│  ┌──────────┐  ┌──────────┐                 │
│  │ 测试连接  │  │    保存  │                 │
│  └──────────┘  └──────────┘                 │
└──────────────────────────────────────────────┘
```

### 4.3 左侧导航栏变更

**ManageLayout.vue 侧边栏菜单新增：**

```
服务管理
├── 🔑 服务授权     → /service-manage/authorization
├── 🎯 目标配置     → /service-manage/targets       ← 新增
├── 🚀 服务升级     → /service-manage/upgrade
├── ℹ️ 服务信息     → /service-manage/info
└── 📝 操作日志     → /service-manage/logs
```

---

## 5. 后端架构设计

### 5.1 整体架构

```
┌──────────────────────────────────────────────────────────────┐
│  Frontend (Vue SPA)                                          │
│  /service-manage/* → 服务管理模块前端页面                     │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTP API
┌──────────────────────▼───────────────────────────────────────┐
│  Backend (Flask)                                              │
│  routes/service_manage.py  ← 服务管理 API 路由层              │
│  services/service_manage/  ← 业务逻辑层（新增）               │
│    ├── license_service.py  ← 授权文件服务（代理/本地）       │
│    ├── project_service.py  ← 项目信息服务                    │
│    └── target_service.py   ← 目标配置服务（可复用监测模块）  │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTP Proxy
┌──────────────────────▼───────────────────────────────────────┐
│  5.44 统一管理平台（目标服务器）                               │
│  /exapi/system/*  → 授权 API                                 │
│  /backstage/exapi/system/*  → 授权后台 API                   │
└──────────────────────────────────────────────────────────────┘
```

### 5.2 关键设计决策

| 决策 | 方案 |
|------|------|
| 授权 API 实现方式 | 后端代理模式：前端请求 → 自研后端 → 转发到配置的目标服务器 |
| 目标配置存储 | 复用 `target_service.py` 的加密存储机制（Fernet），或独立 JSON 文件 |
| 文件上传 | 前端 → 后端暂存 → 转发到目标服务器 |
| 任务状态轮询 | 后端轮询目标服务器，前端通过 SSE 或定时轮询获取状态 |

### 5.3 路由规划

```python
# routes/service_manage.py 新增 API 路由

# 授权相关
/api/service-manage/license/download          # GET  下载激活文件
/api/service-manage/license/upload            # POST 上传授权文件
/api/service-manage/license/task-status       # GET  查询授权任务状态
/api/service-manage/project                   # POST 保存项目信息
/api/service-manage/deploy-view/download      # GET  下载部署视图
/api/service-manage/deploy-view/upload        # POST 上传部署视图
/api/service-manage/self-check/download       # GET  下载自检文档
/api/service-manage/self-check/upload         # POST 上传自检文档

# 目标配置
/api/service-manage/targets                   # GET  目标列表
/api/service-manage/targets                   # POST 新增目标
/api/service-manage/targets/:id               # PUT  更新目标
/api/service-manage/targets/:id               # DELETE 删除目标
/api/service-manage/targets/test              # POST 测试连接
```

---

## 6. 数据类型定义

### 6.1 目标配置类型

```typescript
// frontend/src/types/service-manage.ts

/** 目标服务器配置 */
export interface ManageTarget {
  id: string
  name: string
  host: string
  port: number
  protocol: 'http' | 'https'
  auth_type: 'password' | 'token' | 'none'
  username: string
  has_password: boolean
  connected: boolean
  created_at: string
  updated_at: string
}

/** 新建目标请求 */
export interface CreateManageTargetRequest {
  name: string
  host: string
  port?: number
  protocol?: 'http' | 'https'
  auth_type?: 'password' | 'token' | 'none'
  username?: string
  password?: string
}

/** 测试连接请求 */
export interface TestManageTargetRequest {
  host: string
  port: number
  protocol: 'http' | 'https'
  username?: string
  password?: string
}
```

### 6.2 授权相关类型

```typescript
/** 授权任务状态 */
export interface LicenseTaskStatus {
  taskId: string
  status: 'pending' | 'processing' | 'completed' | 'failed'
  message: string
}

/** 项目信息 */
export interface ProjectInfo {
  salesPeople: string
  deployer: string
  orderTime: string
  serverPassword: string
  projectOverview: string
}
```

---

## 7. 非功能需求

| 需求 | 要求 |
|------|------|
| 权限控制 | 服务授权/目标配置仅管理员可操作（`requiresAdmin: true`） |
| 安全性 | 服务器密码Fernet加密存储，传输使用HTTPS |
| 错误处理 | 统一错误响应格式，前端友好提示 |
| 文件大小限制 | 上传授权文件限制 2048M |
| 任务超时 | 授权任务状态轮询超时 5 分钟 |
| 响应式 | 适配移动端（768px 断点，卡片单列布局） |

---

## 8. 目录结构变更

```
# 新增文件
frontend/src/api/service-manage/             # 服务管理 API 封装
  ├── index.ts                               #   API 索引
  ├── license.ts                             #   授权 API
  ├── project.ts                             #   项目信息 API
  └── target.ts                              #   目标配置 API
frontend/src/types/service-manage.ts         # 服务管理类型定义
frontend/src/views/service-manage/Targets.vue # 目标配置页面

# 修改文件
frontend/src/views/service-manage/Authorization.vue  # 补全功能
frontend/src/layouts/ManageLayout.vue                  # 新增"目标配置"菜单项
frontend/src/router/index.ts                           # 新增目标配置路由
skill/code/web/routes/service_manage.py               # 补全 API 路由
skill/code/web/services/service_manage/               # 新建业务逻辑层（可选目录）

# 数据文件
skill/code/web/service_manage_data/                   # 服务管理数据目录
  ├── targets.json                                    # 目标配置存储
  └── projects.json                                   # 项目信息存储
```

---

## 9. 附录：5.44 平台 API 参考

以下为 5.44 统一管理平台的原生 API，作为自研平台代理实现时的参考。

| 序号 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/exapi/system/downLincenceFile?category=java_python` | POST | 下载激活文件 |
| 2 | `/backstage/exapi/system/uploadLincenceFile` | POST | 上传授权文件（multipart） |
| 3 | `/backstage/exapi/system/licenceTaskStatus?taskId=xxx` | GET | 轮询授权任务状态 |
| 4 | `/exapi/system/setOtherInfo` | POST | 保存项目信息 |
| 5 | `/exapi/system/exportDeployView` | GET | 导出部署视图 |
| 6 | `/exapi/system/exportServiceDetect` | GET | 导出自检文档 |

**认证方式：** JWT Bearer Token + HMAC 签名（`x-sign`、`x-random`、`x-timestamp` 自定义头）