# Google 表單半自動化行政流程平台：Codex 開發技術文件

> 版本：v0.1  
> 目標：提供 Codex 接手開發「Google 表單半自動化行政流程平台」的產品需求、系統架構、資料表、Apps Script 模組與 MVP 開發任務。  
> 核心主張：**讓 Google 表單不只是收資料，而是行政流程的入口。**

---

## 1. 專案背景

學校與組織行政常使用 Google 表單處理：

- 人力調查
- 班親會回覆
- 親子活動報名
- 一般活動報名
- 研習報名
- 活動回饋
- 核銷資料上傳
- 設備報修

但真正耗費行政時間的，通常不是建立表單本身，而是表單送出後的後續流程：

- 寄送確認信
- 更新總名冊
- 處理修改與取消
- 通知承辦人
- 統計人數、餐點、人力缺口
- 列出未回覆名單
- 整理開放式意見
- 產生簽到表、名冊、成果摘要
- 保留異動紀錄
- 期限後鎖定資料

本系統目標是建立一套「Google 表單半自動化行政流程平台」，讓承辦人可透過表單專案建立器快速建立不同類型的行政表單，並依據表單類型自動套用對應的後續流程。

---

## 2. 產品定位

### 2.1 不是什麼

本系統不是要取代 Google 表單，也不是要重做一套完整表單系統。

### 2.2 是什麼

本系統是建立在 Google Workspace 上的表單後處理平台：

```text
Google Forms：收集資料
Google Sheets：儲存回應、設定與總表
Google Drive：建立專案資料夾與附件整理
Apps Script：自動化流程引擎
Gemini API：摘要、分類、提醒與草稿產生
```

### 2.3 核心概念

```text
一套表單專案建立器
＋
多種表單模板
＋
共用基礎流程
＋
不同情境 workflow 模組
＋
Gemini API 摘要與提醒
```

---

## 3. 系統目標

### 3.1 一般目標

1. 承辦人可以從「總控表單」建立新的表單專案。
2. 系統自動複製對應表單模板。
3. 系統自動建立專案資料夾。
4. 系統自動建立並綁定回應試算表。
5. 系統自動寫入設定表。
6. 系統依表單類型載入對應 workflow。
7. 填表者可在期限內修改資料。
8. 修改後自動更新有效總名冊。
9. 修改後通知承辦人並保留異動紀錄。
10. Gemini API 產生摘要、提醒與行政判讀輔助。

### 3.2 半自動化原則

系統自動完成：

- 建立表單
- 建立資料夾
- 建立回應 Sheet
- 寄確認信
- 建立修改連結
- 更新總名冊
- 統計人數
- 標記異常
- 產生摘要草稿

承辦人保留判斷：

- 啟用表單
- 確認欄位對應
- 審核特殊狀況
- 決定補件或取消
- 正式結案
- 發布最終通知

---

## 4. 使用者角色

| 角色 | 說明 |
|---|---|
| 系統管理者 | 建立模板、維護 Apps Script、設定 Gemini API Key、管理全域設定 |
| 承辦人 | 建立表單專案、調整表單、確認欄位、查看統計與異動 |
| 填表者 | 填寫表單、在期限內修改資料或取消 |
| AI/Gemini | 協助摘要、分類、提醒、產生草稿，不做最終決策 |

---

## 5. 完整流程

### 5.1 建立階段

```text
承辦人填寫「表單專案建立表」
↓
選擇表單類型
↓
系統複製對應 Google 表單模板
↓
系統建立專案資料夾
↓
系統建立回應試算表
↓
系統將表單連結到回應試算表
↓
系統寫入 form_instances 設定表
↓
系統建立初始欄位 mapping
↓
系統寄出「表單專案已建立」通知
↓
專案狀態：draft
```

### 5.2 調整階段

```text
承辦人修改表單標題、說明、選項或部分欄位
↓
承辦人回到管理介面或控制 Sheet 點選「檢查欄位」
↓
系統讀取目前表單欄位
↓
系統建立或更新 field_mapping
↓
承辦人確認欄位對應
↓
承辦人設定修改期限、名額、需求人數等
↓
承辦人啟用表單
↓
專案狀態：active
```

