3.5 KiB
3.5 KiB
技术栈
后端
- 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.manifestbuild/windows/info.jsonbuild/windows/icon.ico
wails3 build 会重新生成 frontend/bindings，当前 CLI 生成的是 .js bindings。
版本升级规则
- 升级 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 或图表后端。