184 lines
5.2 KiB
Markdown
184 lines
5.2 KiB
Markdown
# 技术栈
|
||
|
||
## 后端
|
||
|
||
- 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 安装命令：
|
||
|
||
```powershell
|
||
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。
|
||
- 只沉淀项目级组合组件和使用示例，例如筛选表格、设置项、状态标签、日志列表。
|
||
|
||
## 目录职责
|
||
|
||
```text
|
||
.
|
||
├── main.go # Wails 应用入口、服务注册、资源嵌入
|
||
├── internal/
|
||
│ ├── models/ # 数据模型
|
||
│ └── services/ # Wails 服务、配置、数据库、热键、OCR
|
||
├── platform/ # Windows / macOS 平台差异实现
|
||
├── frontend/
|
||
│ ├── src/ # Vue 源码
|
||
│ ├── bindings/ # Wails 生成的前端绑定
|
||
│ └── dist/ # 前端构建产物，git 忽略
|
||
├── build/ # Wails 打包配置
|
||
└── docs/ # Harness Coding 文档
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
安装前端依赖：
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm install
|
||
```
|
||
|
||
后端测试：
|
||
|
||
```powershell
|
||
go test ./...
|
||
```
|
||
|
||
前端构建：
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm run build
|
||
```
|
||
|
||
前端类型检查：
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm run typecheck
|
||
```
|
||
|
||
后端编译：
|
||
|
||
```powershell
|
||
go build -o bin\cmbone.exe .
|
||
```
|
||
|
||
统一验证入口：
|
||
|
||
```powershell
|
||
.\init.ps1
|
||
```
|
||
|
||
开发启动：
|
||
|
||
```powershell
|
||
wails3 dev
|
||
```
|
||
|
||
Wails 构建：
|
||
|
||
```powershell
|
||
wails3 build
|
||
```
|
||
|
||
Windows 快捷脚本：
|
||
|
||
```powershell
|
||
.\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` 列表注册新服务。
|
||
|
||
从项目根目录执行：
|
||
|
||
```powershell
|
||
$env:Path += ";$(go env GOPATH)\bin"
|
||
wails3 generate bindings -clean=true
|
||
```
|
||
|
||
生成结果位于 `frontend/bindings/`。当前 Wails v3 alpha CLI 生成 `.js` 文件，前端源码使用无扩展名 import，例如：
|
||
|
||
```ts
|
||
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 或图表后端。
|