# wailskit

**Repository Path**: ichliebedich-DaCapo/wailskit

## Basic Information

- **Project Name**: wailskit
- **Description**: Wails 桌面应用通用工具库（logger/setting/backup/update）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wailskit

Wails 桌面应用通用工具库，从多个 Wails 工程（ZQTable/ZQcom/ElaNote）抽离的纯后端通用功能。

## 设计原则

- **不耦合 Wails 框架**：所有 UI/事件相关操作通过接口注入
- **不耦合业务逻辑**：只提供通用引擎，业务方注入配置和回调
- **按需引入**：包级别 import，未引用的包不编译进二进制

## 包含模块

| 包 | 功能 | 依赖 |
| --- | --- | --- |
| `logger` | 结构化日志（slog + 文件轮转 + 前端转发） | 仅标准库 |
| `setting` | KV 设置存储（GORM） | gorm.io/gorm |
| `backup` | 数据库备份恢复（VACUUM INTO + 文件复制） | gorm.io/gorm |
| `update` | Gitee Releases 在线更新（检查/下载/--replace 自替换） | 仅标准库 |
| `hexutil` | 十六进制字符串与字节数组互转（HEX 编解码） | 仅标准库 |
| `textencoding` | 文本编码转换（17 种编码 + 系统代码页探测） | golang.org/x/text |
| `serial` | Windows 串口底层（枚举/详情/读写/配置校验/波特率检测） | golang.org/x/sys |
| `process` | 当前进程 CPU/内存占用采样 | golang.org/x/sys |
| `debugapi` | 运行时调试/自动化 HTTP JSON-RPC（反射调 App 方法 + UI 事件桥） | 仅标准库 |

## 使用方式

```go
import (
    "gitee.com/ichliebedich-DaCapo/wailskit/logger"
    "gitee.com/ichliebedich-DaCapo/wailskit/setting"
    "gitee.com/ichliebedich-DaCapo/wailskit/backup"
    "gitee.com/ichliebedich-DaCapo/wailskit/update"
    "gitee.com/ichliebedich-DaCapo/wailskit/hexutil"
    "gitee.com/ichliebedich-DaCapo/wailskit/textencoding"
    "gitee.com/ichliebedich-DaCapo/wailskit/serial"
    "gitee.com/ichliebedich-DaCapo/wailskit/process"
    "gitee.com/ichliebedich-DaCapo/wailskit/debugapi"
)
```

### logger

```go
logger.Init(logger.Config{
    Dir:        filepath.Join(dataDir, "logs"),
    Level:      logger.LevelInfo,
    MaxSize:    10 * 1024 * 1024,
    MaxBackups: 5,
})
logger.Info("应用启动", "version", version)
```

### setting

```go
svc := setting.New(db, setting.WithDefaults(map[string]string{
    "app.language": "zh-CN",
    "ui.theme":     "light",
}))
svc.Set("app.language", "en-US")
lang := svc.GetWithDefault("app.language", "zh-CN")
```

### backup

```go
// 备份
err := backup.VacuumInto(db, "/path/to/backup.db")

// 恢复（调用方负责关闭/重开 db 连接）
err := backup.RestoreDatabase(srcPath, dbPath)
```

### update

```go
checker := update.New(update.AppMeta{
    Version:    "v1.0.0",
    ReleaseURL: "https://gitee.com/owner/repo/releases",
    Name:       "MyApp",
}, update.WithEmitter(myEmitter), update.WithQuitter(myQuitter),
   update.WithUserAgent("MyApp-Updater/1.0"),
   update.WithTempDirName("MyApp"))

result, err := checker.CheckForUpdates()
err = checker.InstallUpdate(update.UpdateInstallRequest{Version: "v1.0.1", URL: "..."})
```

