koishi-plugin-class-score-system 1.0.0

package/src/index.ts

@@ -0,0 +1,41 @@
+import { Context, Schema } from 'koishi'
+import { extendDatabase } from './models/database'
+import { ServerConfigService } from './services/server'
+import { QqBindingService } from './services/binding'
+import { GroupAdminService } from './services/group-admin'
+import { registerBindServerCommand } from './commands/bind-server'
+import { registerQueryScoreCommand } from './commands/query-score'
+import { registerBindQqCommand } from './commands/bind-qq'
+import { registerAdjustScoreCommand } from './commands/adjust-score'
+import { registerRankingCommand } from './commands/ranking'
+import { registerStatisticsCommand } from './commands/statistics'
+import { registerGroupAdminCommand } from './commands/admin-manager'
+import { registerMenuCommand } from './commands/menu'
+
+export const name = 'class-score-system'
+export const inject = ['database', 'puppeteer']
+
+export interface Config {}
+
+export const Config: Schema<Config> = Schema.object({})
+
+export function apply(ctx: Context) {
+  ctx.logger.info('班级操行分管理系统插件正在加载...')
+
+  extendDatabase(ctx)
+
+  const serverService = new ServerConfigService(ctx)
+  const bindingService = new QqBindingService(ctx)
+  const adminService = new GroupAdminService(ctx)
+
+  registerGroupAdminCommand(ctx, adminService)
+  registerBindServerCommand(ctx, serverService, adminService)
+  registerQueryScoreCommand(ctx, serverService, bindingService)
+  registerBindQqCommand(ctx, serverService, bindingService)
+  registerAdjustScoreCommand(ctx, serverService, adminService)
+  registerRankingCommand(ctx, serverService)
+  registerStatisticsCommand(ctx, serverService, bindingService)
+  registerMenuCommand(ctx)
+
+  ctx.logger.info('班级操行分管理系统插件加载完成')
+}

package/src/locales/zh-CN.yml

