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：保存当前语言。
• GetSettingsSchema() ([]models.AppSettingGroup, error)：返回统一设置 schema、默认值和当前值。

约束：

• 配置持久化走 SQLite appconfig 表。
• 统一设置 schema 定义在 internal/services/settings_schema.go，覆盖主题、语言、窗口行为、快捷键、数据目录、日志策略和登录 provider 配置。
• 新增配置项时，必须补充 key、类型、默认值、说明和必要选项，并同步初始化 SQL。
• SetAppConfig 会校验 schema 已知配置项；只读项不能通过通用配置接口修改。
• 快捷键 schema 项只用于统一展示，实际热键更新仍走 HotkeyService。

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

文件：internal/services/auth_service.go

• GetAuthProviders() []models.AuthProviderOption：返回可用 provider 列表。
• GetAuthMode() string：读取当前 auth provider。
• SetAuthMode(mode string) error：切换 local 或 remote provider。
• Login(provider string, username string, password string) (models.AuthSession, error)：登录并返回会话。
• Logout() error：退出当前会话。
• GetCurrentSession() (models.AuthSession, error)：读取当前有效会话；无会话时返回空 session。

约束：

• 前端不得写死固定账号密码。
• LocalAuthProvider 只用于演示和离线模式，默认账号来自后端初始化配置。
• 默认本地演示账号：admin / admin123；密码在数据库中以 salt + SHA-256 hash 保存，不在前端页面或绑定中保存。
• RemoteAuthProvider 用于真实后端登录，目前保留边界并返回未配置错误。
• 登录成功、失败和退出必须写审计日志。

ImageOptimizationService

文件：internal/services/image_optimization_service.go

• CreateTask(input models.ImageTaskInput) (models.ImageTaskDetail, error)：创建本地模拟图片优化任务，并写入任务和结果。
• ListTasks(filter models.ImageTaskFilter) ([]models.ImageTask, error)：按状态、操作类型分页查询任务。
• GetTask(id int64) (models.ImageTaskDetail, error)：查询任务和结果详情。
• CancelTask(id int64) error：取消待处理或处理中任务；当前模拟任务会立即成功，通常不可取消。

约束：

• 当前 provider 是本地模拟实现，不调用真实 AI 后端。
• 任务主表为 image_tasks，结果表为 image_task_results。
• 模拟任务会生成成功状态、耗时、输出路径和前后文件大小字段，供后续页面和统计模块使用。

AuditLogService

文件：internal/services/log_service.go

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

约束：

审计日志记录用户动作，不记录系统堆栈。 当前已接入登录、设置变更和图片任务创建。

AppLogService

文件：internal/services/log_service.go

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

约束：

运行日志用于排错，可以记录错误详情和模块名。 当前已接入图片任务创建失败和服务内部错误路径。

MetricsService

文件：internal/services/metrics_service.go

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

约束：

• 统计按本机本地自然日计算，查询时转换为 UTC 字符串匹配现有 created_at。
• days <= 0 时默认 7 天，最大 30 天。
• 当前直接基于 image_tasks 和 audit_logs 聚合，不新增统计缓存表。

前端绑定

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

当前 Wails v3 CLI 会生成 .js bindings。前端源码使用无扩展名 import，允许 Vite 解析到这些 .js 文件。

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

wails3 generate bindings

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