Merge pull request #6 from lyleshaw/main

[docs] add docs

Author: daniel-hutao

README.md

@@ -1,6 +1,152 @@
 # ospp-cr-bot
 开源之夏 - 一种通用的 Code Review 机器人
 
+## 背景
+
+Code Review 是软件研发协作中的重要⼀环，⼤家在代码提交后都需要等待 Reviewer 的 Review；同时当Reviewer 提交了“修改建议”后，PR/MR 的提交者还需要根据“修改建议”相 应更新⾃⼰的代码。在这个过程中可能代码提交者等了半天也没有⼈来 Review，或者 Reviewer 提交了“修改建议”后等了半天也没有看到提交者修改。所以各⽅及时收到“动作通知”，⾼效完成⾃⼰的“Review/Fix”⼯作是⾮常重要的。
+
+## 目标
+
+1. 通过 webhook 实现通过对 GitHub 的 PR/MR/Review/Comment 等事件的监听
+2. 创建⻜书机器⼈应⽤，并调⽤ fastwego 的⻜书 SDK 实现对⻜书机器⼈发送消息函数 的封装
+3. 设计配置⽂件格式，使项⽬可以优雅的读⼊⻜书号/群 与 Github/Gitlab Repo 之间 的映射关系
+4. 实现对推送⼈的持续通知等需求
+5. 通过 helm 完成部署
+
+> Ref: https://summer-ospp.ac.cn/#/org/prodetail/22abc0185
+
+## 方案
+
+### 整体架构
+
+![img.png](docs/img/img.png)
+
+### 业务流程时序图
+
+![img_1.png](docs/img/img_1.png)
+
+## ShowCase
+
+![img_2.png](docs/img/img_2.png)
+
+## 私有化指南
+
+### 部署指南
+
+1. 创建飞书应用
+
+在飞书开放平台的开发中后台（https://open.feishu.cn/app）创建应用。
+
+![img_3.png](docs/img/img_3.png)
+
+2. 项目启动配置
+
+![img_4.png](docs/img/img_4.png)
+
+![img_5.png](docs/img/img_5.png)
+
+在应用根目录下创建 .env文件, 填入如上四个凭证：
+
+```yaml
+   LarkAppId=cli_xxx
+   LarkAppSecret=xxx
+   VerificationToken=xxx
+   EncryptKey=xxx
+```
+
+在权限管理中为应用开通必要权限
+
+![img_6.png](docs/img/img_6.png)
+
+在 事件订阅/应用功能-机器人 中分别填入接口 URL 做鉴权，URL 分别为：
+
+```bash
+http://domain:port/api/lark/cardCallback
+http://domain:port/api/lark/callback
+```
+
+![img_7.png](docs/img/img_7.png)
+
+![img_8.png](docs/img/img_8.png)
+
+3. 获取群聊 ID 及用户 ID 并配置 yaml 文件
+
+启动应用后，在需要订阅消息的群聊中@cr-bot，会收到以 @oc_ 开头的一串字符，此为该群聊群号，向 bot 发送私聊消息 ID 会收到以 @ou_ 开头的一串字符，此为该用户 ID
+
+![img_9.png](docs/img/img_9.png)
+
+![img_10.png](docs/img/img_10.png)
+
+此时可参照 common.yaml.example 文件填写 bot 配置并创建 common.yaml 文件：
+   
+```yaml
+tasks:
+- name: "Task 1"
+  repo: lyleshaw/repoTest // GitHub URL
+  repoType: github // 仓库类型，可选 github 和 gitlab
+  receiver: oc_xxxxxxxx // 该仓库指定的群聊
+  pushChannel: lark // 推送渠道，可选 lark 和 slack
+maps:
+- name: "1"
+  github: lyleshaw // github ID
+  lark: ou_xxxxxx // 飞书用户 ID
+  role: member // 角色
+  boss: 0 // 上级的 GitHub 账号，若无则填 0
+- name: "2"
+  github: abc
+  lark: ou_xxxxxx
+  role: contributor
+  boss: lyleshaw
+scheduler:
+  - timeUnread1: 30 // PR/Issue 消息第一次发送消息后若未读，经过 TimeUnread1 分钟后重发
+  - timeUnread2: 30 // PR/Issue 消息第二次发送消息后若未读，经过 TimeUnread2 分钟后发送给上级
+  - timeUnread3: 660 // PR/Issue 消息第三次发送消息后若未读，经过 TimeUnread3 分钟后抄送群聊
+  - commentUnread: 60 // Comment 消息第一次发送后若未读，经过 CommentUnread 分钟后抄送群聊
+```
+
+修改完配置后，重启项目即可开始使用
+
+### 修改指南
+
+1. 修改升级逻辑
+
+见 internal/pkg/eventListener/eventListener.go 文件及其注释
+
+2. 修改推送内容
+  
+参考 https://open.feishu.cn/tool/cardbuilder?from=howtoguide 搭建消息卡片，并修改 internal/pkg/pushChannel/lark/messageTemplate 下的文件
+
+## Check List
+- [x] 主体功能
+  - [x] 读取配置
+  - [x] GitHub 消息接收
+    - [x] PR
+    - [x] Issue
+    - [x] Comment
+    - [x] Review
+  - [x] 飞书消息卡片
+    - [x] PR
+    - [x] Issue
+    - [x] Comment
+    - [x] Review
+  - [x] 消息升级
+    - [x] PR/Issue 30 分钟后未读重复提醒
+    - [x] PR/Issue 60 分钟后未读提醒上级
+    - [x] PR/Issue 12 小时后未读抄送群聊
+    - [x] Comment/Review 无@成员抄送群聊
+    - [x] Comment/Review 有@成员提醒
+    - [x] Comment/Review 有@成员 30 分钟后未读抄送群聊
+  - [ ] Helm 部署
+- [x] 测试
+  - [x] PR/Issue 部分
+  - [x] Comment/Review 部分
+- [x] 代码优化
+  - [x] Log 打点
+  - [x] 细节
+- [ ] 后续支持
+  - [ ] Slack 支持
+  - [ ] GitLab 支持
+=======
 ## How to Build
 
 ```bash
@@ -50,4 +196,4 @@ tasks:
 请在启动服务后，拉入群聊并 @cr-bot-test，bot 会获取你的 Lark ID 并回复。
 
 ![img.png](docs/imgs/img.png)
-![img.png](img.png)
+![img.png](img.png)

common.yaml.example

@@ -16,3 +16,9 @@ maps:
     lark: ou_xxxxxx
     role: contributor
     boss: lyleshaw
+
+scheduler:
+  - timeUnread1: 30
+  - timeUnread2: 30
+  - timeUnread3: 660
+  - commentUnread: 60

docs/img/img.png

@@ -14,8 +14,9 @@ var (
 )
 
 type Config struct {
-	Tasks []Tasks `yaml:"tasks"`
-	Maps  []Maps  `yaml:"maps"`
+	Tasks     []Tasks   `yaml:"tasks"`
+	Maps      []Maps    `yaml:"maps"`
+	Scheduler Scheduler `yaml:"scheduler"`
 }
 type Tasks struct {
 	Name         string `yaml:"name"`
@@ -32,6 +33,13 @@ type Maps struct {
 	Boss   string `yaml:"boss"`
 }
 
+type Scheduler struct {
+	TimeUnread1   int `yaml:"timeUnread1"`
+	TimeUnread2   int `yaml:"timeUnread2"`
+	TimeUnread3   int `yaml:"timeUnread3"`
+	CommentUnread int `yaml:"commentUnread"`
+}
+
 func InitConfig() {
 	config, err := ioutil.ReadFile("./common.yaml")
 	if err != nil {

docs/img/img_1.png

@@ -1,6 +1,9 @@
 package constants
 
-import "time"
+import (
+	"github.com/lyleshaw/ospp-cr-bot/internal/pkg/config"
+	"time"
+)
 
 type MsgType int
 
@@ -11,9 +14,9 @@ const (
 	Unread3 MsgType = 3
 )
 
-const (
-	TimeUnread1   = 30 * time.Minute // PR/Issue 消息第一次发送消息后若未读，经过 TimeUnread1 后重发
-	TimeUnread2   = 30 * time.Minute // PR/Issue 消息第二次发送消息后若未读，经过 TimeUnread2 后发送给上级
-	TimeUnread3   = 11 * time.Hour   // PR/Issue 消息第三次发送消息后若未读，经过 TimeUnread3 后抄送群聊
-	CommentUnread = 1 * time.Hour    // Comment 消息第一次发送后若未读，经过 CommentUnread 后抄送群聊
+var (
+	TimeUnread1   = time.Duration(config.Cfg.Scheduler.TimeUnread1) * time.Minute   // PR/Issue 消息第一次发送消息后若未读，经过 TimeUnread1 后重发
+	TimeUnread2   = time.Duration(config.Cfg.Scheduler.TimeUnread2) * time.Minute   // PR/Issue 消息第二次发送消息后若未读，经过 TimeUnread2 后发送给上级
+	TimeUnread3   = time.Duration(config.Cfg.Scheduler.TimeUnread3) * time.Minute   // PR/Issue 消息第三次发送消息后若未读，经过 TimeUnread3 后抄送群聊
+	CommentUnread = time.Duration(config.Cfg.Scheduler.CommentUnread) * time.Minute // Comment 消息第一次发送后若未读，经过 CommentUnread 后抄送群聊
 )

docs/img/img_10.png

@@ -130,7 +130,7 @@ func GitHubWebHook(c *gin.Context) {
 
 		// 定时未读则转发群聊
 		time.AfterFunc(constants.CommentUnread, func() {
-			issueCommentMsg = lark.MsgTemplateUpgrade(issueCommentMsg, "有人")
+			issueCommentMsg = lark.MsgTemplateUpgrade(issueCommentMsg)
 			for _, receiver := range atPeople {
 				if _, ok := config.MsgQueue[receiver+number+string(gitHubEvent)]; ok {
 					if config.MsgQueue[receiver+number+string(gitHubEvent)] == constants.Unread1 {
@@ -326,7 +326,7 @@ func GitHubWebHook(c *gin.Context) {
 
 		// 定时未读则转发群聊
 		time.AfterFunc(constants.CommentUnread, func() {
-			prReviewMsg = lark.MsgTemplateUpgrade(prReviewMsg, "有人")
+			prReviewMsg = lark.MsgTemplateUpgrade(prReviewMsg)
 			for _, receiver := range atPeople {
 				if _, ok := config.MsgQueue[receiver+number+string(gitHubEvent)]; ok {
 					if config.MsgQueue[receiver+number+string(gitHubEvent)] == constants.Unread1 {
@@ -413,7 +413,7 @@ func GitHubWebHook(c *gin.Context) {
 
 		// 定时未读则转发群聊
 		time.AfterFunc(constants.CommentUnread, func() {
-			prCommentMsg = lark.MsgTemplateUpgrade(prCommentMsg, "有人")
+			prCommentMsg = lark.MsgTemplateUpgrade(prCommentMsg)
 			for _, receiver := range atPeople {
 				if _, ok := config.MsgQueue[receiver+number+string(gitHubEvent)]; ok {
 					if config.MsgQueue[receiver+number+string(gitHubEvent)] == constants.Unread1 {

docs/img/img_2.png

@@ -19,9 +19,9 @@ var (
 	createMessageURL = "https://open.feishu.cn/open-apis/im/v1/messages"
 )
 
-func MsgTemplateUpgrade(msgTemplate string, receiver string) string {
-	msgTemplate = strings.Replace(msgTemplate, messageTemplate.PrTitle1, fmt.Sprintf(messageTemplate.PrTitle2, receiver), -1)
-	msgTemplate = strings.Replace(msgTemplate, messageTemplate.IssueTitle1, fmt.Sprintf(messageTemplate.IssueTitle2, receiver), -1)
+func MsgTemplateUpgrade(msgTemplate string) string {
+	msgTemplate = strings.Replace(msgTemplate, messageTemplate.PrTitle1, messageTemplate.PrTitle2, -1)
+	msgTemplate = strings.Replace(msgTemplate, messageTemplate.IssueTitle1, messageTemplate.IssueTitle2, -1)
 	msgTemplate = strings.Replace(msgTemplate, messageTemplate.PrCommentTitle1, messageTemplate.PrCommentTitle2, -1)
 	msgTemplate = strings.Replace(msgTemplate, messageTemplate.IssueCommentTitle1, messageTemplate.IssueCommentTitle2, -1)
 	msgTemplate = strings.Replace(msgTemplate, messageTemplate.PrReviewTitle1, messageTemplate.PrReviewTitle2, -1)
@@ -200,17 +200,18 @@ func TimeCheck2(receiveID string, receivers []string, msgTemplate string, number
 			if config.MsgQueue[receiver+number+gitHubEvent] == constants.Unread2 {
 				// 如果第二次未读，则调整状态为第三次未读，并发送消息给上级
 				config.MsgQueue[receiver+number+gitHubEvent] = constants.Unread3
-				msgTemplate = MsgTemplateUpgrade(msgTemplate, receiver)
+				msgTemplate = MsgTemplateUpgrade(msgTemplate)
+				msgTemplate_ := fmt.Sprintf(msgTemplate, receiver)
 				if config.LarkMaps[receiver].Boss == "0" {
-					_, err := SendGroupMessage(receiveID, msgTemplate)
+					_, err := SendGroupMessage(receiveID, msgTemplate_)
 					if err != nil {
 						log.Errorf("send message error: %+v", err)
 					}
 					continue
 				}
-				_, err := SendMessage(config.LarkMaps[config.LarkMaps[receiver].Boss].Lark, msgTemplate)
+				_, err := SendMessage(config.LarkMaps[config.LarkMaps[receiver].Boss].Lark, msgTemplate_)
 				if err != nil {
-					log.Errorf("send message failed, msgTemplate=%s, receivers=%+v, gitHubEvent=%s", msgTemplate, receivers, gitHubEvent)
+					log.Errorf("send message failed, msgTemplate=%s, receivers=%+v, gitHubEvent=%s", msgTemplate_, receivers, gitHubEvent)
 					log.Errorf("send message failed, err=%v", err)
 				}
 				log.Infof("msgQ=%v", config.MsgQueue)
@@ -231,9 +232,10 @@ func TimeCheck3(receiveID string, receivers []string, msgTemplate string, number
 	for _, receiver := range receivers {
 		if _, ok := config.MsgQueue[receiver+number+gitHubEvent]; ok {
 			if config.MsgQueue[receiver+number+gitHubEvent] == constants.Unread3 {
-				msgTemplate = MsgTemplateUpgrade(msgTemplate, receiver)
+				msgTemplate = MsgTemplateUpgrade(msgTemplate)
+				msgTemplate_ := fmt.Sprintf(msgTemplate, receiver)
 				// 如果第三次未读，则从队列清除，并发送群消息
-				_, err := SendGroupMessage(receiveID, msgTemplate)
+				_, err := SendGroupMessage(receiveID, msgTemplate_)
 				if err != nil {
 					log.Errorf("send message error: %+v", err)
 				}