@@ -0,0 +1,58 @@
+commands:
+  bind-server:
+    name: 绑定服务器
+    description: 绑定CSMS服务器
+    usage: '/绑定服务器 <服务器地址> <管理员用户名> <管理员Token>'
+  query-score:
+    name: 查询积分
+    description: 查询积分和排名
+    usage: '/查询积分 [用户名]'
+  adjust-score:
+    name: 调整积分
+    description: 调整积分（仅管理员）
+    usage: '/调整积分 <用户名> <分数> <原因>'
+  bind-qq:
+    name: 绑定QQ
+    description: 绑定QQ号与系统账号
+    usage: '/绑定QQ <用户名>'
+  ranking:
+    name: 排行榜
+    description: 显示积分排行榜
+    usage: '/排行榜 [数量]'
+  statistics:
+    name: 统计
+    description: 显示积分统计信息
+    usage: '/统计 [用户名]'
+
+messages:
+  success:
+    server-configured: 服务器配置成功
+    server-validated: 服务器配置验证成功
+    qq-bound: QQ绑定成功
+    qq-unbound: QQ解除绑定成功
+    score-adjusted: 积分调整成功
+    user-created: 用户创建成功
+  error:
+    no-server-config: 未配置CSMS服务器，请先使用 /绑定服务器 命令配置
+    invalid-token: 无效的Token格式，Token必须由数字和英文大写字母组成
+    invalid-qq: 无效的QQ号码格式
+    invalid-score: 分数必须在 -1000 到 1000 之间
+    invalid-username: 用户名不能为空且长度不能超过50个字符
+    invalid-description: 描述信息长度不能超过255个字符
+    invalid-limit: 数量必须在 1 到 50 之间
+    server-not-found: 服务器未找到
+    user-not-found: 用户未找到
+    user-already-bound: 该QQ号已绑定其他用户
+    user-not-bound: 该QQ号未绑定任何用户
+    api-request-failed: API请求失败
+    insufficient-permission: 权限不足，仅管理员可执行此操作
+    binding-failed: 绑定失败
+    unbinding-failed: 解除绑定失败
+    configuration-failed: 配置保存失败
+  help:
+    bind-server: 绑定CSMS服务器\n用法：/绑定服务器 <服务器地址> <管理员用户名> <管理员Token>\n示例：/绑定服务器 https://example.com admin ABC123
+    query-score: 查询积分\n用法：/查询积分 [用户名]\n示例：/查询积分 张三
+    adjust-score: 调整积分\n用法：/调整积分 <用户名> <分数> <原因>\n示例：/调整积分 张三 +5 表现优秀
+    bind-qq: 绑定QQ\n用法：/绑定QQ <用户名>\n示例：/绑定QQ 张三
+    ranking: 排行榜\n用法：/排行榜 [数量]\n示例：/排行榜 10
+    statistics: 统计\n用法：/统计 [用户名>\n示例：/统计 张三

package/src/models/database.ts

@@ -0,0 +1,84 @@
+import { Context, Schema, Tables } from 'koishi'
+
+export interface ServerConfig {
+  id: number
+  guildId: string
+  name: string
+  address: string
+  username: string
+  token: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface QqBinding {
+  id: number
+  guildId: string
+  userId: number
+  username: string
+  openId: string   // Koishi session.userId（QQ OpenID，非传统QQ号）
+  serverId: number
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface GroupAdmin {
+  id: number
+  guildId: string
+  openId: string     // OpenID（用户确认时获取）
+  remark: string     // 备注（用于减管）
+  verify: number     // 验证状态：0=待确认, 1=已确认
+  createdAt: Date
+}
+
+declare module 'koishi' {
+  interface Tables {
+    server_configs: ServerConfig
+    qq_bindings: QqBinding
+    group_admins: GroupAdmin
+  }
+}
+
+export function extendDatabase(ctx: Context) {
+  ctx.model.extend('server_configs', {
+    id: 'integer',
+    guildId: 'string',
+    name: 'string',
+    address: 'string',
+    username: 'string',
+    token: 'string',
+    createdAt: 'timestamp',
+    updatedAt: 'timestamp',
+  }, {
+    primary: 'id',
+    autoInc: true,
+  })
+
+  ctx.model.extend('qq_bindings', {
+    id: 'integer',
+    guildId: 'string',
+    userId: 'integer',
+    username: 'string',
+    openId: 'string',
+    serverId: 'integer',
+    createdAt: 'timestamp',
+    updatedAt: 'timestamp',
+  }, {
+    primary: 'id',
+    autoInc: true,
+    unique: ['openId', 'guildId'],
+  })
+
+  ctx.model.extend('group_admins', {
+    id: 'integer',
+    guildId: 'string',
+    openId: 'string',
+    remark: 'string',
+    verify: 'integer',
+    createdAt: 'timestamp',
+  }, {
+    primary: 'id',
+    autoInc: true,
+    unique: ['openId', 'guildId'],
+  })
+}

package/src/services/api.ts

@@ -0,0 +1,335 @@
+import { Context } from 'koishi'
+
+export interface CsmsUser {
+  id: number
+  username: string
+  qq_number: string | null
+  total_score: number
+  add_score: number
+  deduct_score: number
+  score_count: number
+  group_index?: number
+  row_index?: number
+  col_index?: number
+  created_at: string
+}
+
+export interface CsmsScoreLog {
+  id: number
+  user_id: number
+  score_change: number
+  description: string
+  created_at: string
+}
+
+export interface AddScoreUser {
+  username: string
+  score_change: number
+}
+
+export interface AddScoreBatchData {
+  users: AddScoreUser[]
+  description: string
+}
+
+export interface AddScoreResult {
+  success: boolean
+  message: string
+  summary: {
+    success_count: number
+    failed_count: number
+    total_count: number
+  }
+  details: Array<{
+    username: string
+    user_id?: number
+    score_change: number
+    success: boolean
+    error?: string
+  }>
+}
+
+export interface ApiResponse<T = any> {
+  data?: T
+  error?: string
+  success?: boolean
+  message?: string
+  total?: number
+  limit?: number
+  offset?: number
+}
+
+export class CsmsApiService {
+  private baseUrl: string
+  private token: string
+  private ctx: Context
+
+  constructor(ctx: Context, baseUrl: string, token: string) {
+    this.ctx = ctx
+    this.baseUrl = baseUrl.replace(/\/api\/global_api\.php$/, '').replace(/\/$/, '')
+    this.token = token
+  }
+
+  /**
+   * 发送 API 请求
+   * 按照 global_api.md 文档规范实现
+   */
+  private async request<T>(params: Record<string, string | number | undefined>): Promise<ApiResponse<T>> {
+    try {
+      const url = `${this.baseUrl}/api/global_api.php`
+      // 过滤掉 undefined 值
+      const cleanParams: Record<string, string> = {}
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+          cleanParams[key] = String(value)
+        }
+      }
+      
+      this.ctx.logger.debug(`API请求: ${url}`, cleanParams)
+      
+      const response = await this.ctx.http.get<ApiResponse<T>>(url, { 
+        params: cleanParams,
+        headers: {
+          'Authorization': this.token,
+        }
+      })
+      
+      this.ctx.logger.debug(`API响应:`, response)
+      return response
+    } catch (error: any) {
+      this.ctx.logger.error('CSMS API 请求失败:', error)
+      return { error: error.message || 'API请求失败' }
+    }
+  }
+
+  /**
+   * 验证 Token - 使用自定义的 add_score 接口测试
+   * 注意: 文档未提供专门的 validate_token 接口，用此方法间接验证
+   */
+  async validateToken(): Promise<{ valid: boolean; username?: string }> {
+    try {
+      // 尝试调用 add_score 接口（需要有效token），传入无效数据来检测token是否有效
+      const url = `${this.baseUrl}/api/global_api.php`
+      const params = {
+        action: 'add_score',
+        data: JSON.stringify({
+          username: '__validate__',
+          score_change: 0,
+          description: '__token_validation__'
+        }),
+        token: this.token,
+      }
+      
+      this.ctx.logger.info(`验证Token中...`)
+      const response = await this.ctx.http.get<ApiResponse>(url, { params })
+      
+      // 如果返回 error: "用户不存在" 或类似，说明 token 有效
+      // 如果返回 error: "未授权" 或 "Token无效"，说明 token 无效
+      if (response.error) {
+        const errorLower = response.error.toLowerCase()
+        if (errorLower.includes('未授权') || errorLower.includes('token') || errorLower.includes('无效')) {
+          this.ctx.logger.warn(`Token验证失败: ${response.error}`)
+          return { valid: false }
+        }
+        // 其他错误（如用户不存在）说明token有效
+        this.ctx.logger.info(`Token验证成功`)
+        return { valid: true }
+      }
+      
+      return { valid: true }
+    } catch (error: any) {
+      this.ctx.logger.error(`Token验证异常:`, error)
+      return { valid: false }
+    }
+  }
+
+  /**
+   * 查询用户列表
+   * GET /api/global_api.php?users&order_by=xxx&order=DESC&limit=20&offset=0
+   */
+  async getUsers(options?: {
+    where?: Record<string, any>
+    order_by?: string
+    order?: 'ASC' | 'DESC'
+    limit?: number
+    offset?: number
+    search?: string
+  }): Promise<ApiResponse<CsmsUser[]>> {
+    const params: Record<string, string> = { users: '' }
+    
+    if (options?.where) {
+      params.where = JSON.stringify(options.where)
+    }
+    if (options?.order_by) {
+      params.order_by = options.order_by
+    }
+    if (options?.order) {
+      params.order = options.order
+    }
+    if (options?.limit !== undefined) {
+      params.limit = options.limit.toString()
+    }
+    if (options?.offset !== undefined) {
+      params.offset = options.offset.toString()
+    }
+    if (options?.search) {
+      params.search = options.search
+    }
+    
+    return this.request<CsmsUser[]>(params)
+  }
+
+  /**
+   * 查询单个用户
+   * GET /api/global_api.php?users&id=xxx
+   */
+  async getUserById(id: number): Promise<ApiResponse<CsmsUser[]>> {
+    return this.request<CsmsUser[]>({ users: '', id: id.toString() })
+  }
+
+  /**
+   * 按用户名查询用户
+   * GET /api/global_api.php?users&where={"username":"xxx"}
+   */
+  async getUserByUsername(username: string): Promise<ApiResponse<CsmsUser[]>> {
+    return this.request<CsmsUser[]>({ 
+      users: '', 
+      where: JSON.stringify({ username }) 
+    })
+  }
+
+  /**
+   * 按QQ号查询用户
+   * GET /api/global_api.php?users&where={"qq_number":"xxx"}
+   */
+  async getUserByQq(qqNumber: string): Promise<ApiResponse<CsmsUser[]>> {
+    return this.request<CsmsUser[]>({ 
+      users: '', 
+      where: JSON.stringify({ qq_number: qqNumber }) 
+    })
+  }
+
+  /**
+   * 获取排行榜（按 total_score 降序）
+   * GET /api/global_api.php?users&order_by=total_score&order=DESC&limit=20
+   */
+  async getRanking(limit: number = 20, offset: number = 0): Promise<ApiResponse<CsmsUser[]>> {
+    return this.request<CsmsUser[]>({
+      users: '',
+      order_by: 'total_score',
+      order: 'DESC',
+      limit: limit.toString(),
+      offset: offset.toString(),
+    })
+  }
+
+  /**
+   * 查询积分记录
+   * GET /api/global_api.php?score_logs&where={"user_id":xxx}&order_by=created_at&order=DESC&limit=50
+   */
+  async getScoreLogs(userId: number, limit: number = 50): Promise<ApiResponse<CsmsScoreLog[]>> {
+    return this.request<CsmsScoreLog[]>({
+      score_logs: '',
+      where: JSON.stringify({ user_id: userId }),
+      order_by: 'created_at',
+      order: 'DESC',
+      limit: limit.toString(),
+    })
+  }
+
+  /**
+   * 创建新用户
+   * GET /api/global_api.php?users&action=create&data={"username":"xxx"}&token=xxx
+   */
+  async createUser(username: string): Promise<ApiResponse<CsmsUser>> {
+    return this.request<CsmsUser>({
+      users: '',
+      action: 'create',
+      data: JSON.stringify({ username }),
+    })
+  }
+
+  /**
+   * 更新用户信息（如绑定QQ号）
+   * GET /api/global_api.php?users&action=update&id=xxx&data={"qq_number":"xxx"}&token=xxx
+   */
+  async updateUser(userId: number, data: Record<string, any>): Promise<ApiResponse<CsmsUser>> {
+    return this.request<CsmsUser>({
+      users: '',
+      action: 'update',
+      id: userId.toString(),
+      data: JSON.stringify(data),
+    })
+  }
+
+  /**
+   * 绑定用户QQ号
+   */
+  async bindQq(userId: number, qqNumber: string): Promise<ApiResponse<CsmsUser>> {
+    return this.updateUser(userId, { qq_number: qqNumber })
+  }
+
+  /**
+   * 批量加减分
+   * GET /api/global_api.php?action=add_score&data={"users":[...],"description":"xxx"}&token=xxx
+   */
+  async batchAddScore(data: AddScoreBatchData): Promise<AddScoreResult> {
+    this.ctx.logger.info(`batchAddScore 请求数据:`, JSON.stringify(data))
+    
+    const response = await this.request<AddScoreResult>({
+      action: 'add_score',
+      data: JSON.stringify(data),
+    })
+    
+    this.ctx.logger.info(`batchAddScore API 响应:`, JSON.stringify(response))
+    
+    // 检查错误
+    if (response.error) {
+      return {
+        success: false,
+        message: response.error,
+        summary: { success_count: 0, failed_count: 0, total_count: 0 },
+        details: [],
+      }
+    }
+    
+    // CSMS API 直接返回 AddScoreResult 对象，不在 data 字段中
+    // 检查 response 是否就是 AddScoreResult
+    if (response.data && typeof response.data === 'object' && 'summary' in response.data) {
+      return response.data as AddScoreResult
+    }
+    
+    // 兼容：检查 response 本身是否就是 AddScoreResult 格式
+    if (response && typeof response === 'object' && 'summary' in response) {
+      return response as AddScoreResult
+    }
+    
+    // 检查 response.data 是否为数组形式（兼容某些情况）
+    if (Array.isArray(response.data)) {
+      return {
+        success: true,
+        message: '操作完成',
+        summary: { success_count: response.data.length, failed_count: 0, total_count: response.data.length },
+        details: response.data,
+      }
+    }
+    
+    this.ctx.logger.error(`batchAddScore 返回数据格式异常，原始响应:`, response)
+    return {
+      success: false,
+      message: 'API 返回数据格式异常',
+      summary: { success_count: 0, failed_count: 0, total_count: 0 },
+      details: [],
+    }
+  }
+
+  /**
+   * 单用户加减分
+   */
+  async addScore(username: string, scoreChange: number, description: string): Promise<AddScoreResult> {
+    return this.batchAddScore({
+      users: [{ username, score_change: scoreChange }],
+      description,
+    })
+  }
+}

package/src/services/binding.ts

@@ -0,0 +1,72 @@
+import { Context } from 'koishi'
+import { QqBinding } from '../models/database'
+
+export class QqBindingService {
+  private ctx: Context
+
+  constructor(ctx: Context) {
+    this.ctx = ctx
+  }
+
+  /**
+   * openId 即 session.userId（QQ OpenID，非传统QQ号）
+   */
+  async bindQq(guildId: string, userId: number, username: string, openId: string, serverId: number): Promise<QqBinding> {
+    const now = new Date()
+    
+    const bindings = await this.ctx.database.get('qq_bindings', { openId, guildId })
+    if (bindings.length > 0) {
+      await this.ctx.database.set('qq_bindings', { openId, guildId }, {
+        userId,
+        username,
+        serverId,
+        updatedAt: now,
+      })
+      return { ...bindings[0], userId, username, serverId, updatedAt: now }
+    }
+    
+    const binding = await this.ctx.database.create('qq_bindings', {
+      guildId,
+      userId,
+      username,
+      openId,
+      serverId,
+      createdAt: now,
+      updatedAt: now,
+    })
+    
+    return binding
+  }
+
+  async unbindQq(guildId: string, openId: string): Promise<boolean> {
+    await this.ctx.database.remove('qq_bindings', { openId, guildId })
+    return true
+  }
+
+  async unbindByUserId(guildId: string, userId: number): Promise<boolean> {
+    await this.ctx.database.remove('qq_bindings', { userId, guildId })
+    return true
+  }
+
+  async getUserByOpenId(guildId: string, openId: string): Promise<QqBinding | null> {
+    const bindings = await this.ctx.database.get('qq_bindings', { openId, guildId })
+    return bindings[0] || null
+  }
+
+  async getQqByUserId(guildId: string, userId: number): Promise<QqBinding | null> {
+    const bindings = await this.ctx.database.get('qq_bindings', { userId, guildId })
+    return bindings[0] || null
+  }
+
+  async getAllBindings(guildId: string): Promise<QqBinding[]> {
+    return this.ctx.database.get('qq_bindings', { guildId })
+  }
+
+  async getBindingsByServer(guildId: string, serverId: number): Promise<QqBinding[]> {
+    return this.ctx.database.get('qq_bindings', { serverId, guildId })
+  }
+
+  async getBindingsByUsername(guildId: string, username: string): Promise<QqBinding[]> {
+    return this.ctx.database.get('qq_bindings', { username, guildId })
+  }
+}

package/src/services/group-admin.ts

@@ -0,0 +1,89 @@
+import { Context } from 'koishi'
+import { GroupAdmin } from '../models/database'
+
+export class GroupAdminService {
+  private ctx: Context
+
+  constructor(ctx: Context) {
+    this.ctx = ctx
+  }
+
+  /**
+   * 添加已验证的管理员（verify = 1，用于绑定服务器时自动升级）
+   */
+  async addAdmin(guildId: string, openId: string, remark: string): Promise<GroupAdmin> {
+    const existing = await this.ctx.database.get('group_admins', { guildId, openId })
+    if (existing.length > 0) {
+      // 已存在则更新为已验证
+      await this.ctx.database.set('group_admins', { guildId, openId }, { remark, verify: 1 })
+      return { ...existing[0], remark, verify: 1 }
+    }
+
+    return this.ctx.database.create('group_admins', {
+      guildId,
+      openId,
+      remark,
+      verify: 1,
+      createdAt: new Date(),
+    })
+  }
+
+  /**
+   * 创建待确认的群管记录（Verify = 0）
+   */
+  async createPendingAdmin(guildId: string, openId: string, remark: string): Promise<GroupAdmin> {
+    // 检查是否已存在（按 openId 查）
+    const existing = await this.ctx.database.get('group_admins', { guildId, openId })
+    if (existing.length > 0) {
+      return existing[0]
+    }
+
+    return this.ctx.database.create('group_admins', {
+      guildId,
+      openId,
+      remark,
+      verify: 0,
+      createdAt: new Date(),
+    })
+  }
+
+  /**
+   * 确认群管（将 Verify 改为 1）
+   */
+  async confirmAdmin(guildId: string, openId: string): Promise<boolean> {
+    await this.ctx.database.set('group_admins', { guildId, openId }, { verify: 1 })
+    return true
+  }
+
+  /**
+   * 移除群管（按备注 查找并删除）
+   */
+  async removeAdminByRemark(guildId: string, remark: string): Promise<boolean> {
+    await this.ctx.database.remove('group_admins', { guildId, remark })
+    return true
+  }
+
+  /**
+   * 检查是否为已确认的群管（OpenID + Verify = 1）
+   */
+  async isAdmin(guildId: string, openId: string): Promise<boolean> {
+    const admins = await this.ctx.database.get('group_admins', { guildId, openId })
+    return admins.length > 0 && admins[0].verify === 1
+  }
+
+  /**
+   * 获取所有群管
+   */
+  async getAllAdmins(guildId: string): Promise<GroupAdmin[]> {
+    return this.ctx.database.get('group_admins', { guildId })
+  }
+
+  /**
+   * 检查用户是否有管理权限（按 OpenID + Verify = 1）
+   */
+  async hasAdminPermission(session: any): Promise<boolean> {
+    const openId = session.userId?.toString()
+    if (!openId || !session.guildId) return false
+    return await this.isAdmin(session.guildId, openId)
+  }
+}