srdb/examples/webui/README.md

SRDB WebUI - 数据库管理工具

一个功能强大的 SRDB 数据库管理工具，集成了现代化的 Web 界面和实用的命令行工具。

📋 目录

• 功能特性
• 快速开始
• Web UI 使用指南
• 命令行工具
• 技术架构
• 开发说明

---

🎯 功能特性

Web UI

📊 数据管理

• 表列表 - 查看所有表及其 Schema 信息
• 数据浏览 - 分页浏览表数据，支持自定义列选择
• 列持久化 - 自动保存列选择偏好到 localStorage
• 数据详情 - 点击查看完整的行数据（JSON 格式）
• 智能截断 - 长字符串自动截断，点击查看完整内容
• 时间格式化 - 自动格式化 _time 字段为可读时间

🌳 LSM-Tree 管理

• Manifest 视图 - 可视化 LSM-Tree 层级结构
• 文件详情 - 查看每层的 SST 文件信息
• Compaction 监控 - 实时查看 Compaction Score 和统计
• 层级折叠 - 可展开/收起查看文件详情

🎨 用户体验

• 响应式设计 - 完美适配桌面和移动设备
• 深色/浅色主题 - 支持主题切换
• 实时刷新 - 一键刷新当前视图数据
• 移动端优化 - 侧边栏抽屉式导航

命令行工具

提供多个实用的数据库诊断和管理工具：

命令	功能	说明
serve	Web UI 服务器	启动 Web 管理界面
check-data	数据检查	检查表数据完整性
check-seq	序列号检查	验证特定序列号的数据
dump-manifest	Manifest 导出	导出 LSM-Tree 结构信息
inspect-sst	SST 文件检查	检查单个 SST 文件
inspect-all-sst	批量 SST 检查	检查所有 SST 文件
test-fix	修复测试	测试数据修复功能
test-keys	键测试	测试键的存在性

---

🚀 快速开始

1. 启动 Web UI

cd examples/webui

# 使用默认配置（数据库：./data，端口：8080）
go run main.go serve

# 自定义配置
go run main.go serve --db /path/to/database --port 3000

# 启用自动数据插入（用于演示）
go run main.go serve --auto-insert

2. 访问 Web UI

打开浏览器访问：http://localhost:8080

3. 命令行工具示例

# 检查表数据
go run main.go check-data --db ./data --table users

# 检查特定序列号
go run main.go check-seq --db ./data --table users --seq 123

# 导出 Manifest
go run main.go dump-manifest --db ./data --table users

# 检查 SST 文件
go run main.go inspect-sst --db ./data --table users --file 000001.sst

---

📖 Web UI 使用指南

界面布局

┌─────────────────────────────────────────────────┐
│  SRDB Tables                          [🌙/☀️]  │  ← 侧边栏
│  ├─ users                                       │
│  ├─ orders                                      │
│  └─ logs                                        │
├─────────────────────────────────────────────────┤
│  [☰] users                        [🔄 Refresh] │  ← 页头
│  [Data] [Manifest / LSM-Tree]                  │  ← 视图切换
├─────────────────────────────────────────────────┤
│                                                 │
│  Schema (点击字段卡片选择要显示的列)            │  ← Schema 区域
│  ┌──────────┬──────────┬──────────┐            │
│  │⚡ id     │● name    │⚡ email   │            │
│  │[int64]   │[string]  │[string]  │            │
│  └──────────┴──────────┴──────────┘            │
│                                                 │
│  Data (1,234 rows)                              │  ← 数据表格
│  ┌─────┬──────┬───────────┬─────────┐          │
│  │ _seq│ name │ email     │ Actions │          │
│  ├─────┼──────┼───────────┼─────────┤          │
│  │  1  │ John │ john@...  │ Detail  │          │
│  │  2  │ Jane │ jane@...  │ Detail  │          │
│  └─────┴──────┴───────────┴─────────┘          │
│                                                 │
├─────────────────────────────────────────────────┤
│  [10/page] [Previous] Page 1 of 5 [Go] [Next] │  ← 分页控件
└─────────────────────────────────────────────────┘

功能说明

1. 表列表（侧边栏）

• 显示所有表及其字段信息
• 点击表名切换到该表
• 展开/收起查看字段详情
• 字段图标：⚡ = 已索引，● = 未索引

2. Data 视图

• Schema 区域：点击字段卡片选择要显示的列
• 数据表格：显示选中的列数据
• 系统字段：
  • _seq：序列号（第一列）
  • _time：时间戳（倒数第二列，自动格式化）
• Detail 按钮：查看完整的行数据（JSON 格式）
• 分页控件：
  • 每页大小：10/20/50/100
  • 上一页/下一页
  • 跳转到指定页

3. Manifest 视图

• 统计卡片：
  • Active Levels：活跃层数
  • Total Files：总文件数
  • Total Size：总大小
  • Compactions：Compaction 次数
• 层级卡片：
  • 点击展开/收起查看文件列表
  • Score 指示器：
    • 🟢 绿色：健康（< 50%）
    • 🟡 黄色：警告（50-80%）
    • 🔴 红色：需要 Compaction（≥ 80%）
• 文件详情：
  • 文件编号、大小、行数
  • Seq 范围（min_key - max_key）

4. 刷新按钮

• 点击刷新当前视图的数据
• Data 视图：重新加载表数据
• Manifest 视图：重新加载 LSM-Tree 结构

5. 主题切换

