Initial qiwei secondary development handoff

二次开发指南.md

@@ -0,0 +1,139 @@
+# 企业微信售后客服工具二次开发指南
+
+本文档面向接手本项目的同事，用于快速了解项目结构、开发环境、运行调试、打包发布和常见二开入口。
+
+## 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. 提交前按检查清单确认无本机/客户敏感文件。