cmbone/docs/api.md

API 与模块合约

本项目没有固定远程 HTTP API。这里记录 Wails 暴露给前端的 Go 服务方法、本地模块合约，以及目标 provider 边界。

当前已存在服务

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 图片内容。

约束：

• 当前是存量示例服务，后续可并入商品图片 AI 优化样例。
• 失败时返回错误给前端。
• 平台依赖或能力缺失时，不应导致主窗口不可启动。

目标新增服务

AuthService

目标方法：

• Login(username string, password string) (Session, error)：登录并返回会话。
• Logout() error：退出当前会话。
• GetCurrentSession() (Session, error)：读取当前会话。
• SetAuthMode(mode string) error：切换 local 或 remote provider。

约束：

• 前端不得写死固定账号密码。
• LocalAuthProvider 只用于演示和离线模式。
• RemoteAuthProvider 用于真实后端登录。
• 登录成功、失败和退出必须写审计日志。

AuditLogService

目标方法：

• Record(action string, targetType string, targetID string, detail string) error：记录审计事件。
• List(filter AuditLogFilter) ([]AuditLog, error)：分页查询审计日志。
• Export(filter AuditLogFilter) (string, error)：导出审计日志文件。

审计日志记录用户动作，不记录系统堆栈。

AppLogService

目标方法：

• Record(level string, module string, message string, detail string) error：记录运行日志。
• List(filter AppLogFilter) ([]AppLog, error)：分页查询运行日志。
• Export(filter AppLogFilter) (string, error)：导出运行日志文件。

运行日志用于排错，可以记录错误详情和模块名。

ImageOptimizationService

目标方法：

• CreateTask(input ImageTaskInput) (ImageTask, error)：创建图片优化任务。
• ListTasks(filter ImageTaskFilter) ([]ImageTask, error)：查询任务列表。
• GetTask(id int64) (ImageTaskDetail, error)：查询任务详情和结果。
• CancelTask(id int64) error：取消待处理或处理中任务。

MVP 可以先用本地模拟 provider，后续再接真实 AI 后端。

MetricsService

目标方法：

• GetDashboardMetrics() (DashboardMetrics, error)：返回今日处理图片数、成功率、平均耗时、失败数、今日操作日志数。
• GetProcessingTrend(days int) ([]DailyMetric, error)：返回最近 N 天处理趋势。

统计早期直接基于 image_tasks、image_task_results、audit_logs 聚合。

前端绑定

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

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

wails3 generate bindings

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