• 点击右上角的 🌙/☀️ 图标
• 切换深色/浅色主题
• 自动保存到 localStorage

---

🛠️ 命令行工具

serve - Web UI 服务器

启动 Web 管理界面。

go run main.go serve [flags]

参数：

• --db - 数据库目录（默认：./data）
• --port - 服务端口（默认：8080）
• --auto-insert - 启用自动数据插入（用于演示）

示例：

# 基本使用
go run main.go serve

# 自定义端口
go run main.go serve --port 3000

# 启用自动插入（每秒插入一条随机数据到 logs 表）
go run main.go serve --auto-insert

check-data - 数据检查

检查表数据的完整性。

go run main.go check-data --db ./data --table <table_name>

check-seq - 序列号检查

验证特定序列号的数据。

go run main.go check-seq --db ./data --table <table_name> --seq <sequence_number>

dump-manifest - Manifest 导出

导出 LSM-Tree 层级结构信息。

go run main.go dump-manifest --db ./data --table <table_name>

inspect-sst - SST 文件检查

检查单个 SST 文件的内容和元数据。

go run main.go inspect-sst --db ./data --table <table_name> --file <file_name>

inspect-all-sst - 批量 SST 检查

检查表的所有 SST 文件。

go run main.go inspect-all-sst --db ./data --table <table_name>

---

🏗️ 技术架构

前端技术栈

• Lit - 轻量级 Web Components 框架
• ES Modules - 原生 JavaScript 模块
• CSS Variables - 主题系统
• Shadow DOM - 组件封装

组件架构

srdb-app (主应用)
├── srdb-theme-toggle (主题切换)
├── srdb-table-list (表列表)
├── srdb-page-header (页头)
│   └── [🔄 Refresh] (刷新按钮)
├── srdb-table-view (表视图容器)
│   ├── srdb-data-view (数据视图)
│   │   ├── Schema 区域
│   │   │   ├── srdb-field-icon (字段图标)
│   │   │   └── srdb-badge (类型标签)
│   │   └── 数据表格
│   └── srdb-manifest-view (Manifest 视图)
│       └── srdb-badge (Score 标签)
└── srdb-modal-dialog (模态对话框)

后端架构

webui.go
├── API Endpoints
│   ├── GET /api/tables - 获取表列表
│   ├── GET /api/tables/{name}/schema - 获取表 Schema
│   ├── GET /api/tables/{name}/data - 获取表数据（分页）
│   ├── GET /api/tables/{name}/data/{seq} - 获取单条数据
│   └── GET /api/tables/{name}/manifest - 获取 Manifest 信息
├── Static Files
│   └── /static/* - 静态资源服务
└── Index
    └── / - 首页

数据流

用户操作
  ↓
组件事件 (CustomEvent)
  ↓
app.js (事件总线)
  ↓
API 请求 (fetch)
  ↓
webui.go (HTTP Handler)
  ↓
SRDB Database
  ↓
JSON 响应
  ↓
组件更新 (Lit reactive)
  ↓
UI 渲染

---

🔧 开发说明

项目结构

webui/
├── commands/
│   └── webui.go              # Web UI 服务器实现
├── static/
│   ├── index.html            # 主页面
│   ├── css/
│   │   └── styles.css        # 全局样式
│   └── js/
│       ├── app.js            # 应用入口和事件总线
│       ├── components/       # Web Components
│       │   ├── app.js        # 主应用容器
│       │   ├── badge.js      # 标签组件
│       │   ├── data-view.js  # 数据视图
│       │   ├── field-icon.js # 字段图标
│       │   ├── manifest-view.js # Manifest 视图
│       │   ├── modal-dialog.js  # 模态对话框
│       │   ├── page-header.js   # 页头
│       │   ├── table-list.js    # 表列表
│       │   ├── table-view.js    # 表视图容器
│       │   └── theme-toggle.js  # 主题切换
│       └── styles/
│           └── shared-styles.js # 共享样式
└── webui.go                  # Web UI 后端实现

添加新组件

1. 在 static/js/components/ 创建组件文件
2. 继承 LitElement
3. 定义 static properties 和 static styles
4. 实现 render() 方法
5. 使用 customElements.define('srdb-xxx', Component) 注册
6. 在 app.js 中导入

添加新 API

1. 在 webui.go 中添加 handler 方法
2. 在 setupHandler() 中注册路由
3. 返回 JSON 格式的响应
4. 在前端组件中调用 API

样式规范

• 使用 CSS Variables 定义颜色和尺寸
• 组件样式封装在 Shadow DOM 中
• 共享样式定义在 shared-styles.js
• 响应式断点：768px

命名规范

• 组件名：srdb-xxx（kebab-case）
• 类名：ComponentName（PascalCase）
• 文件名：component-name.js（kebab-case）
• CSS 类：.class-name（kebab-case）

---

📝 注意事项

性能优化

1. 列选择：只加载选中的列，减少数据传输
2. 字符串截断：长字符串自动截断，按需加载完整内容
3. 分页加载：大表数据分页加载，避免一次性加载全部
4. Shadow DOM：组件样式隔离，避免全局样式污染

浏览器兼容性

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

需要支持：

• ES Modules
• Web Components
• Shadow DOM
• CSS Variables

已知限制

1. 大数据量：单页最多显示 1000 条数据
2. 字符串长度：超过 100 字符自动截断
3. 并发限制：同时只能查看一个表的数据

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License