koishi-plugin-qq-aifdian-group

v1.2.1

Published

2 months ago

QQ入群验证-爱发电订单号验证-赞助群入群验证

0High
0Medium
0Low

xiaoyuhai

chatbot koishi plugin qq ifdian verification group captcha 爱发电入群验证

qq-aifdian-group - 爱发电入群验证插件

QQ 群入群验证插件，支持爱发电订单号验证、数学计算验证等多种验证方式。

✨ 特性

🔐 多种验证模式：支持爱发电订单验证、数学计算验证、两者组合验证
📊 可视化群管理：左侧侧边栏独立管理页面，直观查看和配置各群验证设置
🎯 单群独立配置：每个群可以独立设置验证模式、头衔奖励等
💾 数据持久化：订单绑定关系存储在数据库中，重启不丢失
🔍 详细日志记录：每次验证决策都有完整日志，便于审计和排查问题
👑 头衔奖励：验证通过后自动授予自定义头衔

🚀 快速开始

1. 安装插件

npm install koishi-plugin-qq-aifdian-group

2. 配置插件

在 Koishi 管理后台找到 qq-aifdian-group 插件进行配置：

基础配置

爱发电 Token：从爱发电开发者平台获取
爱发电用户 ID：同上
管理员 QQ：可以执行管理命令的 QQ 号列表

⚠️ 重要提示：默认配置策略

新版本的默认行为已更改：

✅ 所有群默认不启用验证（需要手动开启）
✅ 默认验证模式为"数学计算"（人工审核友好）
✅ 全局验证默认关闭

这样做的好处是：

避免意外启用爱发电验证导致所有群都需要订单才能加入
新添加的群配置默认为禁用状态，需要明确启用
如果需要使用爱发电验证，必须显式配置并启用

群配置（推荐）

在 QQ 中发送 同步群 命令，自动将所有群添加到配置
打开 Koishi 管理后台 → 左侧菜单 → 💳 爱发电管理
在"群配置"部分可视化编辑各群设置：
- ✅ 手动启用需要验证的群
- 🎯 选择验证模式（数学计算/爱发电订单/两者都需要）
- 👑 设置头衔奖励

3. QQ 群设置

⚠️ 重要：QQ 群的入群验证方式必须设置为：

✅ "允许任何人加群" 或
✅ "需要发送验证信息"

❌ 不要使用 "需要回答问题并由管理员审核" 模式（该模式没有备注字段）

用户在入群申请的备注中填写爱发电订单号。

📱 可视化群管理

左侧侧边栏入口

插件会在 Koishi 管理后台左侧添加一个独立的 "💳 爱发电管理" 菜单项，点击后进入专属管理页面。

页面功能详解

📊 统计面板

总群数：显示已在配置中添加的群组总数
已启用验证群数：显示当前启用了入群验证的群组数量
订单绑定数：显示数据库中已绑定的爱发电订单数量（需要连接数据库）

⚙️ 全局配置概览

全局验证状态：显示是否启用了全局验证功能
- 绿色标签表示已启用
- 灰色标签表示未启用
验证模式：显示当前的全局验证模式
- 数学计算验证
- 爱发电订单验证
- 两者都需要
管理员数量：显示已配置的管理员 QQ 号数量

📋 群组配置列表 可视化展示所有群的验证配置，每个群组卡片包含：

群号：QQ 群号码
状态标签：
- ✅ 绿色 "Enabled" - 该群已启用验证
- ⚪ 灰色 "Disabled" - 该群未启用验证
验证模式：显示该群使用的验证方式
头衔奖励：
- 🏆 黄色标签显示头衔名称（如果启用）
- 灰色 "Disabled" 表示未启用头衔奖励
快速操作按钮：
- 点击 "Disable" 按钮禁用该群验证
- 点击 "Enable" 按钮启用该群验证

💡 使用提示区域 提供实用的配置建议：

如何使用"同步群"命令自动添加所有群
如何快速启用/禁用群组验证
如何为不同群组配置不同的验证模式
数据存储位置说明
管理员权限提醒

交互特性

响应式设计：自适应不同屏幕尺寸
悬停效果：鼠标悬停在群组卡片上时显示边框高亮和阴影
即时反馈：点击启用/禁用按钮立即更新状态
图标系统：使用 Material Design Icons 提供直观的视觉提示
颜色编码：通过颜色快速识别状态（绿色=启用，灰色=禁用，蓝色=主要信息）

