ISV接入钉钉详细示例以及代码(JAVA版本)  --服务窗代码部分放出

本帖和代码  持续更新,请收藏关注。
talk is cheap, show me the code
============================================




注册套件,并且授权企业
1.前提准备
        公网服务器,假设IP地址为127.0.0.1
        TOMCAT端口假设为8080
        MYSQL数据库
        (工程目前只依赖了 TOMCAT,MYSQL,这两个个中间件,如果不满足请自行解决。删除了ACTIVEMQ和REDIS,降低工程配置和维护难度)





2.部署接入工程
      1).下载代码 (代码分析见后续)
        github地址为
        https://github.com/hetaoZhong/ding-isv-access.git      开放平台对接工程
         https://github.com/hetaoZhong/ding-isv-app.git      钉钉微应用DEMO(比较简单.仅供参考。这个不推荐了。服务化的部署方式不适合代码DEMO。和 ding-isv-access工程二合一了 )


      1).新建MYSQL数据库,名称为ding_isv_access。(如果不喜欢这个名称,可自行更换)
          将 ding-isv-access 工程中的 db_sql.sql 文件执行到mysql数据库
          如果发现执行过程中出现 (创建DB和表的过程中出现Unknown character set: 'utf8mb4'),
          请升级mysql版本至>5.5,或者将db_sql.sql文件中的utf8mb4编码更改成utf8

       4).修改ding-isv-access的配置文件,auto-config.xml. 各种配置项的属性看注释自行理解
  
       5).打包编译 ding-isv-access 。 mvn clean package -Dmaven.test.skip=true
         打包之前看一下个人目录之下antx.properties是否存在，如果存在需要清理一下 rm -rf ~/antx.properties

       6).将打包好的ding-isv-access .war放入tomcat启动。
          访问 http://127.0.0.1:8080/ding-isv-access/checkpreload.htm 返回success 表示启动完毕

        7)如果提示加解密错误,请看文档升级无限制加解密包 https://open-doc.dingtalk.com/docs/doc.htm?spm=a219a.7386797.0.0.A5d7BC&treeId=175&articleId=104945&docType=1

        8)如果您正在成为钉钉的ISV,请参考ISV上塔流程https://open-doc.dingtalk.com/docs/doc.htm?docType=1&articleId=106046


3.开发者平台注册套件
    1) 在开发者平台注册套件的时候，填写回调地址http://127.0.0.1:8080/ding-isv-access/suite/create
        在代码中可以发现suite/create该路径。 里面的suitesecret和token可以更换。也可以直接在开发者后台输入代码中的值


    2) 套件注册成功，在db中插入套件信息
         insert into isv_suite(id, gmt_create, gmt_modified, suite_name, suite_key, suite_secret, encoding_aes_key, token, event_receive_url)
         values(1, '2016-03-14 18:08:09', '2016-03-14 18:08:09', 'X套件', 'suitekeyX', 'suitesecretX','suiteAesKeyX', 'suiteTokenX', '');
         或者运行代码中的测试用例插入
    3)数据插入之后,修改套件地址         http://127.0.0.1:8080/ding-isv-access/suite/callback/{suiteKey} 占位符请自行替换

    4)观察服务端log.
          /home/mint/logs/ding-isv-access/ding-isv-access.log               该log记录了tomcat的ding-isv-access工程启动情况
         /home/mint/logs/ding-isv-access/biz/http_request_helper.log   该log记录了所有通过httpclient开放平台请求的http记录
          /home/mint/logs/ding-isv-access/biz/http_invoke.log               该log记录了所有通过sdk开放平台请求的http记录
         /home/mint/logs/ding-isv-access/biz/task.log                             该log记录了所有定时任务相关日志。
         /home/mint/logs/ding-isv-access/biz/suite_callback.log             该log记录了所有开放平台调用套件回调信息的日志


4.创建微应用
        在开发者后台创建微应用


5.生成先下部署二维码(该过程要求开发者后台的关联的钉钉企业必须是认证企业)
        在开发者后台生成线下部署二维码,
        第一次生成二维码的时候,建议不要勾选 开启序列号校验选项。
        之后再次生成二维码可以勾选
        生成二维码的时候,钉钉会把套件为指定的一家企业开通,开发者需要观察服务端日志。


