208 lines
6.5 KiB
Markdown
208 lines
6.5 KiB
Markdown
# 架构设计
|
||
|
||
## 总览
|
||
|
||
```text
|
||
main.go
|
||
├─ Wails application
|
||
├─ embedded frontend/dist
|
||
├─ embedded frontend/src/locales/*.json
|
||
└─ services
|
||
├─ AppService
|
||
├─ AppConfigService
|
||
├─ HotkeyService
|
||
├─ SystemInfo
|
||
├─ OCRService # 当前存量示例
|
||
├─ AuthService # 目标模块
|
||
├─ AuditLogService # 目标模块
|
||
├─ AppLogService # 目标模块
|
||
├─ ImageOptimizationService # 目标业务样例
|
||
└─ MetricsService # 目标模块
|
||
|
||
frontend/src
|
||
├─ router
|
||
├─ layouts
|
||
├─ pages
|
||
├─ components
|
||
├─ modules
|
||
├─ utils
|
||
└─ locales
|
||
```
|
||
|
||
前端通过 `frontend/bindings` 调用 Wails 暴露的 Go 服务。后端服务访问本地 SQLite、平台热键、文件系统、真实后端或 AI provider。
|
||
|
||
## 后端边界
|
||
|
||
- `main.go`：只负责应用组装、资源嵌入、服务注册和启动。
|
||
- `internal/models/`：定义数据库和服务返回的结构体。
|
||
- `internal/services/store.go`：负责 SQLite 连接、迁移和基础读写。
|
||
- `internal/services/appservice.go`：负责窗口、托盘、语言资源和应用生命周期。
|
||
- `internal/services/appconfig_service.go`：负责配置读写的 Wails 服务边界。
|
||
- `internal/services/hotkey_service.go`：负责热键读取、更新和重新注册。
|
||
- `internal/services/ocr_service.go`：当前 OCR 存量示例，后续可演进为图片 AI 能力的一部分。
|
||
- `platform/`：隔离 Windows / macOS 热键和系统能力差异。
|
||
|
||
目标新增边界：
|
||
|
||
- `AuthService`：登录、退出、会话读取；内部通过 `AuthProvider` 接入本地固定账号或真实后端。
|
||
- `AuditLogService`：记录和查询用户操作审计日志。
|
||
- `AppLogService`：记录和查询运行错误，必要时可落本地滚动日志文件。
|
||
- `ImageOptimizationService`：商品图片 AI 优化任务的创建、状态、结果和失败原因。
|
||
- `MetricsService`：对业务任务和日志做基础聚合，输出统计卡片和趋势数据。
|
||
|
||
服务之间不要互相绕过边界直接操作平台实现。新增平台能力时，优先放在 `platform/`，再由 `internal/services/` 暴露稳定方法。
|
||
|
||
## 前端边界
|
||
|
||
- `frontend/src/router/index.ts`：维护页面路由。
|
||
- `frontend/src/layouts/`：目标目录，放登录布局和主应用布局。
|
||
- `frontend/src/modules/auth/`：目标目录，放登录页面、会话状态和 provider 调用。
|
||
- `frontend/src/modules/settings/`：目标目录，放设置页和设置项。
|
||
- `frontend/src/modules/image-optimizer/`：目标目录，放商品图片 AI 优化样例。
|
||
- `frontend/src/modules/logs/`：目标目录，放审计日志和运行日志页面。
|
||
- `frontend/src/modules/metrics/`：目标目录，放统计卡片和趋势图。
|
||
- `frontend/src/modules/components-demo/`：目标目录，放常用组件示例。
|
||
- `frontend/src/components/`：通用展示组件和组合控件。
|
||
- `frontend/src/utils/`：国际化、主题、OS、热键等工具函数。
|
||
- `frontend/bindings/`：由 Wails 生成或按 Wails 合约维护，不写业务逻辑。
|
||
|
||
## 登录架构
|
||
|
||
登录必须通过 provider 边界实现：
|
||
|
||
```text
|
||
AuthService
|
||
└─ AuthProvider
|
||
├─ LocalAuthProvider
|
||
└─ RemoteAuthProvider
|
||
```
|
||
|
||
- `LocalAuthProvider`：用于模板演示和离线模式，固定账号密码由后端配置或安全哈希保存，不写死在前端。
|
||
- `RemoteAuthProvider`：用于真实后端，负责请求登录接口并保存 token / session。
|
||
- 前端只关心登录、退出和当前会话，不关心 provider 细节。
|
||
|
||
## 日志架构
|
||
|
||
审计日志和运行日志分开：
|
||
|
||
- 审计日志：记录用户可解释动作，支持查询、筛选和导出。
|
||
- 运行日志：记录系统错误和排错信息，支持按时间、级别、模块查看。
|
||
|
||
审计日志用于“责任链”，运行日志用于“故障定位”。不要用一张表混合两种语义。
|
||
|
||
## 数据模型
|
||
|
||
SQLite 数据库位于用户配置目录下的 `cmbone/cmbone.db`，不进入 git。
|
||
|
||
当前核心表：
|
||
|
||
```sql
|
||
hotkeys(
|
||
id INTEGER PRIMARY KEY,
|
||
keycode INTEGER,
|
||
modifiers INTEGER,
|
||
description TEXT,
|
||
target TEXT
|
||
)
|
||
```
|
||
|
||
```sql
|
||
appconfig(
|
||
id INTEGER PRIMARY KEY,
|
||
key TEXT,
|
||
type TEXT,
|
||
value TEXT,
|
||
description TEXT,
|
||
state INTEGER
|
||
)
|
||
```
|
||
|
||
目标新增表：
|
||
|
||
```sql
|
||
auth_sessions(
|
||
id INTEGER PRIMARY KEY,
|
||
user_id TEXT,
|
||
username TEXT,
|
||
provider TEXT,
|
||
token TEXT,
|
||
created_at DATETIME,
|
||
expires_at DATETIME,
|
||
active INTEGER
|
||
)
|
||
```
|
||
|
||
```sql
|
||
audit_logs(
|
||
id INTEGER PRIMARY KEY,
|
||
actor TEXT,
|
||
action TEXT,
|
||
target_type TEXT,
|
||
target_id TEXT,
|
||
detail TEXT,
|
||
created_at DATETIME
|
||
)
|
||
```
|
||
|
||
```sql
|
||
app_logs(
|
||
id INTEGER PRIMARY KEY,
|
||
level TEXT,
|
||
module TEXT,
|
||
message TEXT,
|
||
detail TEXT,
|
||
created_at DATETIME
|
||
)
|
||
```
|
||
|
||
```sql
|
||
image_tasks(
|
||
id INTEGER PRIMARY KEY,
|
||
source_path TEXT,
|
||
status TEXT,
|
||
operation TEXT,
|
||
duration_ms INTEGER,
|
||
error_message TEXT,
|
||
created_at DATETIME,
|
||
updated_at DATETIME
|
||
)
|
||
```
|
||
|
||
```sql
|
||
image_task_results(
|
||
id INTEGER PRIMARY KEY,
|
||
task_id INTEGER,
|
||
output_path TEXT,
|
||
before_size INTEGER,
|
||
after_size INTEGER,
|
||
created_at DATETIME
|
||
)
|
||
```
|
||
|
||
统计数据早期直接用 SQL 聚合，不急着落 `daily_metrics` 缓存表。数据量变大后再增加缓存表。
|
||
|
||
迁移要求：
|
||
|
||
- 初始化必须幂等。
|
||
- 新字段必须有默认值或迁移逻辑。
|
||
- schema 变化必须同步 `store_test.go`、`api.md` 和 `current-state.md`。
|
||
|
||
## 窗口与页面
|
||
|
||
- 主窗口路由：`/#/`
|
||
- 第二窗口路由：`/#/second`
|
||
- 目标主应用路由：登录页、Dashboard、图片优化、日志、统计、设置、组件示例。
|
||
- 托盘菜单由 `AppService` 配置。
|
||
- 热键触发目标可以是打开主窗口、打开快捷功能或创建快速任务。
|
||
|
||
窗口策略：主窗口承载长期业务操作，默认应充分利用屏幕空间；第二窗口只保留轻量快捷功能，不承载复杂业务流程。
|
||
|
||
## 关键风险
|
||
|
||
- 范围膨胀：模板容易变成“大而全平台”，必须按任务小步交付。
|
||
- Wails v3 仍是 alpha，CLI、Go 模块和 runtime 必须保持匹配。
|
||
- bindings 若与 Go 服务签名不一致，前端会在运行时失败。
|
||
- 登录 provider、AI provider 和日志模块必须有清晰边界，否则后续替换困难。
|
||
- OCR、热键、托盘依赖平台能力，跨平台修改必须分别验证。
|
||
- Vite 构建可能出现 chunk size warning，警告不等于失败，但需要避免无节制增加前端体积。
|