# QA 測項展開 — 使用者指南

---

## Quick Start（5 秒版）

1. 在 **qa-test-expander** 頻道貼上規格書 Sheet 連結
2. 說「展開 XX 章節」→ 回答機器人的問題
3. 等 5-15 分鐘 → 結果出現在你的 Sheet 新分頁中
4. 看到紅色的 → 去確認；黑色的 → 直接可用

---

## 系統概覽

```
你提供規格書(Sheet) → 機器人自動轉換格式 → 機器人展開測試項目 → 你確認結果
```

本系統由以下機器人協作完成：

| 機器人 | 角色 | 你需要互動嗎？ |
|--------|------|--------------|
| **qa-test-expander** | 主腦 — 接收指令、展開測項 | ✅ 所有操作都跟它說 |
| **qa-sheet-worker** | 讀寫工 — 讀取/寫入 Sheet | ❌ 背景自動，不用管 |

**你只需要在 qa-test-expander 頻道操作，其餘全自動。**

---

## 詳細步驟

### Phase 0：首次建置（第一次使用才做，之後不用再做）

> ⚠️ 沒有先建置，機器人就沒有權限讀寫你的 Sheet。第一次使用的人一定要先做這關。
> 分「你親自做」和「交給 general」兩部分——**你做申請，general 做程式串接**。

#### 🙋 你親自做的（Google 帳號權限，general 代替不了）

**Step 0-1：建立 Google Cloud 專案 + 開啟 API**
- 到 Google Cloud Console（console.cloud.google.com）建立專案（或用現有的）
- 在「API 和服務」啟用 **Google Sheets API**
- 👉 之後若要讓機器人「新建檔案」，順便開 **Google Drive API**

**Step 0-2：建立「機器人帳號」**
- 進「IAM 與管理」→「服務帳號」→「建立服務帳號」，取個名字
- 建好後系統自動給一個 email（`xxx@xxx.iam.gserviceaccount.com`）→ **記下來**

**Step 0-3：下載金鑰檔**
- 進該帳號 →「金鑰」→「新增金鑰」→ 選 **JSON** → 自動下載一個 `.json` 檔
- ⚠️ 這是機密，等於帳號密碼，別外流

**Step 0-4：把 Sheet 共用給機器人**
- 打開規格書 Google Sheet →「共用」→ 貼上 Step 0-2 的 email → 權限選「編輯者」
- 👉 **每一份**新的 Sheet 都要做這步

#### 🤖 交給 general 做的（程式串接，自動）

**Step 0-5：把金鑰交給 general**
- 在 general 頻道上傳 Step 0-3 的 JSON 金鑰檔
- 說「幫我串接 QA 測項系統」
- general 自動:把金鑰放安全位置 + 寫好程式 + 設定好機器人 → 完成
- 完成後跟 general 確認「串接好了嗎」

> 💡 建置只做這一次。之後每天使用只要做下面 Phase 1~3。
> （程式串接的技術細節見文末「附錄:技術細節」，一般使用者不用看。）

---

### Phase 0.5：每次使用前確認（30 秒）
- [ ] 哪個遊戲？（A9+ / A8+ / 其他）
- [ ] 要展開哪個章節/頁籤？
- [ ] CN（中國版）還是 FA（海外版）？
- [ ] 這份新 Sheet 有沒有共用給機器人？（沒有的話回 Step 0-4）

---

### Phase 1：規格書轉換（自動，約 2 分鐘）

**Step 1-1：貼上連結 + 說要做什麼**

在 qa-test-expander 頻道輸入：
```
這是 A9+ 的規格書，請轉換並展開「系統設定」頁籤
https://docs.google.com/spreadsheets/d/xxxxxxxxx/edit#gid=123456
```

**Step 1-2：等待 + 確認摘要**

機器人會回覆類似：
```
✅ 已轉換！
- 章節數：5 個
- 項目數：15 個（✅12 / 🔒3 / ❌0）
- 排除：2 個已移除項目

確認展開嗎？
```

**你的回應（範例）：**