### 5.3 使用階段

```text
填表者送出表單
↓
回應資料進入 response Sheet
↓
Apps Script onFormSubmit 觸發
↓
系統讀取 form_instances 設定
↓
系統執行共用基礎模組
    - 產生填報編號
    - 產生修改 token
    - 寫入有效總名冊
    - 寫入歷史紀錄
    - 寄確認信
    - 通知承辦人
↓
系統依 workflow_type 執行專屬流程
    - 人力調查：統計各時段人力
    - 班親會：統計出席與未回覆
    - 親子活動：統計家庭、人數、餐點、保險
    - 活動報名：處理錄取、候補、取消
↓
Gemini API 產生摘要與提醒
↓
更新總覽與統計表
```

### 5.4 修改階段

```text
填表者點擊確認信中的修改連結
↓
系統檢查 token 是否有效
↓
系統檢查是否在修改期限內
↓
顯示原始資料
↓
填表者修改資料或取消參加
↓
系統比對前後差異
↓
系統更新有效總名冊
↓
系統寫入 response_history
↓
系統通知承辦人異動內容
↓
系統重新統計人數或人力缺口
↓
Gemini API 產生異動影響摘要
```

### 5.5 結束階段

```text
到達修改截止期限
↓
系統鎖定一般填表者修改功能
↓
承辦人仍可於後台手動修正
↓
系統產生最終名冊、簽到表或統計摘要
↓
活動後寄出回饋表
↓
Gemini API 摘要回饋
↓
產生成果報告草稿
↓
專案狀態：archived
```

---

## 6. 表單模板與 workflow 類型

### 6.1 支援的模板

| template_code | 名稱 | workflow_type |
|---|---|---|
| STAFFING_SURVEY | 人力調查表 | staffing_flow |
| CLASS_PARENT_MEETING | 班親會調查表 | parent_meeting_flow |
| FAMILY_EVENT | 親子活動報名表 | family_event_flow |
| EVENT_REGISTRATION | 一般活動報名表 | event_registration_flow |
| TRAINING_REGISTRATION | 研習報名表 | event_registration_flow |
| FEEDBACK_SURVEY | 活動回饋問卷 | feedback_flow |
| REIMBURSEMENT_UPLOAD | 核銷資料上傳表 | reimbursement_flow |
| REPAIR_REPORT | 設備報修表 | repair_flow |

### 6.2 共用模組

| 模組 | 函式建議名稱 | 說明 |
|---|---|---|
| 表單複製 | copyTemplateForm() | 複製母模板表單 |
| 資料夾建立 | createProjectFolder() | 建立專案資料夾與子資料夾 |
| 回應表建立 | createResponseSheet() | 建立回應 Sheet 並綁定表單 |
| 設定寫入 | createFormInstance() | 寫入 form_instances |
| 欄位讀取 | readFormFields() | 讀取表單欄位 |
| 欄位對應 | buildFieldMapping() | 建立標準欄位對應 |
| 填報編號 | generateCaseNo() | 產生唯一填報編號 |
| 修改 token | generateEditToken() | 建立修改連結 token |
| 確認信 | sendConfirmationEmail() | 寄送確認與修改連結 |
| 異動通知 | notifyOwnerChange() | 通知承辦人修改內容 |
| 歷史紀錄 | writeResponseHistory() | 保存修改前後資料 |
| Gemini 摘要 | callGeminiSummary() | 呼叫 Gemini API 產生摘要 |
| 狀態更新 | updateStatus() | 更新專案或填報狀態 |

### 6.3 workflow 模組

| workflow_type | 函式建議名稱 | 核心工作 |
|---|---|---|
| staffing_flow | runStaffingFlow() | 統計各日期/時段人力，判斷不足或超過 |
| parent_meeting_flow | runParentMeetingFlow() | 統計家長出席、未回覆、提問摘要 |
| family_event_flow | runFamilyEventFlow() | 統計家庭、人數、餐點、保險與特殊需求 |
| event_registration_flow | runEventRegistrationFlow() | 處理錄取、候補、取消、活動提醒 |
| feedback_flow | runFeedbackFlow() | 摘要回饋、滿意度統計、成果草稿 |
| reimbursement_flow | runReimbursementFlow() | 檢查附件、缺件、金額與核銷狀態 |
| repair_flow | runRepairFlow() | 分類報修案件、通知負責人、追蹤狀態 |

