cmbone

基于 SuiDemo 迁移而来的 Wails v3 桌面项目，目标是打造一个 Windows-first、可扩展到其他平台的可复用桌面应用模板。

模板内置方向包括：应用壳、设置、登录、主业务模块、操作日志、数据统计和常用业务组件。第一批业务样例以“电商商品图片 AI 优化”为主，用它验证模板是否能支撑真实业务闭环。

技术栈

• 后端：Go 1.23.0、Wails v3.0.0-alpha.9、SQLite
• 前端：Vue 3、TypeScript、Vite、Tailwind CSS、Ant Design Vue
• 当前功能：多语言、主题切换、统一设置 schema、主窗口状态恢复、本地配置、快捷键、本地登录 provider、商品图片 AI 优化页面、本地模拟图片优化任务、审计日志、运行日志、P0 数据统计服务、OCR 示例
• 目标模板模块：登录、设置、主业务、审计日志、运行日志、数据统计、常用组件示例

环境准备

当前项目按本机 Go 1.23.0 锁定依赖，不要直接安装 wails3@latest。

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

如果安装后 PowerShell 找不到 wails3，把 Go bin 目录加入当前终端 PATH：

$env:Path += ";$(go env GOPATH)\bin"
wails3 doctor

目录结构

.
├── main.go                  # Wails 应用入口
├── internal/
│   ├── models/              # 后端数据模型
│   └── services/            # 后端服务和数据库逻辑
├── platform/                # Windows/macOS 平台差异代码
├── frontend/
│   ├── src/                 # Vue 前端源码
│   ├── bindings/            # Wails 前端绑定
│   └── dist/                # 前端构建产物，供 Go embed 使用
└── build/                   # Wails 构建配置

常用命令

go test ./...

cd frontend
npm install
npm run build

安装 wails3 后可以使用：

wails3 dev
wails3 build

Windows 下也可以直接运行：

.\dev.bat
.\build.bat

dev.bat 会从 9245 开始选择一个空闲 Vite 端口，避免已有 dev server 占用端口时无法打开 GUI。 开发启动使用快速前端 dev 构建以尽快打开桌面窗口；提交前仍以 npm run build 做完整 TypeScript 检查和生产构建。

本地演示登录账号为 admin / admin123；密码由后端初始化为 hash，不写在前端页面里。

维护约定

• Go 模块名统一为 cmbone。
• 当前依赖按系统 Go 1.23.0 锁定，升级 Go 前不要随意升级 Wails、SQLite 或热键库。
• 修改后端服务后，优先使用 wails3 generate bindings 重新生成 frontend/bindings；如果本机没有 CLI，只做小范围手动绑定。
• 提交前至少运行 go test ./... 和 npm run build。
• 模板能力按任务逐步落地，不一次性堆完整平台；优先保证 Windows 10+ 体验和可维护性。

Harness Coding 文档

本项目已接入 Harness Coding 文档，用于让后续维护者和 AI coding agent 快速恢复上下文、领取任务并验证改动。

• AGENTS.md：仓库级 agent 入口。
• docs/00-ai-start-here.md：固定开工流程。
• docs/current-state.md：当前真实状态和命令。
• docs/06-tasks.md：任务看板。
• progress.md：执行流水和验证证据。

统一验证入口：

.\init.ps1