srdb/examples/README.md

# SRDB Examples

本目录包含 SRDB 数据库的示例程序和工具。

## 目录结构

```
examples/
└── webui/              # Web UI 和命令行工具集
    ├── main.go         # 主入口点
    ├── commands/       # 命令实现
    │   ├── webui.go            # Web UI 服务器
    │   ├── check_data.go       # 数据检查工具
    │   ├── check_seq.go        # 序列号检查工具
    │   ├── dump_manifest.go    # Manifest 导出工具
    │   ├── inspect_all_sst.go  # SST 文件批量检查
    │   ├── inspect_sst.go      # SST 文件检查工具
    │   ├── test_fix.go         # 修复测试工具
    │   └── test_keys.go        # 键存在性测试工具
    └── README.md       # WebUI 详细文档
```

---

## WebUI - 数据库管理工具

一个集成了 Web 界面和命令行工具的 SRDB 数据库管理工具。

### 功能特性

#### 🌐 Web UI
- **表列表展示** - 可视化查看所有表及其 Schema
- **数据分页浏览** - 表格形式展示数据，支持分页和列选择
- **Manifest 查看** - 查看 LSM-Tree 结构和 Compaction 状态
- **响应式设计** - 基于 HTMX 的现代化界面
- **大数据优化** - 自动截断显示，点击查看完整内容

#### 🛠️ 命令行工具
- **数据检查** - 检查表和数据完整性
- **序列号验证** - 验证特定序列号的数据
- **Manifest 导出** - 导出 LSM-Tree 层级信息
- **SST 文件检查** - 检查和诊断 SST 文件问题

### 快速开始

#### 1. 启动 Web UI

```bash
cd examples/webui

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

# 或指定自定义配置
go run main.go serve -db ./mydb -addr :3000
```

然后打开浏览器访问 `http://localhost:8080`

#### 2. 查看帮助

```bash
go run main.go help
```

输出：
```
SRDB WebUI - Database management tool

Usage:
  webui <command> [flags]

Commands:
  webui, serve       Start WebUI server (default: :8080)
  check-data         Check database tables and row counts
  check-seq          Check specific sequence numbers
  dump-manifest      Dump manifest information
  inspect-all-sst    Inspect all SST files
  inspect-sst        Inspect a specific SST file
  test-fix           Test fix for data retrieval
  test-keys          Test key existence
  help               Show this help message

Examples:
  webui serve -db ./mydb -addr :3000
  webui check-data -db ./mydb
  webui inspect-sst -file ./data/logs/sst/000046.sst
```

---

## 命令详解

### serve / webui - 启动 Web 服务器

启动 Web UI 服务器，提供数据可视化界面。

```bash
# 基本用法
go run main.go serve

# 指定数据库路径和端口
go run main.go webui -db ./mydb -addr :3000
```

**参数**：
- `-db` - 数据库目录路径（默认：`./data`）
- `-addr` - 服务器地址（默认：`:8080`）

**功能**：
- 自动创建示例表（users, products, logs）
- 后台自动插入测试数据（每秒一条）
- 提供 Web UI 和 HTTP API

---

### check-data - 检查数据

检查数据库中所有表的记录数。

```bash
go run main.go check-data -db ./data
```

**输出示例**：
```
Found 3 tables: [users products logs]
Table 'users': 5 rows
Table 'products': 6 rows
Table 'logs': 1234 rows
```

---

### check-seq - 检查序列号

验证特定序列号的数据是否存在。

```bash
go run main.go check-seq -db ./data
```

**功能**：
- 检查 seq=1, 100, 729 等特定序列号
- 显示总记录数
- 验证数据完整性

---

### dump-manifest - 导出 Manifest

导出数据库的 Manifest 信息，检查文件重复。

```bash
go run main.go dump-manifest -db ./data
```

**输出示例**：
```
Level 0: 5 files
Level 1: 3 files
Level 2: 1 files
```

---

### inspect-all-sst - 批量检查 SST 文件

检查所有 SST 文件的完整性。

```bash
go run main.go inspect-all-sst -dir ./data/logs/sst
```

**输出示例**：
```
Found 10 SST files

File #1 (000001.sst):
  Header: MinKey=1 MaxKey=100 RowCount=100
  Actual: 100 keys [1 ... 100]

File #2 (000002.sst):
  Header: MinKey=101 MaxKey=200 RowCount=100
  Actual: 100 keys [101 ... 200]
  *** MISMATCH: Header says 101-200 but file has 105-200 ***
```

---

### inspect-sst - 检查单个 SST 文件

详细检查特定 SST 文件。

```bash
go run main.go inspect-sst -file ./data/logs/sst/000046.sst
```

**输出示例**：
```
File: ./data/logs/sst/000046.sst
Size: 524288 bytes

Header:
  RowCount: 100
  MinKey: 332
  MaxKey: 354
  DataSize: 512000 bytes

Actual keys in file: 100 keys
  First key: 332
  Last key: 354
  All keys: [332 333 334 ... 354]

Trying to get key 332:
  FOUND: seq=332, time=1234567890
```

---

### test-fix - 测试修复

