飞书设置

1. 页面概览

飞书设置页是 AIP 管理后台集中配置飞书机器人的入口，路由 /admin/feishu，需管理员角色。它以 FEISHU_ 前缀的 key 读写系统设置（system_settings 表），覆盖机器人总开关、App ID/App Secret、域名、允许用户/群白名单、群聊/会话模式、进度样式与默认通道等 11 项配置。页面顶部提供「运行状态」卡（配置/运行/启用三态），并附飞书开放平台接入步骤说明。

配置采用"整页表单 + 顶部保存"模式：一次「保存」把全部字段逐项 PUT 到设置表，修改后重启 AIP 生效。若设置表缺项，页面会按运行状态自动兜底回填，凭证已配置且未显式禁用时提示"机器人默认启用"。

2. 访问入口

2.1 路由与菜单

path /admin/feishu、name FeishuSettings、title 飞书设置；挂载在父路由 /admin（AdminLayout）下，侧边栏菜单项「飞书设置」。源码 action/web/src/views/FeishuSettingsPage.vue（懒加载注册）。

2.2 认证与权限

该子路由 meta 显式 requiresAuth: true, requiresAdmin: true；后端 GET /feishu/status 与 PUT /settings 均在 admin 组。请求经 aipClient.js 附带 aip_token。

2.3 端口与 API 前缀

AIP 后端 18080，前缀 /aip-api（baseURL /aip-api/v1，Vite 代理重写为 /api/v1）。

3. 界面布局

飞书设置                                    [保存]
[操作结果提示 alert（可关闭）]
[提示：FEISHU_ 前缀配置项存入系统设置，修改后重启 AIP 生效]
运行状态：配置状态(已配置 App ID/未配置) | 运行状态(运行中/未运行) |
          启用开关(已启用/未启用)    [刷新状态]
飞书机器人接入说明：1 建应用 → 2 开启机器人能力 → 3 订阅事件与回调
                  → 4 填 App ID/Secret → 5 开开关并重启
配置表单：启用飞书机器人(开关) | App ID | App Secret | 域名 |
          允许用户 open_id | 允许群 chat_id | 仅群聊 | 群内共享会话 |
          线程隔离 | 进度样式(下拉) | 默认通道(下拉)

• 运行状态卡：展示 /feishu/status 三态 + 按状态切换的引导提示，「刷新状态」手动重拉。
• 接入说明：五步操作指引，指向飞书开放平台（open.feishu.cn）。
• 配置表单：11 个字段按类型渲染（开关/下拉/文本/密码），key 旁标注 FEISHU_* 原名。

4. 交互元素

5. 后端关联

5.1 端点表

5.2 请求与响应

GET /feishu/status 引擎未启动时返回配置态（running=false），已启动时返回引擎状态并强制 running=true。布尔字段存储为字符串 "true"/"false"，回填时 String(s.value) === 'true' 转回布尔。

5.3 关键机制

• 页面先 GET /settings 过滤 FEISHU_ 前缀项回填表单，再请求 /feishu/status；applyStatusBackfill 对设置表缺失字段用运行状态兜底。saveAll 组装 11 个 payload 后 Promise.all 并发写入，任一失败整批报错。
• 后端位置：handleFeishuStatus/handleFeishuPush 在 action/products/aip/server/handlers_feishu.go；机器人引擎在 action/products/aip/feishu/，工作流 send_notification 支持 channel=feishu 私聊推送。

6. 权限与安全

• 认证：JWT Bearer Token（aip_token），401 自动登出跳登录页。
• 管理员专属：前端 requiresAdmin 守卫 + 后端 admin 组双重校验。
• 敏感凭证：FEISHU_APP_SECRET 密码框输入，仅写入设置表；/feishu/push 同 admin 权限防冒充。白名单字段限制机器人响应范围，* 表示不限制。

7. 常见问题与排错

问题 1：运行状态卡显示"无法获取运行状态"

• 现象：状态区提示确认后端可用后点「刷新状态」重试。
• 原因：GET /feishu/status 失败（后端未启动、Token 失效或网络中断）。
• 处理：检查 Network 中 /aip-api/v1/feishu/status；401 重新登录，后端未启动则先拉起 AIP 进程。

问题 2：保存后机器人不响应消息

• 现象：配置已保存但飞书里机器人无反应。
• 原因：配置需重启 AIP 生效；或 FEISHU_ENABLED 未打开、App ID/Secret 有误。
• 处理：确认保存提示"保存成功，重启 AIP 后生效"，重启再测；核对 open.feishu.cn 凭证与回调订阅。

问题 3：运行状态显示"已配置但未运行"

• 现象：configured=true 但 running=false。
• 原因：凭证齐全但启动时机器人未拉起（启动日志报错），或 WebSocket 长连接中断。
• 处理：查 AIP 启动日志 StartFeishuIfEnabled 相关错误；确认回调/事件订阅与网络可达性。

问题 4：表单被自动回填了未保存过的值

• 现象：进入页面 App ID 等字段已有内容，但从未保存过。
• 原因：applyStatusBackfill 用运行状态兜底回填了设置表缺失字段。
• 处理：属预期行为；直接点「保存」即可把回填值写入设置表。

8. 已知缺陷与边界