Merge branch 'main' of https://github.com/SCAICT/doc

SCAICT · Aug 26, 2024 · 40cf37b · 40cf37b
2 parents 5b3042f + 96f8730
commit 40cf37b
Show file tree

Hide file tree

Showing 35 changed files with 320 additions and 257 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
-# 中電會 第三屆專案開發文檔
+# 中電會 第3屆專案開發說明文件
 
-> start at 7/26/2024 
+> start at 7/26/2024
 
-為了不要被第四屆罵說第三屆學長伺服器設後不理，撰寫了這份文檔。
+為了不要被第4屆罵說第3屆學長伺服器設後不理，撰寫了這份說明文件。
 
 
 ## 本地開發

diff --git a/blog/authors.yml b/blog/authors.yml
@@ -1,11 +1,11 @@
 elvismao:
   name: 毛哥EM
-  title: 第三屆資訊組組長
+  title: 第3屆資訊組組長
   url: https://github.com/Edit-Mr
   image_url: https://github.com/Edit-Mr.png
 
 yangshun:
   name: Each Chen
-  title: 第三屆資訊組組
+  title: 第3屆資訊組組員
   url: https://github.com/iach526526
   image_url: https://github.com/iach526526.png
diff --git a/docs/SCAICT-uwu/command/_category_.json b/docs/SCAICT-uwu/command/_category_.json
@@ -1,9 +1,8 @@
 {
-    "label": "指令表",
-    "position": 7,
-    "link": {
-      "type": "generated-index",
-      "description": " ⬆️ ⬆️ ⬇️ ⬇️ ⬅️ ➡️ ⬅️ ➡️ 🅱️ 🅰️在這裡，參數如果是必填會用 { } 包起來，選填用[ ]。| 分隔多個可選參數"
-    }
+  "label": "指令表",
+  "position": 7,
+  "link": {
+    "type": "generated-index",
+    "description": " ⬆️ ⬆️ ⬇️ ⬇️ ⬅️ ➡️ ⬅️ ➡️ 🅱️ 🅰️在這裡，參數如果是必填會用 { } 包起來，選填用[ ]。| 分隔多個可選參數"
   }
-  
+}
diff --git a/docs/SCAICT-uwu/command/class.md b/docs/SCAICT-uwu/command/class.md
@@ -3,24 +3,30 @@ sidebar_position: 4
 authors: [iach526526]
 slug: class
 title: 身分組
-description: 本條目包括創建、發送、領取特殊身分組
+description: 本頁面包括新增、發送、領取特殊身分組
 ---
+
 中電喵支援輸入兌換代碼獲得一些不公開的身分組，這項功能提供主題課程、~~工人交接~~、~~特殊身分組購買~~使用。到 #🎁兌換區 輸入擁有的兌換代碼就會生效兌換成獎勵
 
 ![alt text](../../../static/img/exchange.png)
 
 > 註：不公開身分組指的是你無法在頻道與身分組列表透過點選主動獲得的身分組
 
-# 創建
+## 新增身分組
+
 - 限制使用權限:true
   - admin only
+
 > ```add_class {class_code} {name} {theme}{teacher}{time}```
+
 - class_code：兌換代碼
 - name：代碼對應分送的身分組名稱
 - theme：課程主題，用於領取時顯示領了什麼課的身分組
 - time：課程時間，用於領取顯示課程時間
 
-這些參數會在資料庫 (JSON) 寫入一筆資料，提供日後的輸入做比對
-<!-- 我覺得它應該被改成 SQL 或 SOL lite配合日後的其他禮物領取 -->
+這些參數會在資料庫（JSON）寫入一筆資料，提供日後的輸入做比對
+<!-- 我覺得它應該被改成 SQL 或 SQLite配合日後的其他禮物領取 -->
+
 ## 領取身分組
+
 到 #🎁兌換區 點擊按鈕即可輸入
diff --git a/docs/SCAICT-uwu/command/ctf.md b/docs/SCAICT-uwu/command/ctf.md
@@ -5,11 +5,13 @@ slug: ctf
 title: CTF 指令
 description: 找出 flag ，獲得豐厚獎勵
 ---
-## 創建一道題目
+## 新增一道題目
+
 - 限制使用權限：true
   - 允許使用的身分組：ctf 出題者
 
 > ```/create create {title:str} {flag:str} {score:int} [limit:int] [case:bool] [start:YY-MM-DD HH:MM:SS] [end:YY-MM-DD HH:MM:SS]```
+
 - title：題目標題
 - flag ：該題解答，格式建議為 ```SCAICT{falg_string}```
 - score：解題後能獲得的電電點數量，現在只能選擇贈送電電點，暫時沒有以抽獎劵作為獎勵的功能
