botmux 3.18.7 → 3.18.8

package/dist/im/lark/event-dispatcher.js

@@ -23,9 +23,10 @@ import { isTeamGroupChat } from '../../services/team-groups-store.js';
 import { isPlatformTeamBot, isPlatformHallChat, isPlatformTeamMember } from '../../services/platform-team-store.js';
 import { getBotUnionId, recordBotUnionId, recordBotUnionIdFromMentions } from '../../services/bot-union-ids-store.js';
 import { getDocSubscription, putDocSubscription, removeDocSubscription, listAllDocSubscriptions } from '../../services/doc-subs-store.js';
+import { wasPendingReviewNotified, markPendingReviewNotified } from '../../services/under-review-notify-store.js';
 import { getDocComment, isBotAuthoredReply, hasBotSentinel, commentTriggerAllowed, BOT_REPLY_SENTINEL } from './doc-comment.js';
 import { BOTMUX_REQUIRED_SCOPES, DOC_FEATURE_SCOPES, DOC_WATCH_SCOPES, DOC_COMMENT_EVENT, VC_MEETING_BOT_EVENTS, VC_MEETING_FEATURE_SCOPES, VC_MEETING_REALTIME_VOICE_SCOPES, buildEventSubDeepLink, buildScopeDeepLink, } from '../../setup/verify-permissions.js';
-import { automateOpenPlatformSetup, probeVcMeetingEventSubscription, readDefaultScopeManifest, filterScopeManifest } from '../../setup/open-platform-automation.js';
+import { automateOpenPlatformSetup, probeVcMeetingEventSubscription, readDefaultScopeManifest, filterScopeManifest, inspectUnderReviewConfigHints } from '../../setup/open-platform-automation.js';
 import { larkHosts, normalizeBrand, sdkDomain } from './lark-hosts.js';
 import { tryHandleGrantCommand } from './grant-command.js';
 import { tryHandleInviteCommand } from './invite-command.js';
@@ -184,36 +185,28 @@ const SELF_MANAGE_SCOPE = 'application:application:self_manage';
 function getAdminOpenId(bot) {
     return bot.resolvedAllowedUsers.find(u => u.startsWith('ou_'));
 }
+/**
+ * 给管理员发一条提醒。**返回是否真的发出去了。**
+ *
+ * 为什么要返回值：多数调用点是 best-effort、不关心成败（所以这里吞掉异常而不是抛，
+ * 避免一次 DM 失败中断整条自检流程）。但「按待审版本节流」那处必须知道成败 ——
+ * 先记「已通知」再发的话，一次网络失败就把那个版本永久节流掉，人再也收不到提醒，
+ * 且是零信号的静默丢失。所以由这里如实回报，让**只有关心的那一处**去判断。
+ */
 async function dmAdmin(larkAppId, adminOpenId, content, contextTag) {
     try {
         await sendUserMessage(larkAppId, adminOpenId, content, 'text');
         logger.info(`[${larkAppId}] notified admin ${adminOpenId.substring(0, 12)} about ${contextTag}`);
+        return true;
     }
     catch (err) {
         logger.warn(`[${larkAppId}] failed to DM admin about ${contextTag}: ${err?.message ?? err}`);
+        return false;
     }
 }
