# 系统管理功能

状态：已定版（2026-09-07 实施，契约 1.23.0）

实施摘要：
- 权限：`sys_role` 新增 `manage_system` / `manage_audit_log` 两管理位（Alembic `0029` + Flyway `V14` + 达梦适配 `db/migration-dm/V14`，三迁移幂等）；`AllowedModule` 新增 `SYSTEM_MANAGEMENT`（manage_system 推导，admin 恒真）、`AUDIT_LOG` 改由 manage_audit_log 推导；备份 6 接口鉴权由 ADMIN 硬判定改为系统管理权位，审计接口改为日志审计权位。
- 后端（Python `dms/services/system_management_service.py` / Java `com.dms.service.SystemManagementService` 双版对齐，12 接口 + `POST backup/test-target`）：资源快照、指标采样历史、进程监控、存储用量、转换器状态、健康体检、系统信息、运行参数总览、运行日志尾部/下载、清空预览缓存、强制下线、备份目标连通测试。
- 采样：`sys_metric_sample` 表 + 后台线程（30 秒间隔、保留 7 天自动清理，`DMS_METRIC_INTERVAL_SECONDS` / `DMS_METRIC_RETENTION_DAYS` 可调）；CPU/内存采样入库，磁盘实时查询不采样。
- 日志：新增 `DMS_LOG_FILE` 配置（缺省 `logs/dms-server.log`），Python logging FileHandler / Java logback RollingFileAppender 双端落盘，级别统一为 DEBUG/INFO/WARNING/ERROR/CRITICAL（Java WARN 规范化为 WARNING 落盘）。
- 审计动作：新增 `PREVIEW_CACHE_CLEAR` / `FORCE_OFFLINE` / `BACKUP_TEST_TARGET`（迁移同步扩 CHECK 白名单，含达梦大小写不敏感探测重建）。
- 前端：新页签「系统管理」（`features/system/`：systemTypes 守卫、systemApi、SystemDashboard）；备份管理页签整体迁入 SystemDashboard；日志审计页签新增「运行日志」大尺寸模态窗口（尾部行数/级别过滤/刷新/全文下载）；角色维护面板管理位区新增「系统管理」「日志审计」复选框；审计页可见性由 ADMIN 硬判定改为 allowedModules 驱动。
- 验证：Python pytest 全量通过（含 `test_system_management.py` 引擎级 + 接口级）；Java mvn compile/test 通过；前端 tsc 通过、vitest 424 项全绿。

## 1. 需求

- 新建「系统管理」页签统一收纳系统级管理功能，备份管理页签整体迁入；拥有「系统管理」权限位的角色可见（admin 恒有）；
- 角色配置处新增「系统管理」「日志审计」管理位（与分类/机构/用户编辑并列）；日志审计页签由 ADMIN 硬判定改为「日志审计」权位控制；
- 首期功能：服务器资源监控、应用进程监控、存储用量统计、转换服务状态、健康检查面板、备份管理迁入、备份目标连通测试、运行日志在线查看（并入日志审计页签，单开窗口）、系统信息卡片、运行参数总览（只读）、预览缓存清理、强制下线；
- 二期（本期不做）：在线会话统计、阈值告警、孤儿文件清理。

## 2. 权限设计

- `sys_role` 两新列：`manage_system` / `manage_audit_log`（BOOLEAN NOT NULL DEFAULT 0）；
- 模块推导：`SYSTEM_MANAGEMENT` ← manage_system；`AUDIT_LOG` ← manage_audit_log；其余模块推导不变；admin 恒真；
- 鉴权口径：
  - `system/**` 全部接口（除 logs）：系统管理权位；
  - `system/logs` 与 `system/logs/download`（运行日志）：**日志审计权位**（功能并入日志审计页签）；
  - `backup/**` 6 接口 + `backup/test-target`：ADMIN 硬判定 → 系统管理权位；
  - `audit/**` 既有接口：ADMIN 硬判定 → 日志审计权位；
