Koishi Plugin PointMint

模块化架构 | 高度可定制｜可审计事务追踪｜实时积分生态 - 基于双效校验机制的经济引擎

功能特性

核心能力

• 双效校验机制：通过实现事务ID生成与验证，确保每笔积分操作的可追溯性
• 实时积分系统：提供类实现完整的积分生命周期管理（增/删/查/改）
• 审计追踪体系：通过记录全量操作日志，支持自定义日志保留策略

功能亮点

• 用户积分排行榜（TopN 查询）
• 自动用户名同步机制
• 弹性积分初始化策略
• 操作结果多状态码返回
• 插件间调用追踪标识

流程图

sequenceDiagram
    participant C as other plugin
    participant S as Service
    participant order as Order Manager
    participant trans as Transaction Engine
    participant DB as Database
    
    C->>S: 发起支付请求
    S-->>order: 创建订单(状态:PENDING)
    order-->>S: 返回订单信息
    S->>C: 返回订单信息
    
    par 超时监控
        order->>order: 超时检查
        alt 超时且未完成
            order->>order: 标记订单为FAILED
        end
    and 业务处理
        S-->>trans: 发起操作请求
        trans-->>order: 验证订单有效性
        alt 订单状态为PENDING
            order-->>trans: 订单有效
            trans->>trans: 获取分布式锁(订单ID)
            trans->>DB: 写入账户变更
            DB-->>trans: 写入成功
            trans-->>order: 尝试标记订单为SUCCESS
            alt 标记成功
                order-->>trans: 确认成功
            else 标记失败(已超时)
                order-->>trans: 订单已FAILED
                trans->>DB: 回滚账户变更
                DB-->>trans: 回滚成功
            end
            trans->>trans: 释放分布式锁
        else 订单状态不为PENDING
            order-->>trans: 订单无效
            trans-->>S: 返回失败
        end
    end

Loading

开发者快速接入指南

Note

正在撰写……

接口文档

基础数据结构

基础数据结构提供了必要的接口定义，用于实现插件间的交互。

Warning

• 插件目前还在开发版本，下面的接口在接下来的版本中可能会有变动

• 为了方便称呼，以下文档中有关于虚拟货币的称呼统一为“积分”，您可以设置您的货币为其他任意名称

• 如果你在使用过程中遇到了问题，欢迎提交Issue

export interface ApiResponseNoData {
    code: number // 状态码
    msg: string // 状态信息
}

状态码表

状态码	状态信息	说明
200	成功	操作成功
204	成功	操作成功，但是操作没有实质性改变数据
400	错误	操作失败，参数有误
403	错误	操作失败，用户没有足够的积分用于操作
500	错误	操作失败，服务器内部错误，可能是配置项错误或bug

1. 积分查询

1. 设置积分

async set(
  userid: string, // 用户唯一标识符
  transactionId: string, // 事务id，见第二节
  points: number, // 积分值，必须 >= 0
  pluginName?: string // 插件名，用于追踪调用关系
): Promise<ApiResponseNoData>

2. 增加积分

async add(
  userid: string,
  transactionId: string,
  points: number,
  pluginName?: string
): Promise<ApiResponseNoData>

3. 扣除积分

async reduce(
  userid: string,
  transactionId: string,
  points: number,        // 必须 > 0
  pluginName?: string
): Promise<ApiResponseNoData>

5. 获取积分排行

async getTopN(
  num: number  // 需要查询的排行榜名额数量，必须为正整数
): Promise<Array<{
  userid: string   // 用户唯一标识符
  username: string // 用户当前名称
  points: number   // 用户当前积分
}>>
// 返回示例
[
    { userid: '123456', username: 'Alice', points: 100},
    { userid: '654321', username: 'Bob', points: 90}
]

2. 获取事务id

事务id是用于操作积分的必要数值，对积分进行操作的方法都需要传入事务id。 你可以通过以下方法获取事务id：

async generateTransactionId(): Promise<string>

3. 其他方法

1. 更新用户名

async updateUserName(
  userid: string,
  username: string,
  pluginName?: string
): Promise<ApiResponseNoData>

2. 回写操作 回写操作是将某项操作回写。例如，你通过reduce方法后，所要提供的服务未能正常提供，可以通过该方法回退

async rollback(
  userid: string,
  transactionId: string,
  pluginName?: string
): Promise<ApiResponseNoData>