---

## 7. Google Sheets 控制中心設計

建議建立一份「系統控制中心」Google Sheet，包含以下工作表。

```text
settings
form_templates
form_instances
field_mapping
responses
response_history
workflow_requirements
email_templates
ai_prompts
logs
```

---

## 8. 資料表規格

### 8.1 settings

| 欄位 | 說明 |
|---|---|
| key | 設定鍵 |
| value | 設定值 |
| note | 備註 |

範例：

| key | value |
|---|---|
| ROOT_FOLDER_ID | Google Drive 根資料夾 ID |
| SYSTEM_OWNER_EMAIL | 系統管理者 email |
| GEMINI_MODEL | gemini-2.5-flash |
| DEFAULT_EDIT_DAYS | 3 |

> 注意：Gemini API Key 不建議明碼放在 Sheet 中。Apps Script 端建議使用 PropertiesService 儲存。

---

### 8.2 form_templates

| 欄位 | 說明 |
|---|---|
| template_code | 模板代碼 |
| template_name | 模板名稱 |
| workflow_type | workflow 類型 |
| template_form_id | 母模板 Google Form ID |
| default_folder_structure | 預設資料夾結構，可 JSON |
| status | active / inactive |

---

### 8.3 form_instances

| 欄位 | 說明 |
|---|---|
| instance_code | 表單專案代碼 |
| template_code | 來源模板 |
| workflow_type | workflow 類型 |
| project_name | 專案名稱 |
| form_id | 實際 Google Form ID |
| response_sheet_id | 回應 Sheet ID |
| project_folder_id | 專案資料夾 ID |
| owner_name | 承辦人姓名 |
| owner_email | 承辦人 Email |
| start_date | 活動開始日期 |
| end_date | 活動結束日期 |
| form_deadline | 填寫截止期限 |
| edit_deadline | 修改截止期限 |
| capacity | 名額上限 |
| status | draft / active / closed / archived |
| created_at | 建立時間 |
| updated_at | 更新時間 |

---

### 8.4 field_mapping

| 欄位 | 說明 |
|---|---|
| instance_code | 表單專案代碼 |
| standard_key | 標準欄位 key |
| form_field_title | 實際表單欄位名稱 |
| required | 是否必填 |
| field_type | text / email / phone / checkbox / radio / date / number |
| enabled | TRUE/FALSE |

標準欄位範例：

| standard_key | 說明 |
|---|---|
| name | 姓名 |
| email | 電子郵件 |
| phone | 電話 |
| unit | 單位 |
| note | 備註 |
| availability | 可參加時段 |
| adult_count | 成人數 |
| child_count | 兒童數 |
| meal | 餐點 |
| question | 提問內容 |

---

### 8.5 responses

此表保存「目前有效資料」，是總名冊來源。

| 欄位 | 說明 |
|---|---|
| response_id | 系統內部 ID |
| instance_code | 表單專案代碼 |
| case_no | 填報編號 |
| form_response_id | Google Form response ID |
| name | 姓名 |
| email | 電子郵件 |
| phone | 電話 |
| unit | 單位 |
| normalized_json | 標準化資料 JSON |
| raw_json | 原始資料 JSON |
| edit_token_hash | 修改 token hash |
| edit_deadline | 修改期限 |
| status | active / modified / cancelled / locked / manual_review |
| last_modified_at | 最後修改時間 |
| created_at | 建立時間 |

---

### 8.6 response_history

每次新增、修改、取消都寫入歷史表。

| 欄位 | 說明 |
|---|---|
| history_id | 歷史紀錄 ID |
| response_id | 對應 responses |
| instance_code | 表單專案代碼 |
| action | created / modified / cancelled / admin_edit |
| before_json | 修改前 JSON |
| after_json | 修改後 JSON |
| diff_summary | 差異摘要 |
| modified_by | user / admin |
| modified_at | 修改時間 |
| notified | TRUE/FALSE |