@@ -19,12 +21,15 @@ description: 找出 flag ，獲得豐厚獎勵
 - end：結束時間，預設永不結束
 
 ## 刪除一道題目
+
 - 限制使用權限：true
   - 允許使用的身分組：ctf 出題者
+
 >```/ctf delete {qid} {channel_id} {key}```
-- qid：每道 ctf 的唯一 ID ，會顯示在該題目的下方
-- channel_id：該題目的題目敘述和按鈕存在的頻道，如果題目在討論串發布，需要在討論串列表右鍵點選「複製討論串 ID」
-- key ：欲刪除題目的 flag，這是防呆保護，出題者應該知道自己的 flag
+
+- qid：每道 CTF 的唯一 ID ，會顯示在該題目的下方
+- channel_id：該題目的題目說明和按鈕存在的頻道，如果題目在討論串發布，需要在討論串列表右鍵點選「複製討論串 ID」
+- key：欲刪除題目的 flag，這是防呆保護，出題者應該知道自己的 flag
 
 下圖是拿到刪除 CTF 需要的參數範例。如果在頻道上按了右鍵沒有複製 ID 的選項，你需要到設定開啟開發者模式
-![ctfID](../../../static/img/ctfID.png)
+![ctfID](../../../static/img/ctfID.png)
diff --git a/docs/SCAICT-uwu/command/point.md b/docs/SCAICT-uwu/command/point.md
@@ -5,14 +5,17 @@ slug: point
 title: 電電點操作指令
 description: 獲得、查詢自己的電電點
 ---
+
 ## 你有有多少電電點
+
 > ```/check_point```
-- 限制使用權限：false
 
+- 限制使用權限：false
 
 無須攜帶任何參數，會檢索指令發起人當前的連續登入、電電點數量狀態
 
 ## 每日充電
+
 > ```/charge```
 
 - 限制使用權限：false

diff --git a/docs/SCAICT-uwu/command/send-gift.md b/docs/SCAICT-uwu/command/send-gift.md
@@ -5,13 +5,16 @@ slug: gift
 title: 發送禮物給某人
 description: 贈送禮物
 ---
+
 # /dm_gift
+
 > ```dm_gift {target_str...} {電電點 | 抽獎券} {贈送物品數量}```
 
 - 限制使用權限：true
   - admin only
 
 ## 描述
+
 這個指令可以選擇多個使用者統一發送相同數量的電電點或抽獎券，第一個參數 ```target_str``` 要填入 Discord 使用者名稱，**不是**顯示名稱。下圖框選起來的部分才是使用者名稱
 
-![DCid](../../../static/img/DCid.png)
+![DCid](../../../static/img/DCid.png)
diff --git a/docs/SCAICT-uwu/dev/_category_.json b/docs/SCAICT-uwu/dev/_category_.json
@@ -1,9 +1,8 @@
 {
-    "label": "開發者專區",
-    "position": 6,
-    "link": {
-      "type": "generated-index",
-      "description": "又臭又長的東西"
-    }
+  "label": "開發者專區",
+  "position": 6,
+  "link": {
+    "type": "generated-index",
+    "description": "又臭又長的東西"
   }
-  
+}
diff --git a/docs/SCAICT-uwu/dev/about-project.md b/docs/SCAICT-uwu/dev/about-project.md
@@ -9,11 +9,13 @@ description: 介紹一下
 # 關於這個專案
 
 恭喜你成為中電喵飼養員，為了成為稱職的飼養員，你需要有以下先備知識：
-- python 程式設計
+
+- Python 程式設計
 - SQL 資料庫維護
 - 億點點 Linux 操作技巧
 
-以下是中電喵專案的檔案樹，為了篇幅省略了一些小檔案或不重要的資料夾（如 .git ），這裡定義重資料夾之間的相對關係。
+以下是中電喵專案的檔案樹，為了篇幅省略了一些小檔案或不重要的資料夾（如 .git ），這裡著重定義資料夾之間的相對關係。
+
 ```
 |   app.py
 |   main.py
@@ -68,32 +70,35 @@ description: 介紹一下
 |       
 \---test
 ```
-## 中電喵，啟動！
 
+## 中電喵，啟動！
 
 ### \.github
+
 在 GitHub repository 的自動化執行腳本。目前有的自動化腳本：
-- pylint
-    - Python 程式碼風格檢查程式，變數名稱亂寫可是不能成功 PR 的喔！
-- notion API
-  - 連接中電會工人 notion 代辦事項和 Discord hook ，用來顯示中電喵 repo 的 issue
 
+- Notion API
+  - 連接中電會工人 Notion 代辦事項和 Discord hook ，用來顯示中電喵 repo 的 issue
+- Pylint
+  - Python 程式碼風格檢查程式，變數名稱亂寫可是不能成功 PR 的喔！
 
 ### 中電喵本體
