問題追蹤系統使用手冊

系統簡介

本問題追蹤系統基於 Gogs 建立，提供完整的問題管理、追蹤和協作功能。系統支援：

問題報告：結構化的問題報告模板
標籤分類：自動分組的標籤系統（優先級、類型、狀態）
任務分配：指派負責人和里程碑
協作討論：評論和附件上傳
狀態追蹤：問題狀態的開關管理

創建問題

步驟 1：進入問題創建頁面

登入系統後，進入專案頁面
點擊上方導航的「問題管理」標籤
點擊右上角的「創建問題」按鈕

步驟 2：填寫問題資訊

系統會自動載入預設的問題報告模板，請依序填寫以下欄位：

📋 標題（必填）

在「標題」欄位中，簡潔明確地描述問題的核心內容，例如：

登入頁面無法載入
匯出功能產生的檔案格式錯誤
新增使用者權限驗證失敗

📝 問題描述

在內容編輯區域的「### 問題描述」區塊中，詳細說明問題的具體情況：

問題發生的場景
影響範圍
用戶體驗

🔄 重現步驟

在「### 重現步驟」區塊中，按照順序列出重現問題的步驟：

1. 進入系統首頁
2. 點擊「設定」選單
3. 選擇「使用者管理」
4. 點擊「新增使用者」按鈕
5. 預期應開啟新增表單，但實際無反應

✅ 預期結果

在「### 預期結果」區塊中，描述正常情況下應該發生的結果

❌ 實際結果

在「### 實際結果」區塊中，描述實際發生的情況（問題表現）

🔧 環境資訊

在「### 環境資訊」區塊中，提供以下資訊：

測試系統：使用的測試環境名稱
作業系統：Windows 10 / macOS / Linux 等
瀏覽器/裝置：Chrome 118+ / Firefox / Safari / 手機型號等
應用程式版本：系統版本號
發生時間：問題發生的日期時間

💬 錯誤訊息

在「### 錯誤訊息」區塊中，如有錯誤訊息，請貼上完整內容：

錯誤代碼：ERR_001
錯誤訊息：無法連線至資料庫
堆疊追蹤：...

📌 其他資訊

在「### 其他資訊」區塊中，填寫：

是否為首次發生：是 / 否
發生頻率：每次 / 經常 / 偶爾
相關 Issue：可參考其他相關問題的編號（如：#123）

步驟 3：設定標籤

在右側邊欄的「標籤」區域，點擊齒輪圖示可以開啟標籤選擇選單。標籤會自動分組顯示：

優先級標籤（選一個）

🔴 嚴重：系統完全無法使用、數據丟失、安全漏洞
🟠 高：核心功能無法使用，影響大量用戶
🟡 中：功能部分失效或體驗不佳
🟢 低：輕微問題、優化建議
⚪ 不修正：已知但不計劃修正的問題

類型標籤（選一個）

🔵 問題：一般性問題
🟡 Bug：系統錯誤或缺陷
🔷 功能請求：新功能需求
🔵 任務：一般工作任務
🟣 文檔：文檔相關工作

狀態標籤（選一個）

⚪ 待處理：問題已建立，等待處理
🟡 進行中：正在處理中
🟢 待測試：已完成，等待測試
🔴 已阻擋：因某些原因無法繼續

步驟 4：設定負責人與里程碑（可選）

在右側邊欄可以設定：

里程碑（Milestone）：點擊「里程碑」區域的齒輪圖示，選擇將問題歸類到特定的里程碑（如：v1.0、Q1 Release 等）
指派成員（Assignee）：點擊「指派成員」區域的齒輪圖示，指派處理此問題的人員

步驟 5：上傳附件（可選）

在內容編輯區域下方，有檔案上傳區域（顯示「拖曳文件到此處或單擊上傳」）。

系統支援上傳多種檔案類型：

圖片檔（截圖、錯誤畫面）
文件檔（PDF、Word、Excel 等）
影片檔（錄影重現問題）
其他檔案

上傳方式：

