# 系统配置

> 模块编码：system
> 端侧：Web专属（仅超级管理员）
> 关联文档：01-模块划分 §2.3 / 02-功能清单-超级管理员 §3 / 03-业务流转逻辑-超级管理员 §9 / 05-接口规范 §9.2 / 06-项目技术要求 §8.3~8.4
> 强制规范遵循 `07-前端界面开发规范.md`

## 功能概览

| 项目 | 说明 |
|------|------|
| 菜单名称 | 系统配置 |
| 子菜单 | 系统版本管理、缓存管理 |
| 功能编号 | SA-S-01 ~ SA-S-02 |
| 权限编码前缀 | system:version:* / system:cache:* |

---

## 页面1：系统版本管理页

**页面编号**：SA-S-01-P01
**端侧归属**：Web专属
**页面路径**：/system/versions

### 界面布局

```
┌──────────────────────────────────────────────────────────────────┐
│ [面包屑] 系统配置 > 系统版本管理                                    │
├──────────────────────────────────────────────────────────────────┤
│ [当前版本信息卡片]                                                 │
│ ┌──────────────────────┐  ┌──────────────────────┐              │
│ │ 管理后台版本           │  │ 小程序版本             │              │
│ │ 当前版本：v1.2.0       │  │ 当前版本：v1.1.0       │              │
│ │ 最低兼容：v1.0.0       │  │ 最低兼容：v1.0.0       │              │
│ │ 发布日期：2026-04-01   │  │ 发布日期：2026-03-15   │              │
│ └──────────────────────┘  └──────────────────────┘              │
├──────────────────────────────────────────────────────────────────┤
│ [操作栏]  [新增版本]                                              │
├──────────────────────────────────────────────────────────────────┤
│ [列表区]                                                          │
│ 序号 | 版本号 | 端侧 | 最低兼容版本 | 是否强制更新 | 发布日期 | 操作 │
│ 1    | v1.2.0 | Web   | v1.0.0      | 否           | 2026-04-01| 编辑│
│ 2    | v1.1.0 | 小程序 | v1.0.0      | 否           | 2026-03-15| 编辑│
│ 3    | v1.0.0 | 小程序 | v1.0.0      | 是           | 2026-01-01| —   │
├──────────────────────────────────────────────────────────────────┤
│ [分页]  共5条                                                     │
└──────────────────────────────────────────────────────────────────┘
```

### 查询条件

| 字段名 | 控件类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| — | — | — | — | 无筛选条件，展示全部版本 |

### 列表字段

| 序号 | 字段名 | 列宽 | 支持排序 | 说明 |
|------|--------|------|----------|------|
| 1 | 序号 | 60px | — | 自增 |
| 2 | 版本号 | 100px | 是 | 语义化版本号 |
| 3 | 端侧 | 80px | 否 | Web/小程序 |
| 4 | 最低兼容版本 | 120px | 否 | 低于此版本需强制更新 |
| 5 | 是否强制更新 | 110px | 否 | 是(红色)/否(绿色) |
| 6 | 发布日期 | 120px | 是 | 默认倒序 |
| 7 | 更新说明 | 200px | 否 | 简述本次更新内容 |
| 8 | 操作 | 80px | — | 编辑 |

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 新增版本 | system:version:create | 操作栏 | 始终 | 弹窗 |
| 编辑 | system:version:update | 行操作 | 始终 | 弹窗 |

### 表单字段（新增/编辑弹窗）

| 字段名 | 控件类型 | 必填 | 默认值 | 数据来源 | 校验规则 |
|--------|----------|------|--------|----------|----------|
| 版本号 | 文本输入 | 是 | — | 自填 | 语义化版本格式(x.y.z) |
| 端侧 | 下拉单选 | 是 | — | 固定选项 | Web/小程序 |
| 最低兼容版本 | 文本输入 | 是 | — | 自填 | 语义化版本格式 |
| 是否强制更新 | 开关 | 是 | 否 | — | 强制更新时用户无法跳过 |
| 更新说明 | 多行文本 | 是 | — | 自填 | 最大500字 |

### 通知触发

