# SKILL-021 — 產品營收系統（一鍵部署）

> 把下面的指令貼到你的 **general 頻道**，機器人就會自動幫你建好整套營收系統。

---

## 快速開始（貼這段到 general 頻道）

```
請幫我建立產品營收系統，需要以下 3 個機器人：

1. 建立 營收拉取（API 資料拉取）
   - 角色：呼叫後台 API 拉取各產品營收 CSV 資料
   - API：http://192.168.5.18:1688/rd1_backendweb/api/income/
   - 支援產品：A9PLUS（狂野飆車9 Plus）、A8DX（閃電摩托 DX）
   - 參數：project, start_time(YYYYMMDD), end_time(YYYYMMDD), locale(CN/FA，必須大寫), format=csv
   - 驗證：筆數>0、header 存在、空白回傳=停下回報
   - 語言：繁體中文

2. 建立 營收報表（Google Sheets 寫入）
   - 角色：管理營收 Google Sheets，寫入資料、更新樞紐分析、管理總表
   - 需要：Google Service Account JSON 金鑰
   - SOP：
     a. Step 0：寫入前先保存總表 C 欄到 G 欄（G 欄不准為 0）
        - Row 8：G8=C8（X家/），H8=E8的值+"台"
        - 保存後讀回驗證
     b. Step 4：舊資料搬到前月分頁
     c. Step 5：新資料寫入 DX大陸數據（row 2 開始，保留公式欄）
     d. Step 6：更新樞紐（日期用 NUMBER_BETWEEN + 序號，店名用 NOT_BLANK）
     e. Step 6.5：讀取大陸營收「總和」行 C 欄 → 填入 R 欄對應月份
     f. Step 7：驗證（N/A=0、無空白店名、R 欄已更新）
   - 異常：任何步驟做不到 → 停下回報
   - Drive 限制：無法建新檔案，直接在指定試算表操作
   - 語言：繁體中文

3. 建立 機台管理（機台 ID 同步）
   - 角色：新機台 ID 同步、IP 查地區、維護機台對照表
   - IP 判斷店家規則：
     a. IP 不同 = 不同店家（即使店名一樣）
     b. 未設定 + 同地區不同 IP → 加序號「未設定(地區_1)」
     c. 有店名 + 不同 IP 不同地區 → 加地區「XX(朝阳店)」「XX(廊坊店)」
     d. 有店名 + 不同 IP 同地區 → 加序號
     e. 同 IP 機台地區必須一致
   - IP 查詢：ip-api.com batch API，lang=zh-CN
   - 寫入後同步到營收報表的「同步機台ID」分頁
   - 語言：繁體中文

建好後請建立團隊「產品營收團隊」，成員為以上 3 個機器人。
```

---

## 初始化設定

建好後，General 會問你以下資訊：

| 項目 | 說明 | 範例 |
|------|------|------|
| API URL | 後台營收 API 位址 | http://192.168.5.18:1688/rd1_backendweb/api/income/ |
| Service Account 路徑 | Google JSON 金鑰路徑 | /root/.agend/credentials/google-service-account.json |
| 營收報表 ID | Google Sheets ID | 14wQLe_s7bPU2l9i-Xm6NudfKkoc6r68ed4_HBhbIRoU |
| 機台對照表 ID | Google Sheets ID | 1oNr7iP5wXFUuinNfMrhaFRN2OVtmJy6ZGrZv6rDwEps |
| 產品代碼 | API project 代碼 | A9PLUS, A8DX |

---

## 使用方式

### 每月營收更新（3 步驟）

**Step 1：跟 General 說**
```
A9PLUS 產品營收
```

**Step 2：General 確認**
- 試算表連結？
- 月份？（例如 202608）
- 語系？（CN / FA / 都要）

**Step 3：自動執行**
1. ⏳ 營收拉取 → API 拉 CSV
2. ⏳ 營收報表 → 保存上月→搬前月→寫入→樞紐→R欄→驗證
3. ⏳ 機台管理 → 新機台 ID 同步
4. ✅ 完成通知

---

## SOP 完整規則

### 營收拉取規則
| 項目 | 內容 |
|------|------|
| locale | 必須大寫（CN, FA） |
| timeout | 120 秒 |
| 驗證 | 筆數>0, header 存在 |
| 空白回傳 | 停下回報（可能參數錯） |
| 存檔 | /tmp/{project}_{YYYYMM}_{locale}.csv |

### 營收報表規則
| 步驟 | 規則 |
|------|------|
| Step 0 保存上月 | C欄→G欄，H8=E8+"台"，讀回驗證 |
| Step 5 寫入 | row 2 開始，不留空行，保留公式欄 |
| Step 6 樞紐 | 日期=NUMBER_BETWEEN+序號，店名=NOT_BLANK |
| Step 6.5 R欄 | 找「總和」行C欄值→填R欄月份（位置不固定） |
| Step 7 驗證 | N/A=0, 無空白店名, R欄更新 |
| 異常 | 停下回報，不自行變通 |
| Drive | 無法建副本，直接操作 |

### 機台管理規則
| 項目 | 規則 |
|------|------|
| IP 判斷 | 不同 IP = 不同店家 |
| 未設定命名 | 未設定(地區)，同地區不同IP加序號 |
| 有店名命名 | 加地區區分（朝阳店/廊坊店），同地區加序號 |
| 同 IP | 地區必須一致 |
| IP 查詢 | ip-api.com, lang=zh-CN, 限速 45/min |
| 同步 | 寫入後同步到營收報表「同步機台ID」 |

---

## 驗證清單

每次執行完必須確認：
- [ ] DX大陸數據 N/A = 0
- [ ] 大陸營收樞紐無空白店名
- [ ] 同步機台ID vs 機台對照表一致
- [ ] R 欄已更新為最新總和
- [ ] 總表 G 欄有上月數據（不為 0）

---

## 常見問題

**Q：API 回傳空白怎麼辦？**
A：確認 project 代碼是否正確（A9PLUS 不是 A9+），locale 是否大寫。

**Q：Drive 空間不足？**
A：Service Account 無法建新檔案，跳過建副本步驟直接操作。

**Q：樞紐顯示空白店名？**
A：檢查同步機台ID 中該機台的地區是否和同 IP 的其他機台一致。

**Q：N/A 怎麼修？**
A：該機台 ID 不在同步機台ID 表中，從 CSV 取得店名/IP 資訊新增。

**Q：總表顯示 #NUM! 或 #DIV/0!？**
A：樞紐無資料（可能日期篩選範圍不對或資料被過濾掉）。

---

## 機器人分工

| 機器人 | 你跟它說什麼 | 它會做什麼 |
|--------|-------------|-----------|
| **營收拉取** | 不需要直接操作 | 拉 API CSV |
| **營收報表** | 不需要直接操作 | 寫入+樞紐+驗證 |
| **機台管理** | 不需要直接操作 | 新機台同步+IP查詢 |
| **General** | 「A9PLUS 產品營收」 | 協調三個機器人 |

---

## 下載

- [📋 SKILL-021.md](SKILL-021.md) — 本頁 Markdown 版