# 系统配置

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

## 功能概览

| 项目 | 说明 |
|------|------|
| 菜单名称 | 系统配置 |
| 子菜单 | 系统版本管理、缓存管理 |
| 功能编号 | 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 | 小程序启动时调用 |

---

## 页面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 | 清理全部缓存 |

---

## 需求追溯

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| 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）