测试数据检索的修复功能。

```bash
go run main.go test-fix -db ./data
```

**功能**：
- 测试首部、中部、尾部记录
- 验证 Get() 操作的正确性
- 显示修复状态

---

### test-keys - 测试键存在性

测试特定键是否存在。

```bash
go run main.go test-keys -db ./data
```

**功能**：
- 测试预定义的键列表
- 统计找到的键数量
- 显示首尾记录

---

## 编译安装

### 编译二进制

```bash
cd examples/webui
go build -o webui main.go
```

### 全局安装

```bash
go install ./examples/webui@latest
```

然后可以在任何地方使用：

```bash
webui serve -db ./mydb
webui check-data -db ./mydb
```

---

## Web UI 使用

### 界面布局

访问 `http://localhost:8080` 后，你会看到：

**左侧边栏**：
- 表列表，显示每个表的字段数
- 点击展开查看 Schema 详情
- 点击表名切换到该表

**右侧主区域**：
- **Data 视图**：数据表格，支持分页和列选择
- **Manifest 视图**：LSM-Tree 结构和 Compaction 状态

### HTTP API 端点

#### 获取表列表
```
GET /api/tables-html
```

#### 获取表数据
```
GET /api/tables-view/{table_name}?page=1&pageSize=20
```

#### 获取 Manifest
```
GET /api/tables-view/{table_name}/manifest
```

#### 获取 Schema
```
GET /api/tables/{table_name}/schema
```

#### 获取单条数据
```
GET /api/tables/{table_name}/data/{seq}
```

详细 API 文档请参考：[webui/README.md](webui/README.md)

---

## 在你的应用中集成

### 方式 1：使用 WebUI 包

```go
package main

import (
    "net/http"
    "code.tczkiot.com/srdb"
    "code.tczkiot.com/srdb/webui"
)

func main() {
    db, _ := srdb.Open("./mydb")
    defer db.Close()

    // 创建 WebUI handler
    handler := webui.NewWebUI(db)

    // 启动服务器
    http.ListenAndServe(":8080", handler)
}
```

### 方式 2：挂载到现有应用

```go
mux := http.NewServeMux()

// 你的其他路由
mux.HandleFunc("/api/myapp", myHandler)

// 挂载 SRDB Web UI 到 /admin/db 路径
mux.Handle("/admin/db/", http.StripPrefix("/admin/db", webui.NewWebUI(db)))

http.ListenAndServe(":8080", mux)
```

### 方式 3：使用命令工具

将 webui 工具的命令集成到你的应用：

```go
import "code.tczkiot.com/srdb/examples/webui/commands"

// 检查数据
commands.CheckData("./mydb")

// 导出 manifest
commands.DumpManifest("./mydb")

// 启动服务器
commands.StartWebUI("./mydb", ":8080")
```

---

## 开发和调试

### 开发模式

在开发时，使用 `go run` 可以快速测试：

```bash
# 启动服务器
go run main.go serve

# 在另一个终端检查数据
go run main.go check-data

# 检查 SST 文件
go run main.go inspect-all-sst
```

### 清理数据

```bash
# 删除数据目录
rm -rf ./data

# 重新运行
go run main.go serve
```

---

## 注意事项

1. **数据目录**：默认在当前目录创建 `./data` 目录
2. **端口占用**：确保端口未被占用
3. **并发访问**：Web UI 支持多用户并发访问
4. **只读模式**：Web UI 仅用于查看，不提供数据修改功能
5. **生产环境**：建议添加身份验证和访问控制
6. **性能考虑**：大表分页查询性能取决于数据分布

---

## 技术栈

- **后端**：Go 标准库（net/http）
- **前端**：HTMX + 原生 JavaScript + CSS
- **渲染**：服务端 HTML 渲染（Go）
- **数据库**：SRDB (LSM-Tree)
- **部署**：所有静态资源通过 embed 嵌入，无需单独部署

---

## 故障排除

### 常见问题

**1. 启动失败 - 端口被占用**
```bash
Error: listen tcp :8080: bind: address already in use
```
解决：使用 `-addr` 指定其他端口
```bash
go run main.go serve -addr :3000
```

**2. 数据库打开失败**
```bash
Error: failed to open database: invalid header
```
解决：删除损坏的数据目录
```bash
rm -rf ./data
```

**3. SST 文件损坏**
使用 `inspect-sst` 或 `inspect-all-sst` 命令诊断：
```bash
go run main.go inspect-all-sst -dir ./data/logs/sst
```

---

## 更多信息

- **WebUI 详细文档**：[webui/README.md](webui/README.md)
- **SRDB 主文档**：[../README.md](../README.md)
- **Compaction 说明**：[../COMPACTION.md](../COMPACTION.md)
- **压力测试报告**：[../STRESS_TEST_RESULTS.md](../STRESS_TEST_RESULTS.md)

---

## 贡献

欢迎贡献新的示例和工具！请遵循以下规范：

1. 在 `examples/` 下创建新的子目录
2. 提供清晰的 README 文档
3. 添加示例代码和使用说明
4. 更新本文件

---

## 许可证

与 SRDB 项目相同的许可证。