- 前端：导航项由 `allowedModules` 下发；角色维护面板管理位区新增两复选框；admin 不受矩阵约束、默认全选。

## 3. 接口（契约 1.23.0）

均为 `/api/v1` 前缀，响应 camelCase：

| 方法 | 路径 | 权限 | 说明 |
| --- | --- | --- | --- |
| GET | `system/metrics/current` | 系统管理 | CPU（占用率/核数/1分钟负载，Windows 负载为 null）/内存/交换/磁盘分区实时快照 + 开机时间（Java 无 API 恒空串） |
| GET | `system/metrics/history?hours=` | 系统管理 | 采样历史（hours ∈ 1/6/24/168/720，缺省 24），`{hours, entries[]}` |
| GET | `system/process` | 系统管理 | 进程 PID/CPU/RSS/VMS/线程数/启动时间/运行时长/运行时版本（Python 版 psutil、Java 版 MXBean，`pythonVersion` 字段名契约定版，Java 填 JDK 版本） |
| GET | `system/storage-usage` | 系统管理 | 七目录（original/preview/extracted/temporary/quarantine/recycle/voucher）字节数与文件数 |
| GET | `system/converter` | 系统管理 | LibreOffice 可用状态/可执行文件/并发上限/进行中/累计成功/累计失败/预览开关/超时（内存计数，重启清零） |
| GET | `system/health` | 系统管理 | 体检 5 项：DATABASE / STORAGE_WRITABLE / LIBREOFFICE / BACKUP_TARGET / STORAGE_ENCRYPTION，逐项 `{item, ok, detail}` |
| GET | `system/info` | 系统管理 | 14 字段：契约版本/后端类型(JAVA\|PYTHON)/运行时版本/OS/主机名/架构/数据库类型/启动时间/运行时长/工作目录/存储根/备份配置路径/.env 路径/日志文件路径 |
| GET | `system/runtime-config` | 系统管理 | 只读配置总览（分类分组），密钥类（JWT 密钥/KEK/rsync 密码等）仅显示配置状态不回显值 |
| GET | `system/logs?lines=&level=` | 日志审计 | 日志文件尾部（lines ∈ 1..5000 缺省 500，级别过滤），`{file, lines[], truncated, error?}`；级别过滤为全量扫描后取尾部时 `truncated=true` |
| GET | `system/logs/download` | 日志审计 | 日志全文（text/plain 附件流） |
| POST | `system/maintenance/preview-cache` | 系统管理 | 清空 preview/ 目录，`{removedFiles, removedBytes}`，审计 `PREVIEW_CACHE_CLEAR` |
| POST | `system/users/{userId}/force-offline` | 系统管理 | 目标用户 authVersion+1 全令牌失效，`{userId, username, authVersion}`，审计 `FORCE_OFFLINE`；不能对自己执行 |
| POST | `backup/test-target` | 系统管理 | 按当前备份配置探测目标可写，`{ok, target?, error?}`，审计 `BACKUP_TEST_TARGET` |

写操作（清缓存/强制下线/目标测试）不需要二次认证（与备份触发一致口径）。

## 4. 关键设计

### 4.1 指标采样

- 表 `sys_metric_sample`（id/sampled_at/cpu_percent/mem_used_bytes/mem_total_bytes），迁移 `0029`/`V14` 幂等建表；
- Python 后台守护线程（`MetricSampler`）按 `DMS_METRIC_INTERVAL_SECONDS`（缺省 30 秒）采样入库；Java `@Scheduled` 固定延迟同口径；
- 清理：每次采样顺带删除早于 `DMS_METRIC_RETENTION_DAYS`（缺省 7 天）的旧样本；
- 磁盘不采样（分区实时查询，量小无历史需求）。

### 4.2 运行日志

