Merge #56

56: feat: add ListUnassignedExternalContact TransferExternalContact GetTransferExternalContactResult TransferGroupChatExternalContact r=xen0n a=w3xse7en

ListUnassignedExternalContact doc:https://open.work.weixin.qq.com/api/doc/90000/90135/92124
TransferExternalContact doc:https://open.work.weixin.qq.com/api/doc/90000/90135/92125
GetTransferExternalContactResult doc:https://open.work.weixin.qq.com/api/doc/90000/90135/92973
TransferGroupChatExternalContact doc:https://open.work.weixin.qq.com/api/doc/90000/90135/92127

Co-authored-by: w3xse7en <w3xse7en@outlook.com>

Author: bors[bot]

README.md

@@ -111,7 +111,7 @@ in at least 2 of Qiniu's internal systems.
 <details>
 <summary>外部联系人管理 API</summary>
 
-* [ ] 离职成员的外部联系人再分配
+
 * [x] 成员对外信息
 * [x] 客户管理
     - [x] 获取客户列表
@@ -120,6 +120,11 @@ in at least 2 of Qiniu's internal systems.
 * [x] 客户标签管理
    - [x] 管理企业标签
    - [x] 编辑客户企业标签
+* [x] 客户分配
+   - [x] 获取离职成员列表
+   - [x] 分配在职或离职成员的客户
+   - [x] 查询客户接替结果
+   - [x] 分配离职成员的客户群
 * [x] 变更回调通知
     - [x] 添加企业客户事件
     - [x] 编辑企业客户事件

apis.md.go