---

### 8.7 workflow_requirements

用於人力調查、親子活動、場次報名等需求判斷。

| 欄位 | 說明 |
|---|---|
| instance_code | 表單專案代碼 |
| slot_key | 場次或時段代碼 |
| slot_label | 顯示名稱 |
| required_count | 需求人數 |
| max_count | 上限人數 |
| note | 備註 |

範例：

| slot_key | slot_label | required_count | max_count |
|---|---|---:|---:|
| day1_am | 6/10 上午 | 5 | 8 |
| day1_pm | 6/10 下午 | 5 | 8 |
| day2_am | 6/11 上午 | 5 | 8 |
| day2_pm | 6/11 下午 | 5 | 8 |

---

### 8.8 email_templates

| 欄位 | 說明 |
|---|---|
| template_code | 信件模板代碼 |
| subject | 主旨 |
| body_html | HTML 內容 |
| workflow_type | 適用 workflow |
| status | active / inactive |

可用變數：

```text
{{name}}
{{case_no}}
{{project_name}}
{{edit_url}}
{{edit_deadline}}
{{owner_email}}
{{summary}}
```

---

### 8.9 ai_prompts

| 欄位 | 說明 |
|---|---|
| prompt_code | Prompt 代碼 |
| workflow_type | workflow 類型 |
| purpose | summary / diff / risk / report |
| prompt_text | Prompt 內容 |
| output_schema | JSON Schema |
| status | active / inactive |

---

### 8.10 logs

| 欄位 | 說明 |
|---|---|
| log_id | 紀錄 ID |
| timestamp | 時間 |
| level | INFO / WARN / ERROR |
| instance_code | 表單專案代碼 |
| action | 執行動作 |
| message | 訊息 |
| payload_json | 補充資料 |

---

## 9. 重要功能規格

### 9.1 表單專案建立器

承辦人填寫「表單專案建立表」後，系統自動：

1. 讀取 template_code
2. 複製 template_form_id
3. 建立專案資料夾
4. 建立回應 Sheet
5. 將 Form destination 設為該 Sheet
6. 寫入 form_instances
7. 初步讀取表單欄位
8. 建立 field_mapping 草稿
9. 發信通知承辦人

---

### 9.2 欄位確認

承辦人修改表單後，系統需支援重新讀取欄位：

1. 讀取目前 Google Form 的所有 item title
2. 與 standard_key 做初步配對
3. 寫入 field_mapping
4. 承辦人可手動修正
5. 啟用前檢查必要欄位是否存在

---

### 9.3 修改連結

系統產生 token：

```text
edit_token = random UUID / secure random string
edit_token_hash = SHA-256(edit_token)
edit_url = Web App URL + ?token=edit_token
```

注意事項：

- Sheet 中只保存 hash，不保存明碼 token。
- token 應有期限。
- 期限過後一般使用者不可修改。
- 承辦人後台仍可 admin_edit。

---

### 9.4 修改資料流程

填表者進入 edit_url 後：

1. 系統驗證 token
2. 查詢 responses
3. 檢查 edit_deadline
4. 顯示可修改欄位
5. 儲存後：
   - 更新 responses.normalized_json
   - 更新 responses.status = modified 或 cancelled
   - 寫入 response_history
   - 通知 owner_email
   - 執行 workflow 重新統計
   - 呼叫 Gemini 產生異動摘要

---

### 9.5 總名冊

總名冊來源永遠以 responses 表為準，不直接用原始 Form Response Sheet。

原因：

- Google Form 回應可能有多筆重複
- 使用者可能修改或取消
- 系統需維持一筆有效紀錄
- 需保留歷史但不污染當前名冊

---

## 10. Gemini API 設計

### 10.1 使用原則

Gemini 不負責精確計算，精確計算由 Apps Script 完成。

Apps Script 負責：

- 計算人數
- 判斷低於需求
- 判斷超過上限
- 找出異動資料
- 建立統計 JSON

Gemini 負責：

- 摘要現況
- 解釋異動影響
- 產生承辦人提醒
- 整理開放式意見
- 產生報告草稿