| 情況 | 你怎麼回 |
|------|---------|
| 都正確 | 「OK」或「確認展開」 |
| 章節/數量不對 | 「時間設定應該有 10 項不是 7 項」 |
| 排除有誤 | 「測試模式不要排除，那個還要用」 |
| 某章節不用展開 | 「第 3 章不用展開」 |
| 回答不確定項 | 「Row 800 是備註，不用獨立成章節」 |
| 看不懂摘要在說什麼 | 「第 2 章那個是什麼？可以展開看嗎？」 |

⚠️ 不需要回答得很正式，用白話說就好，機器人聽得懂。有疑問直接問它。

---

### Phase 2：展開測試項目（自動，約 5 分鐘）

**Step 2-1：回答確認問題**

機器人會問：
- CN 還是 FA 版？
- 要包含隱藏項目嗎？
- 寫入到哪裡？（新分頁 or 指定位置）
  👉 **不確定就選「新分頁」** —— 最安全，不會動到你現有的資料。只有當你想把測項接在某個既有分頁後面時，才選「指定位置」。

直接回答即可。

**⚠️ 新遊戲首次展開時：**

如果這是一個全新的遊戲（系統中沒有對應的用語對照表），機器人會額外：
1. 自動掃描規格書，推測該遊戲的操控裝置和用語
2. 列出推測結果，問你「這樣對嗎？」
3. 你確認/修正後，系統自動存檔

這只有**第一次**會出現，之後同遊戲不會再問。

**⚠️ 大量測項時（大規模測試常見）：**

如果一份規格有大量「同樣邏輯重複很多次」的項目（例如 50 個角色都要驗「名稱格式」、一堆賽道都驗同一種屬性），機器人會問你要怎麼展：

```
偵測到「角色名稱驗證」有 120 個同邏輯的驗證點。
A. 全量展開（每個獨立一條）→ 約 120 條
B. 抽樣展開（5 個代表完整測，其餘做格式驗證）→ 約 30 條
選哪個？
```

**怎麼選：**
- 要一個一個仔細測 → 選 **A**（條數多但完整）
- 只要抽幾個代表確認格式對就好 → 選 **B**（省時間）
- 先選 B 後來想全測 → 可以，跟機器人說「補展剩下的」

> 注意：如果是「50 個不同功能」（例如操作員選單 50 個設定各不相同）不會觸發這個問題，會直接全展。只有「同一種邏輯重複」才會問。

**⚠️ 規格有引用其他表時（DataTable / 卡牌數值常見）：**

如果規格引用了別的資料（例如卡牌表引用技能表、賽道表引用屬性表），機器人會先問：

```
發現這份規格引用了「技能表」，請問對應資料在哪？
```

**你怎麼回：**
- 有那份資料 → 貼連結給它
- 沒有 / 不用管 → 說「不用管那個引用」→ 相關項目會標 🟡 提醒

**⚠️ 操作員選單規格 — 用語表提問（新功能）：**

展開操作員選單規格時，機器人可能會問兩種問題：

1. **發現新操控詞**：
   ```
   發現用語表沒有的操控詞「HANDBRAKE 手煞車鍵」，
   要收進 A9 用語表嗎？
   ```
   → 要就說「要」，機器人補進去，下次自動生效；不要就說「不用」。

2. **分不清是實體按鍵還是選單鍵**：
   ```
   「上鍵」我不確定是框體實體按鍵還是選單導航鍵，你知道嗎？
   ```
   → 你回答「是框體實體按鍵」或「是選單鍵」即可。

> 這些你**不用主動做什麼**，機器人不確定才會問，你回答就好。判斷邏輯是機器人內部處理，你不用懂。

**Step 2-2：等待完成**

機器人自動展開 + 寫入，完成後通知：
```
✅ 展開完成！
📊 展開：32 項 | ✅ 28 項 | 🟡 3 項 | ⏭️ 1 項
📎 結果：https://docs.google.com/spreadsheets/d/xxx/edit#gid=新分頁
```

---

### Phase 3：確認結果（約 5-10 分鐘）

**Step 3-1：打開 Sheet 檢查**

