140 lines
6.3 KiB
Markdown
140 lines
6.3 KiB
Markdown
# 企业微信售后客服工具二次开发指南
|
||
|
||
本文档面向接手本项目的同事，用于快速了解项目结构、开发环境、运行调试、打包发布和常见二开入口。
|
||
|
||
## 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` 对应的版本兼容。
|
||
|
||
首次拉取后执行：
|
||
|
||
```powershell
|
||
cd C:\path\to\qiwei
|
||
npm install --prefix frontend
|
||
go mod download
|
||
```
|
||
|
||
如本机没有 Wails CLI，可安装：
|
||
|
||
```powershell
|
||
go install github.com/wailsapp/wails/v2/cmd/wails@latest
|
||
```
|
||
|
||
## 3. 本地启动与调试
|
||
|
||
主程序开发调试：
|
||
|
||
```powershell
|
||
cd C:\path\to\qiwei
|
||
wails dev
|
||
```
|
||
|
||
前端热更新由 Wails 调用 `frontend:dev:watcher`，实际执行的是 `npm run dev`。前端代码主要在 `frontend/src` 下修改。
|
||
|
||
辅助程序单独构建通常需要 32 位 Windows 目标：
|
||
|
||
```powershell
|
||
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. 构建与发布
|
||
|
||
主程序生产构建：
|
||
|
||
```powershell
|
||
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。
|
||
|
||
建议提交前检查：
|
||
|
||
```powershell
|
||
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. 提交前按检查清单确认无本机/客户敏感文件。
|