---

### 10.2 Structured Output

Gemini API 建議使用結構化輸出，要求回傳 JSON。官方文件指出 Gemini API 可依 JSON Schema 產生結構化結果，適合資料抽取、分類與工作流處理。

範例輸出 schema：

```json
{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "risk_level": { "type": "string", "enum": ["low", "medium", "high"] },
    "key_findings": {
      "type": "array",
      "items": { "type": "string" }
    },
    "suggested_actions": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["summary", "risk_level", "key_findings", "suggested_actions"]
}
```

---

### 10.3 人力調查摘要 Prompt 範例

```text
你是學校行政人力調查助理。請根據以下統計資料，產生給承辦人的摘要。

請注意：
1. 不要自行重新計算人數。
2. 只根據輸入資料判斷。
3. 請指出哪個日期或時段人力不足、足夠或超過。
4. 請列出最近異動對人力的影響。
5. 請提供具體但保守的處理建議。

輸入資料：
{{stats_json}}

請用 JSON 回傳：
{
  "summary": "...",
  "risk_level": "low|medium|high",
  "key_findings": ["..."],
  "suggested_actions": ["..."]
}
```

---

## 11. Apps Script 模組規劃

建議檔案結構：

```text
Code.gs
Config.gs
FormProjectService.gs
FormTemplateService.gs
FolderService.gs
SheetService.gs
MappingService.gs
ResponseService.gs
HistoryService.gs
EmailService.gs
GeminiService.gs
WorkflowRouter.gs
workflows/StaffingFlow.gs
workflows/ParentMeetingFlow.gs
workflows/FamilyEventFlow.gs
workflows/EventRegistrationFlow.gs
workflows/FeedbackFlow.gs
workflows/ReimbursementFlow.gs
workflows/RepairFlow.gs
WebApp.gs
Utils.gs
```

### 11.1 入口函式

```javascript
function onProjectCreateSubmit(e) {
  // 處理總控表單送出，建立表單專案
}

function handleFormSubmit(e) {
  // 處理各實際表單送出
}

function doGet(e) {
  // 顯示修改頁或管理頁
}

function doPost(e) {
  // 儲存修改資料
}
```

### 11.2 Workflow Router

```javascript
function runWorkflow(eventType, instance, responseData) {
  switch (instance.workflow_type) {
    case 'staffing_flow':
      return runStaffingFlow(eventType, instance, responseData);

    case 'parent_meeting_flow':
      return runParentMeetingFlow(eventType, instance, responseData);

    case 'family_event_flow':
      return runFamilyEventFlow(eventType, instance, responseData);

    case 'event_registration_flow':
      return runEventRegistrationFlow(eventType, instance, responseData);

    case 'feedback_flow':
      return runFeedbackFlow(eventType, instance, responseData);

    default:
      return runDefaultFlow(eventType, instance, responseData);
  }
}
```

---

## 12. Workflow 詳細規格

### 12.1 人力調查 staffing_flow

#### 目標

支援多日期、多時段人力調查，允許填表者在期限內修改。

#### 主要欄位

- name
- email
- phone
- unit
- availability
- role_preference
- flexible_support
- note

#### 功能

1. 統計各時段可參加人數
2. 比對 workflow_requirements
3. 判斷不足、足夠、超過
4. 修改後重新計算
5. 通知承辦人異動影響
6. Gemini 產生總覽摘要

#### 統計輸出

```json
{
  "slots": [
    {
      "slot_key": "day1_am",
      "slot_label": "6/10 上午",
      "required_count": 5,
      "current_count": 3,
      "gap": -2,
      "status": "shortage"
    }
  ],
  "recent_changes": [
    {
      "name": "王小明",
      "change": "6/10 上午由可參加改為不可參加",
      "impact": "day1_am 人力 -1"
    }
  ]
}
```

---

### 12.2 班親會 parent_meeting_flow

#### 目標

支援班親會出席調查、家長提問摘要與未回覆名單。

#### 主要欄位

- student_name
- class_no
- parent_name
- email
- phone
- attendance
- attendance_mode
- attendee_count
- questions
- suggestions

#### 功能

