本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/docs/SplitDB控制台拆分与操作日志改造计划 (2).md。

FlintHub 1.0 — SplitDB 控制台拆分与操作日志查看改造计划

文档状态：待确认（2026-08-16）

目标：① 将原 /admin/database/engine（P29 引擎控制台）拆分为「引擎概览（只读）」与「引擎设置（操作）」两个独立页面；② 后台菜单重组为「数据管理 / 站长工具」两组；③ 新增「操作日志」查看页 /admin/logs/audit；④ 保留旧路径重定向

基线：FlintHub 1.0（SplitDB 纯 SQLite 分片引擎）；PHP 8.0.2（SQLite 3.33.0）；P29 引擎控制台已上线

关联文档：update/SplitDB引擎控制台改造计划.md（P29 设计与决策）、update/SplitDB引擎控制台使用说明.md（P29 使用说明，本次需同步修订）

一、现状勘察结论（已读代码确认）

二、页面拆分设计

2.1 路由总览

2.2 引擎概览 /admin/database/overview（只读）

保留原 engine 页的只读监控数据：

• 无任何 POST 表单；自动扩容检查（maybeAutoExpand）不在本页触发。

2.3 引擎设置 /admin/database/settings（操作型）

2.4 旧路径兼容

• engine() 保留为临时重定向：GET/POST /admin/database/engine → redirect('/admin/database/overview')（302，redirect() 已防开放重定向）；
• 旧 engine.php 视图文件：删除（不再被引用），同步删除 update/ 镜像对应文件。

三、后台菜单重组（app/Views/admin/_sidebar.php）

3.1 新结构

┌─ 数据管理 ──────────────────────────────┐
│  SplitDB 概览  → /admin/database/overview   (icon: database)   nav_active=database_overview
│  SplitDB 设置  → /admin/database/settings   (icon: settings)   nav_active=database_settings
│  备份优化      → /admin/database             (icon: save)       nav_active=database
├─ 站长工具 ──────────────────────────────┤
│  操作日志      → /admin/logs/audit          (icon: list)        nav_active=logs_audit
│  维护工具      → /admin/maintenance         (icon: wrench)      nav_active=maintenance
└──────────────────────────────────────────┘

• 「数据管理」组 header：icon database（沿用）；
• 「站长工具」组 header：icon wrench（新增 header，与既有「外观管理」「扩展」header 平级）；
• 菜单项顺序按上表；__nav_active 值分别绑定各子链接 active 态；
• 折叠/展开逻辑（_sidebar.php 底部 JS）按 header 分组自动生效，无需改动 JS。

四、操作日志查看页（/admin/logs/audit）

4.1 控制器

新建 app/Controllers/Admin/LogController.php（extends BaseController，构造器即管理员 + 30 分钟二次验证，等价 need_admin()）。

★ 权限等级考量（2026-08-16 用户反馈）：审计日志含 IP/UA/管理操作详情，属敏感数据。经勘察，本系统无 moderator/版主角色体系——后台权限仅 Auth::isAdmin()（role='admin' && group_id=4），Permission 助手是版块级矩阵而非用户角色级。因此本期保持 need_admin()（BaseController 构造器），不做 need_manage()（该概念在代码库中无既有实现，引入需新增角色字段与权限矩阵，超出本期范围）。扩展点：若后续需让版主可查，在 audit() 入口追加角色判断（如 Auth::isAdmin() || 版主组判定）即可，不影响本期实现。

public function audit()
{
    // GET 参数：page / action / date（YYYY-MM-DD）
    $page   = max(1, (int)($_GET['page'] ?? 1));
    $action = (string)($_GET['action'] ?? '');      // 白名单：允许 [a-z_]，非法置空
    $date   = (string)($_GET['date'] ?? '');        // 白名单：\d{4}-\d{2}-\d{2}
    $perPage = 50;

    $audit = \app\Helpers\AuditLog::query($action, 0, $page, $perPage, $date); // 扩展后签名
    // 计算 totalPages 并钳制 $page（越界回落最后一页，同 P26 规范）

    $this->view('admin/logs/audit', [
        'items' => $audit['items'], 'total' => $audit['total'],
        'page' => $page, 'totalPages' => $totalPages,
        'action' => $action, 'date' => $date,
        '__nav_active' => 'logs_audit',
    ]);
}

• 筛选表单为 GET（无需 CSRF，与后台用户搜索一致）；
• action 白名单正则 /^[a-z_]{1,32}$/；date 白名单 /^\d{4}-\d{2}-\d{2}$/（不合法置空）。

