cmbone/docs/03-tech-stack.md

技术栈

后端

• Go：1.23.0
• 桌面框架：github.com/wailsapp/wails/v3 v3.0.0-alpha.9
• 本地数据库：modernc.org/sqlite v1.38.2
• 系统热键：golang.design/x/hotkey v0.4.1

运行策略：

• Windows 10+ 是主要目标环境。
• macOS / Linux 保留代码边界，但不在 MVP 承诺完整体验。
• 平台差异统一放在 platform/ 或明确 provider 层。

Wails CLI 安装命令：

go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9

不要直接安装 wails3@latest，避免 CLI、Go SDK 和前端 runtime 版本不匹配。

前端

• Vue：^3.2.45
• TypeScript：^4.9.3
• Vite：^8.1.3
• Wails runtime：@wailsio/runtime 3.0.0-alpha.66
• UI：Ant Design Vue ^4.2.6
• 样式：Tailwind CSS ^3.4.1
• 国际化：Vue I18n ^11.1.5

UI 策略：

• 不自研完整组件库。
• 优先复用 Ant Design Vue。
• 只沉淀项目级组合组件和使用示例，例如筛选表格、设置项、状态标签、日志列表。

目录职责

.
├── main.go                  # Wails 应用入口、服务注册、资源嵌入
├── internal/
│   ├── models/              # 数据模型
│   └── services/            # Wails 服务、配置、数据库、热键、OCR
├── platform/                # Windows / macOS 平台差异实现
├── frontend/
│   ├── src/                 # Vue 源码
│   ├── bindings/            # Wails 生成的前端绑定
│   └── dist/                # 前端构建产物，git 忽略
├── build/                   # Wails 打包配置
└── docs/                    # Harness Coding 文档

常用命令

安装前端依赖：

cd frontend
npm install

后端测试：

go test ./...

前端构建：

cd frontend
npm run build

前端类型检查：

cd frontend
npm run typecheck

后端编译：

go build -o bin\cmbone.exe .

统一验证入口：

.\init.ps1

开发启动：

wails3 dev

Wails 构建：

wails3 build

Windows 快捷脚本：

.\dev.bat
.\build.bat

dev.bat 会先切到项目根目录，把 Go bin 加入当前进程 PATH，再从 9245 开始选择空闲端口运行 wails3 dev。 开发启动链路使用 npm run build:dev 做快速前端 dev 构建，避免 vue-tsc 阻塞 GUI 打开；完整类型检查仍由 npm run build 或 npm run typecheck 执行。

Windows build 资源：

• build/windows/wails.exe.manifest
• build/windows/info.json
• build/windows/icon.ico

wails3 build 会重新生成 frontend/bindings，当前 CLI 生成的是 .js bindings。

Wails Bindings 生成流程

版本要求：

• Go：1.23.0
• Wails CLI：wails3 v3.0.0-alpha.9
• 前端 runtime：@wailsio/runtime 3.0.0-alpha.66

需要重新生成 bindings 的情况：

• 新增、删除或改名 Wails 服务。
• 修改 Go 服务的公开方法签名。
• 修改前端需要使用的请求模型、返回模型或 JSON 字段。
• 在 main.go 的 Services 列表注册新服务。

从项目根目录执行：

$env:Path += ";$(go env GOPATH)\bin"
wails3 generate bindings -clean=true

生成结果位于 frontend/bindings/。当前 Wails v3 alpha CLI 生成 .js 文件，前端源码使用无扩展名 import，例如：

import { ListTasks } from '../../../bindings/cmbone/internal/services/imageoptimizationservice'

失败处理：

• wails3 找不到：确认已安装固定版本，并把 $(go env GOPATH)\bin 加入当前 PowerShell PATH。
• 版本不匹配：不要用 latest，重新安装 github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9。
• Go 编译错误：先运行 go test ./... 或 go build -o bin\cmbone.exe .，修复服务或模型错误后再生成。
• 前端类型或 import 错误：重新执行 wails3 generate bindings -clean=true，再运行 cd frontend && npm run build。
• 本机暂时无法生成：只允许按已有 binding 模式做最小手工修正，并在 progress.md 写清原因、范围和后续补救。

提交要求：

• 服务或模型变更必须和对应 frontend/bindings 变更同一个 task 提交。
• 提交前至少运行 go test ./...、cd frontend && npm run build。
• 涉及完整启动或打包链路时，再运行 go build -o bin\cmbone.exe . 或 cmd /c build.bat。

版本升级规则

• 升级 Go 前，先确认 Wails v3 alpha、SQLite 和热键库的兼容性。
• 升级 Wails 后，同时检查 @wailsio/runtime 和 frontend/bindings。
• 升级 Vite / TypeScript 后，必须跑 npm run build。
• 依赖升级必须单独提交，不和业务功能混在一起。

目标模块技术边界

• 设置：通过 settings_schema.go 集中定义 key、类型、默认值、说明、选项和只读策略。
• 登录：通过 AuthProvider 支持本地固定账号和真实后端，不在前端写死密码。
• 主业务：商品图片 AI 优化通过服务层封装，MVP 可先用本地模拟 provider。
• 操作日志：审计日志进 SQLite，运行日志可进 SQLite 或本地滚动日志文件。
• 数据统计：MVP 直接 SQL 聚合，不提前引入 BI 或图表后端。