1. 統計出席、無法出席、未回覆
2. 統計實體/線上參加
3. 列出未回覆學生
4. Gemini 摘要家長關注議題
5. 產生班親會討論重點
6. 會後可產生會議紀錄草稿

---

### 12.3 親子活動 family_event_flow

#### 目標

以家庭為單位處理親子活動報名。

#### 主要欄位

- student_name
- parent_name
- email
- phone
- adult_count
- child_count
- meal
- transport
- insurance_info
- special_needs

#### 功能

1. 統計家庭數
2. 統計成人數、兒童數、總人數
3. 統計餐點
4. 統計交通方式
5. 檢查保險資料是否完整
6. 修改後更新人數、餐點、保險名冊
7. Gemini 摘要特殊需求

---

### 12.4 一般活動 event_registration_flow

#### 目標

處理一般活動、研習、講座報名。

#### 主要欄位

- name
- email
- unit
- phone
- session
- meal
- certificate_needed
- note

#### 功能

1. 產生報名編號
2. 判斷錄取/候補
3. 允許期限內修改或取消
4. 修改後自動調整名單
5. 產生簽到表
6. 活動前寄提醒
7. 活動後寄回饋表

---

## 13. 權限與安全

### 13.1 API Key

- Gemini API Key 不可寫在前端。
- Apps Script 中使用 PropertiesService 儲存。
- 不要將 Key 放入公開 GitHub。

### 13.2 修改 token

- token 明碼只寄給填表者。
- Sheet 中只保存 hash。
- token 應有期限。
- 修改頁不得暴露其他填表者資料。

### 13.3 個資

系統會處理姓名、電話、email、學生姓名、保險資料等個資，需注意：

- 權限限縮
- 不公開共享 Sheet
- 報表匯出需遮蔽不必要個資
- Gemini 呼叫時只送必要欄位，避免送過量個資

---

## 14. 技術注意事項

1. Google Apps Script 可透過 Forms Service 建立、存取與修改 Google Forms。
2. Google Form 可設定回應目的地為 Google Sheets。
3. onFormSubmit 可作為表單或試算表提交後的觸發流程。
4. Apps Script installable triggers 有數量與授權限制；若每張表單都建立獨立觸發器，需注意擴充性。
5. Gemini API 應使用 structured output，避免自由文字造成後續解析錯誤。
6. 對於多表單，建議用「主程式 + workflow_type router」，不要每一張表單複製一份獨立 Apps Script。
7. 精確統計由程式完成，Gemini 僅負責摘要與建議。
8. 所有自動寄信內容建議保留 logs。
9. 修改資料一定要保留 response_history，不可只覆蓋資料。
10. 總名冊以 responses 有效資料為準，不直接依賴原始 Form Response。

---

## 15. MVP 開發範圍

### 15.1 MVP 只做一個模板

建議第一版先做：

```text
人力調查表 staffing_flow
```

原因：

- 可展示可修改機制
- 可展示人力缺口統計
- 可展示 Gemini 摘要價值
- 比一般報名表更能凸顯行政流程平台價值

### 15.2 MVP 功能

1. 總控表單建立人力調查專案
2. 複製人力調查模板
3. 建立專案資料夾
4. 建立回應 Sheet
5. 寫入 form_instances
6. 建立 field_mapping
7. 表單送出後：
   - 建立填報編號
   - 寫入 responses
   - 產生修改連結
   - 寄確認信
   - 通知承辦人
8. 填表者可用修改連結修改資料
9. 修改後：
   - 更新 responses
   - 寫入 response_history
   - 通知承辦人前後差異
   - 重新統計人力
10. Gemini 產生人力總覽摘要

### 15.3 MVP 暫不做

- 完整後台 Web UI
- 多模板管理介面
- 核銷附件上傳
- 報修派工
- 複雜權限系統
- LINE/Google Chat 通知
- 自動產生 PDF 報告

---

## 16. Codex 開發任務拆解

### Phase 1：基礎設定與資料表

- 建立 Apps Script 專案結構
- 建立設定常數
- 建立 Sheet 讀寫工具
- 建立 settings/form_templates/form_instances/responses/response_history/logs 讀寫函式