+
 中電喵聊天程式從 main.py 開始，會先從 cog/ 讀取相依 .py檔案，cog/*.py 定義了斜線指令要執行的行為，若指令有一些非常通用或冗長的函式:例如資料庫接等其他特殊行為。獨立出來的 python 檔案會放在 cog/core 提供引用
 
 ### 中電商店
-中電商店的主程式是 app.py，網頁框架使用 flask。引入 \templates、\static 靜態資源渲染，使用 \cog\core 裡面的程式和資料庫溝通。
 
+中電商店的主程式是 app.py，網頁框架使用 flask。引入 \templates、\static 靜態資源渲染，使用 \cog\core 裡面的程式和資料庫溝通。
 
 ### DataBase
+
 在中電喵的幼貓時期，其實是把所有成員的電電點、CTF題目等動態資料用 JSON 儲存在/DataBase，現在這裡只有幾個檔案需要留意：
+
 - class.json
-  - 中電喵有個指令是管理者創建課程，使用者可以在兌換區輸入課程行前信的課程代碼領取課程身分組存取課程用頻到，這個檔案儲存了可兌換的課程資料
+  - 中電喵有個指令是管理者新增課程，使用者可以在兌換區輸入課程行前信的課程代碼領取課程身分組並存取課程用頻道，這個檔案儲存了可兌換的課程資料
 - server.config.json
-  - 存放中電會 Discord 伺服器內的特殊頻道、表情符號 ID。程式運行中會
+  - 存放中電會 Discord 伺服器內的特殊頻道、表情符號 ID。程式運行中會<!-- 會怎樣？ -->
 - server.config-alph.json
   - server.config 的複製檔案，但是所有頻道和表情 ID 都是來自另一個和中電會 Discord 社群相同的伺服器，開發人員可以使用自己的 bot 在 alph 伺服器測試開發中的功能
 - slot.json
   - 中電商店抽獎券
-
diff --git a/docs/SCAICT-uwu/dev/code/_category_.json b/docs/SCAICT-uwu/dev/code/_category_.json
@@ -5,4 +5,4 @@
         "type": "generated-index",
         "description": "不要看到程式碼就關掉啦"
     }
-}
+}
diff --git a/docs/SCAICT-uwu/dev/code/admin.md b/docs/SCAICT-uwu/dev/code/admin.md
@@ -5,8 +5,10 @@ slug: admin-code
 title: admin_role
 description: 管理者指令
 ---
+
 # admin_role
-admin_role 裡面的指令使用都和伺服器管理有關，大部分都是擁有伺服器最高管理權限的帳號才可以使用的指令。使用前應該先檢查發起命令的用戶：
+
+admin_role 裡面的指令使用都和伺服器管理有關，大部分都是擁有伺服器最高管理權限的帳號才可以使用的指令。使用前應該先檢查發起命令的使用者：
 ```ctx.author.guild_permissions.administrator```
 若得到 false 應該直接拒絕執行。
 
@@ -15,6 +17,7 @@ admin_role 裡面的指令使用都和伺服器管理有關，大部分都是擁
 使用 ```discord.utils.find``` 搜尋使用者名並發起私訊傳送獎勵按鈕，因為遍歷需要花一點時間，所以呼叫 ```await ctx.defer()``` 先在 Discord 顯示中電喵正在思考，避免回應超時被 Discord kill 掉。
 
 Discord 會在按鈕傳送時給每個按鈕一個唯一 ID，btnID （即是訊息 ID），中電喵會把 btnID、獎品類型、贈送數量、收件者存入 gift 表格。
+
 ```bash
 DB> describe gift;
 +-----------+-------------------------------+------+-----+---------+-------+

diff --git a/docs/SCAICT-uwu/dev/code/overView.md b/docs/SCAICT-uwu/dev/code/overView.md
@@ -5,25 +5,30 @@ slug: about
 title: Link Start!
 description: 介紹一下
 ---
+
 # 程式碼專區
+
 > 屎山何其多
 
 ## 簡介
+
 每頁會解釋中電喵 cog 裡面的 Python 檔案，相關的功能會放在同一個檔案，日後有新功能務必用檔名聯想這是幹什麼用的。cog 裡面的程式基本上都是核心的聊天指令，太胖或是太通用的 function 可以放到 cog/core 裡面方便引入。
 
 - 舉例：
 
 cog/core SQL.py 檔有一個 function write 需要呼叫，應該寫成：
+
 ```py
-from cog.core.SQL import write
+from cog.core.sql import write
 ```
 
 注意盡量不要單獨 import 整個檔案
 
 - 錯誤示範
 
 ```py
-import cog.core.SQL as SQL
+import cog.core.sql as SQL
+
 # call function
 SQL.write(argv...)
 ```
@@ -37,29 +42,23 @@ SQL.write(argv...)
 +-------------------+
 | Tables_in_Discord |
 +-------------------+
-| CommentPoints     |
-| USER              |
+| comment_points    |
+| user              |
 | ctf_data          |
 | ctf_history       |
 | game              |
 | gift              |
 +-------------------+
 ```
 
-### CommentPoints
-
-
-### USER
+### comment_points
 
+### user
 
 ### ctf_data
 
-
 ### ctf_history
 
-
 ### game
 
-
 ### gift
-
diff --git a/docs/SCAICT-uwu/dev/maintain.md b/docs/SCAICT-uwu/dev/maintain.md
@@ -12,25 +12,32 @@ description: 這 很 重 要！
 
 ## 如何在伺服器上長時間運作？
 
-若在伺服器上的專案資料夾執行 "python main.py" 這個指令只會在 ssh 連線階段執行這個工作，這適合短時間的測試，斷開終端機後服務就會關閉。所以要在啟動指令前加上 ***nohop*** 讓工作可以在背景持續執行。此時程式所有的 print 或 error 回報預設會在該專案目錄下面的 nohup.out ，想要更改儲存位置和檔名可以使用管道符號。
+若在伺服器上的專案資料夾執行 "python main.py" 這個指令只會在 ssh 連線階段執行這個工作，這適合短時間的測試，斷開終端機後服務就會關閉。所以要在啟動指令前加上 ***nohop*** 讓工作可以在背景持續執行。此時程式所有的 print 或 error 回報預設會在該專案目錄下面的 nohup.out ，想要變更儲存位置和檔名可以使用管道符號。
 
+利用管道符號把程式輸出存在 `/var/log/DiscordBot/` ，並用時間命名
 
-利用管道符號把程式輸出存在 /var/log/DiscordBot/ ，並用時間命名
 ### 執行中電喵本體
+
 ```bash
 nohup python3 main.py &>/var/log/DiscordBot/Log_$(date +%Y-%m-%dT%H-%M-%S).log&
 ```
+
 ### 中電商店
+
 ```bash
 nohup flask run &>/var/log/uwuStore/Log_$(date +%Y-%m-%dT%H-%M-%S).log&
 ```
+
 執行後 CLI 會顯示 Process ID，下面的例子是開啟了一個 Process ID 為 48763 的工作。這個 ID 是唯一的，用來辨別這個運行的工作。每次開啟服務後建議寫在記事本，下次關服務會比較好找到這個服務。
+
 ```
 [2] 48763
 ```
+
 ## 關閉長時間運作的服務
 
-關閉用  htop 運行中的服務，可以使用：
+關閉用 htop 運行中的服務，可以使用：
+
 - ```kill <Process ID>```
 - ```htop```找到要關閉的 Process 按下 F9
 
@@ -41,7 +48,9 @@ nohup flask run &>/var/log/uwuStore/Log_$(date +%Y-%m-%dT%H-%M-%S).log&
 > Tips：在 htop 內可以使用 F6 排序幫助尋找目標 Process ；選取到目標服務後按下 F9 可以 kill 掉它
 
 ## 備份資料庫
+
 ### mysqldump 指令
+
 定期備份資料庫是一件很重要的事，使用 mysqldump 指令把某個 database 的表格樣式和儲存的資料都儲存到一個 .spl 檔。裡面會存構成目前資料庫需要的指令。
 
 ```bash
@@ -52,10 +61,11 @@ mysql -u [username] -p [database] < backup.sql     #把 .sql 執行把資料庫
 ```
 
 ### 定期備份資料庫
+
 crontab
 
-## 文檔撰寫
+## 撰寫說明文件
 
-當開發完一個新的指令或更新功能，得在文檔紀錄新的變動，建議先撰寫使用者向的使用說明，再寫技術文檔。組織語言讓不會使用的人學會之後，對功能的細節也會更清楚，過程中也會想到開發時沒有想到的例外狀況或更多應用情境。
+當開發完一個新的指令或更新功能，得在說明文件記錄新的變動，建議先撰寫使用者向的使用說明，再寫技術說明文件。組織語言讓不會使用的人學會之後，對功能的細節也會更清楚，過程中也會想到開發時沒有想到的例外狀況或更多應用情境。
 
-親測有效，整理發送課程身分組的時候就想到其實可以把一直想不到方法實踐的購買特殊身分組用在兌換區。
+親測有效，整理發送課程身分組的時候就想到其實可以把一直想不到方法實踐的購買特殊身分組用在兌換區。