qiweimanager-master/二次开发指南.md

企业微信售后客服工具二次开发指南

本文档面向接手本项目的同事，用于快速了解项目结构、开发环境、运行调试、打包发布和常见二开入口。

1. 项目概览

本项目是基于 Wails 的 Windows 桌面工具，后端使用 Go，前端使用 Vue 3 + Vite + Element Plus。主程序负责桌面界面、配置管理、操作日志、企业微信账号展示和业务功能入口；helper 辅助程序负责和企业微信客户端、本地 HTTP 接口、自动回复、售后知识库等能力协作。

核心目录说明：

• main.go、app.go、after_sales*.go、http_client.go：Wails 主程序和业务接口。
• helper/：32 位辅助程序源码，包含企业微信连接、自动回复、售后知识库、素材、AI 调用等逻辑。
• frontend/src/：前端 Vue 页面和组件。
• config/：配置结构、默认配置、材料和知识库相关配置。
• logger/：日志模块。
• requestdata/、eventdata/：企业微信接口请求/事件样例数据。
• scripts/、tools/：打包脚本和辅助工具。
• build/：仅保留 Wails 图标、manifest、安装脚本等构建配置。
• release/：交付验证用安装包和运行依赖，不作为日常开发输出目录。

2. 开发环境

建议环境：

• Windows 10/11。
• Go 1.24.x，项目 go.mod 当前声明 go 1.24.1。
• Node.js + npm，前端使用 Vite。
• Wails v2，建议安装 Wails CLI 后执行 wails doctor 检查环境。
• 企业微信 Windows 客户端，需和 Helper_4.1.33.6009.dll、Loader_4.1.33.6009.dll 对应的版本兼容。

首次拉取后执行：

cd C:\path\to\qiwei
npm install --prefix frontend
go mod download

如本机没有 Wails CLI，可安装：

go install github.com/wailsapp/wails/v2/cmd/wails@latest

3. 本地启动与调试

主程序开发调试：

cd C:\path\to\qiwei
wails dev

前端热更新由 Wails 调用 frontend:dev:watcher，实际执行的是 npm run dev。前端代码主要在 frontend/src 下修改。

辅助程序单独构建通常需要 32 位 Windows 目标：

cd C:\path\to\qiwei\helper
$env:GOARCH='386'
go build -ldflags='-H windowsgui -s -w' -o ..\build\bin\helper.exe .

主程序启动时会优先在运行目录查找 helper_auto_reply.exe，不存在时查找 helper.exe。如果本地调试企业微信相关能力，需保证运行目录内存在对应 helper 和 DLL。

4. 构建与发布

主程序生产构建：

cd C:\path\to\qiwei
wails build

构建输出通常在 build/bin。如果需要制作 Windows 安装包，优先复用 scripts/package-windows.ps1 和 build/windows/installer 下的 NSIS 配置。

本次交付中 release/qiweimanager-amd64-installer.exe 是原项目现有安装包，供同事和客户快速验证当前版本；后续新版本应重新构建并替换发布包。

5. 前后端调用关系

Wails 会把 Go 端绑定方法暴露给前端，前端生成代码位于 frontend/wailsjs。常见流程：

1. 前端 Vue 组件调用 frontend/wailsjs/go/main/App 中的方法。
2. 调用进入 app.go 的 App 方法。
3. 需要企业微信能力时，主程序通过 HTTPClient 请求本机 helper HTTP 接口。
4. helper 调用企业微信相关能力，返回结果给主程序和前端。

新增后端方法时，需要在 App 上新增公开方法，然后重新运行 Wails 开发或构建流程，让 frontend/wailsjs 更新。

6. 常见二开入口

• 自动回复/AI 配置：后端看 app.go 中 GetAutoReplyConfig、SaveAutoReplyConfig、SetAutoReplyEnabled 等方法，helper 侧看 helper/auto_reply*.go。
• 售后知识库：主程序看 after_sales*.go，helper 侧看 helper/after_sales*.go。
• 工程师派单/售后问题：前端看 frontend/src/components/EngineerDispatch.vue、AfterSalesIssues.vue，后端看 after_sales_dispatch.go。
• 企业微信账号与消息发送：主程序看 GetWxWorkAccountList、SendWxWorkData，helper 侧看 wxwork_instance_http.go、http_server.go、client_*。
• 配置管理：看 config/types.go、config/config_manager.go 和 config/config.json。
• 日志与操作记录：看 logger/、operation_record.go、前端 OperationLogs.vue。

7. 配置与敏感信息

config/config.json 当前未包含真实客户密钥，但后续实施时可能写入回调地址、Token、设备码、文件上传地址等信息。真实客户环境中的配置文件、账号状态、知识库索引和运行日志不要提交到 Git。

建议提交前检查：

git status --short
git diff -- config/config.json

如必须提供配置示例，请新增 config/config.example.json，不要提交客户真实配置。

8. 企业微信与 Helper 注意事项

• DLL 文件名中的版本号需要和目标企业微信客户端版本匹配。
• 主程序和 helper 都会写运行日志，日志目录不要提交 Git。
• helper 可能监听本机 HTTP 端口，默认端口由 callbackConfig.httpPort 控制，当前默认 10001。
• 主程序退出时会尝试关闭 helper 进程；调试时如果端口占用或进程残留，可先在任务管理器中结束相关进程。
• 企业微信升级可能导致 DLL 不兼容，需要重新验证账号识别、消息收发和自动回复链路。

9. 提交 Git 前检查清单

提交公司仓库前建议确认：

• frontend/node_modules、frontend/dist、.gocache、build/tmp、日志目录未出现在 git status 中。
• release/ 中只保留需要交付验证的安装包和运行依赖。
• 没有提交客户真实 Token、设备码、账号状态、聊天记录、运行日志、知识库索引。
• go test ./... 能通过，或已记录失败原因。
• 前端依赖可安装，npm run build --prefix frontend 能通过，或已记录失败原因。
• README 和本二开指南能让新同事完成首次启动。

10. 推荐开发流程

1. 从公司 Git 拉取代码。
2. 安装 Go、Node、Wails 环境。
3. 执行 npm install --prefix frontend 和 go mod download。
4. 运行 wails dev 做功能开发。
5. 修改后执行 Go 测试和前端构建。
6. 需要发布时执行 wails build，再用打包脚本生成安装包。
7. 提交前按检查清单确认无本机/客户敏感文件。