確認重點：
- [ ] 測試步驟是否合理
- [ ] 預期結果是否正確
- [ ] 🟡 標黃的項目是否需要修正
- [ ] 備註欄的規格參照是否正確

**Step 3-2：回報**

- 沒問題 → 「Review OK」
- 需修改 → 直接說哪裡要改，機器人修正

👉 **這些不是固定指令，用白話講就好。** 「都對了」「這樣可以」「沒問題」機器人都聽得懂；要改也是直接講「第 3 項的預期結果不對，應該是 XXX」，不用背特定格式。

---

## 顏色/標記說明

展開後的 Sheet 中你會看到以下標記：

| 標記 | 意思 | 你要做什麼 |
|------|------|-----------|
| ✅ 黑色 | 確定正確 | 直接可用，不用動 |
| 🟢 綠色（✅ 已確認） | 你確認過的項目 | 已完成，不用再動 |
| 🟡 黃色 [待確認] | 機器人不確定 | 你需要確認步驟/預期結果是否正確 |
| 🔴 紅色 [?] | 資訊不足 | 需要去實機確認或補充規格。👉 確認完回來跟機器人說結果（例如「Row 10 那個音量範圍是 0~100」），它會幫你補上去 |
| 灰色 [AI推斷] | 機器人根據上下文推測 | 確認對不對就好 |
| ⏭️ 跳過 | 隱藏/已移除的項目 | 不用管 |

> 💡 當你確認完一個 🟡 黃色項目、回報「改好了」後，機器人會把它的預期結果和備註加上**綠色的「✅ 已確認」標記**，並把黃底改回白底 —— 代表這項已經處理完、不用再看。

---

## 「測試進度總覽」分頁怎麼看（新）

每份測試 Sheet 的**最前面**會自動有一個「測試進度總覽」分頁，讓你一眼看到測試進度，不用自己算。

**它會顯示：**

| 欄位 | 意思 |
|------|------|
| 項目頁籤 | 每個測試分頁的名稱 |
| 測項數量 | 這個分頁總共幾條測試 |
| 已完成數量 | 已測了幾條（PASS+FAIL） |
| PASS / FAIL | 通過 / 失敗各幾條 |
| N/A / BLOCK | 不適用 / 卡關各幾條 |
| 進度 | 完成百分比（自動算） |
| 通過率 | 通過百分比（自動算） |

**你要做的：**
- 測試人員在各測試分頁的狀態欄填 **PASS / FAIL / N/A / BLOCK**
- 總覽分頁會**自動統計**，不用手動加總
- 隨時打開總覽分頁就能看到整體進度

> ⚠️ 不要刪除總覽分頁或裡面的公式，機器人靠它追蹤進度。

---

## 常見操作

### 規格書更新了，之前展的過時了
```
「規格書更新了，請重新展開系統設定」
```
機器人會重新讀取 + 重新展開。
👉 **會怎麼處理舊的:** 重新展開會覆蓋掉舊的那個分頁內容，但**你之前確認過的綠色標記會盡量保留**。如果你擔心，可以先跟機器人說「這次展開存到新分頁，不要蓋掉舊的」，它就會另開一個分頁。

### 展開結果有錯
```
「第 5 項步驟有錯，應該是先按 Start 再選時區」
```
機器人會修正。
👉 **具體會怎麼做:** 機器人直接改**原本那一格**的內容（不會另開新的、不會動到其他項目），改完會回你一句「已修正第 5 項」讓你知道。你重新整理 Sheet 就看得到。

### 想展開其他章節
```
「接下來展開 Coin Option 章節」
```
直接說就好，不用重新貼連結（同一份規格書的話）。

### 機器人沒反應
- 等 30 秒再試一次
- 確認你在正確的頻道（qa-test-expander）
- 如果還是沒反應，到 **general** 頻道反映
  👉 **反映時講這些:** 卡在哪一步（例如「貼連結後沒回應」）、你貼的指令、如果畫面有錯誤訊息就截圖。general 會幫你檢查機器人狀態。

---

## 不要做的事

