From 7fbcd3a8381c97a749e5bc2665d42e70f7da0b0f Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Thu, 9 Jul 2026 01:18:11 +0800
Subject: [PATCH] docs: document wails binding generation

---
 README.md             | 19 +++++++++++++++++++
 docs/03-tech-stack.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 docs/06-tasks.md      |  2 +-
 docs/current-state.md | 10 +++++++++-
 progress.md           | 12 ++++++++++++
 5 files changed, 83 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ef4cafc..41fb00d 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,25 @@ Windows 下也可以直接运行：
 `dev.bat` 会从 `9245` 开始选择一个空闲 Vite 端口，避免已有 dev server 占用端口时无法打开 GUI。
 开发启动使用快速前端 dev 构建以尽快打开桌面窗口；提交前仍以 `npm run build` 做完整 TypeScript 检查和生产构建。
 
+## 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，不写在前端页面里。
 
 ## 维护约定
diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md
index f861e4c..5d4db47 100644
--- a/docs/03-tech-stack.md
+++ b/docs/03-tech-stack.md
@@ -125,6 +125,48 @@ Windows build 资源：
 
 `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 和热键库的兼容性。
diff --git a/docs/06-tasks.md b/docs/06-tasks.md
index e3c3c5b..68fdbae 100644
--- a/docs/06-tasks.md
+++ b/docs/06-tasks.md
@@ -47,7 +47,7 @@
 | ID | 任务 | 依赖 | 验收要点 | 状态 |
 | --- | --- | --- | --- | --- |
 | T-030 | 建立常用组件示例页 | T-012 | 输入框、多选框、下拉框、多行文本、表格、筛选、分页、状态标签有可运行示例 | DONE |
-| T-031 | 文档化 Wails bindings 生成流程 | T-012 | README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求 | TODO |
+| T-031 | 文档化 Wails bindings 生成流程 | T-012 | README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求 | DONE |
 | T-032 | 补充 Windows 打包验证文档 | T-031 | `wails3 package` 前置条件、输出目录和常见失败处理写入 README 或 docs | TODO |
 | T-033 | 完成一次模板 smoke 清单 | T-023 | 登录、设置、业务样例、日志、统计、组件示例、托盘、热键都按清单验证并记录结果 | TODO |
 | T-034 | 添加 Windows Wails 快捷脚本 | T-001 | `dev.bat` 一行切到项目根目录、补 Go bin PATH、自动选择空闲端口并运行 `wails3 dev`；`build.bat` 一行切到项目根目录、补 Go bin PATH 并运行 `wails3 build`；README、技术栈、当前状态和执行流水已同步 | DONE |
diff --git a/docs/current-state.md b/docs/current-state.md
index c206349..c9df16d 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -23,6 +23,7 @@
 - 前端 runtime：`@wailsio/runtime 3.0.0-alpha.66`
 - 前端框架：Vue 3、Vite、TypeScript、Tailwind CSS、Ant Design Vue
 - 当前 Wails 前端 bindings：由 `wails3 build` / `wails3 generate bindings` 生成的 `.js` 文件。
+- 已文档化 Wails bindings 生成流程：README 和技术栈文档包含固定版本、生成命令、失败处理和提交要求。
 - 本地数据库：SQLite，用户配置目录下 `cmbone/cmbone.db`
 - 当前本地演示账号：`admin` / `admin123`，密码由后端初始化为 salt + SHA-256 hash，不写死在前端。
 - 当前主窗口路由：`/#/` 重定向到 `/#/dashboard`。
@@ -211,9 +212,16 @@ wails3 build
 - 表格区支持关键字、分类、状态筛选，展示分页和状态标签。
 - `go test ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。
 
+同日完成 Wails bindings 生成流程文档：
+
+- README 新增 `Wails Bindings` 章节。
+- `docs/03-tech-stack.md` 新增 `Wails Bindings 生成流程` 章节。
+- 明确固定版本：Go `1.23.0`、Wails CLI `v3.0.0-alpha.9`、`@wailsio/runtime 3.0.0-alpha.66`。
+- 明确生成命令、生成时机、常见失败处理、提交要求和验证命令。
+
 ## 下一步
 
-从 [`06-tasks.md`](06-tasks.md) 领取第一个 `TODO` 任务。目前建议先做 `T-031`：文档化 Wails bindings 生成流程。
+从 [`06-tasks.md`](06-tasks.md) 领取第一个 `TODO` 任务。目前建议先做 `T-032`：补充 Windows 打包验证文档。
 
 ## 当前 blocker
 
diff --git a/progress.md b/progress.md
index 2ce3075..5e2c678 100644
--- a/progress.md
+++ b/progress.md
@@ -341,3 +341,15 @@
 - 非阻塞警告：
   - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
   - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。
+
+### 文档化 Wails bindings 生成流程
+
+- 任务：完成 `T-031`，README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求。
+- 结果：
+  - README 新增 `Wails Bindings` 章节。
+  - `docs/03-tech-stack.md` 新增 `Wails Bindings 生成流程` 章节。
+  - 明确固定版本、生成时机、生成命令、失败处理、提交要求和验证命令。
+- 验证：
+  - `git diff --check` 通过。
+- 非阻塞警告：
+  - 文档任务未改运行代码，未重复执行构建。