Complete Mini Program customer service management implementation with tests and documentation

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

MINIAPP_KEFU_SERVICE.md

@@ -0,0 +1,80 @@
+# WeChat Mini Program Customer Service Management
+
+This document describes the new customer service management functionality added to the WxJava Mini Program SDK.
+
+## Overview
+
+Previously, the mini program module only had:
+- `WxMaCustomserviceWorkService` - For binding mini programs to enterprise WeChat customer service
+- `WxMaMsgService.sendKefuMsg()` - For sending customer service messages
+
+The new `WxMaKefuService` adds comprehensive customer service management capabilities:
+
+## Features
+
+### Customer Service Account Management
+- `kfList()` - Get list of customer service accounts
+- `kfAccountAdd()` - Add new customer service account  
+- `kfAccountUpdate()` - Update customer service account
+- `kfAccountDel()` - Delete customer service account
+
+### Session Management
+- `kfSessionCreate()` - Create customer service session
+- `kfSessionClose()` - Close customer service session
+- `kfSessionGet()` - Get customer session status
+- `kfSessionList()` - Get customer service session list
+
+## Usage Example
+
+```java
+// Get the customer service management service
+WxMaKefuService kefuService = wxMaService.getKefuService();
+
+// Add a new customer service account
+WxMaKfAccountRequest request = WxMaKfAccountRequest.builder()
+    .kfAccount("service001@example")
+    .kfNick("Customer Service 001")
+    .kfPwd("password123")
+    .build();
+boolean result = kefuService.kfAccountAdd(request);
+
+// Create a session between user and customer service
+boolean sessionResult = kefuService.kfSessionCreate("user_openid", "service001@example");
+
+// Get customer service list
+WxMaKfList kfList = kefuService.kfList();
+```
+
+## Bean Classes
+
+### Request Objects
+- `WxMaKfAccountRequest` - For customer service account operations
+- `WxMaKfSessionRequest` - For session operations
+
+### Response Objects  
+- `WxMaKfInfo` - Customer service account information
+- `WxMaKfList` - List of customer service accounts
+- `WxMaKfSession` - Session information
+- `WxMaKfSessionList` - List of sessions
+
+## API Endpoints
+
+The service uses the following WeChat Mini Program API endpoints:
+- `https://api.weixin.qq.com/cgi-bin/customservice/getkflist` - Get customer service list
+- `https://api.weixin.qq.com/customservice/kfaccount/add` - Add customer service account
+- `https://api.weixin.qq.com/customservice/kfaccount/update` - Update customer service account
+- `https://api.weixin.qq.com/customservice/kfaccount/del` - Delete customer service account
+- `https://api.weixin.qq.com/customservice/kfsession/create` - Create session
+- `https://api.weixin.qq.com/customservice/kfsession/close` - Close session
+- `https://api.weixin.qq.com/customservice/kfsession/getsession` - Get session
+- `https://api.weixin.qq.com/customservice/kfsession/getsessionlist` - Get session list
+
+## Integration
+
+The service is automatically available through the main `WxMaService` interface:
+
+```java
+WxMaKefuService kefuService = wxMaService.getKefuService();
+```
+
+This fills the gap mentioned in the original issue and provides full customer service management capabilities for WeChat Mini Programs.

weixin-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaKefuServiceImplTest.java

@@ -0,0 +1,60 @@
+package cn.binarywang.wx.miniapp.api.impl;
+
+import cn.binarywang.wx.miniapp.api.WxMaKefuService;
+import cn.binarywang.wx.miniapp.api.WxMaService;
+import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfList;
+import cn.binarywang.wx.miniapp.bean.kefu.request.WxMaKfAccountRequest;
+import me.chanjar.weixin.common.error.WxErrorException;
+import org.testng.Assert;
+import org.testng.annotations.Test;
+
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 小程序客服管理服务测试.
+ *
+ * @author <a href="https://github.com/binarywang">Binary Wang</a>
+ */
+public class WxMaKefuServiceImplTest {
+
+  @Test
+  public void testKfList() throws WxErrorException {
+    WxMaService service = mock(WxMaService.class);
+    when(service.get(anyString(), any())).thenReturn("{\"kf_list\":[]}");
+
+    WxMaKefuService kefuService = new WxMaKefuServiceImpl(service);
+    WxMaKfList result = kefuService.kfList();
+
+    Assert.assertNotNull(result);
+    Assert.assertNotNull(result.getKfList());
+    Assert.assertEquals(result.getKfList().size(), 0);
+  }
+
+  @Test
+  public void testKfAccountAdd() throws WxErrorException {
+    WxMaService service = mock(WxMaService.class);
+    when(service.post(anyString(), anyString())).thenReturn("{\"errcode\":0}");
+
+    WxMaKefuService kefuService = new WxMaKefuServiceImpl(service);
+    WxMaKfAccountRequest request = WxMaKfAccountRequest.builder()
+        .kfAccount("test@kfaccount")
+        .kfNick("测试客服")
+        .kfPwd("password")
+        .build();
+
+    boolean result = kefuService.kfAccountAdd(request);
+    Assert.assertTrue(result);
+  }
+
+  @Test
+  public void testKfSessionCreate() throws WxErrorException {
+    WxMaService service = mock(WxMaService.class);
+    when(service.post(anyString(), anyString())).thenReturn("{\"errcode\":0}");
+
+    WxMaKefuService kefuService = new WxMaKefuServiceImpl(service);
+    boolean result = kefuService.kfSessionCreate("test_openid", "test@kfaccount");
+    Assert.assertTrue(result);
+  }
+}

