cmbone/docs/api.md

API 与模块合约

本项目没有远程 HTTP API。这里记录 Wails 暴露给前端的 Go 服务方法和本地模块约定。

AppService

文件：internal/services/appservice.go

• OpenSecondWindow()：打开或显示第二窗口。
• SetLanguage(lang string) error：切换应用语言，并刷新相关菜单/状态。

约束：

• 窗口创建、显示、隐藏和托盘菜单逻辑集中在 AppService。
• 语言资源来自 frontend/src/locales/*.json 的嵌入文件。

AppConfigService

文件：internal/services/appconfig_service.go

• GetAppConfig(key string) (string, error)：读取配置值。
• SetAppConfig(key string, value string) error：保存配置值。
• GetLanguage() string：读取当前语言。
• SetLanguage(lang string) error：保存当前语言。

约束：

• 配置持久化走 SQLite appconfig 表。
• 新增配置项时，必须有默认值和迁移逻辑。

HotkeyService

文件：internal/services/hotkey_service.go

• GetHotkeys() ([]models.Hotkey, error)：读取热键配置。
• UpHotkey(id int, key int, modifier int) error：更新热键配置并重新注册。

约束：

• 热键数据来自 SQLite hotkeys 表。
• 平台注册通过 platform/ 实现，服务层不直接写平台细节。
• 更新失败时必须返回错误，不只打印日志。

SystemInfo

文件：internal/services/systeminfo.go

• GetOS() string：返回当前系统标识。

OCRService

文件：internal/services/ocr_service.go

• RecognizeImageBase64(base64str string) (string, error)：识别 base64 图片内容。

约束：

• 失败时返回错误给前端。
• 平台依赖或能力缺失时，不应导致主窗口不可启动。

前端绑定

绑定目录：frontend/bindings/cmbone/internal/services

服务签名变化后优先执行：

wails3 generate bindings

如果本地无法生成 bindings，只允许根据现有绑定模式做最小修正，并在 progress.md 写清原因和验证结果。