← 返回索引

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

自動建立營收拉取 + 報表 + 機台管理，含完整 SOP

v3 合併版

🚀 概述

此 Skill 用於自動建立「產品營收」agent 團隊。將此檔案交給你的 PM agent，它會自動建立 3 個專職 agent 並完成配置。

v3 合併：OAuth、格式轉換、樞紐 visibleValues + Step 0 保存上月、Step 6.5 R欄、機台 IP 命名規則、同步到報表

初始化設定

變數說明範例
API_URL後台營收 API 位址http://192.168.5.18:1688/rd1_backendweb/api/income/
SERVICE_ACCOUNT_PATHGoogle SA JSON 金鑰路徑/path/to/service-account.json
SERVICE_ACCOUNT_EMAILService Account emailbacon-812@xxx.iam.gserviceaccount.com
OAUTH_CLIENT_SECRET_PATHOAuth Client Secret JSON/path/to/oauth_client_secret.json
OAUTH_CREDENTIALS_PATHOAuth Token 存放路徑/path/to/oauth_credentials.json
REVENUE_SHEET_ID最近一個月的營收報表 ID12MTWgWfVb1bRGWwE9IJDYd0l2kbDUxjxPBAr-tHyu6Q
MACHINE_TABLE_ID機台 ID 對照表 ID1oNr7iP5wXFUuinNfMrhaFRN2OVtmJy6ZGrZv6rDwEps
PRODUCTS產品代碼A8DX, SR4, A9PLUS, A8PLUS
PRODUCT_SHEET_MAP產品→機台對照表分頁A8DX→閃電摩托, SR4→極速摩托4, A9PLUS→狂野飆車, A8PLUS→A8+

⚠️ 前置作業：OAuth 授權（必須！）

Service Account 的 Drive 配額為 0，無法建立副本。必須用使用者帳號的 OAuth。

首次授權流程

  1. PM 產生授權連結（scope: drive + spreadsheets）
  2. 使用者在瀏覽器授權後，網址列出現 http://localhost/?code=XXXX
  3. 使用者複製 code= 後的值給 PM
  4. PM 交換 token（refresh_token 永久有效）

Token 刷新

curl -s -X POST https://oauth2.googleapis.com/token \
  -d "refresh_token={REFRESH_TOKEN}" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}" \
  -d "grant_type=refresh_token"

機器人分工

角色負責步驟說明
PMStep 2 + Step 10OAuth 建副本、分享給 SA、彙整報告
營收拉取Step 1API 拉 CSV
營收報表Step 0 + 3~7報表全部操作
機台管理Step 8~9新機台同步 + 同步到報表

完整工作流（10 步）

1營收拉取 — API 拉 CSV

GET {API_URL}?project={CODE}&start_time={YYYYMMDD}&end_time={YYYYMMDD}&locale={CN/FA}&format=csv
規則說明
locale必須大寫（CN, FA）
timeout120 秒
驗證筆數>0、header 存在
空白回傳停下回報（參數錯誤）
存檔/tmp/{project}_{YYYYMM}_{locale}.csv

2PM — OAuth 建副本 + 共用給 SA

  1. 刷新 access_token
  2. POST /drive/v3/files/{前月ID}/copy → 取得新 Sheet ID
  3. POST /drive/v3/files/{新ID}/permissions → writer 權限給 SA email
  4. 將新 Sheet ID 傳給營收報表

0營收報表 — 儲存前月總表摘要（Step 3 之前）

3營收報表 — 更新總表

4營收報表 — 搬前月分頁

5營收報表 — 寫入新月份營收

資料格式轉換規則

欄位類型CSV 格式轉換方式
時間（長）HH:MM:SS(H×3600+M×60+S)/86400
時間（短）HH:MM(H×3600+M×60)/86400
百分比XX.XX%去掉 % 除以 100
日期YYYY-MM-DD轉為 Excel 序號
數值整數/小數直接寫入
⚠️ 「平均遊戲時間」和「平均InGame時間」是 HH:MM（2段），必須支援 2 段和 3 段。

6營收報表 — 更新樞紐分析

Step 6.5：營收報表 — R 欄月度圖表更新

  1. 在各營收分頁找到樞紐「總和」行的 C 欄值（日均局數）
  2. 填入 R 欄對應當月的位置
  3. 規則：只顯示今年+去年；跨年時最舊年份拿掉，今年替換到去年

7營收報表 — 驗證

項目條件
筆數CSV 筆數 = Sheets 行數
取樣首/中/末三行比對一致
時間欄位非 0（平均遊戲時間/InGame）
N/A所有 N/A = 0
空白店名樞紐無空白店名
Source rangeendRowIndex 正確
總表 G 欄不為 0
R 欄當月已填入

8機台管理 — 新機台 ID 同步

IP-Based 機台命名規則

情境規則
不同 IP= 不同店家（即使店名一樣）
未設定 + 同地區不同 IP加序號：未設定(地區_1)、未設定(地區_2)
有店名 + 不同 IP 不同地區加地區：XX(朝阳店)、XX(廊坊店)
有店名 + 不同 IP 同地區加序號：XX_1、XX_2
同 IP地區必須一致
⚠️ 確認寫入正確分頁（產品中文名，不是 "Machineid"）

9機台管理 — 同步到報表

10PM — 彙整驗證報告

PM 觸發清單

關鍵字：{產品名} 產品營收 / {產品名} 營收

確認流程：
1. 確認要執行？
2. 前月份營收試算表連結？
3. 營收月份？（例如 202608）
4. 語系？（CN / FA / 都要）

已知限制

限制因應
IMPORTRANGE 授權新副本需使用者手動點「允許存取」
SA Drive 配額 = 0用 OAuth 建副本
樞紐日期格式用序號 + visibleValues 折衷
Agent 超時大任務分段執行
urn:ietf:wg:oauth:2.0:oob 已停用用 http://localhost

常見問題

Q：API 回傳空白？

確認 project code（A9PLUS 不是 A9+）、locale 大寫。

Q：Drive 空間不足？

SA 無法建檔，用 OAuth 繞過。

Q：樞紐顯示空白店名？

檢查同步機台ID 中該機台地區是否與同 IP 一致。

Q：N/A 怎麼修？

該機台不在同步表中，從 CSV 取得資訊新增。

Q：總表 #NUM! 或 #DIV/0!？

樞紐無資料（日期篩選範圍不對或被過濾）。

Q：R 欄填入後圖表沒更新？

確認填的是數值非字串。

版本紀錄

v3（2026-08）合併版

v2 經驗教訓

  1. SA Drive 配額 = 0 → OAuth
  2. HH:MM 格式未處理 → 支援 2/3 段
  3. Source range 未更新 → 每次必更新
  4. 機台寫錯分頁 → 確認中文名
  5. 店名篩選用錯 → NOT_BLANK
  6. 日期篩選缺 visibleValues → 必須包含
  7. oob redirect 已停用 → localhost
  8. IMPORTRANGE 需手動授權 → 已知限制

下載