-/**
- * Try to auto-fix missing scopes using the same Open Platform web-session
- * automation that powers `botmux setup`. If ~/.botmux/feishu-session.json holds
- * a valid cached session, this adds all botmux-required scopes and publishes
- * a new app version — no user interaction needed.
- *
- * Returns `true` if scopes were successfully applied (caller should stop),
- * `false` to fall through to the manual DM warning.
- *
- * `opts.disableQrLogin` — when the only thing missing is a non-critical scope,
- *   we still try to grab it (the automation imports the full manifest), but must
- *   NOT pop a second QR code if the cached session is gone. Passing this makes a
- *   missing/expired session fail cleanly (reason `invalid_session`) instead of
- *   prompting a login.
- * `opts.silent` — suppress the admin success DM (used for the opt-in / optional
- *   path so a bot that never asked for the feature isn't pinged; the log line is
- *   enough). Failures are always silent here regardless.
- */
 async function tryAutoFixScopes(larkAppId, bot, brand, missingCritical, missingOptional, opts) {
     if (brand !== 'feishu')
-        return false;
+        return { kind: 'failed' };
     try {
         const totalMissing = missingCritical.length + missingOptional.length;
         logger.info(`[${larkAppId}] attempting auto-fix for ${totalMissing} missing scopes via Open Platform...`);
@@ -271,15 +264,28 @@ async function tryAutoFixScopes(larkAppId, bot, brand, missingCritical, missingO
                 : result.privilegeRangeWarning
                     ? `, 权限数据范围未能自动配置（${result.privilegeRangeWarning}）`
                     : '';
-            // 「无变更→有意跳过发版」≠「发了版但没解析到 versionId」：后者要提示去开放平台
-            // 确认，前者根本没建版本，报 `version n/a published` 会误导（#1044）。
+            // 三种结局互斥，判定顺序不能反（#1044 的 publishSkipped 必须最先判）：
+            //   ① publishSkipped —— 无变更、**根本没建版本**，报 `version n/a published` 会误导
+            //   ② versionWarning —— 建/提交了但回读仍是草稿。「version X published」曾是**谎报**：
+            //      `publish/commit` 回 code=0 而版本仍停在未提交草稿态，日志照样写 published，
+            //      于是那个草稿一路卡死后续每一次自愈（`app_version/create` 撞 code=10043）。
+            //   ③ 正常发布
             const versionDetail = result.publishSkipped
                 ? '无变更，已跳过发版'
-                : `version ${result.versionId ?? 'n/a'} published`;
+                : result.versionWarning
+                    ? `version ${result.versionId ?? 'n/a'} NOT published（${result.versionWarning}）`
+                    : `version ${result.versionId ?? 'n/a'} ${result.versionReused ? '(复用既有草稿) ' : ''}published`;
+            // 「秒过」与「要人审」是两种截然不同的结局，日志必须分开——否则运维看到
+            // published 会以为权限已经生效，而实际上可能还在等某个人点同意。
+            const approvalDetail = result.approvalAutoPassed === true
+                ? '（审批流自动通过，已即时生效）'
+                : result.approvalHumanApprovers?.length
+                    ? `（需人工审批：${result.approvalHumanApprovers.join('、')}）`
+                    : '';
             const summary = `[${larkAppId}] auto-fix ${autoFixEffective ? 'succeeded' : 'could NOT apply the missing scopes'}: ${scopeDetail}${privilegeRangeDetail}, ` +
-                `${versionDetail}, ` +
+                `${versionDetail}${approvalDetail}, ` +
                 `${result.subscribedEventCount} events subscribed`;
-            if (autoFixEffective)
+            if (autoFixEffective && !result.versionWarning)
                 logger.info(summary);
             else
                 logger.warn(summary);
@@ -287,7 +293,7 @@ async function tryAutoFixScopes(larkAppId, bot, brand, missingCritical, missingO
             // never enabled the feature must not be pinged just because a non-critical
             // scope was topped up in the background). The log line above is the record.
             if (opts?.silent)
-                return true;
+                return { kind: 'fixed' };
             // Notify admin that auto-fix worked — even if im:message was missing before,
             // the newly published version should now have it.
             const adminOpenId = getAdminOpenId(bot);
@@ -296,14 +302,30 @@ async function tryAutoFixScopes(larkAppId, bot, brand, missingCritical, missingO
                 const missingList = fixedList.map(s => `• ${s.desc} (\`${s.name}\`)`).join('\n');
                 // 标题跟着实际结果走：一项都没落地时说「已自动修复」是谎报，管理员会以为
                 // 不用管，而这条路径的下游（缺 critical scope）恰恰是最需要人工介入的。
-                await dmAdmin(larkAppId, adminOpenId, (autoFixEffective
+                // 同理「新版本已发布」也不能写死：scope 写进了清单但版本没提交，权限就**不会
+                // 生效**，而管理员读到「已发布」只会干等。versionWarning 有值时直接给出
+                // 手动收尾的动作。
+                //
+                // 三种结局要分清，因为「用户接下来该做什么」完全不同：
+                //   ① 秒过（审批流全自动通过）→ 已经生效了，什么都不用做
+                //   ② 要人审 → 已提交，但在等具体某个人；告诉他等谁，免得重复点或干等
+                //   ③ 判不出来 → 保持中性措辞，不猜
+                const versionLine = result.versionWarning
+                    ? `⚠️ 但新版本**没有成功提交发布**（${result.versionWarning}）。权限要等版本发布后才生效。`
+                    : result.approvalAutoPassed === true
+                        ? '新版本已提交，审批流**自动通过**，权限已即时生效。'
+                        : result.approvalHumanApprovers?.length
+                            ? `新版本已提交，但需要**人工审批**（审批人：${result.approvalHumanApprovers.join('、')}），`
+                                + '通过后权限才生效——不用重复提交，等审批即可。'
+                            : '新版本已发布。';
+                await dmAdmin(larkAppId, adminOpenId, (autoFixEffective && !result.versionWarning
                     ? `✅ botmux 已自动为机器人 "${bot.botName ?? larkAppId}" 修复了缺失的权限：\n\n`
-                    : `⚠️ botmux 尝试自动为机器人 "${bot.botName ?? larkAppId}" 补齐以下权限，但没能申请成功，需要你手动开通：\n\n`) +
+                    : `⚠️ botmux 尝试自动为机器人 "${bot.botName ?? larkAppId}" 补齐以下权限，但没能全部落地，需要你手动收尾：\n\n`) +
                     `${missingList}\n\n` +
-                    `${scopeDetail}，新版本已发布。\n` +
+                    `${scopeDetail}，${versionLine}\n` +
                     `权限变更可能需要 1-2 分钟生效。如仍有问题执行 \`botmux restart\`。`, autoFixEffective ? `auto-fixed ${fixedList.length} scopes` : `auto-fix could not apply ${fixedList.length} scopes`);
             }
-            return true;
+            return { kind: 'fixed' };
         }
         // Auto-fix failed — log reason. Critical path falls through to a manual
         // deep-link DM; the silent optional-scope top-up path does NOT DM (it just
@@ -319,15 +341,32 @@ async function tryAutoFixScopes(larkAppId, bot, brand, missingCritical, missingO
             missing_csrf: '开放平台页面未返回 CSRF token',
             scope_mapping_failed: '权限映射失败',
             api_error: '开放平台 API 错误',
+            app_under_review: '应用正在飞书审核中（配置被开放平台写锁，审批通过后自动恢复）',
         };
-        logger.warn(`[${larkAppId}] auto-fix not possible (${result.reason}: ${reasons[result.reason] ?? result.message}). ` +
+        // ⚠️ 泛化标签和具体消息**两个都要打**。这里曾写成
+        // `reasons[result.reason] ?? result.message`——`api_error` 在表里有值,`??`
+        // 永远短路,于是 `result.message` 一次都进不了日志。线上真实后果:一天 5 次自愈
+        // 失败只留下 5 行「开放平台 API 错误」,而被吞掉的那句正是唯一有用的诊断
+        // (`code=10043 版本已创建,请刷新`),排查只能靠重放整条链路才拿到。
+        // 泛化标签帮人快速归类,具体消息才说得清到底哪儿坏——别再让前者盖掉后者。
+        const reasonLabel = reasons[result.reason] ?? result.reason;
+        // 审核中不是「修不了」，是「现在不能改、审批通过就好」。日志级别降为 info 并显式
+        // 说明不会落回深链 DM——把权限链接推给管理员是**错误的建议**：审核期间开放平台
+        // 连 scope/update 都拒（实测 code=10046），点了也写不进去。
+        if (result.reason === 'app_under_review') {
+            logger.info(`[${larkAppId}] auto-fix deferred: ${reasonLabel}` +
+                `${result.message ? ` — ${result.message}` : ''}`);
+            return { kind: 'under_review', inReviewVersionId: result.inReviewVersionId };
+        }
+        logger.warn(`[${larkAppId}] auto-fix not possible (${result.reason}: ${reasonLabel}` +
+            `${result.message ? ` — ${result.message}` : ''}). ` +
             (opts?.silent ? 'Leaving opt-in scope ungranted (no DM).' : 'Falling back to manual deep-link DM.'));
-        return false;
+        return { kind: 'failed' };
     }
     catch (err) {
         logger.warn(`[${larkAppId}] auto-fix error: ${err?.message ?? err}` +
             (opts?.silent ? ' — leaving opt-in scope ungranted (no DM)' : ' — falling back to manual DM'));
-        return false;
+        return { kind: 'failed' };
     }
 }
 export async function checkRequiredScopes(larkAppId) {
@@ -360,7 +399,9 @@ export async function checkRequiredScopes(larkAppId) {
             if (brand === 'feishu') {
                 const requiredNow = BOTMUX_REQUIRED_SCOPES.map(s => ({ name: s.name, desc: s.desc }));
                 const fixed = await tryAutoFixScopes(larkAppId, bot, brand, requiredNow, []);
-                if (fixed)
+                // 审核中同样直接返回：这条路径下游是让管理员去点 self_manage 深链，而审核期间
+                // 写锁生效，点了也开不了——等审批通过下次重启自检即可。
+                if (fixed.kind !== 'failed')
                     return;
             }
             const selfManageAuthUrl = buildScopeDeepLink(bot.config.larkAppId, SELF_MANAGE_SCOPE, brand);
@@ -512,10 +553,14 @@ export async function checkRequiredScopes(larkAppId) {
             // before (no API call / no prompt / no nag).
             if (missingOptional.length > 0 && brand === 'feishu') {
                 const toppedUp = await tryAutoFixScopes(larkAppId, bot, brand, [], missingOptional, { disableQrLogin: true, silent: true, grantedScopeNames: grantedScopeBuckets });
-                if (toppedUp) {
+                // 只有真的补上了才说「auto-topped-up」：审核中什么都没写进去（开放平台
+                // 连 scope/update 都拒），说补上了就是谎报。审核中静默跳过，等审批通过。
+                if (toppedUp.kind === 'fixed') {
                     logger.info(`[${larkAppId}] auto-topped-up ${missingOptional.length} optional scope(s): ${missingOptional.map(s => s.name).join('、')}`);
                     return;
                 }
+                if (toppedUp.kind === 'under_review')
+                    return;
                 logger.debug(`[${larkAppId}] optional scope(s) missing (${missingOptional.map(s => s.name).join('、')}); no cached web session to auto-apply — leaving to opt-in feature owner`);
             }
             logger.info(`[${larkAppId}] all critical scopes granted (${BOTMUX_REQUIRED_SCOPES.filter(s => s.critical).length} checked)`);
@@ -526,8 +571,49 @@ export async function checkRequiredScopes(larkAppId) {
         // directly add missing scopes and publish a new version without user interaction.
         // Falls through to manual DM warning if session is missing/expired.
         const autoFixed = await tryAutoFixScopes(larkAppId, bot, brand, missingCritical, missingOptional, { grantedScopeNames: grantedScopeBuckets });
-        if (autoFixed)
+        if (autoFixed.kind === 'fixed')
             return;
+        // 审核中：**不推权限深链**（审核期间连 scope/update 都被拒，点了写不进去），
+        // 也**不说「等审批通过就好」**——触发审批通常意味着有配置不合规，那一版不会自己
+        // 通过（模板建的应用出生带「数据范围=全部」，正撞租户「非必要不申请全员数据」的
+        // 加签规则）。所以这里只做一件事：**如实告诉管理员卡在哪、为什么卡、怎么修**。
+        if (autoFixed.kind === 'under_review') {
+            const summary = missingCritical.map(s => `${s.name} (${s.desc})`).join('、');
+            logger.warn(`[${larkAppId}] 缺少 ${missingCritical.length} 项必需权限（${summary}），` +
+                '但应用有一个版本卡在飞书审核中、配置暂时不可写；需人工修配置后撤回重提，botmux 无法自动解决。');
+            const reviewAdmin = getAdminOpenId(bot);
+            // 🔴 同一个待审版本只打扰一次。不做节流的话，卡在审核中是个持续数天的状态
+            //（线上实测 18 天 / 23 天），而本函数每次 daemon 启动都跑一遍 ⟹ 卡 N 天就发 N 条
+            // 一模一样的 DM，等于把这次要消灭的刷屏换个文案请回来。
+            // key 用待审版本 id：对齐「事情有没有变化」而非「过了多久」——人撤回重提了新版本，
+            // 该说；同一版还卡着，不必再说。拿不到 id 时**刻意不节流**（见 store 注释）。
+            const alreadyNotified = wasPendingReviewNotified(config.session.dataDir, larkAppId, autoFixed.inReviewVersionId);
+            if (reviewAdmin && !alreadyNotified) {
+                const rangeHint = await inspectUnderReviewConfigHints(bot.config.larkAppId, brand);
+                const delivered = await dmAdmin(larkAppId, reviewAdmin, `⏳ 机器人 "${bot.botName ?? larkAppId}" 还缺 ${missingCritical.length} 项必需权限，`
+                    + `而它有一个版本**卡在飞书审核中**，开放平台锁定了配置写入，botmux 补不了：\n\n`
+                    + `${missingCritical.map(s => `• ${s.desc} (\`${s.name}\`)`).join('\n')}\n\n`
+                    + `**为什么会进审核**：触发企业审批通常说明有配置不合规，最常见是权限的「数据范围」`
+                    + `没配、默认成「全部/全员」，撞上租户「非必要不申请全员数据，如申请全员范围需提供`
+                    + `充分理由、视情况加签至 CEO-2」的规则。${rangeHint}\n\n`
+                    + `**怎么修**（这一版不会自己通过，需要人工）：\n`
+                    + `1. 开放平台 →「版本管理与发布」→ 点进审核中那一版的**版本详情**，看审批详情里被卡的项\n`
+                    + `2. 修掉不合规项（如把权限的数据范围从「全部」改成「与应用的可用范围一致」）\n`
+                    + `3. 在版本详情页点 **Withdraw** 撤回该版本\n`
+                    + `4. 执行 \`botmux restart\` —— botmux 会自动补齐权限并重新提交\n\n`
+                    + `⚠️ 直接撤回重提**不管用**：不改配置的话同一条规则会再拦一次。\n`
+                    + `⚠️ 此时去权限管理页手动点开通也**无效**：审核期间飞书连「申请权限」都拒绝。`, `app under review, ${missingCritical.length} scopes deferred`);
+                // ⚠️ **发送成功才记账**。反了的话一次网络失败就把这个 versionId 永久节流掉，
+                // 管理员再也收不到提醒，而且是零信号的静默丢失，比刷屏更难发现。
+                if (delivered) {
+                    markPendingReviewNotified(config.session.dataDir, larkAppId, autoFixed.inReviewVersionId);
+                }
+            }
+            else if (alreadyNotified) {
+                logger.info(`[${larkAppId}] 待审版本 ${autoFixed.inReviewVersionId} 已通知过管理员，本次不重复打扰`);
+            }
+            return;
+        }
         // Log + DM consolidated message listing all missing critical scopes.
         const summaryLine = missingCritical.map(s => `${s.name} (${s.desc})`).join('、');
         logger.error(`[${larkAppId}] 缺少 ${missingCritical.length} 项必需权限：${summaryLine}。` +
@@ -602,11 +688,28 @@ export async function ensureVcMeetingEventsSubscribed(larkAppId) {
         }
         // Automation failed (session expired mid-run / api error). Log; DM the admin
         // once so a bot that genuinely lacks the subscription gets a human nudge.
-        logger.warn(`[${larkAppId}] VC event auto-subscribe failed (${result.reason}): ${result.message}`);
+        //
+        // 「应用正在审核中」要单独说：审核期间开放平台锁配置写入，刷新登录态**没有用**
+        // （不是 session 问题），等审批通过重启即可。给错的操作建议比不给更糟——用户会
+        // 反复 `botmux setup` 却始终不见好。
+        const underReview = !result.ok && result.reason === 'app_under_review';
+        if (underReview) {
+            logger.info(`[${larkAppId}] VC event auto-subscribe deferred (app under review): ${result.message}`);
+        }
+        else {
+            logger.warn(`[${larkAppId}] VC event auto-subscribe failed (${result.reason}): ${result.message}`);
+        }
         const adminOpenId = getAdminOpenId(bot);
         if (adminOpenId) {
             await dmAdmin(larkAppId, adminOpenId, `⚠️ botmux 想在启动时自动为机器人 "${bot.botName ?? larkAppId}" 订阅视频会议事件（vc.bot.meeting_*），以便它被拉进会时能自动进会，但自动配置失败：${result.message}\n\n` +
-                `请运行 \`botmux setup\` 刷新飞书开放平台登录态后重启 daemon，botmux 会自动重试。`, 'vc event auto-subscribe failed');
+                (underReview
+                    // ⚠️ 别说「等审批通过就好」：触发审批通常意味着有配置不合规，那一版**不会自己
+                    // 通过**，说「等」等于让人干等。也别说「刷新登录态」——审核锁住的是配置写入，
+                    // 不是 session 问题。
+                    ? '该应用有一个版本**卡在飞书审核中**，配置写入被锁（刷新登录态无效）。触发审批通常说明有配置不合规'
+                        + '（最常见：权限的「数据范围」默认成「全部/全员」）。需人工处理：开放平台 →「版本管理与发布」→ 该版本详情 → '
+                        + '看审批详情修掉不合规项 → 点 **Withdraw** 撤回 → 执行 `botmux restart` 重试。不改配置直接撤回重提会被同一条规则再拦。'
+                    : '请运行 `botmux setup` 刷新飞书开放平台登录态后重启 daemon，botmux 会自动重试。'), underReview ? 'vc event auto-subscribe deferred (under review)' : 'vc event auto-subscribe failed');
         }
     }
     catch (err) {