技术实现

按照 Koishi 官方文档的规范实现：

后端注入 (src/index.ts)：

import {} from '@koishijs/plugin-console'
   
export function apply(ctx: Context, config: Config) {
  ctx.inject(['console'], (ctx) => {
    ctx.console.addEntry({
      dev: resolve(__dirname, '../client/index.ts'),
      prod: resolve(__dirname, '../dist'),
    })
  })
}

前端注册 (client/index.ts)：

import { Context } from '@koishijs/client'
import Page from './page.vue'
   
export default (ctx: Context) => {
  ctx.page({
    name: '爱发电管理',
    path: '/aifdian',
    icon: 'mdi-currency-usd',
    component: Page,
  })
}

Vue 组件 (client/page.vue)：
- 使用 Koishi UI 组件库（k-layout, k-card, k-button, k-tag, k-icon）
- 通过 useService('config') 获取插件配置
- Material Design Icons 图标系统
- 响应式布局设计

技术栈

Vue 3 + Composition API
TypeScript
Koishi Client SDK
Koishi UI Components
Material Design Icons
Vite 构建工具

命令行管理

也可以通过 QQ 发送命令进行管理：

# 查看所有群配置
群列表

# 同步所有群到配置
同步群

# 查询订单绑定
查询订单 <订单号>

# 清除订单绑定
清除订单 <订单号>

# 清除所有订单（重置）
清除所有订单 --confirm

# 查看订单列表
订单列表 [页码] [-l 数量]

⚙️ 配置说明

全局配置

| 配置项 | 说明 | 默认值 | |--------|------|--------| | globalEnabled | 是否启用全局验证 | false | | globalVerificationMode | 全局验证模式 | aifdian | | aifdianToken | 爱发电 API Token | "" | | aifdianUserId | 爱发电用户 ID | "" | | adminQQs | 管理员 QQ 列表 | [] |

群级配置（优先级更高）

每个群可以独立配置：

| 配置项 | 说明 | 默认值 | 可选值 | |--------|------|--------|--------| | groupId | 群号 | "" | 下拉选择（自动显示所有群） | | enabled | 是否启用验证 | false ⚠️ | true / false | | verificationMode | 验证模式 | math ⚠️ | math / aifdian / both | | enableTitleReward | 是否启用头衔奖励 | false | true / false | | titleReward | 头衔名称 | "赞助者" | 自定义文本 |

⚠️ 重要变更：

enabled 默认值为 false，新添加的群配置默认不启用验证
verificationMode 默认值为 math（数学计算验证），更适合作为初始验证方式
如需使用爱发电订单验证，必须手动启用并修改验证模式

🗄️ 数据存储

订单绑定关系存储在数据库表 qqAifdianGroupCache 中：

| 字段 | 类型 | 说明 | |------|------|------| | id | unsigned | 主键（自增） | | key | string | 缓存键（格式：order:{订单号}） | | value | json | 绑定的 QQ 用户 ID | | expireAt | unsigned | 过期时间戳（10年有效期） |

查看数据

Koishi 管理后台：左侧菜单 → 数据库 → qqAifdianGroupCache 表
管理员命令：查询订单 <订单号> 或 订单列表

直接查询数据库（SQLite）：

SELECT * FROM qqAifdianGroupCache WHERE key LIKE 'order:%';

🔧 开发

目录结构

qq-aifdian-group/
├── src/
│   └── index.ts              # 后端插件代码（包含 console 服务注入）
├── client/
│   ├── index.ts               # 前端入口（注册侧边栏页面）
│   ├── page.vue               # Vue 管理页面组件
│   └── tsconfig.json          # 前端 TypeScript 配置
├── dist/                      # 构建输出目录（自动生成）
│   ├── index.mjs              # 编译后的 JavaScript 代码
│   └── style.css              # 编译后的样式文件
├── package.json
├── vite.config.ts             # Vite 构建配置
└── readme.md

构建

开发模式

npm run build

这会同时构建后端和前端代码。

仅构建前端

npm run build:client

构建产物

dist/index.mjs - 编译后的前端 JavaScript 代码
dist/style.css - 编译后的 CSS 样式

这些文件会在插件加载时由 Koishi 控制台自动引用。

前端扩展