| ❌ 不要 | 原因 |
|---------|------|
| 同時給多份規格書 | 一次處理一份，避免混亂 |
| 展開進行中修改規格書 | 會造成讀取結果不一致 |
| 手動改測項 Sheet 的格式/顏色 | 機器人可能會覆蓋你的修改 |
| 刪除 Sheet 中的統計行/提示行 | 機器人需要這些來追蹤狀態 |
| 用 PDF 規格書 | 品質不穩定，建議轉成 Sheet 再用 |

---

## 「職能」欄使用方式

展開完成後，M 欄會自動標上「職能」（程式/美術/企劃）。

**篩選特定職能的測試項目：**
1. 點 M 欄標題的篩選圖示
2. 選擇要看的職能（如「美術」）
3. 只顯示該職能的測試項目
4. 看完後記得取消篩選

**修改職能標籤：**
- 點 M 欄的格子 → 下拉選單選擇正確的職能
- 不需要回報機器人，直接改就好

---

## 支援的規格書格式

| 格式 | 支援度 | 建議 |
|------|--------|------|
| Google Sheet | ⭐⭐⭐⭐ 最佳 | 優先使用 |
| Excel .xlsx | ⭐⭐⭐⭐ 很好 | 上傳到頻道即可 |
| Word .docx | ⭐⭐⭐ 可用 | 可能需要微調 |
| PDF | ⭐⭐ 不建議 | 品質不穩，建議先轉 Sheet |

---

## 時間估算

| 階段 | 時間 | 誰做 |
|------|------|------|
| Phase 0 首次建置 | 約 15-30 分鐘 | 你 + general（僅第一次） |
| Phase 1 轉換 | 1-2 分鐘 | 機器人 |
| 確認摘要 | 30 秒 | 你 |
| Phase 2 展開 | 3-5 分鐘 | 機器人 |
| Phase 3 確認 | 5-10 分鐘 | 你 |
| **日常使用總計** | **約 15 分鐘**（建置後每次） | |


---

## 附錄:技術細節（給 general / 工程人員，一般使用者可略過）

> 以下是程式串接的技術內容，**使用者不需要看**。留存供接手維護、換機、重建時參考。

### 認證方式
Service Account（非 OAuth）— 適合機器人自動化，無需人工登入、無 token 過期。

### 金鑰放置
放在不進版控的固定路徑（本系統:`/root/.agend/credentials/` 底下）。路徑寫死在程式常數，檔案本身不入 git。

### 程式讀金鑰（Python 官方庫 google-api-python-client）
```python
from google.oauth2.service_account import Credentials
from googleapiclient.discovery import build

creds = Credentials.from_service_account_file(CREDS_PATH, scopes=SCOPES)
service = build('sheets', 'v4', credentials=creds)
```
- 讀取:`spreadsheets().get(..., includeGridData=True)`（拿得到顏色/粗體/隱藏行）
- 寫值:`spreadsheets().values().update / batchUpdate`
- 寫格式:`spreadsheets().batchUpdate`

### 函式庫選擇
官方庫 `google-api-python-client`（格式控制完整）為主；`gspread` 較簡單但格式控制弱。需精細格式用官方庫。

### Scope
- 唯讀:`.../auth/spreadsheets.readonly`
- 讀寫:`.../auth/spreadsheets`
- 原則:能唯讀就唯讀，最小權限。

### 技術常見坑
| 情境 | 症狀 | 解法 |
|------|------|------|
| 忘記共用 Sheet | 403 PermissionDenied | 共用給 service account email |
| 唯讀卻要寫 | 403 | 共用給編輯者 |
| 讀不到格式 | values.get 只回文字 | 用 spreadsheets.get + includeGridData=True |
| HYPERLINK 變純文字 | RAW 寫入 | valueInputOption='USER_ENTERED' |
| 寫單格破壞合併 | 標題/提示行消失 | 合併行別單獨寫，或寫完重 merge |
| API 呼叫太多 | 429 Rate limit | 用 batchUpdate 合併請求 |
| 分頁改名定位失效 | 頁籤名找不到 | 用 sheetId（GID）定位 |

---

*使用者指南 v5 | 建置 + 使用一份到底 | 不含機密資料*