直接拖放檔案到上傳區域
或點擊上傳區域選擇檔案
可以同時上傳多個檔案

步驟 6：提交問題

確認所有資訊填寫完整後，點擊頁面底部的綠色「創建問題」按鈕提交問題。

提示：在提交前，可以切換到「效果預覽」標籤查看問題內容的預覽效果。

問題標籤系統

標籤分類說明

系統的標籤會自動分組顯示，方便查找和管理：

優先級（Priority）

用於標示問題的緊急程度和重要性：

標籤	顏色	說明	處理時限建議
嚴重	🔴 紅色	系統完全無法使用、數據丟失、安全漏洞	4小時內處理
高	🟠 橙色	核心功能無法使用，影響大量用戶	24小時內處理
中	🟡 黃色	功能部分失效或體驗不佳	3-5個工作日
低	🟢 綠色	輕微問題、優化建議	下個版本
不修正	⚪ 灰色	已知但不計劃修正	-

類型（Type）

用於分類問題的性質：

標籤	顏色	說明
問題	🔵 藍色	一般性問題或疑問
Bug	🟡 黃色	系統錯誤或缺陷
功能請求	🔷 淺藍色	新功能需求或改進建議
任務	🔵 深藍色	一般工作任務
文檔	🟣 紫色	文檔撰寫或更新工作

狀態（Status）

用於追蹤問題的處理進度：

標籤	顏色	說明
待處理	⚪ 灰色	問題已建立，等待處理
進行中	🟡 黃色	正在處理中
待測試	🟢 綠色	已完成，等待測試驗證
已阻擋	🔴 紅色	因某些原因無法繼續（需說明原因）

標籤使用原則

優先級標籤：每個問題應選擇一個優先級
類型標籤：每個問題應選擇一個類型
狀態標籤：隨著處理進度更新狀態
標籤更新：有權限的用戶可以隨時更新標籤

問題管理

查看問題列表

進入專案頁面，點擊上方導航的「問題管理」標籤
在「問題管理」標籤下，可以選擇：
- 標籤：查看和管理標籤
- 里程碑：查看和管理里程碑
問題列表頁面會顯示：
- 開啟中：顯示開啟的問題數量（綠色圓圈圖示）
- 已關閉：顯示已關閉的問題數量（灰色時鐘圖示）
使用右上方的篩選功能：
- 標籤篩選：按標籤篩選問題
- 里程碑篩選：按里程碑篩選問題
- 指派人篩選：按負責人篩選問題
- 類型篩選：按類型篩選問題
- 排序：選擇排序方式

查看問題詳情

點擊問題標題或編號，進入問題詳情頁面，可以：

查看完整的問題描述和討論
查看所有附件
查看問題歷史記錄

編輯問題

在問題詳情頁面右上角，問題創建者或管理員可以：

點擊「編輯」按鈕編輯問題標題和內容
在右側邊欄修改標籤、里程碑和指派成員

關閉/重新開啟問題

在問題詳情頁面，問題創建者或管理員可以：

在問題狀態區域（顯示「開啟中」）點擊狀態按鈕
或在下方的評論區域，點擊「關閉問題」按鈕關閉已解決的問題
點擊「重新開啟問題」按鈕重新開啟已關閉的問題
關閉問題時可以同時添加評論說明原因

指派負責人

在問題詳情頁面右側邊欄，找到「指派成員」區塊
點擊齒輪圖示
選擇負責人
系統會自動通知被指派的負責人

設定里程碑

在問題詳情頁面右側邊欄，找到「里程碑」區塊
點擊齒輪圖示
選擇里程碑
問題會被歸類到該里程碑

評論與討論

添加評論

在問題詳情頁面底部，找到評論輸入框
切換到「內容編輯」標籤輸入評論內容（支援 Markdown 格式）
可以切換到「效果預覽」標籤預覽評論效果
可以上傳附件（拖曳文件到上傳區域或單擊上傳）
點擊綠色的「評論」按鈕提交，或點擊紅色的「關閉」按鈕取消

評論功能