| 触发操作 | 通知对象 | 通知方式 | 消息模板 | 文档来源 |
|----------|----------|----------|----------|----------|
| 版本发布 | 小程序用户 | 小程序检测 | 下次启动时检测版本更新 | 03-小程序端 §10 / 06 §8.3 |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 列表查询 | /api/v1/system/versions | GET | — |
| 新增 | /api/v1/system/versions | POST | — |
| 编辑 | /api/v1/system/versions/{id} | PUT | — |
| 获取最新版本 | /api/v1/system/versions/latest | GET | 小程序启动时调用 |

### 交互流程要求

1. **页面加载流程**
   - 进入页面 → 并行调用：当前版本信息卡片数据 + 版本列表数据
   - 卡片数据优先渲染

2. **操作流程**
   - **新增版本**：点击"新增版本"→ 弹出表单弹窗 → 填写版本信息 → 保存 → 刷新列表和卡片
   - **编辑**：点击行"编辑"→ 弹出表单弹窗（回填数据）→ 修改 → 保存 → 刷新列表和卡片

3. **弹窗交互**
   - 新增/编辑共用一个 `el-dialog` 弹窗
   - 保存成功后弹窗关闭，列表刷新

4. **异常处理**
   - 版本号格式校验失败 → 字段下方红色提示
   - 版本号已存在 → 提示"该版本号已存在"
   - 新增版本后小程序端自动检测更新

5. **权限控制交互**
   - 无 `system:version:create` → "新增版本"按钮不渲染
   - 无 `system:version:update` → 行"编辑"按钮不渲染

6. **[H1]防重复请求**（列表页）
   - 行内操作按钮点击后整行操作禁用 + loading态
   - 分页切换 abort上一请求后再发新请求

7. **[H2]超时与加载反馈**（列表页）
   - 列表查询 timeout=15秒；写操作(新增/编辑) timeout=30秒
   - 超时 → ElMessage.error("请求超时，请稍后重试") + 按钮恢复
   - 加载>2秒显示全局ElLoading

8. **[H3]操作确认机制**
   - 版本发布无需额外确认（弹窗内已有保存按钮）

9. **[H8]操作结果反馈**
   - 成功 ElMessage.success(2s) → silent刷新
   - 失败 ElMessage.error(0手动关闭)

10. **[H1]防重复请求**（弹窗内保存按钮）
    - 保存按钮 :loading + disabled，API返回后恢复

11. **[H2]超时与加载反馈**（弹窗内提交）
    - 弹窗内提交 timeout=30秒

12. **[H4]脏数据检测**（编辑模式弹窗）
    - 弹窗打开时记录快照
    - 关闭弹窗/点击取消时 isDirty 检测 → 确认提示"修改尚未保存，确定关闭吗？"

13. **[H8]操作结果反馈**（弹窗）
    - 保存成功 → 关闭弹窗 → 刷新列表
    - 保存失败 → 弹窗保持打开，错误提示

### 组件规范

| 元素 | 组件 | 配置参数 |
|------|------|----------|
| 版本信息卡片 | el-card | shadow="hover", :body-style="{padding:'20px'}" |
| 当前版本号 | div | font-size=20px, font-weight=bold |
| 版本列表 | el-table | stripe, border, v-loading |
| 端侧标签 | el-tag | Web:type="primary", 小程序:type="success" |
| 强制更新标签 | el-tag | 是:type="danger", 否:type="success" |
| 新增/编辑弹窗 | el-dialog | width="500px", :close-on-click-modal=false |
| 版本号输入 | el-input | placeholder="x.y.z格式", clearable |
| 端侧下拉 | el-select | :options="[{label:'Web',value:'web'},{label:'小程序',value:'miniapp'}]" |
| 强制更新开关 | el-switch | active-text="是", inactive-text="否" |
| 更新说明 | el-input | type="textarea", :rows=4, maxlength=500, show-word-limit |

### 校验规则

