# Attention Please - DC 簽到提醒機器人

專案開發：Elantris
近期更新：2024-02-15
客服群組：https://discord.gg/Ctwz4BB
說明文件：https://hackmd.io/@eelayntris/attention-please
捐款贊助：[歐付寶贊助連結](https://p.opay.tw/HJBjG)、[歐付寶贊助留言](https://payment.opay.tw/Broadcaster/Donate/1BEFCDA40776A351240A352244F8A10D)
邀請連結：

- [管理員權限](https://discord.com/api/oauth2/authorize?client_id=801820692500054087&permissions=8&scope=bot)：如果你不知道該怎麼設定權限又很信任開發者的話請點這個連結
- [基本權限](https://discord.com/api/oauth2/authorize?client_id=801820692500054087&permissions=274878024704&scope=bot)：使用這隻機器人指令所需要的基本權限
- [空白權限](https://discord.com/api/oauth2/authorize?client_id=801820692500054087&permissions=0&scope=bot)：這個連結不會建立預設身份組，需自行設定機器人權限
- 檢視頻道
- 傳送訊息和建立貼文
- 在討論串和貼文中發送訊息
- 嵌入連結
- 附加檔案
- 讀取歷史訊息

> 讓我們來看看到底是誰都不看公告！ [name=Attention Please#4637][color=#ff922b]

###### tags: `discord` `admin` `attention-please`

[TOC]

---

## 功能特色
透過文字訊息中的標記成員與表情回應來實作 Discord 已讀與抽獎功能，被標記的成員會收到通知、看完訊息後順手按個表情符號代表已讀訊息或參加抽獎，只要輸入指令即可快速檢查哪些成員沒有閱讀公告、參加抽獎的成員是否中獎，適合人數眾多的伺服器檢查大家有沒有認真看公告。

## 指令說明
- 支援斜線指令
- 以下指令語法中後面有冒號的單字是「參數」
- 可以複製指令語法後貼到 DC 訊息輸入框，再選擇對應的機器人指令
- 記得開啟 Discord 設定查看指令提示
- 「文字 & 圖片」
- 「在打字時預覽表情符號、提及以及 markdown 語法」

### 統計結算 /check
統計一則訊息中被標記成員的回應狀況。在發送文字訊息時內容中被標記的成員會收到通知，對該訊息新增回應或點選任何已存在的表情回應代表已讀。

:::warning
這個指令是用來檢查「已經存在」的訊息是否被已讀，不是幫你發送公告訊息，target 參數請輸入「訊息連結」而非公告內容、頻道連結、群組連結。
:::

**指令語法：**

1. `/check target:`
- `target`：目標訊息的連結或 ID
2. `/check target: time: repeat:`
- `target`：目標訊息的連結或 ID
- `time`：預約結算時間（格式：`YYYY-MM-DD HH:mm`）
- `repeat`：重複結算的週期
- 一天（24 小時）
- 一週（7 天）
- 一月（下個月的同一日期）
- 一季（三個月後的同一日期）

**使用範例：**

1. 查看一則訊息有沒有人按表情：
2. 在 2023-12-31 的最後一刻建立預約結算：
3. 自 2023-05-01 起，每個月初結算一次：

**備註說明：**

- 目標訊息內必須含有標記成員，至少要有一人被標記、收到通知：
- @everyone
- @身份組
- @成員
- 指定目標訊息支援三種格式：
1. **訊息連結**（Android 手機部分版本沒有複製訊息連結的按鈕，請改用網頁版或其他裝置）
`https://discord.com/channels/GUILD_ID/CHANNEL_ID/MESSAGE_ID`
2. **頻道 ID-訊息 ID**（電腦版開啟開發者模式後對著訊息按住 shift，選擇 ID 圖示）
`CHANNEL_ID-MESSAGE_ID`
3. **訊息 ID**（開啟開發者模式後在訊息的右鍵選單裡）
`MESSAGE_ID`
:warning: 當使用這個訊息格式時機器人會逐一檢視伺服器內每個文字頻道，根據頻道數量大約會需要等待 5 ~ 15 秒，如果伺服器的文字頻道數量太多時不能使用訊息 ID 來指定目標
- 推薦的指定時間格式為 `YYYY-MM-DD HH:mm`
- 西元年 `2024`
- 月份 `01` ~ `12`
- 天數 `01` ~ `31`
- 時間為 24 小時制 `00:00` ~ `23:59`
- 參數內前五個數字會被自動代入年、月、日、時、分
- 重複週期：
- 僅對預約結算有效，指令中必須同時有 `time`、`repeat` 參數
- 重複預約結算會在統計完結果後試圖清除目標訊息底下的所有表情回應，並且根據重複週期建立下一次的重複預約結算
- 連續多次沒有人簽到（點選任何表情）時會自動移除之後的重複預約
- 名單分類：
- **簽到名單**：有對目標訊息點選任一表情回應的成員
- **缺席名單**：沒有對目標訊息點選任何表情回應的成員
- **無權名單**：對目標訊息所在頻道沒有「檢視頻道」或「檢視歷史訊息」權限的成員
- **無關名單**：有按表情回應但沒有被標記的成員
- **退群名單**：有按表情回應但已經退出伺服器的成員
- 當標記的成員數量過多時會輸出成檔案，並且同時顯示所有名單
- 對著訊息點選右鍵 >「應用程式」>「check」即可使用快速結算，結算結果會發送在與目標訊息相同的文字頻道

### 登記抽獎 /raffle
從指定的目標訊息中設定抽獎規則：

1. 被標記的成員具有「抽獎資格」
2. 被標記的成員只要點選訊息下方任一表情回應即可「參加抽獎」

**指令語法：**

1. `/raffle target: count:`
- `target`：目標訊息的連結或 ID
- `count`：中獎人數
2. `/raffle target: count: time:`
- `target`：目標訊息的連結或 ID
- `count`：中獎人數
- `time`：預約抽獎時間

**使用範例：**

1. 從訊息中抽出 10 位中獎成員：
2. 在 2023-05-01 整點時從訊息中抽出 10 位中獎成員：

**備註說明：**

- 中獎人數必須至少 1 人
- 預約抽獎的時間必須設定在未來
- 不論標記的成員數量多少都會輸出一份文字檔案
- 名單分類：
- 中獎順序：依序從參加者中隨機抽出中獎人
- 備取順序：將未中獎的參加者隨機排序
- 缺席名單：沒有對訊息點選任何表情回應的成員
- 無權名單：對目標訊息所在頻道沒有「檢視頻道」或「檢視歷史訊息」權限的成員
- 無關名單：有按表情回應但沒有被標記的成員
- 退群名單：有按表情回應但已經退出伺服器的成員

### 取消預約 /cancel
取消建立過的預約。

**指令語法：**

1. `/cancel id:`
- `id`：預約的 ID

**使用範例：**

1. 取消目標訊息的預約結算：
2. 取消目標訊息的預約抽獎：

**備註說明：**

- 使用 `/check` 指令建立的預約結算會有一個特殊的 ID，格式為 `check_訊息ID`
- 預約抽獎的格式為 `raffle_訊息ID`

### 偏好設定 /config
機器人偏好設定。

**指令語法：**

1. `/config list type: action:`
切換統計結算時名單顯示或隱藏，預設為全顯示
- `type`：名單類型
- `reacted` 簽到名單
- `absent` 缺席名單
- `locked` 無權名單
- `irrelevant` 無關名單
- `leaved` 退群名單
- `action`：切換為
- `show` 顯示
- `hidden` 不顯示
2. `/config offset offset:`
設定時間偏移量
- `offset`：相對於 UTC+00:00 的時差
- 介於 `-12 ~ 12` 之間的數字
- 預設為 `8`（台北時區 UTC+08:00）
3. `/config length length:`
設定名單長度，使用 check 指令時嵌入內容中允許的成員數量
- `length`：嵌入內容中的結算結果名單最大人數
- 介於 0 ~ 300 之間的數字
- 預設為 100

**使用範例：**

1. 隱藏簽到名單：
> `/config list type:reacted action:hidden`

2. 顯示缺席名單：
> `/config list type:absent action:show`

3. 將時區設定為日本時區（UTC+09:00）：
> `/config offset offset:9`

**備註說明：**

- 時間偏移
- 使用指令時的顯示時間、建立預約結算或預約抽獎時會根據設定的時間偏移量調整為使用者所在的時區
- 時差單位為小時，輸入小數時會四捨五入至最近的時刻（15 分鐘），例如：UTC+08:45 則輸入「8.75」
- 名單長度
- 結算結果會以兩種方式呈現：
- **嵌入內容**：直接掛載在訊息下方，顯示所有被標記的成員，適合標記人數較少的場合
- **文字檔案**：提供一份 txt 純文字檔案，完整呈現所有被標記的成員與成員名稱，適合標記人數較多或成員名稱普遍較長的場合
- 名單長度預設為 100
- 標記人數在 100 人以內時，會將結算結果放進「嵌入內容」
- 標記人數超過 100 人時，會將結算結果輸出成「文字檔案」
- 如果希望無論如何都輸出成文字檔案時可以將名單長度設定為 0