自更新替换采用 `--replace` 方案：新版本以独立进程启动
（`exe --replace <目标exe路径> <父进程PID>`），等待旧进程退出后复制替换 exe 并重启。
业务工程需在 `main()` 中、`wails.Run` 之前拦截该参数并实现替换逻辑
（参考 ZQcom/ElaNote 的 `selfupdate_windows.go`）。

### hexutil

```go
hex := hexutil.BytesToHexString([]byte{0x01, 0x02, 0xFF}) // "01 02 FF"
data, err := hexutil.DecodeHexPayload("0xAA,0x01,0x02")   // 宽松解析
data, err = hexutil.ParseHexString("48656C6C6F")          // 严格解析
```

### textencoding

```go
info := textencoding.SystemInfo() // 系统默认编码（Windows GetACP）
encoded, enc, err := textencoding.Encode("中文", "gb2312")
id := textencoding.NormalizeID("CP936", false) // "gbk"
```

### serial

```go
ports, err := serial.ListPorts()   // 枚举真实串口（注册表 SERIALCOMM）
details := serial.ListDetails(ports) // 补全硬件信息（描述/VID/PID/USB 标识）
cfg, err := serial.NormalizeConfig(serial.Config{
    PortName: "COM3", BaudRate: 115200, DataBits: 8, Parity: "none",
    StopBits: "1", ReadTimeoutMs: 80,
})
port, err := serial.Open(cfg)      // 打开串口（CreateFile + DCB 配置）
n, err := port.Read(buf)
port.Close()

// 波特率自动检测（评分/采样/候选生成）
candidates := serial.BuildBaudCandidates(115200)
assessment := serial.SampleBaudCandidate(port, baudRate)
score := serial.AssessBaudSample(sample)

// process：当前进程资源占用
memMB := process.CurrentProcessMemoryMB()
cpu := process.CurrentProcessCPUUsage()
```

`serial` 只提供真实串口底层：端口枚举/详情/读写/配置校验。
虚拟/测试端口、连接管理、事件推送等业务逻辑由调用方实现 `serial.Port` 接口接入。

### debugapi

运行时调试/自动化 API 通用核心：本地 HTTP JSON-RPC + 反射调用 App 方法 + UI 事件桥。
不依赖 Wails 框架，业务工程注入 `EventBridge`（包装 Wails runtime）：

```go
type wailsEvents struct{ ctx context.Context }

func (e wailsEvents) Emit(event string, data any) {
    wailsruntime.EventsEmit(e.ctx, event, data)
}
func (e wailsEvents) On(event string, callback func(...any)) func() {
    return wailsruntime.EventsOn(e.ctx, event, callback)
}

srv := debugapi.New(app, app.GetDataDir())
if err := srv.Start(ctx, wailsEvents{ctx: ctx}); err != nil { ... }
defer srv.Stop()
```

前端需要配合事件桥：监听 `debug:ui-action`、执行已注册 action、回传 `debug:ui-action-result`。
参考 ElaNote 的 `frontend/src/debugActions.ts` 与 `scripts/debug_api.py`。

## 多工程使用

各工程按需 import 子包，版本独立锁定在 go.mod 中。本地多模块开发使用 go.work：

```go
// go.work（不提交到 git）
go 1.26.3

use (
    ./wailskit
    ./Portable_Tools/ZQTable
    ./Portable_Tools/ZQcom
    ./Portable_Tools/ElaNote
)
```

## 版本

- v0.1.0：初始版本，从 ZQTable v1.0.3 抽离（logger/setting/backup/update）
- v0.1.1：update 增强（离线缓存展示字段补齐、PE 有效性校验）
- v0.2.0：新增 hexutil / textencoding / serial 三包，来自 ZQcom 抽离
- v0.3.0：serial 新增波特率自动检测算法（BuildBaudCandidates/SampleBaudCandidate/AssessBaudSample）；新增 process 包（当前进程 CPU/内存采样）
- v0.4.0：新增 debugapi 包（运行时调试/自动化 HTTP JSON-RPC + UI 事件桥，接口注入 Wails 事件）