# Google Sheets API 操作手冊 (AI 與 Vibe Coding 專用)

本文件定義了透過 Google Apps Script (GAS) 操作 Google Sheets 的介道規範，包含基礎讀寫及強大的多軌序列寫入功能。

## 基礎連線資訊

* **API 網址 (Endpoint)**: `https://script.google.com/macros/s/你的網址/exec`
* **請求方法 (Method)**: `POST`
* **內容類型 (Content-Type)**: `text/plain;charset=utf-8`
* **跳轉處理 (Redirect)**: `follow`

## 認證與全域參數

Payload 必須包含以下認證欄位：

| 欄位名稱 | 型別 | 必填 | 說明 |
| :--- | :--- | :--- | :--- |
| name | String | 是 | 使用者名稱 |
| password | String | 是 | 密碼 |
| sheet | String | 否 | 工作表名稱 (預設為 sheet1) |

## API 功能列表 (Actions)

### 1. 讀取資料 (read)
* **格式**: `{"read": "範圍"}`
* **自動轉義**: 若輸入 `"A"`，會自動視為 `"A:A"`。
* **範例**: `{"read": "A1:B10"}`

### 2. 指定範圍寫入 (write)
* **格式**: `{"write": "範圍", "data": 數值或陣列}`
* **說明**: 直接覆蓋指定範圍。
* **範例**: `{"write": "A1:B1", "data": [["姓名", "得分"]]}`

### 3. 末尾序列寫入 (write2End) —— **支援多軌併行**
* **說明**: 根據目標自動尋找最後一個非空儲存格並接續寫入。內建 `LockService` 保護，支援併發寫入。
* **單軌範例**: `{"write2End": "A", "data": [1, 2]}`
* **多軌範例**:
  ```json
  {
    "write2End": ["A", "B"],
    "data": [
      ["A欄新資料1", "A欄新資料2"],
      ["B欄新資料"]
    ]
  }
  ```

### 4. 最前端插入寫入 (write2Top) —— **支援多軌併行**
* **說明**: 在最前方插入新的行列後寫入，原本資料會自動推移 (無損寫入)。
* **單軌範例**: `{"write2Top": "1", "data": ["標題A", "標題B"]}`
* **多軌範例**:
  ```json
  {
    "write2Top": ["A", "C"],
    "data": [
      ["置頂資料A"],
      ["置頂資料C"]
    ]
  }
  ```

### 5. 清空內容 (delete)
* **格式**: `{"delete": "範圍"}`
* **說明**: 僅清空文字，保留格式。

### 6. 行列/欄位管理
| 功能 | 參數鍵名 | 範例值 |
| :--- | :--- | :--- |
| 新增列 | addRow | "2" (在第 2 列位置插入) |
| 刪除列 | deleteRow | "5:7" (刪除 5 到 7 列) |
| 新增欄 | addColumn | "B" (在 B 欄位置插入) |
| 刪除欄 | deleteColumn | "2" (刪除第 2 欄) |

## 技術規格與限制

1. **併發控制**: 腳本包含 `LockService`，多軌寫入時會自動排隊 (WaitLock: 30s)，防止行號計算衝突。
2. **自動方向判斷**: 
   - 目標為字母 (如 "A")：執行**垂直**操作。
   - 目標為數字 (如 "1")：執行**水平**操作。
3. **資料對齊**: 多軌寫入時，`write2End` 陣列長度必須與 `data` 陣列長度一致。

## AI 提示詞指令集 (System Prompt for Vibe Coding)

當你（AI）調用此 API 時，請遵循以下原則：

1. **選擇最佳 Action**: 
   - 覆蓋特定區域使用 `write`。
   - 紀錄 Log、時間戳或流水帳使用 `write2End`。
   - 需要顯示最新動態使用 `write2Top`。
2. **多軌操作**: 當需要同時更新多個不連續欄位的末尾時，優先使用 `write2End: ["欄位1", "欄位2"]` 減少 HTTP 請求次數。
3. **傳輸規範**: 必須使用 `fetch POST`，headers 設定為 `{'Content-Type': 'text/plain;charset=utf-8'}`。
4. **資料結構**: 
   - `write` 必須使用二維陣列 `[[v1, v2]]`。
   - `write2End`/`write2Top` 處理單軌時用一維 `[v1, v2]`，處理多軌時用嵌套陣列 `[[v1...], [v2...]]`。
5. **轉址處理**: 必須設定 `redirect: 'follow'` 以處理 Google 伺服器的重新導向。