koishi-plugin-afdian-manager

通过爱发电订单号自动审核 QQ 群入群申请。插件优先使用 Koishi 通用 guild-member-request 事件和 handleGuildMemberRequest()，在 OneBot/NapCat 环境下会尝试使用原始加群请求接口作为兜底。

配置

• afdianUserId：爱发电开发者后台的 user_id。
• afdianApiToken：爱发电 API Token，配置界面按密钥输入处理。
• whitelistUsers：无需订单验证的全局 QQ 号列表。
• guildWhitelistUsers：按群号配置的白名单，每项包含 guildId 和 users。
• graceDays：订阅结束后的宽限天数，默认 14。
• orderPattern：从申请理由中提取订单号的正则，默认 \d{14,}。
• allowReject：订单缺失或校验失败时是否主动拒绝入群申请，默认开启。关闭后未填写订单号会不处理，填写订单号但校验失败也不拒绝。
• requestTimeout：爱发电 API 请求超时，单位毫秒。
• maxSponsorPages：按订单用户 ID 反查赞助者过期时间时最多扫描的页数。
• expiredReportFormat：订阅失效名单默认输出格式，text 或 image。图片格式需要启用 koishi-plugin-puppeteer。
• autoRefreshIntervalHours：自动刷新绑定订阅有效期的间隔小时数，默认 24。设置为 0 可关闭。
• refreshBatchSize：每次自动刷新最多检查的绑定数量。
• debug：启用调试命令，默认关闭。命令默认需要 Koishi 权限等级 3。

插件不再提供生效群号列表。需要限制群聊时，请使用 Koishi 的全局过滤器或插件作用域；推荐一个插件配置对应一个群。

白名单有三层，按顺序任意命中都会跳过订单验证：

• whitelistUsers：配置项，全局生效。
• guildWhitelistUsers：配置项，按群号生效。
• afdian-manager.whitelist.add：命令写入数据库，按当前群或指定群生效。

管理命令

管理命令默认需要 Koishi 权限等级 3，会写入或修改插件数据库：

• afdian-manager.whitelist.add <QQ号> [群号]：把 QQ 加入当前群或指定群的白名单。
• afdian-manager.whitelist.remove <QQ号> [群号]：移除当前群或指定群的白名单。
• afdian-manager.whitelist.list [群号]：查看配置全局白名单、配置群级白名单和当前群数据库白名单。
• afdian-manager.bind <QQ号> <订单号> [群号]：校验订单后手动绑定 QQ 和订单。
• afdian-manager.unbind <QQ号> [群号]：解除 QQ 当前订单绑定，订单可重新绑定。
• afdian-manager.refresh <QQ号> [群号]：按当前绑定的爱发电用户 ID 刷新订阅有效期，续费换档位也会按该爱发电账号的当前订阅截止时间延长。
• afdian-manager.expired [群号] --format text|image：输出订阅失效人员名单，方便手动踢出群；配置白名单和命令白名单会被排除。

命令未填写 [群号] 时默认使用当前群聊。图片名单需要 koishi-plugin-puppeteer；未启用时会回退为文本。

调试命令

开启 debug 后会注册以下只读命令，不会写入或修改绑定数据：

• afdian-manager.ping：测试爱发电 API 签名和 Token 是否可用。
• afdian-manager.order <订单号>：查询订单状态、有效期推断结果和本地成员绑定情况。
• afdian-manager.sponsor <爱发电用户ID>：按爱发电用户 ID 查询当前赞助方案。
• afdian-manager.binding [QQ号]：查询本地成员记录；不传 QQ 号时使用当前会话用户。

数据库

插件只会创建 afdianManagerMembers 一张表。每行对应一个 QQ 在一个群里的当前状态，包含订单号、爱发电用户 ID、过期日期、绑定来源、白名单状态和最后检查日期。

日期字段使用 YYYY-MM-DD 字符串，便于直接通过数据库查看。自动刷新会按批次查询赞助者当前方案，并把本地过期日期更新到最新订阅截止日期加 graceDays；如果接口返回的日期早于本地记录，不会把有效期改短。

常用字段：

• memberKey：platform:guildId:userId，主键。
• orderNo：当前绑定的订单号，未绑定时为空。
• afdianUserId：订单对应的爱发电用户 ID，用于续费刷新。
• expireDate：含宽限期后的过期日期，格式 YYYY-MM-DD。
• bindSource：afdian、manual 或 none。
• whitelisted：是否为命令添加的群级白名单。
• lastCheckedDate：最近一次刷新检查日期。