# QuickStart

这份文档用于把 `lark_build_message` 接入项目工程或 CDN 仓库，用飞书企业自建应用替代原飞书机器人助手通知流程。

## 1. 环境要求

- Python 3.8+
- 无第三方 Python 包依赖

执行脚本的机器都需要有 Python，包括本地调试机、Mac 打包机、CDN 机器等。

CDN 机器如果没有 Python，需要联系服务器维护人员安装 Python 3.8+。安装后需要重启Azure Pipeline Agent相关服务，确保管线能识别 `python` 命令。

## 2. 准备工作

脚本通过环境变量或 `.env` 读取配置。接入前需要先准备群聊、飞书应用、多维表格相关信息。

### 2.1 群聊

#### 申请机器人可用权限

要把机器人添加到群聊，操作人需要在机器人的可用范围内。

配置入口：

```text
飞书开放平台
-> Unity打包机器人应用
-> 版本管理与发布
-> 创建新版本
-> 修改可用范围
-> 发布
```

发布后，操作人员才能在群聊里搜索并添加 `Unity打包机器人`。可用范围变更可能有短暂延迟。

#### 添加机器人到群聊

在目标群聊中操作：

```text
群聊右上角 "..."
-> 设置
-> 群机器人
-> 添加机器人
-> Unity打包机器人
```

#### 获取 Chat ID

`Chat ID` 只能通过飞书 API 获取。目录内已提供脚本：

```powershell
python lark_list_chats.py
```

脚本会列出该机器人已加入的群聊，通过群名称找到目标群，并把对应的 `chat_id` 填入：

```text
LARK_CHAT_ID=oc_xxx
```

如果刚把机器人加入群聊后查不到，等几分钟再试，飞书侧可能有同步延迟。

### 2.2 多维表格

原流程里，sandbox 部署完成后会把故障记录表中 `状态` 字段里值为 `修改未部署` 的记录改成 `待验收`。要保留这个功能，需要配置表格权限和表格参数。

#### 添加文档应用权限

需要由拥有看板管理权限的人操作：

```text
多维表格右上角 "..."
-> 更多
-> 添加文档应用
-> 选择 Unity打包机器人
-> 权限设置为 可管理
```

注意：只把机器人拉进群聊，或者只给普通读写权限，是无法调用多维表格 API的。这里需要把自建应用作为文档应用添加，并设置为“可管理”。

#### 获取表格参数

打开故障记录对应的数据表和视图，在浏览器地址栏复制完整链接。例如 Merge 项目：

```text
https://q83p1nq8dm.feishu.cn/base/GPlrbEHEsaJmMZsQPSwcOJvinfg?table=tblRelru6FFaUFfS&view=vewfMfs45d
```

对应关系：

```text
base/ 后面的值 -> LARK_BITABLE_APP_TOKEN
table 参数     -> LARK_BITABLE_TABLE_ID
view 参数      -> LARK_BITABLE_VIEW_ID
```

示例：

```text
LARK_BITABLE_APP_TOKEN=GPlrbEHEsaJmMZsQPSwcOJvinfg
LARK_BITABLE_TABLE_ID=tblRelru6FFaUFfS
LARK_BITABLE_VIEW_ID=vewfMfs45d
```

#### 配置筛选和更新字段

当前默认配置：

```text
LARK_BITABLE_FILTER_FIELD=状态
LARK_BITABLE_FILTER_VALUE=修改未部署
LARK_BITABLE_UPDATE_FIELD=状态
LARK_BITABLE_UPDATE_VALUE=待验收
```

含义：

- 筛选 `状态` 字段值为 `修改未部署` 的记录。
- 把筛选出来的记录的 `状态` 字段改成 `待验收`。

如果其他项目字段名和值一致，保持现状即可。

#### 日志字段

`LARK_BITABLE_SHOW_FIELDS` 只影响脚本日志，用于额外打印命中的记录信息。字段不存在不会影响更新，只会打印为空。

默认值：

```text
LARK_BITABLE_SHOW_FIELDS=问题描述,问题详情,严重程度
```

### 2.3 应用凭证

`LARK_APP_ID` 和 `LARK_APP_SECRET` 是企业自建应用的 ID 和密钥。

查看入口：

```text
飞书开放平台
-> Unity打包机器人应用
-> 凭证与基础信息
```

目前该机器人是项目间共用的，目录中的 `.env` 默认已经配置有效值。后续如果应用凭证变更，再同步更新。

## 3. 提交目录

把整个 `lark_build_message` 目录提交到需要使用通知功能的仓库。

推荐位置：

- 项目工程：放到 `misc/lark_build_message` 之类目录。
- CDN 仓库：可以直接放到仓库根目录。

管线命令里的脚本路径需要和实际提交位置一致。

## 4. 项目工程管线

项目工程主要发送热更完成和分包完成通知。当前打包机多为 Mac，通常使用 CMD/命令行任务执行。

### 4.1 任务组方式

适合多个管线复用。

1. 找到打包管线，通过 `+` 添加一个 CMD 命令行任务。
2. `DisplayName` 设置为：

```text
发送飞书消息
```

3. 脚本内容示例：

```bash
python3 ./misc/lark_build_message/lark_notify.py --method $(method) --platform $(platform)
```

说明：

- `python3` 需要按打包机环境调整，有些机器可能是 `python`。
- `./misc/lark_build_message/lark_notify.py` 需要按实际提交路径调整。

4. 选中这个任务，右键点击 `+ Create task group`。
5. 任务组名称：

```text
发送飞书消息
```

6. 任务组参数：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `method` | `hotfix` | 热更填 `hotfix`，分包填 `subpack` |
| `platform` | `Android` | 填 `Android` 或 `iOS` |

7. 保存任务组后，可以删除临时创建的 CMD 任务。
8. 找到原项目里发送提示消息的位置，添加刚创建的 `发送飞书消息` 任务组，并按类型和平台填写参数。

### 4.2 单任务方式

适合只在少数位置调用。

在原来发送提示消息的位置添加命令行任务：

```text
DisplayName: 发送飞书消息
```

热更示例：

```bash
python3 ./misc/lark_build_message/lark_notify.py --method hotfix --platform Android
```

分包示例：

```bash
python3 ./misc/lark_build_message/lark_notify.py --method subpack --platform Android
```

参数说明：

- `--method hotfix`：热更完成。
- `--method subpack`：分包完成。
- `--platform Android` 或 `--platform iOS`：平台。

## 5. CDN 仓库管线

CDN 管线主要发送部署完成通知。由于 CDN 管线结构较简单，建议直接使用单任务。

如果 CDN 机器是 Windows 环境，建议使用 PowerShell 任务，类型选择 `Inline`。

### 5.1 只发部署通知

```powershell
python lark_build_message\lark_notify.py --method deploy --branch dev
```

说明：

- CDN 机器上 `--method` 固定为 `deploy`。
- `--branch` 按项目习惯填写，例如 `dev`、`sandbox`、`test`、`release`，最终会显示为消息标签。

### 5.2 发部署通知并更新多维表格

适用于需要在部署完成后把多维表格状态从 `修改未部署` 改成 `待验收` 的场景。

Windows PowerShell 推荐写法：

```powershell
python lark_build_message\lark_notify.py --method deploy --branch sandbox
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

python lark_build_message\lark_bitable_update.py
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
```

Unix/macOS 命令行可以使用 `&&`：

```bash
python lark_build_message/lark_notify.py --method deploy --branch sandbox && python lark_build_message/lark_bitable_update.py
```