@@ -89,6 +89,17 @@ Name|Request Type|Response Type|Access Token|URL|Doc
 `execExternalContactDelCorpTag`|`reqExternalContactDelCorpTag`|`respExternalContactDelCorpTag`|+|`POST /cgi-bin/externalcontact/del_corp_tag`|[删除企业客户标签](https://work.weixin.qq.com/api/doc/90000/90135/92117)
 `execExternalContactMarkTag`|`reqExternalContactMarkTag`|`respExternalContactMarkTag`|+|`POST /cgi-bin/externalcontact/mark_tag`|[标记客户企业标签](https://work.weixin.qq.com/api/doc/90000/90135/92118)
 
+# 外部联系人管理 - 客户分配
+
+## API calls
+
+Name|Request Type|Response Type|Access Token|URL|Doc
+:---|------------|-------------|------------|:--|:--
+`execListUnassignedExternalContact`|`reqListUnassignedExternalContact`|`respListUnassignedExternalContact`|+|`POST /cgi-bin/externalcontact/get_unassigned_list`|[获取离职成员的客户列表](https://work.weixin.qq.com/api/doc/90000/90135/92124)
+`execTransferExternalContact`|`reqTransferExternalContact`|`respTransferExternalContact`|+|`POST /cgi-bin/externalcontact/transfer`|[分配成员的客户](https://work.weixin.qq.com/api/doc/90000/90135/92125)
+`execGetTransferExternalContactResult`|`reqGetTransferExternalContactResult`|`respGetTransferExternalContactResult`|+|`POST /cgi-bin/externalcontact/get_transfer_result`|[查询客户接替结果](https://work.weixin.qq.com/api/doc/90000/90135/92973)
+`execTransferGroupChatExternalContact`|`reqTransferGroupChatExternalContact`|`respTransferGroupChatExternalContact`|+|`POST /cgi-bin/externalcontact/groupchat/transfer`|[离职成员的群再分配](https://work.weixin.qq.com/api/doc/90000/90135/92127)
+
 # 应用管理
 
 ## API calls

docs/apis.md

@@ -181,3 +181,38 @@ Name|JSON|Type|Doc
 `ExternalUserID`|`external_userid`|`string`| 外部联系人userid
 `AddTag`|`add_tag`|`[]string`| 要标记的标签列表
 `RemoveTag`|`remove_tag`|`[]string`| 要移除的标签列表
+
+### `ExternalContactUnassignedList` 离职成员的客户列表
+
+Name|JSON|Type|Doc
+:---|:---|:---|:--
+`Info`|`info`|`[]ExternalContactUnassigned`| 离职成员的客户
+`IsLast`|`is_last`|`bool`| 是否是最后一条记录
+`NextCursor`|`next_cursor`|`string`| 分页查询游标,已经查完则返回空("")
+
+```go
+// ExternalContactTransferStatus 客户接替结果状态
+type ExternalContactTransferStatus uint8
+
+const (
+	// ExternalContactTransferStatusSuccess 1-接替完毕
+	ExternalContactTransferStatusSuccess ExternalContactTransferStatus = 1
+	// ExternalContactTransferStatusWait 2-等待接替
+	ExternalContactTransferStatusWait ExternalContactTransferStatus = 2
+	// ExternalContactTransferStatusRefused 3-客户拒绝
+	ExternalContactTransferStatusRefused ExternalContactTransferStatus = 3
+	// ExternalContactTransferStatusExhausted 4-接替成员客户达到上限
+	ExternalContactTransferStatusExhausted ExternalContactTransferStatus = 4
+	// ExternalContactTransferStatusNoData 5-无接替记录
+	ExternalContactTransferStatusNoData ExternalContactTransferStatus = 5
+)
+
+```
+
+### `ExternalContactGroupChatTransferFailed` 离职成员的群再分配失败
+
+Name|JSON|Type|Doc
+:---|:---|:---|:--
+`ChatID`|`chat_id`|`string`| 没能成功继承的群ID
+`ErrCode`|`errcode`|`int`| 没能成功继承的群，错误码
+`ErrMsg`|`errmsg`|`string`| 没能成功继承的群，错误描述

docs/external_contact.md

@@ -1,5 +1,9 @@
 package workwx
 
+import (
+	"time"
+)
+
 // ListExternalContact 获取客户列表
 func (c *WorkwxApp) ListExternalContact(userID string) ([]string, error) {
 	resp, err := c.execExternalContactList(reqExternalContactList{
@@ -81,3 +85,72 @@ func (c *WorkwxApp) MarkExternalContactTag(userID, externalUserID string, addTag
 	})
 	return err
 }
+
+// ExternalContactUnassigned 离职成员的客户
+type ExternalContactUnassigned struct {
+	// HandoverUserID 离职成员的userid
+	HandoverUserID string
+	// ExternalUserID 外部联系人userid
+	ExternalUserID string
+	// DemissionTime 成员离职时间
+	DemissionTime time.Time
+}
+
+// ListUnassignedExternalContact 获取离职成员的客户列表
+func (c *WorkwxApp) ListUnassignedExternalContact(pageID, pageSize uint32, cursor string) (*ExternalContactUnassignedList, error) {
+	resp, err := c.execListUnassignedExternalContact(reqListUnassignedExternalContact{
+		PageID:   pageID,
+		PageSize: pageSize,
+		Cursor:   cursor,
+	})
+	if err != nil {
+		return nil, err
+	}
+	externalContactUnassignedList := resp.intoExternalContactUnassignedList()
+	return &externalContactUnassignedList, nil
+}
+
+// TransferExternalContact 分配成员的客户
+func (c *WorkwxApp) TransferExternalContact(externalUserID, handoverUserID, takeoverUserID, transferSuccessMsg string) error {
+	_, err := c.execTransferExternalContact(reqTransferExternalContact{
+		ExternalUserID:     externalUserID,
+		HandoverUserID:     handoverUserID,
+		TakeoverUserID:     takeoverUserID,
+		TransferSuccessMsg: transferSuccessMsg,
+	})
+	return err
+}
+
+// ExternalContactTransferResult 客户接替结果
+type ExternalContactTransferResult struct {
+	// Status 接替状态， 1-接替完毕 2-等待接替 3-客户拒绝 4-接替成员客户达到上限 5-无接替记录
+	Status ExternalContactTransferStatus
+	// TakeoverTime 接替客户的时间，如果是等待接替状态，则为未来的自动接替时间
+	TakeoverTime time.Time
+}
+
+// GetTransferExternalContactResult 查询客户接替结果
+func (c *WorkwxApp) GetTransferExternalContactResult(externalUserID, handoverUserID, takeoverUserID string) (*ExternalContactTransferResult, error) {
+	resp, err := c.execGetTransferExternalContactResult(reqGetTransferExternalContactResult{
+		ExternalUserID: externalUserID,
+		HandoverUserID: handoverUserID,
+		TakeoverUserID: takeoverUserID,
+	})
+	if err != nil {
+		return nil, err
+	}
+	externalContactTransferResult := resp.intoExternalContactTransferResult()
+	return &externalContactTransferResult, nil
+}
+
+// TransferGroupChatExternalContact 离职成员的群再分配
+func (c *WorkwxApp) TransferGroupChatExternalContact(chatIDList []string, newOwner string) ([]ExternalContactGroupChatTransferFailed, error) {
+	resp, err := c.execTransferGroupChatExternalContact(reqTransferGroupChatExternalContact{
+		ChatIDList: chatIDList,
+		NewOwner:   newOwner,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return resp.FailedChatList, nil
+}

external_contact.go

@@ -722,3 +722,131 @@ func (x respMsgAuditGetGroupChat) intoGroupChat() (resp MsgAuditGroupChat) {
 	}
 	return resp
 }
+
+type reqListUnassignedExternalContact struct {
+	// PageID 分页查询，要查询页号，从0开始
+	PageID uint32 `json:"page_id"`
+	// PageSize 每次返回的最大记录数，默认为1000，最大值为1000
+	PageSize uint32 `json:"page_size"`
+	// Cursor 分页查询游标，字符串类型，适用于数据量较大的情况，如果使用该参数则无需填写page_id，该参数由上一次调用返回
+	Cursor string `json:"cursor"`
+}
+
+var _ bodyer = reqListUnassignedExternalContact{}
+
+func (x reqListUnassignedExternalContact) intoBody() ([]byte, error) {
+	result, err := json.Marshal(x)
+	if err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}
+
+type respListUnassignedExternalContact struct {
+	respCommon
+	Info []struct {
+		HandoverUserid string `json:"handover_userid"`
+		ExternalUserid string `json:"external_userid"`
+		DemissionTime  int    `json:"dimission_time"`
+	} `json:"info"`
+	IsLast     bool   `json:"is_last"`
+	NextCursor string `json:"next_cursor"`
+}
+
+func (x respListUnassignedExternalContact) intoExternalContactUnassignedList() (resp ExternalContactUnassignedList) {
+	list := make([]ExternalContactUnassigned, 0, len(x.Info))
+	for _, info := range x.Info {
+		list = append(list, ExternalContactUnassigned{
+			HandoverUserID: info.HandoverUserid,
+			ExternalUserID: info.ExternalUserid,
+			DemissionTime:  time.Unix(int64(info.DemissionTime), 0),
+		})
+	}
+	resp.Info = list
+	resp.IsLast = x.IsLast
+	resp.NextCursor = x.NextCursor
+	return resp
+}
+
+type reqTransferExternalContact struct {
+	// ExternalUserID 外部联系人的userid，注意不是企业成员的帐号
+	ExternalUserID string `json:"external_userid"`
+	// HandoverUserID 原跟进成员的userid
+	HandoverUserID string `json:"handover_userid"`
+	// TakeoverUserID 接替成员的userid
+	TakeoverUserID string `json:"takeover_userid"`
+	// TransferSuccessMsg 转移成功后发给客户的消息，最多200个字符，不填则使用默认文案，目前只对在职成员分配客户的情况生效
+	TransferSuccessMsg string `json:"transfer_success_msg"`
+}
+
+var _ bodyer = reqTransferExternalContact{}
+
+func (x reqTransferExternalContact) intoBody() ([]byte, error) {
+	result, err := json.Marshal(x)
+	if err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}
+
+type respTransferExternalContact struct {
+	respCommon
+}
+
+type reqGetTransferExternalContactResult struct {
+	// ExternalUserID 外部联系人的userid，注意不是企业成员的帐号
+	ExternalUserID string `json:"external_userid"`
+	// HandoverUserID 原跟进成员的userid
+	HandoverUserID string `json:"handover_userid"`
+	// TakeoverUserID 接替成员的userid
+	TakeoverUserID string `json:"takeover_userid"`
+}
+
+var _ bodyer = reqGetTransferExternalContactResult{}
+
+func (x reqGetTransferExternalContactResult) intoBody() ([]byte, error) {
+	result, err := json.Marshal(x)
+	if err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}
+
+type respGetTransferExternalContactResult struct {
+	respCommon
+	Status       uint8 `json:"status"`
+	TakeoverTime int   `json:"takeover_time"`
+}
+
+func (x respGetTransferExternalContactResult) intoExternalContactTransferResult() ExternalContactTransferResult {
+	return ExternalContactTransferResult{
+		Status:       ExternalContactTransferStatus(x.Status),
+		TakeoverTime: time.Unix(int64(x.TakeoverTime), 0),
+	}
+}
+
+type reqTransferGroupChatExternalContact struct {
+	// ChatIDList 需要转群主的客户群ID列表。取值范围： 1 ~ 100
+	ChatIDList []string `json:"chat_id_list"`
+	// NewOwner 新群主ID
+	NewOwner string `json:"new_owner"`
+}
+
+var _ bodyer = reqTransferGroupChatExternalContact{}
+
+func (x reqTransferGroupChatExternalContact) intoBody() ([]byte, error) {
+	result, err := json.Marshal(x)
+	if err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}
+
+type respTransferGroupChatExternalContact struct {
+	respCommon
+	FailedChatList []ExternalContactGroupChatTransferFailed `json:"failed_chat_list"`
+}