# PRD_计划执行_平台化改造与模块切换

## 1. 项目概述

### 1.1 背景

当前站点是单功能"问题排查 AI 助手"，访问 `/` 直接进入排查页面。需升级为多模块平台：新增平台首页展示模块卡片，问题排查助手降级为其中一个模块入口（`/troubleshoot`），后续可按需接入其他维护模块。

### 1.2 目标

| 目标编号 | 描述 | 优先级 |
|---------|------|--------|
| 1 | 模块注册机制 `modules.py` | 🟠 高 |
| 2 | 平台首页 `/`（模块卡片） | 🟠 高 |
| 3 | 排查助手路由迁移 `/` → `/troubleshoot` | 🟠 高 |
| 4 | 排查助手页加返回首页导航 | 🟡 中 |

### 1.3 开发周期

预估 5.5 小时（约 1 个工作日）。

---

## 2. 技术方案

### 2.1 模块注册机制（`utils/modules.py`，新增）

集中声明模块清单，提供 `get_modules(role=None)` 查询函数：

```python
"""modules.py — 平台模块注册

集中声明平台所有可用模块，供首页渲染和路由使用。
新增模块只需在此文件追加声明 + 注册 Blueprint，不改首页代码。
"""

from flask import session

# ============================================================
# 模块清单（声明式）
# ============================================================

MODULES = [
    {
        "id": "troubleshoot",
        "name": "问题排查助手",
        "icon": "🔍",
        "description": "基于历史知识库的 AI 问题排查，357 条记录",
        "url": "/troubleshoot",
        "enabled": True,
        "roles": [],      # 空 = 所有登录用户可访问
        "sort": 1,
    },
    {
        "id": "service-monitor",
        "name": "服务监控",
        "icon": "📊",
        "description": "服务器与服务运行状态监控、告警通知",
        "url": "/service-monitor",
        "enabled": False,   # 预留，未上线
        "roles": ["admin"],
        "sort": 2,
    },
    # 后续模块在此追加
]


def get_modules(role=None):
    """获取可用模块列表。

    参数：
      role: 用户角色（None=不过滤，返回全部启用模块）

    返回：
      按 sort 排序的模块列表
    """
    result = []
    for m in MODULES:
        if not m.get("enabled", True):
            continue
        if role is not None and m.get("roles") and role not in m["roles"]:
            continue
        result.append(m)
    result.sort(key=lambda x: x.get("sort", 99))
    return result
```

**关键约束**：
- 模块声明集中在此文件，不散落各处
- `roles` 为空表示所有登录用户可访问（不限制）
- `enabled: False` 的模块不展示（预留但未上线）

### 2.2 平台首页路由（`routes/platform.py`，新增）

```python
"""platform.py — 平台首页路由"""

from flask import Blueprint, render_template, session, redirect, url_for
from decorators import page_login_required
from utils.modules import get_modules

bp = Blueprint('platform', __name__)


@bp.route('/')
def index():
    """平台首页 — 模块列表"""
    user = session.get('user')
    if not user:
        return redirect(url_for('auth.login'))

    role = user.get('role', '')
    modules = get_modules(role=role)

    return render_template('platform.html',
        modules=modules,
        user=user,
        platform_name="运维辅助平台",
    )
```

### 2.3 平台首页模板（`templates/platform.html`，新增）

独立模板，风格与现有 `index.html` / `login.html` 一致（渐变背景 + 卡片布局）：

```html
<!-- platform.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=5">
    <title>{{ platform_name }}</title>
    <style>
        /* 复用 login/index 的设计系统变量 + 渐变背景 */
        /* 模块卡片网格：桌面 3 列、平板 2 列、手机 1 列 */
        /* 触控热区 ≥44px */
    </style>
</head>
<body>
    <!-- 顶部：平台标题 + 用户信息 + 退出 -->
    <!-- 主体：模块卡片网格 -->
    <!-- 每个卡片：图标 + 名称 + 描述 + "进入" 按钮 -->
    <!-- 空状态：暂无可用模块 -->
</body>
</html>
```

### 2.4 排查助手路由迁移

#### 2.4.1 `routes/auth.py` 改动

原 `auth.py` 的 `index` 路由（`/` 重定向到 `/login` 或渲染 `index.html`）需移除或改为重定向到 `/troubleshoot`。

实际上 `/` 现在由 `platform.py` 接管，`auth.py` 的 `index` 路由删除即可。

#### 2.4.2 `routes/troubleshoot.py` 改动

新增 `/troubleshoot` 页面路由（渲染 `index.html`）：

```python
@bp.route('/troubleshoot')
def troubleshoot_page():
    """排查助手主页"""
    return render_template('index.html')
```

