def batch_update_cells(self, sheet_url: str, update_data: list[dict]) -> dict | None:

sheet_service.py

@@ -391,9 +391,9 @@ class SheetService:
 
          Args:
              sheet_url (str): Google Sheet 的 URL。
-             update_data (list[dict]): 一個字典列表，每個字典包含:
+             update_data (list[dict]): 一個字典列表，每個字典應包含:
                  'range' (str): 要更新的範圍 (例如 '工作表名!A1')
-                 'value' (str): 要寫入的值
+                 'values' (list[list[str]]): 要寫入的值 (二維列表, 例如 [['value1']])
 
          Returns:
              dict | None: Google API 的返回結果，如果成功。否則返回 None。
@@ -409,44 +409,62 @@ class SheetService:
              logging.warning("沒有需要批次更新的資料。")
              return None
 
-         # 確保 update_data 中的 range 包含 sheet_name
-         # （調用此方法前應已獲取 sheet_name 並填入 range）
-         # 例如 update_data = [{'range': '測試!F2', 'value': 'OO'}, ...]
-
          body = {
              'valueInputOption': 'USER_ENTERED', # 或者 'RAW'
              'data': []
          }
+         valid_updates_count = 0 # 計算實際加入請求的數量
          for item in update_data:
-             # 基本的範圍和值檢查
-             if 'range' not in item or 'value' not in item:
-                 logging.warning(f"跳過格式錯誤的更新項目: {item}")
+             # 修正 1: 檢查 'values' 而不是 'value'，並檢查 'values' 是否為列表
+             if 'range' not in item or 'values' not in item or not isinstance(item['values'], list):
+                 logging.warning(f"跳過格式錯誤的更新項目 (缺少 'range' 或 'values' 非列表): {item}")
                  continue
-             if '!' not in item['range'] or len(item['range'].split('!')[1]) < 2: # 簡單檢查範圍格式
-                 logging.warning(f"跳過範圍格式可能錯誤的更新項目: {item['range']}")
+             # 修正 2: 稍微改進範圍檢查，確保 '!' 後面有內容
+             range_parts = item['range'].split('!', 1) # 最多分割一次
+             if len(range_parts) != 2 or not range_parts[0] or not range_parts[1]:
+                 logging.warning(f"跳過範圍格式錯誤的更新項目 (格式應為 'SheetName!A1'): {item['range']}")
                  continue
 
+             # 修正 3: 直接使用 item['values']，它本身就應該是二維列表
              body['data'].append({
                  'range': item['range'],
-                 'values': [[item['value']]] # value 需要是二維列表
+                 'values': item['values'] # 直接使用傳入的二維列表
              })
+             valid_updates_count += 1
 
-         if not body['data']:
-             logging.warning("沒有有效的資料可以進行批次更新。")
-             return None
+         # 修正 4: 根據實際加入請求的數量判斷是否繼續
+         if not body['data']: # 或者 if valid_updates_count == 0:
+             logging.warning("經過驗證後，沒有有效的資料可以進行批次更新。")
+             # 即使沒有資料，也返回一個表示「沒有執行」的狀態，而不是 None，避免呼叫方誤判
+             # 或者可以返回一個特定的物件或空字典來表示未執行
+             return {"totalUpdatedCells": 0, "replies": [], "message": "No valid data to update after validation."} # 返回模擬的回應
 
          try:
-             logging.info(f"準備批次更新 Spreadsheet ID: {spreadsheet_id}，共 {len(body['data'])} 個儲存格...")
+             # logging.info(f"準備批次更新 Spreadsheet ID: {spreadsheet_id}，共 {len(body['data'])} 個儲存格...")
+             # 使用 valid_updates_count 進行日誌記錄更準確
+             logging.info(f"準備批次更新 Spreadsheet ID: {spreadsheet_id}，共 {valid_updates_count} 個有效儲存格...")
              result = self.service.spreadsheets().values().batchUpdate(
                  spreadsheetId=spreadsheet_id,
                  body=body
              ).execute()
              total_updated = result.get('totalUpdatedCells', 0)
-             logging.info(f"批次更新完成。共更新了 {total_updated} 個儲存格。")
-             return result
+             logging.info(f"批次更新完成。API 回報共更新了 {total_updated} 個儲存格。")
+             # 可以在這裡比較 total_updated 和 valid_updates_count
+             if total_updated != valid_updates_count:
+                  logging.warning(f"預期更新 {valid_updates_count} 個儲存格，但 API 回報更新了 {total_updated} 個。")
+             return result # 返回實際的 API 回應
+         except googleapiclient.errors.HttpError as error: # 更具體地捕獲 HttpError
+             error_details = error.resp.get('content', '{}')
+             try:
+                 error_json = json.loads(error_details)
+                 error_message = error_json.get('error', {}).get('message', str(error))
+             except json.JSONDecodeError:
+                 error_message = str(error)
+             logging.error(f"批次更新儲存格時發生 API 錯誤 (ID: {spreadsheet_id}): {error_message}")
+             logging.error(f"錯誤詳情: {error.content.decode()}") # 打印詳細錯誤內容
+             return None # API 錯誤返回 None
          except Exception as e:
-             logging.error(f"批次更新儲存格時發生 API 錯誤: {e}")
-             # from googleapiclient.errors import HttpError
-             # if isinstance(e, HttpError):
-             #     logging.error(f"錯誤詳情: {e.content}")
-             return None
+             logging.error(f"批次更新儲存格時發生未知錯誤: {e}")
+             import traceback
+             traceback.print_exc()
+             return None # 其他錯誤返回 None