Markdown 支援：支援標題、列表、程式碼區塊、連結等
自動連結轉換：系統會自動將特定格式的文字轉換為可點擊的連結（見下方說明）
@提及：可以提及其他用戶（需確認系統是否支援）
引用：可以引用之前的評論
編輯：評論作者可以編輯自己的評論
刪除：評論作者或管理員可以刪除評論

自動連結轉換功能

Gogs 會自動識別並轉換以下格式為可點擊的連結：

1. Commit Hash（提交哈希值）

方式一：直接使用 Commit Hash

格式：7-40 個十六進制字符（0-9, a-f），且不能是純數字

範例：

2304cda4f9 → 自動轉換為指向該提交的連結
abc123def456 → 自動轉換為指向該提交的連結
d8a994ef243349f321568f9e36d5c3f444b99cae → 自動轉換為完整 SHA1 的連結

說明：

必須是有效的十六進制字符（0-9, a-f）
長度至少 7 個字符，最多 40 個字符
純數字不會被轉換（例如 1234567 不會被轉換）

注意：在文本中，commit hash 前後需要有空格或標點符號分隔。

方式二：使用完整的 Commit URL

格式：https://domain/path/commit/hash 或 http://domain/path/commit/hash

範例：

https://gogs.maaconsultants.com/steve07s/maa-test-issues/commit/2304cda4f9 → 自動轉換為連結
http://gogs.maaconsultants.com/owner/repo/commit/abc123def → 自動轉換為連結

說明：

完整的 commit URL 會被自動識別並轉換為連結
URL 中可以包含 # 後面的錨點（如 #diff-2）
系統會自動處理並顯示為可點擊的連結

2. Issue 編號（問題編號）

方式一：使用簡短格式

格式：# + 數字（前面必須是空格、行首、左括號 ( 或左方括號 [）

範例：

