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

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

## 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. 提交前按检查清单确认无本机/客户敏感文件。