# PRD_需求文档_平台化改造与模块切换

## 基本信息

| 项目 | 内容 |
|------|------|
| 文档类型 | 需求文档 |
| 创建日期 | 2026-07-14 |
| 最后更新 | 2026-07-14 |
| 负责人 | 研发组（Claude 协助） |
| 优先级 | P2 🟠 |
| 状态 | 待开始 |

---

## 一、背景与目标

### 1.1 问题背景

当前「问题排查 AI 助手」是一个独立单功能站点：访问 `/` 直接进入排查助手主页面。平台后续将承载**多个维护类模块**（不仅限于问题知识助手），需要把现有站点升级为一个可扩展的**多模块平台**，问题排查助手降级为其中一个模块。

| 序号 | 现状 | 问题 |
|------|------|------|
| 1 | `/` 直接是排查助手主页 | 无法承载多模块，新模块无入口 |
| 2 | 站点定位是"问题排查助手" | 与"运维平台"定位不符，扩展性差 |
| 3 | 无模块切换机制 | 多模块并存时用户无法在模块间导航 |

### 1.2 修复目标

1. **新增平台首页** `/`：作为统一入口，以卡片/列表形式展示所有可用模块，点击进入对应模块
2. **问题排查助手降级为模块**：原 `/` 主页迁移到 `/troubleshoot`，首页改为模块列表
3. **预留服务监控模块**：在模块清单中声明"服务监控"模块（`enabled: false`，仅管理员可见），为后续接入预留入口
4. **建立模块注册机制**：通过配置声明模块清单，首页动态渲染，便于后续接入新模块
5. **共用服务与认证**：所有模块共用同一 Flask 服务、用户认证、缓存管理，各模块独立路由与页面
6. **保持现有功能零回归**：问题排查助手的搜索/AI 分析/提交/导出/缓存管理等全部功能不变，仅路径调整

### 1.3 范围说明

- 本次**只建框架**，先接入"问题排查助手"一个模块，**预留"服务监控"模块**（`enabled: false`），后续按需接入
- 不涉及微服务拆分，全部在现有 Flask 服务内通过路由隔离实现

---

## 二、需求详情

### 2.1 模块注册机制

#### 2.1.1 需求规格

平台通过配置声明模块清单，首页动态渲染卡片。模块清单字段：

| 字段 | 说明 | 示例 |
|------|------|------|
| `id` | 模块唯一标识 | `troubleshoot` |
| `name` | 模块显示名 | `问题排查助手` |
| `icon` | 模块图标（emoji 或图标类） | `🔍` |
| `description` | 模块一句话描述 | `基于历史知识库的 AI 问题排查` |
| `url` | 模块入口路径 | `/troubleshoot` |
| `enabled` | 是否启用 | `true` |
| `roles` | 允许访问的角色（空=所有登录用户） | `[]` |
| `sort` | 排序权重 | `1` |

#### 2.1.2 实现方式

- 在 `config.json` 新增 `modules` 数组，或新建 `utils/modules.py` 集中声明（推荐后者，便于扩展）
- 首页通过 `get_modules()` 读取清单并渲染卡片

#### 2.1.3 验收标准

- [ ] 模块清单可通过配置增删
- [ ] `enabled: false` 的模块不在首页展示
- [ ] 模块按 `sort` 排序展示

---

### 2.2 平台首页（新增）

#### 2.2.1 需求规格

| 项 | 规格 |
|----|------|
| 路径 | `/`（覆盖原排查助手主页） |
| 访问控制 | 登录后可见（未登录跳 `/login`） |
| 页面内容 | 顶部：平台标题 + 用户信息 + 退出；主体：模块卡片网格 |
| 卡片内容 | 图标 + 模块名 + 描述 + "进入"按钮 |
| 卡片点击 | 跳转到模块 `url` |
| 角色过滤 | 按 `modules[].roles` 过滤当前用户可见模块 |
| 响应式 | 移动端单列、桌面多列（沿用 P2-2 断点策略） |
| 空状态 | 无可用模块时显示"暂无可用模块"提示 |

#### 2.2.2 验收标准

- [ ] 访问 `/` 显示模块列表（非排查助手主页）
- [ ] 未登录跳转 `/login`
- [ ] 卡片点击进入对应模块
- [ ] 移动端响应式正常
- [ ] 普通用户/管理员看到各自有权限的模块

---

### 2.3 问题排查助手降级为模块

#### 2.3.1 路径调整

| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `/`（排查助手主页） | `/troubleshoot` | 排查助手主页迁移 |
| `/login` `/logout` | `/login` `/logout` | 不变（平台级认证） |
| `/api/*` | `/api/*` | 不变（API 路径保持） |

#### 2.3.2 需求规格

- 排查助手主页路由从 `/` 改为 `/troubleshoot`
- 排查助手页面顶部增加"返回平台首页"入口（链接到 `/`）
- 排查助手所有功能（搜索/分析/提交/导出/缓存）**零变更**
- 前端 JS 中的 API 调用路径（相对路径 `/api/...`）**无需改**

#### 2.3.3 验收标准

- [ ] `/troubleshoot` 正常显示排查助手主页
- [ ] `/` 显示平台首页（非排查助手）
- [ ] 排查助手全部功能正常（搜索/AI 分析/提交/导出/缓存）
- [ ] 排查助手页面有返回首页入口

---

### 2.4 平台导航

#### 2.4.1 需求规格

- 排查助手（及后续模块）页面顶部增加统一导航：平台名 + "返回首页"链接
- 首页顶部：平台标题 + 用户信息 + 退出（沿用现有用户信息栏样式）

#### 2.4.2 验收标准

- [ ] 各模块页可一键返回平台首页
- [ ] 平台标题一致

---

## 三、影响范围

### 3.1 涉及文件

| 文件 / 目录 | 变更类型 | 说明 |
|------------|---------|------|
| `web/utils/modules.py` | 新增 | 模块清单声明 + `get_modules()` |
| `web/routes/platform.py` | 新增 | 平台首页路由 `/` |
| `web/routes/auth.py` | 修改 | `/` 重定向改为 `/troubleshoot` 之外的处理（或交由 platform 路由） |
| `web/routes/troubleshoot.py` 或 server.py | 修改 | 排查助手主页路由 `/` → `/troubleshoot` |
| `web/templates/platform.html` | 新增 | 平台首页模板（模块卡片） |
| `web/templates/index.html` | 修改 | 顶部加"返回首页"导航 |
| `web/config.json` | 修改 | 可选：模块配置（若用配置驱动） |
| `deploy/upload_to_server.py` | 修改 | 上传清单补新文件 |

### 3.2 风险评估

| 风险项 | 等级 | 缓解措施 |
|--------|------|---------|
| 原 `/` 路径行为变化，外部书签失效 | 🟠 中 | `/troubleshoot` 与原 `/` 行为一致；老用户从首页点入即可 |
| 排查助手前端 JS 路径依赖 | 🟡 低 | API 用相对路径 `/api/...`，不随主页路径变化 |
| 认证流程受影响 | 🟡 低 | `/login` 不变，首页加 `@page_login_required` |
| 移动端首页布局 | 🟡 低 | 复用 P2-2 断点策略 |

---

## 四、非功能需求

| 项 | 要求 |
|----|------|
| 扩展性 | 新增模块只需在 `modules.py` 声明 + 注册路由，不改首页代码 |
| 兼容性 | 排查助手功能零回归；现有测试用例保持全绿 |
| 性能 | 首页轻量，无额外 API 调用（模块清单内存读取） |
| 安全 | 首页需登录；模块按角色过滤 |
| 可维护性 | 模块声明集中管理，不散落各处 |

---

## 五、时间估算

| 任务 | 工时 |
|------|------|
| 模块注册机制 `modules.py` | 0.5h |
| 平台首页路由 + 模板 | 2h |
| 排查助手路由迁移 `/` → `/troubleshoot` | 0.5h |
| 排查助手页加返回首页导航 | 0.5h |
| 移动端适配首页 | 1h |
| 测试 + 部署 | 1h |
| **合计** | **5.5h** |

---

## 六、验收清单

### 模块注册
- [ ] `modules.py` 声明模块清单
- [ ] `get_modules()` 支持角色过滤

### 平台首页
- [ ] `/` 显示模块卡片列表
- [ ] 未登录跳 `/login`
- [ ] 卡片点击进入模块
- [ ] 移动端响应式

### 排查助手降级
- [ ] `/troubleshoot` 显示排查助手主页
- [ ] 排查助手全部功能正常
- [ ] 页面有返回首页入口

### 测试与部署
- [ ] 现有 145 用例全绿（路由变更需同步改测试）
- [ ] 部署到 5.60 验证

---

## 维护记录

| 日期 | 更新内容 | 更新人 |
|------|---------|--------|
| 2026-07-14 | 初版创建 | 研发组 |
