Enterprise Wechat Facilities

Integration with with Enterprise Wechat. Weixin (wechat) is a popular mobile app in China, which have 6500 million active users. Enterprise Wechat is only used in China; the document and the description of this module use Chinese.

PLEASE NOTICE that Enterprise Wechat Facilities the product itself is only available in Chinese, so the module authors will publish manual and usage notice under Chinese.

用法

1. 你必须先在企业微信网站申请一个账户，并且获得相应的 Corp ID 和管理组 Secret。 目前本模块只支持在一个site使用一组corpid。如果在微信企业号中一个管理员通过管理员权限组的方式管理多个应用，可以使用全局corpsecret。
   由于企业微信中每个应用的secret都不同，则必须为每个agent单独设置secret，才能在一个实施中支持多个企业微信应用。但必须设置全局corpsecret以便获得可见的应用列表。
2. 在 Drupal 的扩展页面启用此模块。

插件

本模块不包含任何应用或Agent的实现，而使用Drupal的插件机制来管理Agent。意即，你必须在 DrupalqyweixinAgentBase 这个类的基础上自行派生类，并将其放置在模块的 src/Plugin/QyWeixinAgent 目录下，作为微信企业号的插件。插件使用 Annotation 方式发现，所以foo模块的微信企业号插件 (foo/src/Plugin/QyWeixinAgent/Bar.php) 应该类似这样：

/**
 * @file
 * Contains DrupalfooPluginQyWeixinAgentBar.
 */

namespace DrupalfooPluginQyWeixinAgent;

use DrupalqyweixinCorpBase;
use DrupalqyweixinAgentBase;

/**
 * foo interface for qyweixin.
 *
 * @QyWeixinAgent(
 *   id = "foo",
 * )
 */
class Bar extends AgentBase {
}

本模块目前只支持插件类与应用(Agent)的一对一关系，无法将不同的应用对应到同一个类上。

插件可自行决定将配置表单放置在哪里。插件可以自定义路由或菜单，但若此配置仅仅与微信有关，可以写在foo.links.task.yml中，作为微信企业号配置页的一个tab。如：

foo.admin.qyweixin:
  title: 'Foo settings'
  route_name: foo.admin.qyweixin
  base_route: qyweixin.admin

主动调用

主动调用时，应该生成一个本插件的实例：

use DrupalqyweixinMessageBase;
$agent=Drupal::service('plugin.manager.qyweixin.agent')->createInstance('foo');
try {
    $msg=new MessageBase();
    $msg->setMsgType(MessageBase::MESSAGE_TYPE_TEXT)->setContent('Hello World')
        ->setToUser(USER_ID);
    $agent->messageSend($msg);
} catch(Exception $e) {
    var_dump($e->getMessage());
}

请注意，本模块不会对错误信息进行任何处理，所有错误信息都将会以异常(Exception)的形式抛出，调用时务必要使用 try...catch 语句。

DrupalqyweixinCorpBase 提供了一些静态方法可供调用，比如获得当前的 AccessToken、获得目前管理组secret可见的应用列表、管理素材等等。使用实例可参见 qyweixin.module 中的各个hook å’Œ DrupalqyweixinFormSettingsForm。

被动响应

被动响应时，本模块会为每一个由本实施接管的应用创建一个路由，其URL为 /qyweixin/foo，其中 foo 为入口类的名称。在微信企业号的官网上设置的回调地址应与此相同。请注意，没有接管的应用不会生成对应的路由。

每个应用所对应的插件中，应该至少实现一个 defaultResponse 方法。企业号框架的相应调度会在无法找到相应请求类型的方法时，调用该函数取得默认的返回。而按请求类型寻找方法的顺序如下：
[MsgType][SubMsgType]Response, [MsgType]Response, defaultResponse

插件返回时可以只返回文本或图像，调度会自动填写微信企业号所需的 XML 格式并进行加密。

Hook

目前本模块支持以下hook调用：

1. hook_qyweixin_to_username_alter()
   此hook允许第三方模块进行通讯录账户的转换。输入为企业内部用户ID，输出为微信企业号通讯录用户帐号。
2. hook_qyweixin_from_username_alter()
   此hook允许第三方模块进行通讯录账户的转换。输入为微信企业号通讯录用户帐号，输出为企业内部用户ID。

注意
第三方hook可以对username(即微信企业号通讯录用户ID)进行任意的修改，甚至包括更改类型。鉴于此情况，希望第三方hook和Agent开发者能够尽量保持一致，在进行一对多或多对一的转换时，使用元素类型为字符串的数组进行多值传递，而不是使用自制的分隔符。