#5 → 自動轉換為指向問題 #5 的連結
#123 → 自動轉換為指向問題 #123 的連結
請參考 (#5) → #5 會被轉換
請參考 [#5] → #5 會被轉換

不支援的格式：

#issues/5 → 不會被轉換（簡短格式不支援此寫法）
abc#5 → 不會被轉換（前面必須有空格或標點）

說明：

只能使用 #數字 格式
前面必須是空格、行首、左括號或左方括號
可以直接引用同一個倉庫中的其他問題

方式二：使用完整的 Issue URL

格式：https://domain/path/issues/數字 或 http://domain/path/issues/數字

範例：

https://gogs.maaconsultants.com/steve07s/maa-test-issues/issues/5 → 自動轉換為連結
https://gogs.maaconsultants.com/steve07s/Authorization/issues/5 → 自動轉換為連結
http://gogs.maaconsultants.com/owner/repo/issues/123 → 自動轉換為連結

說明：

完整的 issue URL 會被自動識別並轉換為連結
URL 中可以包含 # 後面的錨點（如 #issue-685）
系統會自動處理並顯示為可點擊的連結
可以跨倉庫引用（如 steve07s/Authorization/issues/5）

3. 跨倉庫 Issue 引用

格式：owner/repo#數字（前面必須是空格或行首）

範例：

steve07s/maa-test-issues#5 → 自動轉換為指向該倉庫的問題 #5 的連結
owner/repo#123 → 自動轉換為指向該倉庫的問題 #123 的連結

說明：

可以引用其他倉庫的問題
格式必須是 倉庫名/倉庫名#數字
前面必須是空格或行首

4. 用戶名提及

格式：@ + 用戶名（前面必須是空格、行首或非字母數字字符）

範例：

@steve07s → 自動轉換為指向該用戶的連結
@username → 自動轉換為指向該用戶的連結
請 @steve07s 協助處理 → @steve07s 會被轉換

說明：

用戶名可以包含字母、數字、連字符、下劃線和點
前面必須是空格、行首或非字母數字字符
系統可能會通知被提及的用戶

5. 字母數字格式 Issue（如 JIRA 風格）

格式：ABC-1234（前面必須是空格、行首、左括號或左方括號）

範例：

PROJ-123 → 自動轉換為指向該問題的連結
ABC-1234 → 自動轉換為指向該問題的連結

說明：

格式：1-10 個大寫字母 + 連字符 + 數字（不能以 0 開頭）
需要系統配置為使用字母數字格式（IssueNameStyleAlphanumeric）

使用範例

在問題描述或評論中，您可以這樣使用：

這個問題與 commit 2304cda4f9 相關。
或者使用完整 URL：
https://gogs.maaconsultants.com/steve07s/maa-test-issues/commit/2304cda4f9

請參考 #5 的解決方案。
或者使用完整 URL：
https://gogs.maaconsultants.com/steve07s/maa-test-issues/issues/5

@steve07s 請協助處理這個問題。

相關問題請見 steve07s/maa-test-issues#10。
或者使用完整 URL：
https://gogs.maaconsultants.com/steve07s/Authorization/issues/5

重要注意事項

格式要求：
- Issue 編號 #5 前面必須有空格、行首、左括號或左方括號
- Commit hash 必須是有效的十六進制字符
- 不支援 #issues/5 或 !3 格式
不會觸發轉換的情況：
- abc#5 → 不會轉換（前面沒有空格）
- #issues/5 → 不會轉換（格式不支援）
- !3 → 不會轉換（Gogs 不支援此格式）
- 1234567 → 不會轉換（純數字，不是十六進制）
正確使用方式：
- 在 #5 前面加上空格：請參考 #5
- 在行首使用：#5 是一個重要的問題
- 在括號中使用：(請見 #5)

討論最佳實踐

保持專業：使用專業和友善的語氣
提供細節：提供足夠的資訊幫助解決問題
及時回應：收到回應後及時回覆
標記解決：問題解決後標記並關閉

附件上傳

支援的檔案類型

系統支援上傳多種檔案類型：

圖片：JPG, PNG, GIF, WebP, BMP, SVG
文件：PDF, Word, Excel, PowerPoint
影片：MP4, MPEG, WebM, OGG
音訊：MP3, OGG, WAV
其他：ZIP, 其他檔案類型

檔案大小限制

單個檔案最大：200 MB
建議：上傳前先壓縮大檔案

上傳方式

拖放上傳：直接將檔案拖放到上傳區域（顯示「拖曳文件到此處或單擊上傳」）
點擊上傳：點擊上傳區域選擇檔案
批量上傳：可同時上傳多個檔案

附件使用建議

截圖：使用截圖工具捕捉錯誤畫面
錄影：對於複雜的操作流程，可以錄製影片
檔案：提供相關的日誌檔、設定檔等
命名：使用有意義的檔案名稱，方便識別

工作流程

標準問題處理流程

1. 問題報告
   ↓
2. 問題確認（標記為「待處理」）
   ↓
3. 指派負責人
   ↓
4. 開始處理（標記為「進行中」）
   ↓
5. 完成開發（標記為「待測試」）
   ↓
6. 測試驗證
   ↓
7. 問題解決（關閉問題）

問題狀態轉換

待處理 → 進行中：開始處理問題時
進行中 → 待測試：開發完成，等待測試時
待測試 → 已解決：測試通過，關閉問題
進行中 → 已阻擋：遇到阻礙無法繼續時
已阻擋 → 進行中：阻礙解除，繼續處理時

優先級處理順序

嚴重：最高優先級，立即處理
高：高優先級，儘快處理
中：正常優先級，按計劃處理
低：低優先級，有時間再處理
不修正：暫時不處理

最佳實踐

報告問題時

✅ 應該做：

使用清晰明確的標題
提供詳細的重現步驟
包含環境資訊
附上相關截圖或錯誤訊息
選擇合適的優先級和類型標籤

❌ 不應該做：

使用模糊的標題（如：「有問題」）
缺少重現步驟
不提供環境資訊
選擇錯誤的優先級（將低優先級標記為嚴重）

處理問題時

✅ 應該做：

及時更新問題狀態
在評論中說明處理進度
遇到問題時標記為「已阻擋」並說明原因
完成後標記為「待測試」
問題解決後關閉問題並說明解決方案

❌ 不應該做：

長時間不更新狀態
不回應評論
不說明阻礙原因
不關閉已解決的問題

使用標籤時

✅ 應該做：

每個問題選擇一個優先級標籤
每個問題選擇一個類型標籤
根據進度及時更新狀態標籤
使用一致的標籤命名

❌ 不應該做：

同時選擇多個優先級標籤
不選擇類型標籤
長期不更新狀態標籤
隨意創建新標籤（應與管理員討論）

協作溝通時

✅ 應該做：

保持專業和友善的語氣
提供足夠的資訊
及時回應評論
使用 Markdown 格式化內容

❌ 不應該做：

使用不當的語言
提供模糊的資訊
長時間不回應
發送無意義的評論

常見問題

Q: 如何知道我的問題是否被處理？

A: 系統會自動通知你：

問題被指派負責人時
有人添加評論時
問題狀態改變時
問題被關閉時

Q: 可以修改已提交的問題嗎？

A: 可以，問題創建者或管理員可以：

編輯問題標題和內容
修改標籤
更新負責人和里程碑

Q: 如何關閉問題？

A: 問題創建者或管理員可以：

在問題詳情頁面點擊「Close Issue」按鈕
關閉時可以添加評論說明解決方案

Q: 標籤可以同時選擇多個嗎？

A: 可以，但建議：

優先級：只選擇一個
類型：只選擇一個
狀態：只選擇一個
可以同時選擇這三種不同類型的標籤

Q: 如何上傳大檔案？

A: 系統支援最大 200 MB 的檔案，如果檔案太大：

先壓縮檔案
或使用雲端儲存服務分享連結
或聯繫管理員

Q: 問題被標記為「已阻擋」是什麼意思？

A: 表示問題因某些原因無法繼續處理，例如：

等待外部依賴
需要更多資訊
技術限制
其他原因

應在評論中說明阻擋的原因。

聯絡與支援

如有任何問題或建議，請：

在系統中創建一個「問題」類型的 Issue
或聯繫系統管理員

最後更新：2025年

版本：1.0

本手冊會持續更新，請定期查看最新版本。

問題追蹤系統使用手冊

目錄

系統簡介

創建問題

步驟 1：進入問題創建頁面

步驟 2：填寫問題資訊

📋 標題（必填）

📝 問題描述

🔄 重現步驟

✅ 預期結果

❌ 實際結果

🔧 環境資訊

💬 錯誤訊息

📌 其他資訊

步驟 3：設定標籤

優先級標籤（選一個）

類型標籤（選一個）

狀態標籤（選一個）

步驟 4：設定負責人與里程碑（可選）

步驟 5：上傳附件（可選）

步驟 6：提交問題

問題標籤系統

標籤分類說明

優先級（Priority）

類型（Type）

狀態（Status）

標籤使用原則

問題管理

查看問題列表

查看問題詳情

編輯問題

關閉/重新開啟問題

指派負責人

設定里程碑

評論與討論

添加評論

評論功能

自動連結轉換功能

1. Commit Hash（提交哈希值）

方式一：直接使用 Commit Hash

方式二：使用完整的 Commit URL

2. Issue 編號（問題編號）

方式一：使用簡短格式

方式二：使用完整的 Issue URL

3. 跨倉庫 Issue 引用

4. 用戶名提及

5. 字母數字格式 Issue（如 JIRA 風格）

使用範例

重要注意事項

討論最佳實踐

附件上傳

支援的檔案類型

檔案大小限制

上傳方式

附件使用建議

工作流程

標準問題處理流程

問題狀態轉換

優先級處理順序

最佳實踐

報告問題時

處理問題時

使用標籤時

協作溝通時

常見問題

Q: 如何知道我的問題是否被處理？

Q: 可以修改已提交的問題嗎？

Q: 如何關閉問題？

Q: 標籤可以同時選擇多個嗎？

Q: 如何上傳大檔案？

Q: 問題被標記為「已阻擋」是什麼意思？

聯絡與支援