- `DMS_LOG_FILE` 配置日志文件路径（相对运行目录），缺省 `logs/dms-server.log`；目录不存在自动创建（Java `LogFileInitializer` 启动兜底）；
- Python：Root logger 追加 `FileHandler`；Java：logback `RollingFileAppender`（按日滚动）+ 控制台；
- 尾部读取：按字节从文件末尾反向回溯定位行边界，取尾部 N 行；级别过滤时全量扫描匹配行后取尾部并置 `truncated=true`；
- 未配置或文件未生成时 `file` 为空串，前端提示「未配置运行日志文件（DMS_LOG_FILE），或文件尚未生成」。

### 4.3 存储用量与体检

- 存储用量遍历七个存储子目录累加大小与文件数（大目录遍历为毫秒级本地 IO，未做缓存）；
- 体检 5 项：DB 连通（SELECT 1）、存储根可写（临时文件写入探测）、LibreOffice 可用（转换器状态）、备份目标可达（仅启用时探测）、信封加密（KEK 配置状态）。

### 4.4 强制下线

- 复用既有 authVersion 失效机制：目标用户 `auth_version`+1，其全部 JWT 立即失效需重新登录；
- 拒绝对自己执行（HTTP 400）；目标不存在报 404。

## 5. 前端

- 导航：`AllowedModule` 新增 `SYSTEM_MANAGEMENT`，模块页映射 `system`；「备份管理」本地页签下线，`BackupDashboard` 整体嵌入 `SystemDashboard` 底部；
- `SystemDashboard`（`features/system/`）：操作条（刷新/一键体检）、系统信息卡片（14 行）、应用进程卡片、实时资源（CPU/内存/交换 + 分区表，使用率 ≥90% 红色）、资源采样趋势（近 1/6/24 小时与 7/30 天切换，纯 SVG 双折线图：CPU 红/内存蓝，含 25/50/75% 参考线）、存储目录用量表、转换器卡片、运行参数总览表（只读，密钥仅显示状态）、维护操作（清空预览缓存二次确认、测试备份目标、强制下线弹窗）、体检结果弹窗（逐项 ✓/✗ + 详情）；
- 运行日志窗口（`AuditDashboard` 内 `RuntimeLogModal`）：日志审计页筛选栏头部「运行日志」按钮打开；全屏模态（max-w-5xl）：尾部行数选择（200~5000）、级别过滤（DEBUG~CRITICAL）、刷新、下载全文（Blob 锚点落盘 `dms-runtime.log`）、文件路径与截断提示、等宽字体日志正文；
- 角色维护面板：管理位区新增「系统管理」「日志审计」复选框，创建缺省 false、编辑回显；
- 契约守卫：`systemTypes.ts` 逐字段类型守卫（与双后端响应形状逐字对齐），不符契约抛 `contractHttpError`。

## 6. 验证记录

- Python：`pytest` 全量 **298 通过 / 496 跳过**（较备份定版基线 289/470 新增 `test_system_management.py` 引擎级与接口级用例：采样与清理、存储用量七目录、体检形状、参数脱敏、日志尾部与级别过滤、清缓存/强制下线/目标测试；跳过项为 B2 门控的 DB 集成用例，提供 `DMS_TEST_*` 环境变量时执行）；`test_openapi_storage` 守卫 1.23.0 版本与 system 路径白名单；
- Java：`mvn compile` / `mvn test` 通过（29 项测试无回归）；
- 前端：`npx tsc --noEmit` 通过；`npx vitest run` 66 文件 424 项全绿（含 UserSummary/Role 新增权位字段的守卫与 fixture、审计页 allowedModules 驱动的 q3f/f7 断言更新）；
- 双端形状对齐：SystemManagementService（Java）与 system_management_service.py（Python）逐字段核对（coreCount、loadAvgOneMinute、memoryRssBytes、sampledAt 等 camelCase 键双端一致）。

## 7. 二期备忘

- 在线会话统计：需令牌登记表（JWT 无状态），双后端并行时按当前实例口径；
- 阈值告警：磁盘/内存超阈值页签红点；
- 孤儿文件清理：存储有文件但 DB 无记录扫描（含 .upload 残留）。