4.2 AuditLog::query() 扩展（向后兼容）

public static function query(string $action = '', int $userId = 0, int $page = 1,
                             int $perPage = 50, string $date = ''): array
{
    // 追加：if ($date !== '') { $where .= ' AND created_at LIKE :date_prefix'; $params[':date_prefix'] = $date . '%'; }
    // （created_at 存 'Y-m-d H:i:s'，LIKE 'YYYY-MM-DD%' 前缀可命中 idx_audit_logs_created）
}

• 原调用方（若有）零改动：新参数 $date 默认 '' 不改变既有行为；
• 目标类型筛选暂不做（本次需求仅「日期 + 操作类型」，避免过度设计）。

4.3 视图 app/Views/admin/logs/audit.php

• 标题 + 筛选表单：操作类型下拉（可选全部，及从 action 参数回显）+ 日期输入（type=date）+ 查询按钮；
• 操作类型下拉值：从 audit_logs 表 SELECT DISTINCT action 动态读取（2026-08-16 用户反馈，采纳）+「全部」选项——新操作类型自动出现，免维护；
• ★ 性能实测：EXPLAIN QUERY PLAN SELECT DISTINCT action FROM audit_logs = SCAN TABLE audit_logs USING COVERING INDEX idx_audit_logs_action（覆盖索引扫描，不落表）；当前 170 行稳态 0.030~0.047ms，即便万级行仍为亚毫秒级；
• ★ 优化（防大表退化）：DISTINCT 结果落 data/runtime/cache_audit_actions.json（60s TTL，JSON 带 ts），复用引擎统计缓存同款模式；页面加载命中缓存即免查库；刷新缓存由"新增日志写入"自然驱动（60s 后过期重查）；
• 表格列：时间 / 管理员(username) / 操作类型(action) / 目标(target_type + target_id) / IP / 详情(detail，超长截断 title 悬浮)；
• 分页：$this->pagination() 统一样式，URL 带 action/date 参数不丢筛选；
• 空态：「暂无操作日志」；
• 管理员列为空时显示 -（系统任务如 auto_expand 无用户）。

五、改动文件清单

六、安全与健壮性

1. 全部 POST（settings 页 save_buckets/save_auto_expand）走 Csrf::verifyOrDie；overview 纯 GET 只读；
2. 筛选参数白名单：action /^[a-z_]{1,32}$/、date /^\d{4}-\d{2}-\d{2}$/、page intval 钳制；SQL 全参数绑定；
3. AuditLog::query() 扩展向后兼容，原调用方零影响；
4. 扩容记录查询仅读 audit_logs（LIMIT 10），无写操作；
5. 菜单 __nav_active 各值唯一，无高亮串扰；
6. engine 重定向走 Controller::redirect()（防开放重定向，仅相对路径）。

七、验证与交付

1. php -l 全过（改动的全部 PHP 文件）；
2. 功能自测（临时脚本用后即删）：

• overview 页数据：currentBucketSize/quarter/totalThreads/suggestBuckets/bucketStats 正常返回；
• settings 页：save_buckets 白名单+只增不减+写 config 往返还原；save_auto_expand 保存；maybeAutoExpand 守卫（未启用/阈值/24h/flock）；consistencyCheck 两范围；
• 扩容记录：audit_logs 中 auto_expand/admin_action 记录查询正确（含空态）；
• AuditLog::query 日期筛选：LIKE 'YYYY-MM-DD%' 命中与空结果；
• engine 重定向：302 Location 指向 /admin/database/overview；
• 侧边栏：5 个链接 href 与 __nav_active 映射逐一核对；

1. update/ 镜像 fc /b 逐字节一致（engine.php 删除同步）；CHANGELOG 记 P30；使用说明修订；
2. 浏览器复核建议：菜单分组展开/高亮、日志筛选交互（依赖 JS，CLI 无法全覆盖）。

八、待确认点

1. 扩容记录展示：最近 10 条（本次设计）还是提供分页/筛选？默认按本次设计（LIMIT 10 最近记录）。
2. 一致性检查归属：随「引擎设置」页（本次设计，操作型诊断）还是移回「引擎概览」？默认 settings 页。
3. 操作日志类型下拉：从 DB DISTINCT action 动态读取 + 60s 缓存（2026-08-16 用户反馈采纳——性能实测覆盖索引亚毫秒级，免维护，新类型自动出现；替换原静态白名单设计）；
4. engine 重定向：302 临时重定向（本次设计）即可，无需 301。

计划完。待用户确认后按第五节清单串行实施。