插件使用了 Koishi 的控制台扩展功能，在左侧侧边栏添加了独立的管理页面：

实现原理

按照 Koishi 官方文档的规范：

后端注入 (src/index.ts)：

import {} from '@koishijs/plugin-console'
   
export function apply(ctx: Context, config: Config) {
  ctx.inject(['console'], (ctx) => {
    ctx.console.addEntry({
      dev: resolve(__dirname, '../client/index.ts'),
      prod: resolve(__dirname, '../dist'),
    })
  })
}

前端注册 (client/index.ts)：

import { Context } from '@koishijs/client'
import Page from './page.vue'
   
export default (ctx: Context) => {
  ctx.page({
    name: '爱发电管理',
    path: '/aifdian',
    icon: 'mdi-currency-usd',
    component: Page,
  })
}

Vue 组件 (client/page.vue)：
- 使用 Koishi UI 组件库（k-layout, k-card, k-button 等）
- 通过 useService('config') 获取插件配置
- Material Design Icons 图标系统

技术栈

Vue 3 + Composition API
TypeScript
Koishi Client SDK
Koishi UI Components
Material Design Icons

🎉 更新日志

v1.2.1 (2026-06-02)

🐛 修复全局验证默认行为问题
- 群配置的 enabled 默认值从 true 改为 false
- 群配置的 verificationMode 默认值从 aifdian 改为 math
- 避免新添加的群配置默认启用爱发电验证
- 确保未配置的群不会受到全局配置影响
✨ 增强日志输出
- 启动时清晰显示每个群的启用状态和验证模式
- 统计启用的群数量和验证模式分布
- 入群申请时详细记录验证决策过程
📝 更新文档说明
- 在 README 中明确说明新的默认配置策略
- 强调需要手动启用群验证
- 添加重要提示说明默认行为变更

v1.2.0 (2026-06-02)

✨ 新增左侧侧边栏独立管理页面
- 统计面板：显示总群数、已启用验证群数、订单绑定数
- 全局配置概览：查看全局验证设置和管理员信息
- 群组配置列表：可视化查看所有群配置，支持快速启用/禁用
- 使用提示区域：提供配置和使用建议
- 响应式设计，适配不同屏幕尺寸
- 使用 Koishi UI 组件库和 Material Design Icons
✨ 新增 同步群 命令，自动添加所有群到配置
✨ 增强数据库检测，显示具体数据库类型
🐛 修复数据库服务检测逻辑
📝 改进配置描述和帮助信息
🔧 添加前端构建支持
- 创建 client 目录和 Vue 页面组件
- 配置 Vite 构建工具
- 自动生成 dist 目录用于生产环境

v1.1.0

✨ 支持单群独立配置
✨ 新增订单管理命令
✨ 增强日志记录
🐛 修复各种 bug

📚 控制台页面使用说明

访问方式

启动 Koishi 应用
打开浏览器访问 Koishi 管理后台
在左侧菜单中找到 "💳 爱发电管理" 菜单项
点击进入管理页面

页面功能

统计面板

总群数：已配置的群组总数
已启用验证群数：当前启用验证的群组数量
订单绑定数：数据库中绑定的订单数量

全局配置

查看全局验证是否启用
查看当前验证模式
查看管理员数量

群组配置列表

查看所有群的详细配置
快速启用/禁用群组验证
查看每个群的验证模式和头衔奖励设置

使用提示

获取配置建议
了解如何使用命令
数据存储位置说明

技术实现

详见 Koishi 官方文档

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

qq-aifdian-group - 爱发电入群验证插件

✨ 特性

🚀 快速开始

1. 安装插件

2. 配置插件

基础配置

⚠️ 重要提示：默认配置策略

群配置（推荐）

3. QQ 群设置

📱 可视化群管理

左侧侧边栏入口

页面功能详解

交互特性

技术实现

技术栈

命令行管理

⚙️ 配置说明

全局配置

群级配置（优先级更高）

🗄️ 数据存储

查看数据

🔧 开发

目录结构

构建

开发模式

仅构建前端

构建产物

前端扩展

实现原理

技术栈

🎉 更新日志

v1.2.1 (2026-06-02)

v1.2.0 (2026-06-02)

v1.1.0

📚 控制台页面使用说明

访问方式

页面功能

统计面板

全局配置

群组配置列表

使用提示

技术实现

🤝 贡献

📄 许可证