|
|
# 系统配置
|
|
|
|
|
|
> 模块编码：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）
|