### Phase 2：表單專案建立器

- 實作 onProjectCreateSubmit(e)
- 複製模板表單
- 建立專案資料夾
- 建立回應 Sheet
- 綁定 Form destination
- 寫入 form_instances
- 寄通知信給承辦人

### Phase 3：表單送出處理

- 實作 handleFormSubmit(e)
- 找到 instance 設定
- 解析欄位 mapping
- 建立 response_id / case_no
- 寫入 responses
- 產生 edit_token
- 寄確認信
- 通知承辦人

### Phase 4：修改頁

- 實作 doGet(e)
- 驗證 token
- 顯示可修改欄位 HTML
- 實作 doPost(e)
- 更新 responses
- 寫入 response_history
- 通知承辦人

### Phase 5：人力統計

- 實作 workflow_requirements 讀取
- 統計各時段人數
- 判斷 shortage / ok / overflow
- 產生 stats_json
- 寫入統計 Sheet 或 dashboard tab

### Phase 6：Gemini API

- 實作 GeminiService
- 設定 API Key
- 實作 structured output 呼叫
- 將人力統計資料送入 Gemini
- 解析 JSON 回傳
- 寫入 summary
- 寄給承辦人

### Phase 7：穩定性

- 錯誤處理
- logs
- 權限檢查
- token hash
- 避免重複處理
- 防止空資料或欄位缺失造成流程中斷

---

## 17. 驗收標準

### 17.1 建立專案

- 承辦人送出總控表單後，系統能建立新 Google Form。
- 系統能建立專案資料夾。
- 系統能建立並綁定回應 Sheet。
- form_instances 有正確記錄。
- 承辦人收到通知。

### 17.2 填表

- 使用者送出表單後，responses 出現一筆有效資料。
- case_no 正確產生。
- 使用者收到確認信與修改連結。
- 承辦人收到新填報通知。

### 17.3 修改

- 使用者可於期限內修改。
- 修改後 responses 更新。
- response_history 保留前後資料。
- 承辦人收到修改通知。
- 修改後人力統計同步更新。

### 17.4 Gemini

- 系統可將統計 JSON 傳給 Gemini API。
- Gemini 回傳 JSON 格式摘要。
- 摘要能指出人力不足或超過的場次。
- 摘要可寫入 Sheet 或寄給承辦人。

---

## 18. 未來擴充

1. 班親會調查模板
2. 親子活動報名模板
3. 一般活動報名模板
4. 活動回饋模板
5. 核銷上傳模板
6. 設備報修模板
7. Apps Script Web App 管理後台
8. Bootstrap 5 後台介面
9. Google Chat / LINE / Telegram 通知
10. PDF 報告自動產生
11. 權限角色管理
12. 多承辦人協作
13. 學校或組織多單位管理

---

## 19. 參考官方文件

- Google Apps Script Forms Service：可建立、存取與修改 Google Forms。
- Google Apps Script Form Class：包含與表單操作相關的方法。
- Gemini API Structured Output：可要求模型依 JSON Schema 回傳結構化資料。
- Gemini API Reference：REST API 與 generateContent API 相關參考。

---

## 20. 給 Codex 的開發原則

1. 先完成 MVP，不要一開始就做全部模板。
2. 資料結構優先，介面其次。
3. 共用模組優先，不要為每個模板複製一份程式。
4. 所有 workflow 都走 WorkflowRouter。
5. 所有 AI 輸出都必須可解析為 JSON。
6. 精確統計不要交給 AI。
7. 所有異動都要寫入 response_history。
8. 所有寄信與 AI 呼叫都要寫入 logs。
9. token 不可明碼保存。
10. 系統要允許半自動：承辦人可確認、修正、覆核與結案。

---

# 附錄 A：建議專案命名

```text
google-form-admin-flow
```

中文名稱：

```text
Google 表單半自動化行政流程平台
```

---

# 附錄 B：一句話產品說明

讓 Google 表單不只是收資料，而是成為行政流程的入口；透過模板、流程模組、修改機制、總名冊與 Gemini 摘要，讓每一張表單都能接上可追蹤、可更新、可判斷的半自動化行政流程。