Metadata-Version: 2.4
Name: nonebot-plugin-maimai-raking
Version: 0.1.0
Summary: 一个基于 NoneBot2 的舞萌 DX 分群排行榜插件
Project-URL: Homepage, https://github.com/yukko233/nonebot_plugin_maimai_raking
Project-URL: Repository, https://github.com/yukko233/nonebot_plugin_maimai_raking
Project-URL: Issues, https://github.com/yukko233/nonebot_plugin_maimai_raking/issues
Author: yukko
License: GPL-3.0
License-File: LICENSE
Keywords: maimai,maimaidx,nonebot,nonebot-plugin,nonebot2,舞萌
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.23.0
Requires-Dist: nonebot-adapter-onebot>=2.0.0
Requires-Dist: nonebot-plugin-apscheduler>=0.3.0
Requires-Dist: nonebot-plugin-localstore>=0.1.0
Requires-Dist: nonebot2>=2.0.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=1.10.0
Description-Content-Type: text/markdown

# nonebot-plugin-maimai-raking

一个基于 NoneBot2 的舞萌 DX 分群排行榜插件

## ✨ 功能特性

### 🎮 核心功能
- **分群管理**：每个群组独立管理排行榜数据，互不干扰
- **权限控制**：超级管理员、群管理员、群主可以开关功能和管理成员
- **排行榜系统**：用户可自愿加入/退出群内排行榜，支持管理员为他人操作
- **智能昵称**：优先显示群名片，自动更新，提升用户识别度

### 🔄 自动更新
- 每天凌晨 **0:00** 自动更新歌曲数据
- 每天凌晨 **0:05** 自动更新歌曲别名库
- 每天凌晨 **0:10** 自动更新所有启用群的用户昵称
- 每天凌晨 **0:15** 自动更新所有用户的成绩数据
- 用户加入排行榜时自动刷新该群所有成员的昵称
- 管理员可手动使用 `刷新昵称` 命令更新群昵称
- 超管可使用 `更新歌曲数据` 命令手动更新水鱼歌曲数据

### 🎵 歌曲查询
- 支持歌曲名、别名、ID 多种方式查询
- 支持模糊匹配和智能搜索
- 可指定难度查询（绿/黄/红/紫/白）
- 默认显示最高难度的排行榜


## 📦 安装

使用 pip 安装：

```bash
pip install nonebot-plugin-maimai-raking
```

或使用 nb-cli：

```bash
nb plugin install nonebot-plugin-maimai-raking
```

## ⚙️ 配置

在 `.env` 文件中添加以下配置：

```env
# 水鱼查分器 Developer Token（必填）
MAIMAI_DEVELOPER_TOKEN=your_developer_token_here

# 数据存储路径（可选，默认使用 nonebot-plugin-localstore 管理的插件数据目录）
MAIMAI_DATA_PATH=data/maimai_raking

# 缓存存储路径（可选，默认使用 nonebot-plugin-localstore 管理的插件缓存目录）
MAIMAI_CACHE_PATH=data/maimai_cache
```

### 获取 Developer Token