| 字段 | 规则 | 错误提示 |
|------|------|----------|
| 版本号 | 必填, 语义化格式(/^\d+\.\d+\.\d+$/) | "请输入版本号" / "版本号格式为x.y.z" |
| 端侧 | 必填 | "请选择端侧" |
| 最低兼容版本 | 必填, 语义化格式 | "请输入最低兼容版本" / "版本号格式为x.y.z" |
| 更新说明 | 必填, 最大500字符 | "请输入更新说明" / "更新说明不能超过500字符" |

### 响应式布局

| 断点 | 布局调整 |
|------|----------|
| ≥1280px（桌面端） | 版本卡片一行两个；列表完整展示所有列 |
| 1024-1279px（Pad横屏） | 版本卡片一行两个；"更新说明"列隐藏 |
| 768-1023px（Pad竖屏） | 版本卡片一行一个（全宽）；列表仅显示：序号、版本号、端侧、是否强制更新、操作

---

## 页面2：缓存管理页

**页面编号**：SA-S-02-P01
**端侧归属**：Web专属
**页面路径**：/system/cache

### 界面布局

```
┌──────────────────────────────────────────────────────────────────┐
│ [面包屑] 系统配置 > 缓存管理                                       │
├──────────────────────────────────────────────────────────────────┤
│ [缓存状态概览]                                                     │
│ ┌────────────────────────────────────────────────────────────┐   │
│ │ Redis状态：● 已连接    内存使用：128MB/512MB    连接数：24    │   │
│ └────────────────────────────────────────────────────────────┘   │
├──────────────────────────────────────────────────────────────────┤
│ [缓存模块列表]                                                     │
│ 模块名称 | 缓存键前缀 | 缓存条数 | 最后更新时间 | 操作              │
│ 权限缓存 | perm:*     | 1,234   | 10:30:25    | [清理]            │
│ 字典缓存 | dict:*     | 56      | 09:00:00    | [清理]            │
│ 菜单缓存 | menu:*     | 120     | 09:00:00    | [清理]            │
│ 业务缓存 | biz:*      | 0       | —           | [清理]            │
├──────────────────────────────────────────────────────────────────┤
│ [操作栏]  [全部清理]                                              │
└──────────────────────────────────────────────────────────────────┘
```

### 操作按钮

| 按钮 | 权限编码 | 位置 | 显示条件 | 说明 |
|------|----------|------|----------|------|
| 清理（单模块） | system:cache:update | 行操作 | 始终 | 二次确认后清理指定模块缓存 |
| 全部清理 | system:cache:update | 操作栏 | 始终 | 二次确认后清理全部缓存 |

### 缓存模块说明

| 模块 | 缓存键前缀 | 过期策略 | 刷新机制 | 文档来源 |
|------|------------|----------|----------|----------|
| 权限缓存 | perm:* | 2小时TTL | 权限变更时实时刷新（Redis Pub/Sub） | 06 §5.3 / 03-超级管理员 §9 |
| 字典缓存 | dict:* | 24小时TTL | 字典变更时手动/自动刷新 | 06 §5.3 |
| 菜单缓存 | menu:* | 24小时TTL | 菜单变更时手动/自动刷新 | 06 §5.3 |
| 业务缓存 | biz:* | 按需懒加载 | 不缓存，实时查询 | 06 §5.3 |

### 通知触发

| 触发操作 | 通知对象 | 通知方式 | 消息模板 | 文档来源 |
|----------|----------|----------|----------|----------|
| 缓存清理 | 在线用户 | WebSocket推送 | 提示刷新页面 | 03-超级管理员 §9 |
| 权限缓存清理 | 在线用户 | Redis Pub/Sub | 刷新权限缓存 | 03-超级管理员 §9 |

### API端点

| 页面操作 | API路径 | 方法 | 说明 |
|----------|---------|------|------|
| 缓存状态 | /api/v1/system/cache/status | GET | Redis连接状态+各模块缓存统计 |
| 清理单模块 | /api/v1/system/cache/clear/{module} | POST | 清理指定模块缓存 |
| 全部清理 | /api/v1/system/cache/clear-all | POST | 清理全部缓存 |

### 交互流程要求

1. **页面加载流程**
   - 进入页面 → 并行调用：缓存状态概览（`GET /api/v1/system/cache/status`）+ 缓存模块列表
   - 概览数据优先渲染