6.二维码开生成成功,可以扫码开通套件啦


7.钉钉微应用简单DEMO
    1)代码比较简单。仅仅实现了dd.config流程。
        可以修改文件中的corpid.授权该套件的企业的corpid即可。 在调试过程中自己修改
       文件地址为https://github.com/hetaoZhong/ding-isv-app/blob/master/web/src/main/webapp/microapp.html
    2)更多demo在更新中... 前端不会,多包含
         ( DEMO更新中,见谅)


ding-isv-access接入层代码分析
1.代码结构



上图说明如下:

1. 开放平台通过 SuiteCallBack Controller提供的RPC接口推送事件。
      包括
               1)企业授权套件过程中的临时授权码,权限变更,权限解除等等,RPC接口通过 Corp Suite Auth Service处理企业授权事件
               2)企业信息发生变更的回调事件,员工变更,部门变更,群会话变更等等。


2. Suite Service, Crm Service, Dept Service等具体的业务代码,是封装了开放平台提供的http接口。
    这些 Service 接口通过各种 RestHelper向开放平台 请求数据,例如ConfOapi RestHelper。
     同时这些Service也通过springhttpinvoker向微应用业务方提供方法调用

3. SuiteTokenJob,CorpAuthFaileJob,MonitorJob 服务是定时任务.定时生成token,处理授权失败,监控等


4.ISVBizLockSerive是锁服务。





2.数据库表说明

+---------------------------------------------+
| Tables_in_ding_isv_access              |
+-----------------------------+
| QRTZ_BLOB_TRIGGERS                |         QRTZ前缀表明为spring-quarzt用到的表。全部删掉了，维护成本高。不易理解。如果ISV集群方式执行定时任务自行解决
| QRTZ_CALENDARS                        |
| QRTZ_CRON_TRIGGERS              |
| QRTZ_FIRED_TRIGGERS              |
| QRTZ_JOB_DETAILS                      |
| QRTZ_LOCKS                                 |
| QRTZ_PAUSED_TRIGGER_GRPS |
| QRTZ_SCHEDULER_STATE           |
| QRTZ_SIMPLE_TRIGGERS            |
| QRTZ_SIMPROP_TRIGGERS         |
| QRTZ_TRIGGERS                           |
| isv_app                                             |       ISV套件下的微应用信息
| isv_biz_lock                                      |       锁表。 由于系统没有采用redis之类的缓存,所以用了数据库表来实现业务上的加锁功能
| isv_corp                                            |       企业信息表
| isv_corp_app                                    |       企业开通微应用表
| isv_corp_suite_auth                         |       企业授权套件信息
| isv_corp_suite_auth_faile                |        企业授权套件过程中,失败的数据。由定时任务定时处理这个表中的数据进行重试
| isv_corp_suite_callback                   |       企业对套件的回调注册url表(当前这张表没有使用)  
| isv_corp_suite_jsapi_ticket              |        企业的jsapiticke表
| isv_corp_token                                |         企业的accesstoken表
| isv_suite                                          |         ISV套件下的套件信息
| isv_suite_ticket                                |         ISV套件的suiteticket表
| isv_suite_token                                |         ISV套件的suitetoken表.这张表的信息由定时任务定时刷新
+--------------------------------------------+



3.处理企业授权套件流程图如下.

     1.接收开放平台的临时授权码推送
     2.临时授权码做存储,db或者log
     3/4/5/6.使用临时授权码换取永久授权码。                            如果失败,计入失败表,使用定时任务做重试
     7/8/9.调用开放平台接口获取企业和微应用信息,做存储。     如果失败,计入失败表,使用定时任务做重试
     10.调用开放平台接口激活套件。                                         如果失败,计入失败表,使用定时任务做重试
     11.注册企业对套件的回调地址。                                          如果失败,计入失败表,使用定时任务做重试




更新记录
[font=-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol']一.2016.10.30更新
[font=-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol']   1.更新db,具体参照 add-10.11.sql
[font=-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol']   2.增加服务窗授权流程
[font=-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol']   3.增加授权失败的重新授权流程。具体参照 [size=; font-size: 9pt,9pt] ReAuthFailedCorpJob [font=-apple-system, BlinkMacSystemFont, "].java
[font=-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol']   4.调整部分代码结构以及日志格式