#### 2.4.3 `templates/index.html` 改动

顶部用户信息栏增加"返回首页"链接：

```html
<a href="/" class="back-home">🏠 返回首页</a>
```

### 2.5 `server.py` 改动

注册 `platform` Blueprint：

```python
from routes.platform import bp as platform_bp
app.register_blueprint(platform_bp)
```

### 2.6 测试方案

| 模块 | 用例 | 覆盖点 |
|------|------|--------|
| `test_routes_auth.py` | 修改 | `/` 不再重定向到 `/login`（由 platform 接管） |
| `test_routes_troubleshoot.py` | 新增 | `GET /troubleshoot` 返回 200 |
| `test_routes_platform.py` | 新增 | `/` 未登录跳 `/login`；已登录返回模块卡片；角色过滤 |
| `test_modules.py` | 新增 | `get_modules()` 角色过滤 / enabled 过滤 / sort 排序 |

---

## 3. 实施计划

### 3.1 任务分解

| 序号 | 任务 | 预计时间 | 状态 | 依赖 |
|------|------|---------|------|------|
| 1 | `utils/modules.py` 模块注册 | 0.5h | 待开始 | — |
| 2 | `routes/platform.py` 平台首页路由 | 0.5h | 待开始 | 1 |
| 3 | `templates/platform.html` 平台首页模板 | 1.5h | 待开始 | 2 |
| 4 | 排查助手路由迁移 `/` → `/troubleshoot` | 0.5h | 待开始 | 2 |
| 5 | `templates/index.html` 加返回首页导航 | 0.5h | 待开始 | 4 |
| 6 | `server.py` 注册 platform Blueprint | 0.5h | 待开始 | 2 |
| 7 | 测试用例更新 + 新增 | 1h | 待开始 | 4, 5, 6 |
| 8 | 部署 + 验证 | 0.5h | 待开始 | 7 |

---

## 4. 测试验证

### 4.1 验证项

| 验收项 | 标准 | 实测 |
|--------|------|------|
| `/` 显示模块卡片 | 登录后看到"问题排查助手"卡片 | — |
| 卡片点击进入模块 | 跳转到 `/troubleshoot` | — |
| `/troubleshoot` 显示排查助手 | 原有功能全部正常 | — |
| 返回首页 | 排查助手页顶部有"返回首页"链接 | — |
| 角色过滤 | 普通用户/管理员看到各自模块 | — |
| 未登录 | `/` 跳 `/login` | — |
| 移动端 | 首页卡片单列/多列自适应 | — |
| API 不变 | `/api/*` 全部正常 | — |

### 4.2 回归测试

- [ ] 145 用例全绿（路由变更需同步改测试 fixture）
- [ ] 排查助手全流程手动验证

### 4.3 端到端验证

```bash
# 1. 首页验证
curl -s http://192.168.5.60:8088/ -o /dev/null -w "%{http_code}"
# 期望：302（未登录跳 /login）

# 2. 登录后访问首页
# 期望：看到模块卡片

# 3. 排查助手验证
curl -s http://192.168.5.60:8088/api/health
# 期望：ok, 357 记录

# 4. 浏览器验证
# 登录 → 首页 → 点击"问题排查助手" → 排查页面 → 返回首页
```

---

## 5. 执行记录

### 5.1 执行日志

| 日期 | 任务 | 执行人 | 结果 | 备注 |
|------|------|--------|------|------|
| — | — | — | — | 待执行 |

### 5.2 问题记录

| 日期 | 问题 | 解决方案 | 状态 |
|------|------|---------|------|
| — | — | — | — |

---

## 6. 注意事项

1. **路由冲突**：`platform.py` 注册 `/`，`auth.py` 原有 `/` 路由必须删除，否则 Flask 报 `AssertionError: duplicate route`
2. **Blueprint 注册顺序**：`platform` Blueprint 需在 `auth` 之前注册（或确保 `/` 只定义一次）
3. **前端 API 路径不变**：排查助手 JS 中所有 `/api/...` 是绝对路径，不受主页路径迁移影响
4. **测试 fixture 更新**：`conftest.py` 的 `app` fixture 创建的 test client 需适配新路由（`/` 不再是排查助手主页）
5. **部署清单同步**：新增 `modules.py` / `platform.py` / `platform.html` 需加入 `upload_to_server.py`

---

## 7. 相关文档

- [PRD_需求文档_平台化改造与模块切换](PRD_需求文档_平台化改造与模块切换.md) — 本项目需求文档
- [PRD_需求文档_P2级功能增强](PRD_需求文档_P2级功能增强.md) — P2 背景