2. **操作流程**
   - **清理单模块**：点击行"清理"→ 二次确认（"确认清理XX缓存？清理后相关数据将从数据库重新加载"）→ 调用API → 成功提示 → 刷新缓存状态
   - **全部清理**：点击"全部清理"→ 二次确认（"确认清理全部缓存？所有在线用户将收到刷新提示"）→ 调用API → 成功提示 → 刷新缓存状态

3. **缓存状态实时更新**
   - 清理操作完成后自动刷新状态概览和模块列表
   - 支持手动刷新（页面顶部刷新按钮）

4. **异常处理**
   - Redis连接断开 → 状态概览显示"● 未连接"红色标识，清理按钮禁用
   - 清理失败 → 提示错误信息

5. **权限控制交互**
   - 无 `system:cache:update` → 所有清理按钮不渲染

6. **[H1]防重复请求**
   - 行内清理按钮点击后整行操作禁用 + loading态
   - "全部清理"按钮点击后 disabled + loading态，API返回后恢复

7. **[H2]超时与加载反馈**
   - 写操作(缓存清理) timeout=30秒
   - 超时 → ElMessage.error("请求超时，请稍后重试") + 按钮恢复
   - 加载>2秒显示全局ElLoading

8. **[H3]操作确认机制**
   - 缓存清理：ElMessageBox.confirm("确认清理XX缓存？清理后相关数据将从数据库重新加载", { type: 'warning' })
   - 全部清理：ElMessageBox.confirm("确认清理全部缓存？所有在线用户将收到刷新提示", { type: 'error' })

9. **[H8]操作结果反馈**
   - 成功 ElMessage.success(2s) → silent刷新
   - 失败 ElMessage.error(0手动关闭)

### 组件规范

| 元素 | 组件 | 配置参数 |
|------|------|----------|
| Redis状态指示 | el-badge | 已连接:type="success", 未连接:type="danger" |
| 内存使用 | el-progress | :percentage, :stroke-width=10, :color |
| 缓存模块列表 | el-table | stripe, :show-header=true |
| 缓存条数 | el-statistic | :value, 千分位格式化 |
| 清理按钮（行） | el-button | type="danger", link, size="small", icon="Delete" |
| 全部清理按钮 | el-button | type="danger", icon="Delete", plain |
| 刷新按钮 | el-button | icon="Refresh", circle |

### 校验规则

无表单校验（操作类页面）

### 响应式布局

| 断点 | 布局调整 |
|------|----------|
| ≥1280px（桌面端） | 状态概览一行展示；缓存模块列表完整展示 |
| 1024-1279px（Pad横屏） | 状态概览一行展示；"最后更新时间"列隐藏 |
| 768-1023px（Pad竖屏） | 状态概览竖向堆叠；缓存模块列表仅显示：模块名称、缓存条数、操作

---

## 需求追溯

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| SA-S-01 | 系统版本管理 | 02-超级管理员 §3 / 03-超级管理员 §9 | 版本发布→小程序检测更新 | 小程序端版本更新提示(MP-C-05) |
| SA-S-02 | 缓存管理 | 02-超级管理员 §3 / 03-超级管理员 §9 | 清理缓存→通知在线用户刷新 | 权限管理(权限缓存清理) / 物业系统配置(字典缓存) |

## 业务规则

1. **版本更新策略**：小版本更新提示用户可选更新，大版本更新（低于最低兼容版本）强制更新（来源：03-小程序端 §10 / 06 §8.3）
2. **SDK依赖校验**：小程序启动时校验蓝牙SDK、微信SDK等关键依赖版本（来源：03-小程序端 §10）
3. **缓存自动清理**：系统启动时自动全量清理缓存，权限变更时定向清理权限缓存（来源：03-超级管理员 §9 / 06 §8.4）
4. **缓存手动清理**：超级管理员可按模块清理缓存，清理后通知在线用户刷新页面（来源：03-超级管理员 §9）
5. **权限缓存TTL降级**：Redis连接断开时，权限缓存2小时TTL到期后自动刷新（来源：06 §3.1）