# 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 的一致性。自动拒绝已离开白名单群的用户，设置宽限期供用户通过主群关键词重新激活。支持管理员手动触发审计，输出详细逐人报告。

**存储:** MySQL `ltd_manager_bot.whitelist_audit` 表（首次加载自动建表）。

#### 自动 vs 手动审计

| | 自动审计 | 手动审计 |
|---|---|---|
| 触发 | 每 N 分钟自动轮询 | 管理员在白名单群发关键词 |
| 群消息 | 不发送（安静） | 发送完整统计摘要 + 逐人详情 |
| 邮件 | 所有操作始终发送 | 所有操作始终发送 |
| 日志前缀 | `[自动]` | `[手动审计]` |

#### 生命周期状态

```
在白名单群中 ───────────────────────────────► 正常(无操作)
    │
    └── 用户退出群 ──► 检测到离群 ──► 已被拒绝(宽限期开始)
                            │
                            ├── 主群发关键词 ──► 已重新激活
                            ├── 进入警告窗口 ──► 邮件通知(仅一次)
                            └── 宽限期过 ──► 永久删除
```

#### 配置示例

```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]
    whitelist-group-polling-dep-name: "whitelistGroup"
    audit-command-prefixes:                    # 支持多个关键词
      - "审计"
      - "audit"
    re-activation-keywords:
      - "重新激活"
      - "激活白名单"
    grace-period-days: 7
    expiry-warning-days: 2
    poll-interval-minutes: 60
    enable-email: false
    # 邮件模板 (空=使用内置默认，支持占位符)
    email-reject-template: ""
    email-warning-template: ""
    email-removed-template: ""
    email-reactivated-template: ""
```

#### 配置项

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `self-id` | long | 是 | — | 机器人 QQ 号 |
| `filter-qq-list` | long[] | 是 | — | 保护列表，永不自动拒绝 |
| `audit-allowed-ids` | long[] | 是 | — | 允许执行手动审计的 QQ |
| `whitelist-group-polling-dep-name` | string | 是 | — | 白名单群轮询模块的依赖名 |
| `audit-command-prefixes` | string[] | 否 | `["审计"]` | 白名单群触发手动审计的关键词（支持多个） |
| `re-activation-keywords` | string[] | 是 | — | 主群中触发重新激活的关键词列表 |
| `grace-period-days` | int | 是 | — | 被拒绝后允许重新激活的天数 |
| `expiry-warning-days` | int | 是 | — | 宽限期到期前多少天发送警告 |
| `poll-interval-minutes` | long | 否 | `60` | 自动审计间隔（分钟） |
| `enable-email` | boolean | 否 | `false` | 是否启用邮件通知（需 MailModule 依赖） |
| `email-reject-template` | string | 否 | `""` | 拒绝邮件正文。占位符：`${playerName}` `${graceDays}` `${keywords}` |
| `email-warning-template` | string | 否 | `""` | 过期警告邮件正文。占位符：`${playerName}` `${remainDays}` `${keywords}` |
| `email-removed-template` | string | 否 | `""` | 删除邮件正文。占位符：`${playerName}` |
| `email-reactivated-template` | string | 否 | `""` | 重新激活邮件正文。占位符：`${playerName}` `${graceDays}` |

#### 手动审计输出示例

```
审计完成
────────────────
白名单总数: 42
在群正常: 35 人
新发现不在群(已拒绝): 2 人
  • Steve(123456789)
  • Alex(987654321)
宽限期中: Notch(111222333, 剩5天)
已过期删除: 1 人
  • Hero(444555666)
过滤列表跳过: 3 人
```

#### 邮件去重

每类邮件只发送一次：

| 邮件 | 去重方式 |
|---|---|
| 拒绝 | 仅首次检测到离群时发送（`existing == null`） |
| 重新拒绝 | 仅之前已重新激活的用户再次离群时发送 |
| 即将过期警告 | `warningSentTime == 0L` 守卫，仅发一次 |
| 已删除 | 发送后立即从 DB 删除记录，不再匹配 |
| 重新激活 | 仅在宽限期内关键词触发成功时发送 |

#### 状态持久化

审计状态存储在 **MySQL** `ltd_manager_bot.whitelist_audit` 表中（自动建表，零配置）。Bot 重启不丢失已标记的待处理记录。原先基于 JSON 文件的状态持久化已移除。

SQL 模板位于 `config/sql/whitelist/`:
- `create_audit_table.sql` — 建表 DDL
- `query_all_audit.sql` — 查全表
- `query_audit_by_qq.sql` — 按 QQ 查询
- `upsert_audit.sql` — 新增或更新
- `delete_audit.sql` — 删除记录

#### 依赖关系

| 依赖模块 | 类型 | 是否必需 | 用途 |
|---|---|---|---|
| 主群轮询 | `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"
```

#### 邮件通知时机

| 触发条件 | 邮件主题 |
|---|---|
| 首次检测离群 → 被拒绝 | `白名单已被拒绝` — 含宽限期和关键词提示 |
| 重新激活后再离群 → 再次拒绝 | `白名单已被拒绝` — 同上 |
| 进入警告窗口 | `白名单即将过期` — 剩余天数 |
| 宽限期过 → 永久删除 | `白名单已删除` |
| 关键词重新激活成功 | `白名单已重新激活` — 提醒加群 |

---

## 配置参考

### 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
```

管道确保：机器人自己的消息被忽略、只处理新消息、只有匹配关键词的消息才会到达业务处理器。