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

文件：`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` 用于真实后端登录，目前保留边界并返回未配置错误。
- 登录成功、失败和退出必须写审计日志。

## 目标新增服务

### 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`

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

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

```powershell
wails3 generate bindings
```

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