docs: 完善文档

2026-06-09 13:31:05 +08:00 · 2026-06-09 13:31:05 +08:00 · f3af0b7134
commit f3af0b7134
parent 23ca0454ff
4 changed files with 792 additions and 1 deletions
--- a/docs/en/modules.md
+++ b/docs/en/modules.md
@ -0,0 +1,329 @@
+# LTD-ManagerBot Module Documentation
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Infrastructure Modules](#infrastructure-modules)
+- [New Modules](#new-modules)
+  - [RCON Command Module](#rcon-command-module)
+  - [Gitea Webhook Module](#gitea-webhook-module)
+  - [Whitelist Audit Module](#whitelist-audit-module)
+- [Configuration Reference](#configuration-reference)
+
+---
+
+## Quick Start
+
+1. Copy the example configs from `src/main/resources/` to `config/`
+2. Edit `config/application.yaml` — set database, API URLs, tokens
+3. Edit `config/module.yaml` — uncomment and configure desired modules
+4. Place SQL templates in `config/sql/` if using InvitationCodes or WhitelistAudit
+5. Launch the bot
+
+### Minimal `application.yaml` additions for new modules
+
+```yaml
+# Whitelist System API (required by WhitelistAuditModule)
+whitelist-system:
+  url: "https://whitelist.your-server.top"
+  encrypted-token: "your-api-token-here"
+```
+
+---
+
+## Infrastructure Modules
+
+### GroupMessagePollingModule
+
+Polls a QQ group's message history at a fixed interval and emits a `SharedFlow<List<MsgHistorySpecificMsg>>`. Other modules subscribe to this flow to react to messages.
+
+```yaml
+- name: "talkGroup"
+  type: "GROUP_MESSAGE_POLLING_MODULE"
+  enabled: true
+  config:
+    target-group-id: 538751386
+    poll-interval-millis: 5000   # optional, default 5000
+    msg-history-check: 15        # optional, default 15
+```
+
+### MailModule
+
+Queues and sends emails via SMTP. Used by InvitationCodesModule and WhitelistAuditModule.
+
+```yaml
+- name: "talkGroup"
+  type: "MAIL_MODULE"
+  enabled: true
+```
+
+SMTP settings go in `application.yaml` → `mail:` section.
+
+---
+
+## New Modules
+
+### RCON Command Module
+
+**Type:** `RCON_COMMAND_MODULE`
+
+Allows specified QQ users to execute arbitrary Minecraft RCON commands via QQ group messages, with a configurable blocklist to prevent dangerous operations.
+
+#### Workflow
+
+```
+QQ Group: "rcon list"
+    │
+    ├── User NOT in admin-ids → reply: "no permission"
+    ├── Command matches blocklist → reply: "blocked"
+    └── Execute via RCON binary → reply with output
+```
+
+#### Example Config
+
+```yaml
+- name: "talkGroup"
+  type: "RCON_COMMAND_MODULE"
+  enabled: true
+  dependencies:
+    - name: "talkGroup"
+      type: "GROUP_MESSAGE_POLLING_MODULE"
+  config:
+    self-id: 3327379836
+    self-nick-name: "Bot"
+    command-prefix: "rcon"
+    admin-ids: [2561098830]
+    rcon-timeout-sec: 5
+    command-blocklist:
+      - "stop"
+      - "restart"
+      - "op"
+      - "deop"
+      - "whitelist"
+      - "ban"
+      - "ban-ip"
+      - "kick"
+      - "debug"
+      - "execute"
+```
+
+#### Config Reference
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `self-id` | long | yes | — | Bot's QQ ID |
+| `self-nick-name` | string | yes | — | Bot's display name |
+| `command-prefix` | string | yes | — | Trigger prefix in QQ group |
+| `admin-ids` | long[] | yes | — | QQ IDs allowed to execute RCON |
+| `command-blocklist` | string[] | yes | — | Blocked command prefixes (case-insensitive, `/`-prefix stripped) |
+| `rcon-timeout-sec` | long | no | `5` | RCON timeout in seconds |
+
+The RCON binary path and config path are read from `application.yaml` → `tools.rcon`.
+
+#### Blocklist Matching
+
+The blocklist uses **prefix matching** after stripping leading `/`:
+
+- `"stop"` blocks: `stop`, `stop 10s`, `/stop`, `/minecraft:stop`
+- `"ban"` blocks: `ban Steve`, `ban-ip`, `/ban`, etc.
+
+---
+
+### Gitea Webhook Module
+
+**Type:** `GITEA_WEBHOOK_MODULE`
+
+Starts an embedded HTTP server to receive [Gitea webhook](https://docs.gitea.com/usage/webhooks) events and forwards formatted notifications to a QQ group.
+
+#### Supported Events
+
+| Event | QQ Message Format |
+|---|---|
+| `push` | Author, branch, commit count, first 5 commit messages, compare URL |
+| `issues` | Action (opened/closed/reopened), title, body preview, link |
+| `pull_request` | Action, branches (head → base), state, link |
+| `create` | Branch/tag created, author |
+| `delete` | Branch/tag deleted, author |
+| `release` | Tag name, release name, body preview, draft/prerelease flags |
+| `repository` | Action (created/deleted/transferred) |
+| `fork` | Source repo → forked repo |
+
+#### Example Config
+
+```yaml
+- name: "talkGroup"
+  type: "GITEA_WEBHOOK_MODULE"
+  enabled: true
+  config:
+    webhook-port: 8080
+    webhook-path: "/gitea-webhook"
+    webhook-secret: "your-webhook-secret"
+    target-group-id: 538751386
+    events:
+      - "push"
+      - "issues"
+      - "pull_request"
+      - "create"
+      - "delete"
+      - "release"
+```
+
+#### Config Reference
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `webhook-port` | int | yes | — | HTTP server listen port |
+| `webhook-path` | string | no | `/gitea-webhook` | Webhook endpoint path |
+| `webhook-secret` | string | no | `""` | HMAC-SHA256 secret for signature verification |
+| `target-group-id` | long | yes | — | QQ group to send notifications to |
+| `events` | string[] | no | all | Event types to listen for |
+
+#### Gitea-side Setup
+
+In your Gitea repository → **Settings** → **Webhooks** → **Add Webhook** → **Gitea**:
+
+- **Target URL**: `http://<server-ip>:8080/gitea-webhook`
+- **Secret**: Same as `webhook-secret`
+- **Trigger On**: Select desired events
+
+#### Security
+
+- Signature verification: `X-Gitea-Signature` header validated via HMAC-SHA256
+- Empty `webhook-secret` disables verification (not recommended for production)
+
+---
+
+### Whitelist Audit Module
+
+**Type:** `WHITELIST_AUDIT_MODULE`
+
+Periodically checks the whitelist group membership against the whitelist API. Automatically rejects users who left the group, with a configurable grace period for re-activation via keywords in the main group. Supports admin-triggered manual audits.
+
+#### Lifecycle States
+
+```
+In Whitelist Group ───────────────────────────────► OK (no action)
+    │
+    └── User left group ──► Detected ──► Rejected (grace period starts)
+                                │
+                                ├── Keyword in main group ──► Re-Activated
+                                ├── Warning threshold ──► Email/Group notification sent
+                                └── Grace period expired ──► Permanently Removed
+```
+
+#### Two-Trigger System
+
+| Trigger | Group | Who | Action |
+|---|---|---|---|
+| Keyword (e.g. "重新激活") | Main group | Any pending user | Re-activates whitelist |
+| Audit command (e.g. "审计") | Whitelist group | `audit-allowed-ids` only | Runs immediate audit + posts results |
+
+#### Example Config
+
+```yaml
+- name: "talkGroup"
+  type: "WHITELIST_AUDIT_MODULE"
+  enabled: true
+  dependencies:
+    - name: "talkGroup"
+      type: "GROUP_MESSAGE_POLLING_MODULE"
+    - name: "whitelistGroup"
+      type: "GROUP_MESSAGE_POLLING_MODULE"
+    - name: "talkGroup"          # only if enable-email: true
+      type: "MAIL_MODULE"
+  config:
+    self-id: 3327379836
+    filter-qq-list: [2561098830, 3327379836]
+    audit-allowed-ids: [2561098830]
+    whitelist-group-polling-dep-name: "whitelistGroup"
+    audit-command-prefix: "审计"
+    re-activation-keywords:
+      - "重新激活"
+      - "激活白名单"
+      - "reactivate"
+    grace-period-days: 7
+    expiry-warning-days: 2
+    poll-interval-minutes: 60
+    enable-email: false
+```
+
+#### Config Reference
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `self-id` | long | yes | — | Bot's QQ ID |
+| `filter-qq-list` | long[] | yes | — | QQ IDs never auto-rejected |
+| `audit-allowed-ids` | long[] | yes | — | QQ IDs allowed to trigger manual audit |
+| `whitelist-group-polling-dep-name` | string | yes | — | Dependency name for the whitelist group polling module |
+| `audit-command-prefix` | string | no | `"审计"` | Command to trigger manual audit in whitelist group |
+| `re-activation-keywords` | string[] | yes | — | Keywords to re-activate from main group |
+| `grace-period-days` | int | yes | — | Days user has to re-activate after being rejected |
+| `expiry-warning-days` | int | yes | — | Days before expiry to send warning |
+| `poll-interval-minutes` | long | no | `60` | Auto-audit interval in minutes |
+| `enable-email` | boolean | no | `false` | Enable email notifications (requires MailModule) |
+
+#### Manual Audit Output Example
+
+```
+审计完成
+────────────────
+白名单总数: 42
+在群正常: 35 人
+新发现不在群(已拒绝): 2 人
+宽限期中: Steve(剩5天), Alex(剩2天)
+已过期删除: 1 人
+过滤列表跳过: 3 人
+```
+
+#### State Persistence
+
+Audit state is persisted to `data/whitelist_audit_state.json` with automatic backup. Survives bot restarts without losing pending reject records.
+
+#### Dependencies
+
+| Dependency | Type | Required | Purpose |
+|---|---|---|---|
+| Main group polling | `GROUP_MESSAGE_POLLING_MODULE` | yes | Re-activation keyword monitoring |
+| Whitelist group polling | `GROUP_MESSAGE_POLLING_MODULE` | yes | Audit command monitoring + member list |
+| Mail module | `MAIL_MODULE` | if `enable-email: true` | Email notifications |
+
+#### Whitetelist API Config
+
+API URL and token are in `application.yaml` `whitelist-system:` section for security (auto-encrypted):
+
+```yaml
+whitelist-system:
+  url: "https://whitelist.your-server.top"
+  encrypted-token: "your-api-token-here"
+```
+
+---
+
+## Configuration Reference
+
+### SQL Templates
+
+Some modules (InvitationCodesModule, GroupRequestHandlerModule) use SQL templates stored in `config/sql/`. Templates use `${placeholder}` syntax:
+
+```sql
+-- config/sql/invitation/query_qualification.sql
+SELECT q.player_id, q.effective, q.is_used, q.qq, q.status
+FROM ltd_manager_bot.qualified_user_info q
+WHERE q.qq IN (${placeholders})
+```
+
+Usage in code:
+```kotlin
+val sql = SqlTemplate.fromFile("invitation/query_qualification.sql")
+val result = sql.bind("placeholders" to "?, ?, ?")
+```
+
+### Message Filter Pipeline
+
+All message-driven modules use a common `TriggerMessageFilter` pipeline:
+
+```
+IgnoreSelfFilter → NewMessageFilter → KeywordFilter → [CooldownFilter] → handler
+```
+
+This ensures messages from the bot itself are ignored, only new messages are processed, and only keyword-matching messages reach the handler.
--- a/docs/zh/modules.md
+++ b/docs/zh/modules.md
@ -0,0 +1,344 @@
+# LTD-ManagerBot 模块文档
+
+## 目录
+
+- [快速开始](#快速开始)
+- [基础设施模块](#基础设施模块)
+- [新模块](#新模块)
+  - [RCON 命令模块](#rcon-命令模块)
+  - [Gitea Webhook 模块](#gitea-webhook-模块)
+  - [白名单审计模块](#白名单审计模块)
+- [配置参考](#配置参考)
+
+---
+
+## 快速开始
+
+1. 复制 `src/main/resources/` 下的示例配置到 `config/`
+2. 编辑 `config/application.yaml` — 设置数据库、API 地址、密钥
+3. 编辑 `config/module.yaml` — 取消注释并配置需要的模块
+4. 如需使用邀请码或白名单审计模块，将 SQL 模板放入 `config/sql/`
+5. 启动机器人
+
+### 新模块必需的 `application.yaml` 配置
+
+```yaml
+# 白名单系统 API (WhitelistAuditModule 必需)
+whitelist-system:
+  url: "https://whitelist.your-server.top"
+  encrypted-token: "your-api-token-here"
+```
+
+---
+
+## 基础设施模块
+
+### GroupMessagePollingModule (群消息轮询模块)
+
+按固定间隔轮询 QQ 群消息历史，通过 `SharedFlow<List<MsgHistorySpecificMsg>>` 向其他模块分发消息。
+
+```yaml
+- name: "talkGroup"
+  type: "GROUP_MESSAGE_POLLING_MODULE"
+  enabled: true
+  config:
+    target-group-id: 538751386       # 目标群号
+    poll-interval-millis: 5000       # 轮询间隔(毫秒)，可选，默认5000
+    msg-history-check: 15            # 每次检查的历史消息数，可选，默认15
+```
+
+### MailModule (邮件模块)
+
+通过 SMTP 发送邮件。InvitationCodesModule 和 WhitelistAuditModule 会使用此模块。
+
+```yaml
+- name: "talkGroup"
+  type: "MAIL_MODULE"
+  enabled: true
+```
+
+SMTP 设置在 `application.yaml` → `mail:` 段配置。
+
+---
+
+## 新模块
+
+### RCON 命令模块
+
+**类型:** `RCON_COMMAND_MODULE`
+
+允许指定用户在 QQ 群中执行 Minecraft RCON 命令。通过黑名单机制阻止危险操作，非授权用户无法执行。
+
+#### 执行流程
+
+```
+QQ群: "rcon list"
+    │
+    ├── 用户不在 admin-ids 中 → 回复: "你没有权限执行 RCON 命令"
+    ├── 命令匹配 command-blocklist → 回复: "命令已被阻止"
+    └── 通过 RCON 二进制执行 → 回复执行结果
+```
+
+#### 配置示例
+
+```yaml
+- name: "talkGroup"
+  type: "RCON_COMMAND_MODULE"
+  enabled: true
+  dependencies:
+    - name: "talkGroup"
+      type: "GROUP_MESSAGE_POLLING_MODULE"
+  config:
+    self-id: 3327379836
+    self-nick-name: "Bot"
+    command-prefix: "rcon"                     # QQ群触发前缀
+    admin-ids: [2561098830]                    # 允许执行RCON的QQ号
+    rcon-timeout-sec: 5                        # RCON超时(秒)
+    command-blocklist:                         # 危险命令黑名单(前缀匹配)
+      - "stop"
+      - "restart"
+      - "op"
+      - "deop"
+      - "whitelist"
+      - "ban"
+      - "ban-ip"
+      - "kick"
+      - "debug"
+      - "execute"
+```
+
+#### 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `self-id` | long | 是 | — | 机器人 QQ 号 |
+| `self-nick-name` | string | 是 | — | 机器人昵称 |
+| `command-prefix` | string | 是 | — | QQ 群触发前缀 |
+| `admin-ids` | long[] | 是 | — | 允许执行 RCON 的 QQ 号列表 |
+| `command-blocklist` | string[] | 是 | — | 危险命令黑名单(不区分大小写，自动去除 `/` 前缀) |
+| `rcon-timeout-sec` | long | 否 | `5` | RCON 超时时间(秒) |
+
+RCON 二进制路径和配置文件路径从 `application.yaml` → `tools.rcon` 读取。
+
+#### 黑名单匹配规则
+
+黑名单使用**前缀匹配**，自动去除前置 `/`：
+
+- `"stop"` 阻止: `stop`, `stop 10s`, `/stop`, `/minecraft:stop`
+- `"ban"` 阻止: `ban Steve`, `ban-ip`, `/ban` 等
+
+---
+
+### Gitea Webhook 模块
+
+**类型:** `GITEA_WEBHOOK_MODULE`
+
+启动嵌入式 HTTP 服务器，接收 [Gitea Webhook](https://docs.gitea.com/zh-cn/usage/webhooks) 事件，格式化后推送通知到 QQ 群。
+
+#### 支持的事件类型
+
+| 事件 | QQ 消息格式 |
+|---|---|
+| `push` | 推送者、分支、提交数、前5条提交摘要、对比链接 |
+| `issues` | 操作(已创建/已关闭/已重新打开)、标题、内容预览、链接 |
+| `pull_request` | 操作、分支流转(head → base)、状态、链接 |
+| `create` | 创建的分支/标签、创建者 |
+| `delete` | 删除的分支/标签、操作者 |
+| `release` | 标签名、版本名、内容预览、草稿/预发布标记 |
+| `repository` | 仓库操作(已创建/已删除/已转移) |
+| `fork` | 源仓库 → Fork 仓库 |
+
+#### 配置示例
+
+```yaml
+- name: "talkGroup"
+  type: "GITEA_WEBHOOK_MODULE"
+  enabled: true
+  config:
+    webhook-port: 8080                         # 监听端口
+    webhook-path: "/gitea-webhook"             # Webhook 路径
+    webhook-secret: "your-webhook-secret"      # HMAC-SHA256 密钥
+    target-group-id: 538751386                 # 推送 QQ 群号
+    events:                                    # 监听事件列表(空=全部)
+      - "push"
+      - "issues"
+      - "pull_request"
+      - "create"
+      - "delete"
+      - "release"
+```
+
+#### 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `webhook-port` | int | 是 | — | HTTP 服务器监听端口 |
+| `webhook-path` | string | 否 | `/gitea-webhook` | Webhook 端点路径 |
+| `webhook-secret` | string | 否 | `""` | HMAC-SHA256 签名验证密钥，为空则跳过验证 |
+| `target-group-id` | long | 是 | — | 推送通知的目标 QQ 群号 |
+| `events` | string[] | 否 | 全部 | 监听的事件类型列表 |
+
+#### Gitea 端设置
+
+在 Gitea 仓库 → **设置** → **Webhooks** → **添加 Webhook** → **Gitea**：
+
+- **目标 URL**: `http://<服务器IP>:8080/gitea-webhook`
+- **密钥**: 与 `webhook-secret` 一致
+- **触发条件**: 勾选需要的事件
+
+#### 安全性
+
+- 签名验证: 通过 HMAC-SHA256 验证 `X-Gitea-Signature` 请求头
+- 生产环境建议务必设置 `webhook-secret`
+
+---
+
+### 白名单审计模块
+
+**类型:** `WHITELIST_AUDIT_MODULE`
+
+定期检查白名单群成员与白名单 API 的一致性。自动拒绝已离开白名单群的用户，设置宽限期供用户通过主群关键词重新激活。支持管理员手动触发审计。
+
+#### 生命周期状态
+
+```
+在白名单群中 ───────────────────────────────► 正常(无操作)
+    │
+    └── 用户退出群 ──► 检测到离群 ──► 已被拒绝(宽限期开始)
+                            │
+                            ├── 主群发关键词 ──► 已重新激活
+                            ├── 进入警告窗口 ──► 发送邮件/群通知
+                            └── 宽限期过 ──► 永久删除
+```
+
+#### 双触发器系统
+
+| 触发器 | 群 | 谁可使用 | 操作 |
+|---|---|---|---|
+| 关键词 (如"重新激活") | 主群 | 任何待处理用户 | 重新激活白名单 |
+| 审计命令 (如"审计") | 白名单群 | 仅 `audit-allowed-ids` | 立即执行审计 + 输出结果 |
+
+#### 配置示例
+
+```yaml
+- name: "talkGroup"
+  type: "WHITELIST_AUDIT_MODULE"
+  enabled: true
+  dependencies:
+    - name: "talkGroup"                        # 主群轮询 (重新激活关键词)
+      type: "GROUP_MESSAGE_POLLING_MODULE"
+    - name: "whitelistGroup"                   # 白名单群轮询 (审计命令)
+      type: "GROUP_MESSAGE_POLLING_MODULE"
+    - name: "talkGroup"                        # 邮件模块 (enable-email:true 时)
+      type: "MAIL_MODULE"
+  config:
+    self-id: 3327379836
+    # ---- 权限控制 ----
+    filter-qq-list: [2561098830, 3327379836]   # 永不自动拒绝的保护列表
+    audit-allowed-ids: [2561098830]            # 可执行手动审计的管理员QQ
+    # ---- 白名单群手动审计 ----
+    whitelist-group-polling-dep-name: "whitelistGroup"
+    audit-command-prefix: "审计"               # 白名单群触发关键词
+    # ---- 重新激活 ----
+    re-activation-keywords:                    # 主群重新激活关键词
+      - "重新激活"
+      - "激活白名单"
+      - "reactivate"
+    # ---- 时间参数 ----
+    grace-period-days: 7                       # 宽限期(天)
+    expiry-warning-days: 2                     # 到期前N天发警告
+    poll-interval-minutes: 60                  # 自动审计间隔(分钟)
+    # ---- 邮件通知 ----
+    enable-email: false                        # 是否启用邮件通知
+```
+
+#### 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `self-id` | long | 是 | — | 机器人 QQ 号 |
+| `filter-qq-list` | long[] | 是 | — | 保护列表，模块不会自动拒绝这些 QQ 的白名单 |
+| `audit-allowed-ids` | long[] | 是 | — | 允许在白名单群执行手动审计的 QQ |
+| `whitelist-group-polling-dep-name` | string | 是 | — | 白名单群轮询模块的依赖名 |
+| `audit-command-prefix` | string | 否 | `"审计"` | 白名单群触发手动审计的命令 |
+| `re-activation-keywords` | string[] | 是 | — | 主群中触发重新激活的关键词列表 |
+| `grace-period-days` | int | 是 | — | 被拒绝后允许重新激活的天数 |
+| `expiry-warning-days` | int | 是 | — | 宽限期到期前多少天发送警告 |
+| `poll-interval-minutes` | long | 否 | `60` | 自动审计间隔(分钟) |
+| `enable-email` | boolean | 否 | `false` | 是否发送邮件通知(需 MailModule 依赖) |
+
+#### 手动审计输出示例
+
+```
+审计完成
+────────────────
+白名单总数: 42
+在群正常: 35 人
+新发现不在群(已拒绝): 2 人
+宽限期中: Steve(剩5天), Alex(剩2天)
+已过期删除: 1 人
+过滤列表跳过: 3 人
+```
+
+#### 状态持久化
+
+审计状态保存在 `data/whitelist_audit_state.json`，附自动备份。机器人重启不会丢失待处理记录。
+
+#### 依赖关系
+
+| 依赖模块 | 类型 | 是否必需 | 用途 |
+|---|---|---|---|
+| 主群轮询 | `GROUP_MESSAGE_POLLING_MODULE` | 是 | 监听主群重新激活关键词 |
+| 白名单群轮询 | `GROUP_MESSAGE_POLLING_MODULE` | 是 | 监听审计命令 + 获取群成员列表 |
+| 邮件模块 | `MAIL_MODULE` | `enable-email: true` 时 | 发送邮件通知 |
+
+#### 白名单 API 配置
+
+API 地址和密钥在 `application.yaml` 的 `whitelist-system:` 段配置(启动后自动加密):
+
+```yaml
+whitelist-system:
+  url: "https://whitelist.your-server.top"
+  encrypted-token: "your-api-token-here"
+```
+
+#### 邮件通知时机
+
+| 触发条件 | 邮件主题 |
+|---|---|
+| 首次检测离群 → 被拒绝 | `LTD白名单审计通知` — 告知已被拒，宽限期 N 天 |
+| 重新激活后再离群 → 再次拒绝 | `LTD白名单审计通知` — 告知再次被拒 |
+| 进入警告窗口 | `LTD白名单即将过期` — 剩余 N 天 |
+| 宽限期过 → 永久删除 | `LTD白名单已删除` — 已永久删除 |
+| 关键词重新激活成功 | `LTD白名单已重新激活` — 提醒加群 |
+
+---
+
+## 配置参考
+
+### SQL 模板
+
+部分模块(InvitationCodesModule、GroupRequestHandlerModule)使用 `config/sql/` 下的 SQL 模板文件。模板使用 `${placeholder}` 语法：
+
+```sql
+-- config/sql/invitation/query_qualification.sql
+SELECT q.player_id, q.effective, q.is_used, q.qq, q.status
+FROM ltd_manager_bot.qualified_user_info q
+WHERE q.qq IN (${placeholders})
+```
+
+代码中使用：
+```kotlin
+val sql = SqlTemplate.fromFile("invitation/query_qualification.sql")
+val result = sql.bind("placeholders" to "?, ?, ?")
+```
+
+### 消息过滤管道
+
+所有消息驱动的模块使用统一的 `TriggerMessageFilter` 管道：
+
+```
+IgnoreSelfFilter → NewMessageFilter → KeywordFilter → [CooldownFilter] → handler
+```
+
+管道确保：机器人自己的消息被忽略、只处理新消息、只有匹配关键词的消息才会到达业务处理器。
--- a/src/main/resources/application.yaml
+++ b/src/main/resources/application.yaml
@ -106,3 +106,9 @@ dg-lab:
 img-tu:
  url: https://mysite.com/api/1/upload
  encrypted-password: 11223344bbcc
+# ====== 白名单系统 API 配置 (WhitelistAuditModule) ======
+whitelist-system:
+  # 白名单系统 API 地址
+  url: "https://whitelist.your-server.top"
+  # API Key，格式为 ENC(XXX), 首次启动自动加密
+  encrypted-token: "your-api-token-here"
--- a/src/main/resources/module.yaml
+++ b/src/main/resources/module.yaml
@ -1,2 +1,114 @@
+# =============================================================================
+# LTD-ManagerBot 模块配置
+# =============================================================================
+# 所有可用模块类型 (ModuleType):
+#   MAIL_MODULE               - 邮件发送
+#   GROUP_REQUEST_HANDLER_MODULE - 自动处理加群请求
+#   GROUP_MESSAGE_POLLING_MODULE  - 群消息轮询 (基础设施)
+#   INVITE_MODULE             - 邀请码生成与发送
+#   BAN_MODULE                - 禁言/解禁
+#   DG_LAB_MODULE             - DG-Lab 设备控制
+#   MC_SERVER_STATUS_MODULE    - MC 服务器状态查询
+#   RCON_PLAYER_LIST_MODULE    - RCON 玩家列表/TPS 查询
+#   STATE_MODULE              - 机器人状态显示
+#   MOD_GROUP_HANDLER_MODULE  - Mod 群自动处理
+#   HELP_MODULE               - 帮助模块
+#   RCON_COMMAND_MODULE       - 通用 RCON 命令执行
+#   GITEA_WEBHOOK_MODULE      - Gitea Webhook 事件通知
+#   WHITELIST_AUDIT_MODULE    - 白名单审计 (自动拒绝/提醒/过期)
+# =============================================================================
+
 module:
-  modules:
+  modules:
+
+  # ---- 邮件模块 ----
+  # - name: "talkGroup"
+  #   type: "MAIL_MODULE"
+  #   enabled: true
+
+  # ---- 群消息轮询 (主群) ----
+  # - name: "talkGroup"
+  #   type: "GROUP_MESSAGE_POLLING_MODULE"
+  #   enabled: true
+  #   config:
+  #     target-group-id: 538751386
+
+  # ---- 群消息轮询 (白名单群) ----
+  # - name: "whitelistGroup"
+  #   type: "GROUP_MESSAGE_POLLING_MODULE"
+  #   enabled: true
+  #   config:
+  #     target-group-id: 920719236
+
+  # ---- 通用 RCON 命令模块 ----
+  # - name: "talkGroup"
+  #   type: "RCON_COMMAND_MODULE"
+  #   enabled: true
+  #   dependencies:
+  #     - name: "talkGroup"
+  #       type: "GROUP_MESSAGE_POLLING_MODULE"
+  #   config:
+  #     self-id: 3327379836
+  #     self-nick-name: "Bot"
+  #     command-prefix: "rcon"                     # QQ群触发前缀
+  #     admin-ids: [2561098830]                    # 允许执行RCON的QQ号
+  #     rcon-timeout-sec: 5                        # RCON超时(秒)
+  #     command-blocklist:                         # 危险命令黑名单(前缀匹配)
+  #       - "stop"
+  #       - "restart"
+  #       - "op"
+  #       - "deop"
+  #       - "whitelist"
+  #       - "ban"
+  #       - "ban-ip"
+  #       - "kick"
+  #       - "debug"
+  #       - "execute"
+
+  # ---- Gitea Webhook 模块 ----
+  # - name: "talkGroup"
+  #   type: "GITEA_WEBHOOK_MODULE"
+  #   enabled: true
+  #   config:
+  #     webhook-port: 8080                         # 监听端口
+  #     webhook-path: "/gitea-webhook"             # Webhook路径 (默认)
+  #     webhook-secret: "your-webhook-secret"      # HMAC-SHA256密钥
+  #     target-group-id: 538751386                 # 推送QQ群
+  #     events:                                    # 监听事件 (空=全部)
+  #       - "push"
+  #       - "issues"
+  #       - "pull_request"
+  #       - "create"
+  #       - "delete"
+  #       - "release"
+
+  # ---- 白名单审计模块 ----
+  # - name: "talkGroup"
+  #   type: "WHITELIST_AUDIT_MODULE"
+  #   enabled: true
+  #   dependencies:
+  #     - name: "talkGroup"                        # 主群轮询 (重新激活关键词)
+  #       type: "GROUP_MESSAGE_POLLING_MODULE"
+  #     - name: "whitelistGroup"                   # 白名单群轮询 (审计命令)
+  #       type: "GROUP_MESSAGE_POLLING_MODULE"
+  #     - name: "talkGroup"                        # 邮件模块 (enable-email:true时)
+  #       type: "MAIL_MODULE"
+  #   config:
+  #     self-id: 3327379836
+  #     # ---- 权限控制 ----
+  #     filter-qq-list: [2561098830, 3327379836]   # 永不自动拒绝的QQ
+  #     audit-allowed-ids: [2561098830]            # 可执行"审计"命令的QQ
+  #     # ---- 白名单群手动审计 ----
+  #     whitelist-group-polling-dep-name: "whitelistGroup"
+  #     audit-command-prefix: "审计"               # 白名单群触发关键词
+  #     # ---- 重新激活 ----
+  #     re-activation-keywords:                    # 主群重新激活关键词
+  #       - "重新激活"
+  #       - "激活白名单"
+  #       - "reactivate"
+  #     # ---- 时间参数 ----
+  #     grace-period-days: 7                       # 宽限期(天)
+  #     expiry-warning-days: 2                     # 到期前N天警告
+  #     poll-interval-minutes: 60                  # 审计间隔(分钟)
+  #     # ---- 邮件通知 ----
+  #     enable-email: false                        # 是否启用邮件通知