123 lines
4.9 KiB
Markdown
123 lines
4.9 KiB
Markdown
# cmbone
|
||
|
||
基于 SuiDemo 迁移而来的 Wails v3 桌面项目，目标是打造一个 Windows-first、可扩展到其他平台的可复用桌面应用模板。
|
||
|
||
模板内置方向包括：应用壳、设置、登录、主业务模块、操作日志、数据统计和常用业务组件。第一批业务样例以“电商商品图片 AI 优化”为主，用它验证模板是否能支撑真实业务闭环。
|
||
|
||
`ec` 分支开始面向电商运营应用开发，当前新增商品中心，后续会把商品、SKU、渠道、库存和商品图片优化串成业务闭环。
|
||
|
||
## 技术栈
|
||
|
||
- 后端：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`。
|
||
|
||
```powershell
|
||
go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9
|
||
```
|
||
|
||
如果安装后 PowerShell 找不到 `wails3`，把 Go bin 目录加入当前终端 PATH：
|
||
|
||
```powershell
|
||
$env:Path += ";$(go env GOPATH)\bin"
|
||
wails3 doctor
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
.
|
||
├── main.go # Wails 应用入口
|
||
├── internal/
|
||
│ ├── models/ # 后端数据模型
|
||
│ └── services/ # 后端服务和数据库逻辑
|
||
├── platform/ # Windows/macOS 平台差异代码
|
||
├── frontend/
|
||
│ ├── src/ # Vue 前端源码
|
||
│ ├── bindings/ # Wails 前端绑定
|
||
│ └── dist/ # 前端构建产物，供 Go embed 使用
|
||
└── build/ # Wails 构建配置
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
go test ./...
|
||
|
||
cd frontend
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
安装 `wails3` 后可以使用：
|
||
|
||
```bash
|
||
wails3 dev
|
||
wails3 build
|
||
```
|
||
|
||
Windows 下也可以直接运行：
|
||
|
||
```powershell
|
||
.\dev.bat
|
||
.\build.bat
|
||
```
|
||
|
||
`dev.bat` 会从 `9245` 开始选择一个空闲 Vite 端口，避免已有 dev server 占用端口时无法打开 GUI。
|
||
开发启动使用快速前端 dev 构建以尽快打开桌面窗口；提交前仍以 `npm run build` 做完整 TypeScript 检查和生产构建。
|
||
|
||
Windows 打包验证见 [`docs/windows-packaging.md`](docs/windows-packaging.md)。当前默认打包路径是 NSIS，要求本机安装 `makensis`。
|
||
|
||
## Wails Bindings
|
||
|
||
修改 Go 服务的公开方法、参数模型、返回模型，或在 `main.go` 注册新服务后，需要从项目根目录重新生成前端 bindings：
|
||
|
||
```powershell
|
||
$env:Path += ";$(go env GOPATH)\bin"
|
||
wails3 generate bindings -clean=true
|
||
```
|
||
|
||
当前固定使用 `wails3 v3.0.0-alpha.9`，前端 runtime 固定为 `@wailsio/runtime 3.0.0-alpha.66`。不要用 `latest` 混装。
|
||
|
||
常见失败处理：
|
||
|
||
- `wails3` 找不到：先按环境准备安装固定版本，或把 `$(go env GOPATH)\bin` 加入当前终端 PATH。
|
||
- 生成失败：先运行 `go test ./...` 或 `go build -o bin\cmbone.exe .` 修复 Go 编译错误。
|
||
- 前端 import 失效：重新执行 `wails3 generate bindings -clean=true`，前端源码继续使用无扩展名 import。
|
||
|
||
生成后提交 `frontend/bindings` 的变更，并运行 `npm run build` 验证前端类型和打包。
|
||
|
||
本地演示登录账号为 `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`](AGENTS.md)：仓库级 agent 入口。
|
||
- [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：固定开工流程。
|
||
- [`docs/current-state.md`](docs/current-state.md)：当前真实状态和命令。
|
||
- [`docs/06-tasks.md`](docs/06-tasks.md)：任务看板。
|
||
- [`docs/windows-packaging.md`](docs/windows-packaging.md)：Windows 打包验证流程。
|
||
- [`docs/smoke-checklist.md`](docs/smoke-checklist.md)：模板 smoke 验证清单。
|
||
- [`docs/ecommerce-scenario.md`](docs/ecommerce-scenario.md)：`ec` 分支电商场景开发说明。
|
||
- [`progress.md`](progress.md)：执行流水和验证证据。
|
||
|
||
统一验证入口：
|
||
|
||
```powershell
|
||
.\init.ps1
|
||
```
|