weixin-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/demo/WxMaKefuServiceDemo.java

@@ -0,0 +1,84 @@
+package cn.binarywang.wx.miniapp.demo;
+
+import cn.binarywang.wx.miniapp.api.WxMaService;
+import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfList;
+import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfSession;
+import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfSessionList;
+import cn.binarywang.wx.miniapp.bean.kefu.request.WxMaKfAccountRequest;
+import me.chanjar.weixin.common.error.WxErrorException;
+
+/**
+ * 小程序客服管理功能使用示例.
+ * 
+ * @author <a href="https://github.com/binarywang">Binary Wang</a>
+ */
+public class WxMaKefuServiceDemo {
+
+  private final WxMaService wxMaService;
+
+  public WxMaKefuServiceDemo(WxMaService wxMaService) {
+    this.wxMaService = wxMaService;
+  }
+
+  /**
+   * 演示客服账号管理功能
+   */
+  public void demonstrateCustomerServiceManagement() throws WxErrorException {
+    // 1. 获取客服列表
+    WxMaKfList kfList = wxMaService.getKefuService().kfList();
+    System.out.println("当前客服数量: " + kfList.getKfList().size());
+
+    // 2. 添加新客服账号
+    WxMaKfAccountRequest addRequest = WxMaKfAccountRequest.builder()
+        .kfAccount("service001@example")
+        .kfNick("客服001")
+        .kfPwd("password123")
+        .build();
+    
+    boolean addResult = wxMaService.getKefuService().kfAccountAdd(addRequest);
+    System.out.println("添加客服账号结果: " + addResult);
+
+    // 3. 更新客服账号信息
+    WxMaKfAccountRequest updateRequest = WxMaKfAccountRequest.builder()
+        .kfAccount("service001@example")
+        .kfNick("高级客服001")
+        .build();
+    
+    boolean updateResult = wxMaService.getKefuService().kfAccountUpdate(updateRequest);
+    System.out.println("更新客服账号结果: " + updateResult);
+  }
+
+  /**
+   * 演示客服会话管理功能
+   */
+  public void demonstrateSessionManagement() throws WxErrorException {
+    String userOpenid = "user_openid_example";
+    String kfAccount = "service001@example";
+
+    // 1. 创建客服会话
+    boolean createResult = wxMaService.getKefuService().kfSessionCreate(userOpenid, kfAccount);
+    System.out.println("创建会话结果: " + createResult);
+
+    // 2. 获取用户会话状态
+    WxMaKfSession session = wxMaService.getKefuService().kfSessionGet(userOpenid);
+    System.out.println("用户当前会话客服: " + session.getKfAccount());
+
+    // 3. 获取客服的会话列表
+    WxMaKfSessionList sessionList = wxMaService.getKefuService().kfSessionList(kfAccount);
+    System.out.println("客服当前会话数量: " + sessionList.getSessionList().size());
+
+    // 4. 关闭客服会话
+    boolean closeResult = wxMaService.getKefuService().kfSessionClose(userOpenid, kfAccount);
+    System.out.println("关闭会话结果: " + closeResult);
+  }
+
+  /**
+   * 演示客服账号删除功能
+   */
+  public void demonstrateAccountDeletion() throws WxErrorException {
+    String kfAccount = "service001@example";
+    
+    boolean deleteResult = wxMaService.getKefuService().kfAccountDel(kfAccount);
+    System.out.println("删除客服账号结果: " + deleteResult);
+  }
+}