# 星秩AI群管系统 - 使用教程

## 目录

1. [登录与账户管理](#1-登录与账户管理)
2. [仪表盘概览](#2-仪表盘概览)
3. [群组管理](#3-群组管理)
4. [欢迎消息](#4-欢迎消息)
5. [关键词回复](#5-关键词回复)
6. [AI 对话配置](#6-ai-对话配置)
7. [规则引擎](#7-规则引擎)
8. [定时广播](#8-定时广播)
9. [积分系统](#9-积分系统)
10. [积分商城](#10-积分商城)
11. [黑名单管理](#11-黑名单管理)
12. [白名单管理](#12-白名单管理)
13. [防刷屏设置](#13-防刷屏设置)
14. [群组设置](#14-群组设置)
15. [操作日志](#15-操作日志)
16. [常见问题](#16-常见问题)

---

## 1. 登录与账户管理

### 1.1 登录管理后台

1. 打开浏览器，访问前端地址（例如：`http://your-server:5173`）
2. 输入用户名和密码
3. 点击"登录"按钮

> **默认账户**: 用户名 `admin`，密码 `admin123`

### 1.2 修改密码

1. 登录后在侧边栏找到"设置"或用户图标
2. 选择"修改密码"
3. 输入当前密码和新密码
4. 确认修改

### 1.3 创建子管理员（仅超级管理员）

仅 `superadmin` 角色可以创建新的管理员账户。

1. 在管理后台找到"系统设置"或"用户管理"
2. 点击"添加管理员"
3. 填写用户名、密码，选择角色（`admin` 或 `superadmin`）
4. 确认创建

---

## 2. 仪表盘概览

登录后首先看到的是仪表盘，包含以下信息：

### 2.1 数据统计卡片

| 指标 | 说明 |
|------|------|
| **群组总数** | 已添加到系统的 QQ 群数量 |
| **规则总数** | 系统中已配置的规则数量 |
| **活跃规则** | 当前已启用的规则数量 |
| **黑名单人数** | 被拉黑的用户数量 |
| **本周日志** | 最近 7 天的操作日志总数 |

### 2.2 数据趋势图

- **AI 回复趋势**: 显示近 7 天 AI 对话次数
- **违规趋势**: 显示近 7 天触发规则的动作次数
- **消息趋势**: 消息收发统计（需开启消息追踪）

### 2.3 机器人状态

显示 NapCat 连接状态：
- 🟢 **已连接**: 机器人正常运行
- 🔴 **未连接**: 机器人离线，请检查 NapCat 服务

---

## 3. 群组管理

### 3.1 查看群组列表

1. 在侧边栏点击"群组管理"或"群组列表"
2. 查看所有已添加的群组
3. 每行显示：群组名称、群号、成员数、状态、功能开启情况

### 3.2 添加群组

1. 点击"添加群组"按钮
2. 填写群组信息：
   - **群号**: QQ 群号码（数字）
   - **群名称**: 给群组起一个易识别的名字
3. 点击"确认添加"

### 3.3 同步群组（从 QQ 机器人）

如果已经有通过 NapCat 连接的群组，可以一键同步：

1. 点击"同步群组"按钮
2. 系统会自动从 NapCat 获取当前机器人加入的所有群组
3. 新增的群组会被添加到列表，已存在的会更新信息

### 3.4 查看群组成员

1. 点击某个群组的"成员"或"成员管理"按钮
2. 可以看到该群的所有成员列表
3. 支持搜索成员
4. 点击成员可以进行：禁言、踢出、警告等操作

### 3.5 同步成员

点击"同步成员"按钮，从 QQ 服务器拉取最新的群成员列表。

### 3.6 批量操作成员

1. 勾选多个成员前的复选框
2. 选择要执行的操作：
   - **批量禁言**: 设置禁言时长（秒）
   - **批量踢出**: 将选中的成员踢出群聊
   - **批量警告**: 发送警告消息

### 3.7 全员禁言

在群组详情页，可以一键开启/关闭全员禁言：

- 点击"开启全员禁言" → 所有成员无法发言
- 点击"关闭全员禁言" → 恢复正常

---

## 4. 欢迎消息

### 4.1 设置欢迎消息

当有新成员加入群组时，自动发送欢迎消息。

1. 进入群组详情页
2. 找到"欢迎消息"模块
3. 填写欢迎内容（支持文本和变量）：
   ```
   欢迎 @nickname 加入本群！
   请阅读群规，遵守社区秩序。
   ```
4. 设置延迟时间（秒）：成员入群后多久发送欢迎消息
5. 点击"保存"

### 4.2 启用/禁用欢迎消息

- 开启：勾选"启用欢迎消息"
- 关闭：取消勾选

### 4.3 测试欢迎消息

点击"测试"按钮，系统会立即向该群发送一条测试欢迎消息。

### 4.4 支持的变量

| 变量 | 说明 |
|------|------|
| `@nickname` | 替换为新成员昵称 |
| `@groupname` | 替换为群名称 |

---

## 5. 关键词回复

关键词回复允许机器人根据用户发送的特定关键词自动回复。

### 5.1 添加关键词回复

1. 进入群组详情页
2. 找到"关键词回复"模块
3. 点击"添加回复"
4. 填写表单：
   - **触发关键词**: 用户发送什么内容时触发（精确匹配，不区分大小写）
   - **回复类型**: 
     - `文本`: 发送纯文字回复
     - `图片`: 发送一张图片（URL 或上传）
     - `混合`: 发送图文混合内容（JSON 格式）
   - **回复内容**: 根据选择的类型填写相应内容
   - **启用状态**: 是否立即启用
5. 点击"确认添加"

### 5.2 回复类型示例

**文本类型**:
```
发送"帮助"时，回复：📖 群管理帮助信息...
```

**图片类型**:
```
触发词：规则
回复：https://example.com/group-rules.jpg
```

**混合类型**（JSON 数组）:
```json
[
  { "type": "text", "data": { "text": "📋 群规如下：" } },
  { "type": "image", "data": { "url": "https://example.com/rules.jpg" } },
  { "type": "text", "data": { "text": "请大家遵守！" } }
]
```

### 5.3 编辑和删除关键词回复

- 点击某个回复行的"编辑"按钮修改
- 点击"删除"按钮移除（需要确认）

### 5.4 批量启用/禁用

使用开关按钮快速启用或禁用某个关键词回复。

---

## 6. AI 对话配置

### 6.1 配置 AI 模型

1. 进入群组详情页
2. 找到"AI 对话"或"模型设置"模块
3. 填写配置信息：
   - **模型名称**: 如 `gpt-4o-mini`、`gpt-4` 等
   - **API Key**: 你的 AI API 密钥
   - **API Endpoint**: API 地址（留空使用默认地址）
   - **Temperature**: 回答创造性参数（0.0-2.0，默认 0.7）
   - **最大回复长度**: 单次回复最大 Token 数（默认 2000）
4. 点击"保存配置"

### 6.2 触发方式配置

在"触发词"设置中，配置 AI 对话的激活条件：

| 触发类型 | 说明 | 示例 |
|----------|------|------|
| **@mention** | 用户 @机器人 时触发 | `@AI 你好` |
| **keyword** | 包含指定关键词时触发 | `问题` |
| **prefix** | 以指定字符开头时触发 | `!` |

### 6.3 配置 AI Prompt（系统提示词）

1. 在 AI 设置中找到"Prompt 设置"
2. 可以创建多个版本的 Prompt
3. 支持变量替换：
   - `{{user_name}}` - 用户昵称
   - `{{user_id}}` - 用户 QQ 号
   - `{{group_name}}` - 群名称
4. 预览 Prompt 效果
5. 设置为"活跃"版本后，AI 将使用该 Prompt

### 6.4 AI 对话日志

查看 AI 对话历史记录：

1. 在侧边栏点击"AI 日志"或"AI 对话记录"
2. 可以按时间段、用户筛选
3. 每条记录显示：用户、问题、AI 回复、时间

### 6.5 常见触发场景

```
用户发送: @AI 今天天气怎么样？
AI 回复: 今天天气晴朗，适合出行！

用户发送: @AI 帮我解答一个问题
AI 回复: 好的，请问是什么问题呢？
```

---

## 7. 规则引擎

规则引擎用于自动处理群内违规行为。

### 7.1 查看预设模板

系统内置了一些常用规则模板：

| 模板名称 | 触发类型 | 触发内容 | 处理动作 |
|----------|----------|----------|----------|
| 广告链接 | keyword | `http` | warn |
| 敏感词过滤 | keyword | `外挂\|作弊\|破解` | mute |
| 黑名单用户 | blacklist | - | kick |

### 7.2 从模板创建规则

1. 在"规则列表"页面找到"从模板创建"
2. 选择需要的模板
3. 选择应用到哪个群组（或全局）
4. 点击"确认创建"

### 7.3 手动添加规则

1. 点击"添加规则"按钮
2. 填写规则配置：
   - **规则名称**: 给规则起个名字
   - **所属群组**: 选择应用范围（可选全局）
   - **触发类型**:
     - `keyword`: 关键词匹配
     - `regex`: 正则表达式匹配
     - `blacklist`: 黑名单用户自动踢出
   - **触发内容**: 触发时匹配的内容
   - **是否正则**: 启用后触发内容作为正则表达式处理
   - **处理动作**:
     - `warn`: 发送警告消息
     - `mute`: 禁言用户
     - `kick`: 踢出群聊
   - **动作参数**: 如禁言时长（秒）
   - **优先级**: 数字越大优先级越高
   - **启用状态**: 是否立即启用
3. 点击"确认添加"

### 7.4 编辑和删除规则

- 点击规则行的"编辑"按钮修改配置
- 点击"删除"按钮移除规则
- 使用开关快速启用/禁用规则

### 7.5 规则优先级

当多条规则同时满足时，优先级（priority）最高的规则优先执行。

---

## 8. 定时广播

定时广播允许在指定时间自动向群组发送消息。

### 8.1 创建定时任务

1. 进入群组详情页
2. 找到"定时任务"或"定时广播"模块
3. 点击"添加任务"
4. 填写配置：
   - **广播内容**: 要发送的消息内容
   - **执行周期**:
     - `daily`: 每天定时发送
     - `weekly`: 每周定时发送
     - `hourly`: 每小时发送
     - `every`: 每隔 N 分钟发送
   - **时间配置**:
     - 每日: `HH:MM` 格式，如 `09:00`
     - 每周: 选择星期几 + 时间，如 `周一 09:00`
   - **启用状态**: 是否立即启用
5. 点击"确认创建"

### 8.2 周期表达式示例

| 类型 | 表达式 | 说明 |
|------|--------|------|
| 每日 | `daily:09:00` | 每天上午 9 点 |
| 每日 | `daily:20:30` | 每天晚上 8 点 30 分 |
| 每周 | `weekly:1,09:00` | 每周一上午 9 点 |
| 每小时 | `hourly` | 每小时整点 |
| 每30分钟 | `every:30` | 每 30 分钟发送一次 |

### 8.3 编辑和删除任务

- 点击任务行的"编辑"按钮修改
- 点击"删除"按钮移除
- 使用开关快速启用/禁用任务

### 8.4 自动 @全体成员

定时广播发送时会自动在消息开头添加 `@全体成员`，确保所有人都能看到。

---

## 9. 积分系统

### 9.1 签到功能

用户每天可以在群内发送签到命令获取积分。

**签到命令**: `签到` 或 `/sign`

**效果**:
- 每日首次签到可获得积分奖励
- 已签到当天无法重复签到
- 签到成功会发送群消息通知

### 9.2 配置签到设置

1. 进入群组详情页
2. 找到"签到设置"模块
3. 配置：
   - **每日积分**: 每次签到获得的积分数量（默认 1）
   - **启用回复**: 是否在签到后发送群消息通知
4. 点击"保存设置"

### 9.3 查询积分

**群内命令**:
- `我的积分` - 查看当前积分
- `我的排名` - 查看群内积分排名
- `排行榜` - 查看积分排行榜前 10

### 9.4 积分排行榜

管理员可以查看群内积分排行：

1. 进入群组详情页
2. 找到"积分排行"模块
3. 显示：排名、用户昵称、积分
4. 支持手动调整用户积分（点击编辑）

---

## 10. 积分商城

积分商城允许用户用积分兑换虚拟商品（如 CDKey）。

### 10.1 添加商品

1. 进入群组详情页
2. 找到"积分商城"或"商品管理"模块
3. 点击"添加商品"
4. 填写商品信息：
   - **商品名称**: 商品的名字
   - **商品描述**: 商品的详细说明（可选）
   - **价格积分**: 需要多少积分兑换
   - **CDKey 库存**: 每行一个 CDKey，支持批量导入
   - **状态**: 上架 / 下架
5. 点击"确认添加"

### 10.2 管理商品

- **编辑**: 修改商品信息和库存
- **追加 CDKey**: 在现有库存基础上追加新的 CDKey
- **下架**: 将商品从商城下架（已购买用户不受影响）
- **删除**: 永久删除商品（谨慎操作）

### 10.3 用户购买流程

**群内命令**:
- `商品列表` 或 `商城` - 查看可购买商品
- `购买 [商品名称]` - 用积分购买商品

**购买成功时**:
1. 积分从用户账户扣除
2. 系统自动从库存中弹出一个 CDKey
3. CDKey 通过私聊发送给用户
4. 群内发送购买成功通知

### 10.4 查看订单记录

管理员可以查看所有购买记录：

1. 进入群组详情页
2. 找到"订单记录"或"历史订单"
3. 显示：订单号、用户、商品、CDKey、消耗积分、时间

---

## 11. 黑名单管理

### 11.1 添加用户到黑名单

1. 进入群组详情页
2. 找到"黑名单"模块
3. 点击"添加黑名单"
4. 填写信息：
   - **用户 QQ 号**: 要拉黑的用户 QQ 号
   - **昵称**: 用户昵称（可选，便于识别）
   - **原因**: 拉黑原因（可选）
5. 点击"确认添加"

### 11.2 黑名单效果

被拉入黑名单的用户：
- 再次进入群组时会被自动踢出
- 无法通过任何方式在群内发言

### 11.3 手动同步黑名单

当用户在群外被拉黑后，可以手动将黑名单同步到群内：

1. 在黑名单页面点击"同步到群"
2. 系统会自动将黑名单中的用户从对应群组踢出

### 11.4 移除黑名单

点击黑名单条目的"移除"按钮，可以将用户从黑名单中移除。

---

## 12. 白名单管理

### 12.1 添加用户到白名单

1. 进入群组详情页
2. 找到"白名单"模块
3. 点击"添加白名单"
4. 填写信息：
   - **用户 QQ 号**: 要加入白名单的用户 QQ 号
   - **昵称**: 用户昵称（可选）
   - **原因**: 添加原因（可选）
5. 点击"确认添加"

### 12.2 白名单效果

白名单用户会跳过以下所有检查：
- ✅ 不受防刷屏规则限制
- ✅ 不受关键词规则限制
- ✅ 不受 AI 回复限制
- ✅ 可以发送链接

> 白名单优先级最高，用于特殊用户（如管理员小号）。

### 12.3 移除白名单

点击白名单条目的"移除"按钮，可以将用户从白名单中移除。

---

## 13. 防刷屏设置

### 13.1 配置防刷屏规则

1. 进入群组详情页
2. 找到"防刷屏设置"模块
3. 填写配置：
   - **启用防刷屏**: 是否开启防刷屏功能
   - **时间窗口**: 在多少秒内检测（默认 10 秒）
   - **最大次数**: 超过多少次相同消息视为刷屏（默认 5 次）
   - **处理动作**:
     - `warn`: 发送警告
     - `mute`: 禁言用户
     - `kick`: 踢出群聊
   - **禁言时长**: 处理时设置的禁言秒数
4. 点击"保存设置"

### 13.2 防刷屏工作原理

当用户在时间窗口内发送相同内容超过设定次数时，系统会自动执行预设的处理动作。

**示例**:
- 时间窗口: 10 秒
- 最大次数: 5 次
- 处理动作: mute

用户在 10 秒内发送了 5 次相同消息，第 5 次会被自动禁言。

---

## 14. 群组设置

### 14.1 基本设置

在群组详情页可以配置：

| 设置项 | 说明 |
|--------|------|
| **群组名称** | 群组的显示名称 |
| **状态** | online = 正常管理，offline = 暂停管理 |
| **成员数** | 手动更新成员数量 |

### 14.2 高级设置

| 设置项 | 说明 |
|--------|------|
| **全员禁言** | 一键开启/关闭全体成员禁言 |
| **退群自动拉黑** | 成员主动退群时自动加入黑名单 |

---

## 15. 操作日志

### 15.1 查看日志

在侧边栏点击"操作日志"可以查看所有管理操作记录。

每条日志显示：
- 时间
- 操作类型（如：add_blacklist、mute、update_group）
- 执行管理员
- 操作详情

### 15.2 日志筛选

支持按以下条件筛选：
- **操作类型**: 如规则操作、群组操作、黑名单操作等
- **群组**: 只看某个群组的操作
- **时间范围**: 今天、近7天、自定义范围

### 15.3 AI 对话日志

点击"AI 日志"可以查看 AI 对话历史，用于：
- 了解 AI 回复情况
- 排查 AI 回复异常
- 清理过期日志（仅超级管理员可清理）

---

## 16. 常见问题

### Q1: 机器人没有响应消息

**检查步骤**:
1. 确认 NapCat 连接状态（仪表盘显示）
2. 确认群组状态为"online"
3. 检查是否开启了全员禁言
4. 检查用户是否在黑名单/白名单中

### Q2: AI 对话没有回复

**检查步骤**:
1. 确认已在群组中配置 AI 模型设置
2. 确认 API Key 正确且有效
3. 检查"触发词"是否正确配置（如 @mention）
4. 查看 AI 日志排查错误

### Q3: 签到没有反应

**检查步骤**:
1. 确认群组开启了签到功能
2. 检查用户是否已经签到过（每日只能签到一次）
3. 查看签到设置中每日积分是否 > 0

### Q4: 购买商品失败

**可能原因**:
1. 用户积分不足
2. 商品库存 CDKey 已用完
3. 商品已下架

### Q5: 定时任务没有执行

**检查步骤**:
1. 确认任务状态为"启用"
2. 检查 next_run_at 时间是否设置正确
3. 查看服务器日志排查错误

### Q6: 如何让机器人只响应 @mention

**操作步骤**:
1. 进入群组的"触发词"设置
2. 删除或禁用其他的触发类型（如 keyword、prefix）
3. 只保留 @mention 触发类型

### Q7: 如何禁止用户发送链接

**操作步骤**:
1. 创建规则：触发类型 = keyword，触发内容 = `http`
2. 设置处理动作：如 mute，参数 = 600（禁言 10 分钟）
3. 确保规则状态为"启用"

### Q8: 如何查看某个用户的历史记录

**操作步骤**:
1. 进入群组详情
2. 点击"成员管理"
3. 搜索用户 QQ 号或昵称
4. 查看该用户的操作历史（在成员详情中）

---

## 附录 A：群内可用命令一览

| 命令 | 功能 | 示例 |
|------|------|------|
| `/sign` | 签到获取积分 | `/sign` |
| `签到` | 同上 | `签到` |
| `我的积分` | 查看当前积分 | `我的积分` |
| `我的排名` | 查看积分排名 | `我的排名` |
| `排行榜` | 查看积分榜前10 | `排行榜` |
| `商品列表` | 查看积分商城 | `商品列表` |
| `商城` | 同上 | `商城` |
| `购买 [商品名]` | 用积分购买商品 | `购买 游戏CDK` |
| `@AI [内容]` | 触发 AI 对话 | `@AI 帮我解答问题` |
| `[关键词]` | 触发关键词回复 | `帮助` |

---

## 附录 B：API 接口说明（开发者参考）

### 认证

所有管理 API 需要在请求头中携带 JWT Token：

```
Authorization: Bearer <your-jwt-token>
```

### 常用 API 端点

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/auth/login` | 登录 |
| GET | `/api/groups` | 获取群组列表 |
| POST | `/api/groups` | 添加群组 |
| POST | `/api/groups/sync` | 同步群组 |
| GET | `/api/groups/:id/members` | 获取群成员 |
| GET | `/api/rules` | 获取规则列表 |
| POST | `/api/blacklists` | 添加黑名单 |
| GET | `/api/groups/:id/products` | 获取商品列表 |
| POST | `/api/groups/:id/purchase` | 购买商品 |

> 详细 API 文档请参考后端源代码 `backend/src/index.js`。

---

> 如有更多问题或建议，请提交 Issue 或联系开发者。