1. 访问 [水鱼查分器](https://www.diving-fish.com/maimaidx/prober/)
2. 登录你的账号
3. 进入"编辑个人资料"页面
4. 在"需要查分器中的玩家数据用于其他应用程序开发？请点击这里~"中申请 Developer Token

## 📖 使用方法

### 超管命令

以下命令需要**超级管理员**权限：

| 命令 | 说明 |
|------|------|
| `刷新排行榜` | 手动刷新当前群所有成员的成绩数据 |
| `重置刷新次数 <QQ号/@用户>` | 重置指定用户的今日刷新次数 |
| `更新歌曲数据` | 手动更新水鱼歌曲数据（歌曲名称、ID、难度等信息）|
| `清理数据库` | 清理Bot已退出群组的数据 |
| `加入排行榜 <QQ号/@用户> [群号]` | 跨群加入排行榜 |
| `退出排行榜 <QQ号/@用户> [群号]` | 跨群退出排行榜 |

### 管理员命令

以下命令需要**群主、管理员或超管**权限：

| 命令 | 说明 |
|------|------|
| `开启舞萌排行榜` | 在当前群开启排行榜功能 |
| `关闭舞萌排行榜` | 在当前群关闭排行榜功能 |
| `刷新群昵称` | 手动刷新当前群所有成员的群昵称 |
| `刷新昵称` | 手动刷新当前群所有成员的群昵称（简化命令）|
| `开启/关闭wmrt` | 开启/关闭本群的 Rating 排行榜功能 |
| `wmbm+/wmbm- <歌曲名/别名/ID> <新别名>` | 为歌曲添加/删除别名 |
| `加入排行榜 [QQ号/@用户]` | 为他人加入排行榜|
| `退出排行榜 [QQ号/@用户]` | 为他人退出排行榜|

### 用户命令

| 命令 | 说明 |
|------|------|
| `加入排行榜` | 加入排行榜|
| `退出排行榜` | 退出排行榜|
| `刷新成绩` | 刷新自己的成绩数据（每日限2次）|
| `wmrk <歌曲名/别名/ID>` | 查询该歌曲在本群的排行榜（默认最高难度）|
| `wmrk <歌曲名/别名/ID> <难度>` | 查询指定难度的排行榜 |
| `wmbm <歌曲名/别名/ID>` | 查询歌曲的别名信息 |
| `wmrt` | 查看本群全部 Rating 排行榜（前 10 名）|
| `wmrt<分段>` | 查看指定分段的 Rating 排行榜（前 10 名）|

#### 难度参数

- `绿` - Basic
- `黄` - Advanced
- `红` - Expert
- `紫` - Master
- `白` - Re:Master

#### Rating 分段参数

- `wmrt` - 查询全部玩家
- `wmrt0` - 查询 10000-10999 分段
- `wmrt1` - 查询 11000-11999 分段
- `wmrt2` - 查询 12000-12999 分段
- `wmrt3` - 查询 13000-13999 分段
- `wmrt4` - 查询 14000-14999 分段
- `wmrt5` - 查询 15000-15999 分段
- `wmrt6` - 查询 16000-16999 分段
- `wmrt7` - 查询 17000-17999 分段

### 使用示例

#### 用户操作

```
# 加入排行榜
用户: 加入排行榜
Bot: ✅ 已成功加入排行榜！
     昵称: 玩家A
     Rating: 14500

# 查询歌曲排行榜（默认最高难度）
用户: wmrk きたさいたま2000
Bot: [返回きたさいたま2000最高难度(紫)的排行榜图片]

# 查询指定难度
用户: wmrk 北埼玉 红
Bot: [返回きたさいたま2000 Expert 难度的排行榜图片]

# 使用别名查询
用户: wmrk 北埼玉
Bot: [返回きたさいたま2000的排行榜图片]

# 使用 ID 查询
用户: wmrk 388
Bot: [返回对应歌曲的排行榜图片]

# 查询歌曲详细信息
用户: wmbm 北埼玉
Bot: 🎵 歌曲信息
     📝 名称: きたさいたま2000
     🆔 ID: 388
     📊 类型: 标准谱面
     🏷️ 别名 (16个):
      2000
      kita
      きたさいたま2000
      下北泽2000
      五兄弟
      光污染小人
      全网最帅五兄弟
      北埼玉
      北埼玉2000
      北琦玉
      北琦玉2000
      埼玉2000
      太鼓2000
      琦玉2000
      过北脱新
      😁😁😁😁😁

# 刷新自己的成绩
用户: 刷新成绩
Bot: 正在刷新你的成绩数据，请稍候...
Bot: ✅ 成绩刷新完成！
     昵称: 玩家A
     Rating: 15000
     今日剩余刷新次数: 1/2

# 使用@用户加入排行榜
用户: 加入排行榜 @玩家B
Bot: ✅ 已成功为用户 123456789 加入排行榜！
     昵称: 玩家B
     Rating: 13800

# 加入指定群的排行榜（仅超管可执行）
超管: 加入排行榜 123456789 987654321
Bot: ✅ 已成功为用户 123456789 加入群 987654321 的排行榜！
     昵称: 玩家B
     Rating: 13800

超管: 加入排行榜 @玩家A 987654321
Bot: ✅ 已成功为用户 123456789 加入群 987654321 的排行榜！
     昵称: 玩家A
     Rating: 15000

# 使用@用户退出排行榜
用户: 退出排行榜 @玩家C
Bot: ✅ 已成功为用户 987654321 退出排行榜！

# 退出指定群的排行榜
超管: 退出排行榜 123456789 987654321
Bot: ✅ 已成功为用户 123456789 退出群 987654321 的排行榜！

超管: 退出排行榜 @玩家A 987654321
Bot: ✅ 已成功为用户 123456789 退出群 987654321 的排行榜！

# 查询 Rating 排行榜（全部）
用户: wmrt
Bot: 🏆 本群 Rating 排行榜 TOP 10
     ==============================
     🥇 玩家A
        Rating: 15000
     🥈 玩家B
        Rating: 14800
     🥉 玩家C
        Rating: 14500
     4. 玩家D
        Rating: 14200
     ...
     ==============================

# 查询指定分段 Rating 排行榜
用户: wmrt5
Bot: 🏆 本群 Rating 排行榜 W5 TOP 5
     ==============================
     🥇 玩家A
        Rating: 15888
     🥈 玩家B
        Rating: 15666
     🥉 玩家C
        Rating: 15234
     4. 玩家D
        Rating: 15100
     5. 玩家E
        Rating: 15000
     ==============================
     该分段共 5 人

用户: wmrt4
Bot: 🏆 本群 Rating 排行榜 W4 TOP 3
     ==============================
     🥇 玩家F
        Rating: 14999
     🥈 玩家G
        Rating: 14800
     🥉 玩家H
        Rating: 14500
     ==============================
     该分段共 3 人

用户: wmrt0
Bot: 🏆 本群 Rating 排行榜 W0 TOP 2
     ==============================
     🥇 玩家A
        Rating: 10800
     🥈 玩家B
        Rating: 10200
     ==============================
     该分段共 2 人
```

#### 管理员操作

```
# 开启排行榜功能
管理员: 开启舞萌排行榜
Bot: ✅ 已在本群开启舞萌排行榜功能！

# 刷新排行榜数据
超管: 刷新排行榜
Bot: 正在刷新排行榜数据，请稍候...
Bot: 刷新完成！
     成功: 10 人
     失败: 0 人

# 超管重置用户刷新次数
超管: 重置刷新次数 @玩家A
Bot: ✅ 已重置用户 123456789 的今日刷新次数！

超管: 重置刷新次数 987654321
Bot: ✅ 已重置用户 987654321 的今日刷新次数！

# 更新歌曲数据
超管: 更新歌曲数据
Bot: 正在更新歌曲数据，请稍候...
Bot: ✅ 歌曲数据更新完成！
     共加载 1500 首歌曲

# 刷新群昵称
管理员: 刷新群昵称
Bot: 正在刷新群昵称，共 10 位用户...
Bot: ✅ 群昵称刷新完成！

# 刷新昵称（简化命令）
管理员: 刷新昵称
Bot: 正在刷新群昵称，共 10 位用户...
Bot: ✅ 群昵称刷新完成！

# 为他人加入排行榜（当前群）
管理员: 加入排行榜 123456789
Bot: ✅ 已成功为用户 123456789 加入排行榜！
     昵称: 玩家B
     Rating: 13800

# 为他人加入指定群的排行榜（仅超管可执行）
超管: 加入排行榜 123456789 987654321
Bot: ✅ 已成功为用户 123456789 加入群 987654321 的排行榜！
     昵称: 玩家B
     Rating: 13800
```

## 💡 注意事项

### 使用前提

1. ✅ 用户必须先在 [水鱼查分器](https://www.diving-fish.com/maimaidx/prober/) 绑定 QQ 号
2. ✅ 用户需要在水鱼查分器中**关闭隐私设置**（允许第三方查询）
3. ✅ Developer Token 有请求频率限制，请合理使用

### 功能特点

- 📊 排行榜默认显示歌曲的最高难度，可通过参数指定其他难度
- 🎯 排行榜最多显示前 20 名，避免图片过长
- 👥 昵称优先显示群名片，如无群名片则显示 QQ 昵称
- 🔄 用户加入排行榜时会自动刷新该群所有成员的昵称

## 💾 数据存储

插件数据使用 [nonebot-plugin-localstore](https://github.com/nonebot/plugin-localstore) 管理，默认存储在插件专属的数据与缓存目录中。也可通过配置项自定义路径。

### 主数据库
- 📄 `maimai_raking.db` - 主数据库文件
  - `groups` 表 - 群组配置信息
  - `users` 表 - 用户基本信息
  - `user_groups` 表 - 用户-群组关系
  - `records` 表 - 用户成绩记录
  - `custom_aliases` 表 - 自定义歌曲别名

### 缓存数据库
- 📄 `cache.db` - 缓存数据库文件
  - `alias_cache` 表 - 别名数据缓存
  - `cover_cache` 表 - 歌曲封面缓存（BLOB）

## 📄 开源协议

本项目采用 [GPL3.0](LICENSE) 开源协议

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

如果你有任何建议或发现了 Bug，请：
1. 在 GitHub 上提交 Issue
2. Fork 本项目并提交 Pull Request
3. 联系作者反馈问题

## 🔗 相关链接

- [NoneBot2 文档](https://nonebot.dev/)
- [水鱼查分器](https://www.diving-fish.com/maimaidx/prober/)
- [落雪咖啡屋查分器](https://maimai.lxns.net/)
- [舞萌 DX 别名库](https://www.yuzuchan.moe/mai/alias)
- [OneBot 协议](https://onebot.dev/)

## 👨‍💻 致谢

- 感谢 [水鱼查分器](https://www.diving-fish.com/maimaidx/prober/) 提供的成绩 API 支持
- 感谢 [落雪咖啡屋](https://maimai.lxns.net/) 提供的 舞萌美术资源
- 感谢 [柚子舞萌别名库](https://www.yuzuchan.moe/api/maimaidx/maimaidxalias) 提供的别名数据
- 感谢 NoneBot2 社区的支持

---

**本项目完全使用vibe coding**
