koishi-plugin-ggcevo 1.0.4 → 1.0.6

package/lib/index.d.ts

@@ -5,6 +5,13 @@ export interface Config {
     mapMonitorGroups: string[];
     mapMonitorMapIds: number[];
     mapMonitorApiUrl: string;
+    tencentDocsEnabled: boolean;
+    tencentDocsClientId: string;
+    tencentDocsClientSecret: string;
+    tencentDocsAccessToken: string;
+    tencentDocsOpenId: string;
+    tencentDocsBanListFileId: string;
+    tencentDocsBanListSheetId: string;
 }
 export declare const Config: Schema<Config>;
 export declare const inject: {
@@ -33,6 +40,8 @@ declare module 'koishi' {
         ggcevo_exchange_log: ExchangeLog;
         ggcevo_activity: Activity;
         ggcevo_activity_claim_log: ActivityClaimLog;
+        ggcevo_docs_token: GgcEvoDocsToken;
+        ggcevo_ban_record: GgcEvoBanRecord;
     }
 }
 export interface GgcEvoPlayer {
@@ -49,6 +58,34 @@ export interface GgcEvoMapMonitorState {
     lastState: string;
     lastCheckedAt: Date;
 }
+export interface GgcEvoDocsToken {
+    /** 账号标识, 应用级账号固定为 'app_account' */
+    user_id: string;
+    /** 应用级账号 Open ID */
+    docs_user_id: string;
+    access_token: string;
+    refresh_token: string;
+    expires_at: Date;
+    update_time: Date;
+}
+export interface GgcEvoBanRecord {
+    /** 自增ID, 对应文档行号(行号 = id + 1, 跳过表头) */
+    id: number;
+    /** A列: 游戏句柄 */
+    handle: string;
+    /** C列: 封禁等级 */
+    ban_level: string;
+    /** D列: 处罚原因 (text 类型, 支持长文本) */
+    reason: string;
+    /** E列: 处罚次数 */
+    count: string;
+    /** F列: 审核员 */
+    auditor: string;
+    /** G列: 审核时间 */
+    audit_time: string;
+    /** 最近一次同步时间 */
+    update_time: Date;
+}
 export interface Backpack {
     id: number;
     user_id: string;

package/lib/index.js

@@ -35,7 +35,14 @@ var Config = import_koishi.Schema.object({
   mapMonitorEnabled: import_koishi.Schema.boolean().description("是否启用地图检测定时任务").default(false),
   mapMonitorGroups: import_koishi.Schema.array(import_koishi.Schema.string()).description("地图检测广播的群组ID列表").default([]),
   mapMonitorMapIds: import_koishi.Schema.array(import_koishi.Schema.number()).description("需要检测的地图ID列表").default([]),
-  mapMonitorApiUrl: import_koishi.Schema.string().description("地图检测API地址").default("https://server.dreamprotocol.info:13085/mapmonitor/maps")
+  mapMonitorApiUrl: import_koishi.Schema.string().description("地图检测API地址").default("https://server.dreamprotocol.info:13085/mapmonitor/maps"),
+  tencentDocsEnabled: import_koishi.Schema.boolean().description("是否启用腾讯文档功能").default(false),
+  tencentDocsClientId: import_koishi.Schema.string().description("腾讯文档开放平台应用 Client ID(应用ID)").default(""),
+  tencentDocsClientSecret: import_koishi.Schema.string().description("腾讯文档应用 Client Secret(应用级账号模式需要, 用户级模式留空)").role("secret").default(""),
+  tencentDocsAccessToken: import_koishi.Schema.string().description("腾讯文档 Access Token(用户级模式必填, 通过扫码授权获取)").role("secret").default(""),
+  tencentDocsOpenId: import_koishi.Schema.string().description("腾讯文档 Open ID(用户级模式必填, 与 Access Token 同时获取)").default(""),
+  tencentDocsBanListFileId: import_koishi.Schema.string().description("封禁记录在线表格的文件ID(短ID或完整ID)").default("DTVdYZVBDdFhEUkp6"),
+  tencentDocsBanListSheetId: import_koishi.Schema.string().description("封禁记录工作表ID(表格URL中tab参数)").default("BB08J2")
 });
 var inject = {
   required: ["database"]
@@ -183,6 +190,29 @@ function apply(ctx, config) {
   }, {
     primary: ["activity_id", "user_id"]
   });
+  ctx.model.extend("ggcevo_docs_token", {
+    user_id: "string",
+    docs_user_id: "string",
+    access_token: "string",
+    refresh_token: "string",
+    expires_at: "timestamp",
+    update_time: "timestamp"
+  }, {
+    primary: "user_id"
+  });
+  ctx.model.extend("ggcevo_ban_record", {
+    id: "unsigned",
+    handle: "string",
+    ban_level: "string",
+    reason: "text",
+    count: "string",
+    auditor: "string",
+    audit_time: "string",
+    update_time: "timestamp"
+  }, {
+    primary: "id",
+    autoInc: true
+  });
   if (config.mapMonitorEnabled && config.mapMonitorGroups.length > 0 && config.mapMonitorMapIds.length > 0) {
     ctx.setInterval(async () => {
       try {
@@ -1917,6 +1947,307 @@ ${message}
     });
     return `✅ 赎罪券使用成功！`;
   });
+  const DOCS_APP_ACCOUNT_KEY = "app_account";
+  const isUserTokenMode = /* @__PURE__ */ __name(() => !!config.tencentDocsAccessToken && !!config.tencentDocsOpenId, "isUserTokenMode");
+  const isDocsConfigured = /* @__PURE__ */ __name(() => config.tencentDocsEnabled && !!config.tencentDocsClientId && (isUserTokenMode() || !!config.tencentDocsClientSecret), "isDocsConfigured");
+  const docsOAuth = {
+    /** 获取应用级账号 Access Token / Refresh Token (应用级账号为应用全局唯一, 无需用户授权) */
+    async getAppAccountToken() {
+      return ctx.http.get("https://docs.qq.com/oauth/v2/app-account-token", {
+        params: {
+          client_id: config.tencentDocsClientId,
+          client_secret: config.tencentDocsClientSecret
+        }
+      });
+    },
+    /** 使用 Refresh Token 刷新 Access Token (Refresh Token 有效期 1 年, 回包不含新 Refresh Token) */
+    async refreshToken(refreshToken) {
+      return ctx.http.get("https://docs.qq.com/oauth/v2/token", {
+        params: {
+          client_id: config.tencentDocsClientId,
+          client_secret: config.tencentDocsClientSecret,
+          grant_type: "refresh_token",
+          refresh_token: refreshToken
+        }
+      });
+    }
+  };
+  const getValidDocsToken = /* @__PURE__ */ __name(async () => {
+    if (isUserTokenMode()) {
+      return {
+        user_id: DOCS_APP_ACCOUNT_KEY,
+        docs_user_id: config.tencentDocsOpenId,
+        access_token: config.tencentDocsAccessToken,
+        refresh_token: "",
+        expires_at: new Date(Date.now() + 365 * 24 * 60 * 60 * 1e3),
+        // 用户级模式无法自动判断过期, 设为1年后
+        update_time: /* @__PURE__ */ new Date()
+      };
+    }
+    const [record] = await ctx.database.get("ggcevo_docs_token", { user_id: DOCS_APP_ACCOUNT_KEY });
+    if (record && record.expires_at.getTime() > Date.now() + 5 * 60 * 1e3) return record;
+    const formatHttpError = /* @__PURE__ */ __name((e) => {
+      const parts = [];
+      if (e?.name) parts.push(e.name);
+      if (e?.message) parts.push(e.message);
+      if (e?.response) {
+        parts.push(`HTTP ${e.response.status}`);
+        const body = e.response.data;
+        if (body != null) parts.push(typeof body === "string" ? body : JSON.stringify(body));
+      } else if (e?.code) {
+        parts.push(`code=${e.code}`);
+      }
+      return parts.join(" | ") || String(e);
+    }, "formatHttpError");
+    try {
+      let resp;
+      if (record) {
+        resp = await docsOAuth.refreshToken(record.refresh_token).catch((refreshErr) => {
+          ctx.logger("ggcevo").warn("刷新 Token 失败, 回退到重新获取应用级 Token: %s", formatHttpError(refreshErr));
+          return docsOAuth.getAppAccountToken();
+        });
+      } else {
+        resp = await docsOAuth.getAppAccountToken();
+      }
+      if (!resp?.access_token) {
+        ctx.logger("ggcevo").warn("应用级 Token 回包缺少 access_token: %o", resp);
+        return record || null;
+      }
+      await ctx.database.upsert("ggcevo_docs_token", [{
+        user_id: DOCS_APP_ACCOUNT_KEY,
+        docs_user_id: resp.user_id || record?.docs_user_id || "",
+        access_token: resp.access_token,
+        refresh_token: resp.refresh_token || record?.refresh_token || "",
+        expires_at: new Date(Date.now() + (resp.expires_in || 0) * 1e3),
+        update_time: /* @__PURE__ */ new Date()
+      }]);
+      const [updated] = await ctx.database.get("ggcevo_docs_token", { user_id: DOCS_APP_ACCOUNT_KEY });
+      return updated || null;
+    } catch (e) {
+      ctx.logger("ggcevo").warn("获取/刷新腾讯文档应用级 Token 失败: %s", formatHttpError(e));
+      return record || null;
+    }
+  }, "getValidDocsToken");
+  const docsApiRequest = /* @__PURE__ */ __name(async (method, path, data) => {
+    const token = await getValidDocsToken();
+    if (!token) throw new Error("腾讯文档应用级账号不可用, 请检查插件配置(Client ID / Client Secret)");
+    const url = `https://docs.qq.com/openapi${path}`;
+    const headers = {
+      "Access-Token": token.access_token,
+      "Client-Id": config.tencentDocsClientId,
+      "Open-Id": token.docs_user_id
+    };
+    if (method === "GET" || method === "DELETE") {
+      return ctx.http.get(url, { headers, params: data });
+    }
+    headers["Content-Type"] = "application/x-www-form-urlencoded";
+    const form = new URLSearchParams(data || {});
+    if (method === "PUT") return ctx.http.put(url, form, { headers });
+    return ctx.http.post(url, form, { headers });
+  }, "docsApiRequest");
+  ctx.command("腾讯文档/状态", "查看腾讯文档授权状态").action(async () => {
+    if (!isDocsConfigured()) return "❌ 腾讯文档功能未启用或配置不完整。";
+    const token = await getValidDocsToken();
+    if (!token) {
+      return isUserTokenMode() ? "❌ 用户级 Token 模式: 请检查 Access Token / Open ID 配置。" : "❌ 应用级账号 Token 获取失败, 请检查 Client ID / Client Secret 配置。";
+    }
+    const mode = isUserTokenMode() ? "用户级(扫码授权)" : "应用级账号(自动刷新)";
+    return [
+      "📄 腾讯文档授权状态",
+      `授权模式: ${mode}`,
+      `Client ID: ${config.tencentDocsClientId}`,
+      `Open ID: ${token.docs_user_id}`,
+      `令牌过期时间: ${toBeijingTime(token.expires_at.toISOString())}`,
+      `最近更新: ${toBeijingTime(token.update_time.toISOString())}`
+    ].join("\n");
+  });
+  const extractCellText = /* @__PURE__ */ __name((cell) => {
+    if (!cell?.cellValue) return "";
+    const v = cell.cellValue;
+    if (v.text != null) return String(v.text);
+    if (v.number != null) return String(v.number);
+    if (v.time) {
+      const t = v.time;
+      const pad = /* @__PURE__ */ __name((n) => String(n ?? 0).padStart(2, "0"), "pad");
+      const date = `${t.year ?? ""}-${pad(t.month)}-${pad(t.day)}`.replace(/^-+/, "");
+      const time = `${pad(t.hour)}:${pad(t.minute)}:${pad(t.second)}`;
+      return t.hour != null ? `${date} ${time}` : date;
+    }
+    if (v.link) return v.link.text || v.link.url || "";
+    if (v.location) return v.location.name || "";
+    return "";
+  }, "extractCellText");
+  const normalizeHandle = /* @__PURE__ */ __name((raw) => {
+    const s = (raw || "").trim();
+    const m = s.match(/^([1235])-s2-([12])-(\d+)$/i);
+    if (m) return `${m[1]}-S2-${m[2]}-${m[3]}`;
+    return s.toLowerCase();
+  }, "normalizeHandle");
+  const fetchBanRecordsFromDocs = /* @__PURE__ */ __name(async () => {
+    const fileId = config.tencentDocsBanListFileId;
+    const sheetId = config.tencentDocsBanListSheetId;
+    const meta = await docsApiRequest("GET", `/spreadsheet/v3/files/${fileId}`, { concise: 1 });
+    const metaOk = meta?.code === 0 || meta?.ret === 0;
+    if (metaOk === false && meta?.code != null) {
+      throw new Error(`查询工作表信息失败: ${meta.message || "未知错误"}(code=${meta.code})`);
+    }
+    const props = meta?.data?.properties || meta?.properties || [];
+    const sheetInfo = props.find((s) => s.sheetId === sheetId);
+    const rowTotal = Number(sheetInfo?.rowTotal) || 0;
+    if (rowTotal <= 1) return [];
+    const allRows = [];
+    const batchSize = 1e3;
+    for (let start = 2; start <= rowTotal; start += batchSize) {
+      const end = Math.min(start + batchSize - 1, rowTotal);
+      const resp = await docsApiRequest("GET", `/spreadsheet/v3/files/${fileId}/${sheetId}/A${start}:G${end}`);
+      const respOk = resp?.code === 0 || resp?.ret === 0;
+      if (respOk === false && resp?.code != null) {
+        throw new Error(`查询范围 A${start}:G${end} 失败: ${resp.message || "未知错误"}(code=${resp.code})`);
+      }
+      const rows = resp?.data?.gridData?.rows || resp?.gridData?.rows || [];
+      for (const row of rows) {
+        const cells = row.values || [];
+        allRows.push([
+          extractCellText(cells[0]),
+          // A: 句柄
+          extractCellText(cells[1]),
+          // B: (未使用)
+          extractCellText(cells[2]),
+          // C: 封禁等级
+          extractCellText(cells[3]),
+          // D: 处罚原因
+          extractCellText(cells[4]),
+          // E: 处罚次数
+          extractCellText(cells[5]),
+          // F: 审核员
+          extractCellText(cells[6])
+          // G: 审核时间
+        ]);
+      }
+    }
+    return allRows;
+  }, "fetchBanRecordsFromDocs");
+  const syncBanRecords = /* @__PURE__ */ __name(async () => {
+    const rows = await fetchBanRecordsFromDocs();
+    const now = /* @__PURE__ */ new Date();
+    const records = rows.map((r, i) => ({
+      id: i + 1,
+      // 自增 id, 对应文档行号 (id=1 → 文档第2行)
+      handle: r[0] || "",
+      ban_level: r[2] || "",
+      reason: r[3] || "",
+      count: r[4] || "",
+      auditor: r[5] || "",
+      audit_time: r[6] || "",
+      update_time: now
+    }));
+    const oldRecords = await ctx.database.get("ggcevo_ban_record", {}, { fields: ["id"] });
+    const oldCount = oldRecords.length;
+    await ctx.database.remove("ggcevo_ban_record", {});
+    if (records.length > 0) {
+      await ctx.database.upsert("ggcevo_ban_record", records);
+    }
+    const diff = records.length - oldCount;
+    ctx.logger("ggcevo").info(
+      "封禁记录全量同步完成: 旧 %d 条 → 新 %d 条 (%s%d)",
+      oldCount,
+      records.length,
+      diff >= 0 ? "+" : "",
+      diff
+    );
+    return records.length;
+  }, "syncBanRecords");
+  if (isDocsConfigured() && config.tencentDocsBanListFileId && config.tencentDocsBanListSheetId) {
+    const syncTask = /* @__PURE__ */ __name(async () => {
+      try {
+        const count = await syncBanRecords();
+        ctx.logger("ggcevo").info("封禁记录同步完成, 共 %d 条", count);
+      } catch (e) {
+        ctx.logger("ggcevo").warn("封禁记录定时同步失败: %o", e);
+      }
+    }, "syncTask");
+    ctx.setTimeout(syncTask, 5e3);
+    ctx.setInterval(syncTask, 60 * 60 * 1e3);
+  }
+  ctx.command("ggcevo/同步封禁记录", { authority: 3 }).action(async () => {
+    if (!isDocsConfigured()) return "❌ 腾讯文档功能未启用或配置不完整。";
+    try {
+      const count = await syncBanRecords();
+      return `✅ 封禁记录同步完成, 共 ${count} 条。`;
+    } catch (e) {
+      ctx.logger("ggcevo").warn("手动同步封禁记录失败: %o", e);
+      return `❌ 同步失败: ${e?.message || e}`;
+    }
+  });
+  ctx.command("ggcevo/封禁记录").action(async (argv) => {
+    if (!isDocsConfigured()) return "❌ 腾讯文档功能未启用或配置不完整。";
+    const session = argv.session;
+    const handle = await getHandle(session);
+    if (!handle) {
+      return "🔒 需要先绑定游戏句柄。\n💡 使用 `绑定句柄` 命令进行绑定。";
+    }
+    const [lastSync] = await ctx.database.get("ggcevo_ban_record", {}, { limit: 1 });
+    if (!lastSync) {
+      return "⚠️ 封禁记录尚未同步, 请稍后再试或联系管理员。";
+    }
+    const syncTime = lastSync.update_time;
+    const allRecords = await ctx.database.get("ggcevo_ban_record", {}, { sort: { id: "asc" } });
+    const target = normalizeHandle(handle);
+    const records = allRecords.filter((r) => r.handle && normalizeHandle(r.handle) === target);
+    if (records.length === 0) {
+      return [
+        `✅ 句柄 ${handle} 暂无封禁记录。`,
+        `📊 数据最近同步: ${toBeijingTime(syncTime.toISOString())}`
+      ].join("\n");
+    }
+    const formatRecord = /* @__PURE__ */ __name((idx) => {
+      const r = records[idx];
+      return [
+        `📋 封禁记录 (${idx + 1}/${records.length})`,
+        `文档行号: ${r.id + 1} 行`,
+        // id 对应文档行号 (跳过表头)
+        `句柄: ${r.handle}`,
+        `封禁等级: ${r.ban_level || "-"}`,
+        `处罚原因: ${r.reason || "-"}`,
+        `处罚次数: ${r.count || "-"}`,
+        `审核员: ${r.auditor || "-"}`,
+        `审核时间: ${r.audit_time || "-"}`,
+        "",
+        '💡 回复 "下一页"/"上一页"/页码数字 翻页, 或 "退出" 结束'
+      ].join("\n");
+    }, "formatRecord");
+    let page = 0;
+    await session.send([
+      formatRecord(page),
+      `📊 数据最近同步: ${toBeijingTime(syncTime.toISOString())}`
+    ].join("\n"));
+    while (true) {
+      const input = await session.prompt(6e4);
+      if (!input) break;
+      const cmd = input.trim();
+      if (/^(退出|exit|q|end)$/i.test(cmd)) break;
+      if (/^(下一页|下页|next|n)$/i.test(cmd)) {
+        if (page < records.length - 1) {
+          page++;
+          await session.send(formatRecord(page));
+        } else await session.send('已是最后一页。回复 "上一页" 或 "退出"。');
+      } else if (/^(上一页|上页|prev|p|上一个)$/i.test(cmd)) {
+        if (page > 0) {
+          page--;
+          await session.send(formatRecord(page));
+        } else await session.send('已是第一页。回复 "下一页" 或 "退出"。');
+      } else {
+        const n = parseInt(cmd, 10);
+        if (!isNaN(n) && n >= 1 && n <= records.length) {
+          page = n - 1;
+          await session.send(formatRecord(page));
+        } else {
+          await session.send('⚠️ 无效输入, 请回复 "下一页"/"上一页"/页码/退出。');
+        }
+      }
+    }
+    return "已退出封禁记录查询。";
+  });
 }
 __name(apply, "apply");
 function toBeijingTime(isoString) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-ggcevo",
   "description": "GGCEVO 综合插件：星际争霸2游戏句柄绑定 + 签到/抽奖/兑换/背包/活动系统等虚拟物品玩法",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/readme.md

@@ -19,6 +19,8 @@ npm install koishi-plugin-ggcevo
 
 ## 配置项
 
+### 地图检测
+
 | 配置项 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `mapMonitorEnabled` | `boolean` | `false` | 是否启用地图检测定时任务 |
@@ -26,6 +28,24 @@ npm install koishi-plugin-ggcevo
 | `mapMonitorMapIds` | `number[]` | `[]` | 需要检测的地图 ID 列表 |
 | `mapMonitorApiUrl` | `string` | `https://server.dreamprotocol.info:13085/mapmonitor/maps` | 地图检测 API 地址 |
 
+### 腾讯文档（封禁记录查询）
+
+支持两种授权模式，二选一即可：
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `tencentDocsEnabled` | `boolean` | `false` | 是否启用腾讯文档功能 |
+| `tencentDocsClientId` | `string` | `''` | 应用 Client ID（应用ID） |
+| `tencentDocsClientSecret` | `string` | `''` | 应用 Client Secret（**应用级模式必填**，用户级模式留空） |
+| `tencentDocsAccessToken` | `string` | `''` | Access Token（**用户级模式必填**，通过扫码授权获取） |
+| `tencentDocsOpenId` | `string` | `''` | Open ID（**用户级模式必填**，与 Access Token 同时获取） |
+| `tencentDocsBanListFileId` | `string` | `DTVdYZVBDdFhEUkp6` | 封禁记录在线表格文件ID（短ID或完整ID） |
+| `tencentDocsBanListSheetId` | `string` | `BB08J2` | 封禁记录工作表ID（表格URL中 `tab` 参数） |
+
+**授权模式说明：**
+- **用户级模式**（推荐用于无 `Client Secret` 的场景）：填写 `tencentDocsClientId` + `tencentDocsAccessToken` + `tencentDocsOpenId`，三者均通过腾讯文档开放平台扫码授权流程获取。Token 过期后需重新获取并在控制台更新。
+- **应用级模式**：填写 `tencentDocsClientId` + `tencentDocsClientSecret`，插件自动获取并刷新 Token，无需手动维护。需应用已开通 `scope.auth.account` 权限。
+
 ## 指令列表
 
 ### 星际争霸2 句柄（sc2arcade）
@@ -57,6 +77,14 @@ npm install koishi-plugin-ggcevo
 | `活动列表` | — | — | 查看当前所有活动 |
 | `补签` | — | — | 使用补签券补签漏签的日期 |
 | `使用 <name>` | — | — | 使用指定物品（如赎罪券等） |
+| `封禁记录` | — | — | 查询当前绑定句柄在腾讯文档封禁记录表中的全部记录，每页显示 1 条，支持翻页（回复"下一页/上一页/页码/退出"） |
+| `同步封禁记录` | — | 3 | 立即从腾讯文档拉取全量数据并写入数据库（管理员指令） |
+
+### 腾讯文档
+
+| 指令 | 说明 |
+| --- | --- |
+| `腾讯文档/状态` | 查看腾讯文档授权状态（授权模式、Open ID、令牌过期时间等） |
 
 ## 物品与奖池
 
@@ -93,9 +121,43 @@ npm install koishi-plugin-ggcevo
 - `ggcevo_exchange_log` — 兑换记录
 - `ggcevo_activity` — 活动配置
 - `ggcevo_activity_claim_log` — 活动领取记录（主键 `activity_id` + `user_id`）
+- `ggcevo_docs_token` — 腾讯文档令牌缓存（应用级模式使用，主键 `user_id`，应用级账号固定为 `app_account`）
+- `ggcevo_ban_record` — 封禁记录（主键 `id` 自增，对应文档行号 `id+1`，每小时全量同步）
 
 ## 更新日志
 
+### v1.0.6
+
+修复封禁记录同步时长文本写入失败的问题。
+
+- **修复**：`ggcevo_ban_record` 表 `reason`（处罚原因）字段类型由 `string`（VARCHAR(255)）改为 `text`（TEXT，最大 65535 字符），避免处罚原因过长时触发 `ER_DATA_TOO_LONG` 错误
+- 类型变更由 minato 自动执行 `ALTER TABLE`，已有数据不受影响，直接重启即可生效
+
+### v1.0.5
+
+新增**腾讯文档封禁记录查询**功能，基于腾讯文档开放平台 V3 在线表格接口实现。
+
+**新增功能：**
+- **腾讯文档授权**：支持「用户级 Token」与「应用级账号」双授权模式自动识别
+  - 用户级模式：填写 `Client ID` + `Access Token` + `Open ID`（适用于无 Client Secret 的场景）
+  - 应用级模式：填写 `Client ID` + `Client Secret`（自动获取并刷新 Token，需 `scope.auth.account` 权限）
+- **封禁记录同步**：每小时自动从腾讯文档在线表格全量拉取数据写入数据库（启动后延迟 5 秒首次同步），采用全量替换策略保证 `id` 与文档行号严格对应
+- **封禁记录查询**：`封禁记录` 指令查询当前绑定句柄的全部封禁记录，每页 1 条支持翻页（下一页/上一页/页码/退出），显示文档行号便于定位原文档
+- **手动同步**：`同步封禁记录` 指令（管理员权限 3）立即触发同步
+- **授权状态查询**：`腾讯文档/状态` 指令查看当前授权模式与令牌信息
+
+**新增配置项：**
+- `tencentDocsEnabled`、`tencentDocsClientId`、`tencentDocsClientSecret`
+- `tencentDocsAccessToken`、`tencentDocsOpenId`
+- `tencentDocsBanListFileId`（默认 `DTVdYZVBDdFhEUkp6`）、`tencentDocsBanListSheetId`（默认 `BB08J2`）
+
+**新增数据库表：**
+- `ggcevo_docs_token` — 令牌缓存（应用级模式）
+- `ggcevo_ban_record` — 封禁记录（主键自增 `id`，对应文档行号 `id+1`）
+
+**表格结构要求：**
+- A列：句柄 / C列：封禁等级 / D列：处罚原因 / E列：处罚次数 / F列：审核员 / G列：审核时间
+
 ### v1.0.4
 
 - 新增配置项 `mapMonitorApiUrl`，可将地图检测的 API 地址通过配置项填写，默认值为 `https://server.dreamprotocol.info:13085/mapmonitor/maps`。