Koishi 库存管理插件

一个用于机厅水和饮料库存统计的 Koishi 机器人插件。

功能特性

1. 别名功能

• 支持为每个物品设置多个别名（如：water、水、纯净水）
• 可以在配置中自定义多个物品和饮料
• 通过消息监听自动识别，无需注册指令

2. 算法功能

支持以下格式的操作（无需空格）：

• water+1 - 增加1瓶
• water-1 - 减少1瓶
• water=10 - 设置库存为10瓶（会自动计算差值）
• water-1-r - 减少1瓶但不计入排行榜（使用 -r 参数）

3. 排名和累计功能

• 累计功能：统计每个物品的总添加量和总消耗量
• 自动排行榜：每次操作后自动显示对应的排行榜更新
• 排行榜查询指令：使用 rank <物品别名> 查询排行榜
  • rank water - 查询消耗排行榜（默认）
  • rank water -t add - 查询累计排行榜
  • rank water -t consume - 查询消耗排行榜
• 使用 -r 参数可以只修改库存，不计入排行榜统计

4. 白名单功能

• 可以配置白名单群组ID列表
• 只有白名单中的群才能使用插件功能
• 如果白名单为空，则所有群都可以使用

5. 查询功能

支持多种查询格式（可在配置中自定义）：

• water有多少 - 查询库存
• water几 - 查询库存
• waterj - 查询库存

查询结果会显示：

• 当前库存数量
• 累计添加数量
• 累计消耗数量
• 最近5条操作记录（用户昵称和数量）

配置说明

在 Koishi 配置文件中添加：

plugins:
  stock-manager:
    whitelistGroups: []  # 白名单群组ID列表，为空则所有群可用
    getCodeTag: wmc_ref  # 每次修改库存后追加的校验码标识（不含冒号），例如 GETCODE / wmc_ref
    items:
      - name: 纯净水
        aliases: [water, 水, 纯净水]
      - name: 可乐
        aliases: [cola, 可乐, coke]
    queryMessages:  # 查询消息模板
      - '{name}有多少'
      - '{name}几'
      - '{name}j'
    defaultQueryMessage: '{name}当前库存：{count}瓶\n累计添加：{totalAdded}瓶\n累计消耗：{totalConsumed}瓶\n最近操作：{recentRecords}'

占位符说明

• {name} - 物品名称
• {count} - 当前库存
• {totalAdded} - 累计添加
• {totalConsumed} - 累计消耗
• {recentRecords} - 最近操作记录

使用示例

基本操作

用户: water+5
机器人: 纯净水 +5，当前库存：5瓶

wmc_ref: 1700000000000_123456_纯净水_a1b2c3

纯净水累计排行榜：
1. 张三: 5瓶

用户: water-2
机器人: 纯净水 -2，当前库存：3瓶

wmc_ref: 1700000005000_123456_纯净水_d4e5f6

纯净水消耗排行榜：
1. 李四: 2瓶

用户: water=10
机器人: 纯净水 +7，当前库存：10瓶

wmc_ref: 1700000010000_123456_纯净水_0f1e2d

纯净水累计排行榜：
1. 张三: 5瓶
2. 王五: 7瓶

查询操作

用户: water有多少
机器人: 纯净水当前库存：10瓶
累计添加：12瓶
累计消耗：2瓶
最近操作：
张三 +5
李四 -2
王五 +7

排行榜查询

用户: rank water
机器人: 纯净水消耗排行榜：
1. 李四: 5瓶
2. 王五: 3瓶

用户: rank water -t add
机器人: 纯净水累计排行榜：
1. 张三: 10瓶
2. 王五: 7瓶

用户: rank water -t consume
机器人: 纯净水消耗排行榜：
1. 李四: 5瓶
2. 王五: 3瓶

不计入排行榜的操作

用户: water-1-r
机器人: 纯净水 -1，当前库存：9瓶（不计入排行榜）

wmc_ref: 1700000020000_123456_纯净水_9a8b7c

用户: water+5-r
机器人: 纯净水 +5，当前库存：14瓶（不计入排行榜）
（使用 -r 参数只修改库存，不会计入排行榜统计，也不会显示排行榜）

指令说明

排行榜查询指令

• rank <物品别名> - 查询消耗排行榜（默认）
• rank <物品别名> -t add - 查询累计排行榜
• rank <物品别名> -t consume - 查询消耗排行榜

管理指令（隐藏）

插件提供了一些隐藏的管理指令（不会出现在 help 中）：

• stock.set <物品别名> <数量> - 设置库存数量
• stock.list - 查看所有物品及其库存

注意事项

1. 插件通过消息监听工作，操作和查询不需要注册指令
2. 每次操作（+、-、=）后会自动显示对应的排行榜更新
3. 使用 -r 参数的操作只修改库存，不计入排行榜，也不会显示排行榜
4. 所有管理指令默认隐藏，不会出现在 help 中
5. 数据持久化：所有库存数据和操作记录都存储在数据库中，重启后数据不会丢失
6. 只保留最近100条操作记录（自动清理旧记录）
7. 排行榜显示前10名

数据库说明

插件使用 Koishi 的数据库功能来持久化数据，需要安装并配置数据库插件（如 @koishijs/plugin-database-sqlite、@koishijs/plugin-database-mysql 等）。

插件会创建两个数据表：

• stock_item: 存储每个物品的库存数据（库存数量、累计添加、累计消耗）
• stock_record: 存储操作记录（用于排行榜和最近操作显示）

所有数据变更会自动保存到数据库，重启后会自动从数据库加载数据。