# para-26071100 飞书应用配置清单

本文供 `para-26071100` 的飞书企业管理员操作。不要把 App Secret 粘贴到群聊、工单或本文档中；请通过约定的安全渠道交给平台部署人员。

## 1. 创建企业自建应用

1. 打开飞书开放平台开发者后台。
2. 在目标企业下创建“企业自建应用”。
3. 应用名称可填写 `Educraft para-26071100`。
4. 在“凭证与基础信息”记录：
   - App ID（通常以 `cli_` 开头）
   - App Secret
5. 添加并启用“机器人”能力。

Bot Open ID 不需要管理员手工寻找。平台部署人员会使用 App ID/App Secret 调用飞书 Bot Info API 获取，并在 bootstrap 时校验它确实属于这一个应用。

## 2. 开通权限

在“权限管理”中搜索并申请下列能力。飞书控制台的中文名称可能随版本调整；如控制台同时显示 scope，可优先核对括号中的 scope。

- 接收群聊中 @ 机器人的消息（`im:message.group_at_msg:readonly`）
- 以应用身份发送消息（`im:message:send_as_bot`）
- 获取消息内容，用于读取触发消息和线程上下文（`im:message:readonly`）
- 获取与上传图片或文件资源（`im:resource`）
- 添加、删除消息表情回复（`im:message.reactions:write_only`）
- 获取用户基本信息（`contact:user.base:readonly`）

如果飞书 API 调试台提示某个上述操作缺少更细粒度权限，请把提示截图交给平台部署人员，不要直接勾选通讯录全量读取或其他超出清单的权限。

## 3. 配置事件与卡片回调

1. 进入“事件与回调”。
2. 订阅方式选择“使用长连接接收事件”。
3. 添加事件 `im.message.receive_v1`（接收消息）。
4. 启用卡片交互回调 `card.action.trigger`，用于审批、中断运行和群聊建项目按钮。
5. 不需要填写公网 Event Callback URL；Hub 使用飞书长连接。

## 4. 配置 OAuth 回调

域名 DNS 和 TLS 生效后，在安全设置/重定向 URL 中添加：

```text
https://para-26071100.educraft.paradigm-edu.net/auth/feishu/callback
```

该回调用于 OWNER 登录受控的 Host Console。飞书群机器人长连接本身不依赖这个 URL。

## 5. 发布并安装应用

1. 创建应用版本并提交企业管理员审核。
2. 将应用可用范围至少包含试点 OWNER 和试点群成员。
3. 发布版本。
4. 将机器人加入准备试用的飞书群。

## 6. 获取首位 OWNER 身份

平台 bootstrap 需要 OWNER 的飞书 Open ID 和显示名称。可通过飞书 API 调试台的用户信息接口查询；Open ID 通常以 `ou_` 开头。Union ID 可选，不影响首次部署。

请把以下结果通过安全渠道交给平台部署人员：

```text
Organization: para-26071100
App ID: cli_...
App Secret: （安全渠道发送）
OWNER Open ID: ou_...
OWNER 显示名称:
OWNER Union ID: （可选）
试点群名称: （可选，便于验收）
```

## 7. 验收动作

平台通知部署完成后：

1. OWNER 打开 Host Console，完成飞书 OAuth 登录。
2. 在试点群中 @机器人发送一条纯文本消息。
3. 如果群尚未绑定项目，机器人应返回项目创建/绑定卡片。
4. 创建项目后再次 @机器人，确认出现处理状态、流式卡片和最终回答。
5. 再测试一个小文件附件，以及运行中断按钮。

任何一步失败时，请保留发生时间、群名、消息截图和飞书 request/log ID；不要在截图中包含 App Secret 或 Provider token。