安裝與使用教學
這份教學是〈使用手冊〉的網頁版，內容一律以
docs/使用手冊.md 為準，畫面名稱、按鈕文字、錯誤訊息都是直接從程式裡抄出來的。
如果你看到的畫面跟這裡寫的不一樣，代表版本不同，請聯絡供應商。
1. 拿到授權信之後：下載、解壓縮
供應商確認收到你的付款之後，系統會自動寄一封信到你留的 Email，主旨是 「【嘉義街頭藝人登記 RPA】您的授權已開通」。信裡有你的授權碼（一長串英數字）、 到期日，以及一個「下載安裝包」按鈕。
依據：php/lib/mail.php 第 96-114 行的信件樣板。
點「下載安裝包」會下載一個 .zip 壓縮檔（檔名裡有 booking-chiayi 字樣）。
這個下載連結有兩個限制（php/lib/download.php 第 26-27 行）：
| 限制 | 預設值 |
|---|---|
| 有效期限 | 24 小時 |
| 最多下載次數 | 3 次 |
超過時限或用完次數，連結會失效，需要重新申請一份新的（可自己到「我的授權」頁申請）。
下載回來的 zip 檔，滑鼠右鍵點它 →「解壓縮全部」，選一個你記得住的地方（例如桌面），
解開後會得到一個資料夾，裡面至少有 嘉義街頭藝人登記.exe（主程式）、
chrome-extension\ 資料夾（Chrome 擴充）、一份說明文字檔。
dist\嘉義街頭藝人登記\ 底下確實有這個結構
（嘉義街頭藝人登記.exe、chrome-extension\、data\、
logs\、runtime\），但正式交付包由打包工單另行產生，
最終 zip 內容以實際打包輸出為準。
2. 載入 Chrome 擴充
只要做一次（除非之後供應商說擴充有更新）。
- 打開 Chrome，網址列輸入：
chrome://extensions - 右上角把「開發人員模式」打開
- 點「載入未封裝項目」
- 選你解壓縮出來的資料夾底下的
chrome-extension資料夾（不是外層那個大資料夾） - 載入後會看到一個叫「WebOP 嘉義街頭藝人登記」的擴充
依據：chrome-extension\manifest.json 第 3 行 "name": "WebOP 嘉義街頭藝人登記"。
這個擴充要保持啟用狀態，不要之後手動關掉——關掉之後主程式會顯示「擴充未連線」， 登記完全跑不動（見第 10 節）。
3. 啟動主程式
雙擊 嘉義街頭藝人登記.exe。
- 會跳出一個黑色視窗，那是程式本體在背景執行，不要關掉它，可以縮到工作列。
- 幾秒鐘後瀏覽器會自動打開，網址是
http://127.0.0.1:12350/run，這就是操作台。
依據：launcher.py 第 97-125 行 run_all()——先啟動引擎（port 57893）、
等健康檢查通過、再啟動操作台（port 12350）、最後開啟瀏覽器。
操作台上方有五個分頁（operator_ui.py 第 766-767 行）：
| 分頁 | 網址 | 用途 |
|---|---|---|
| 執行 | /run | 開始登記、看即時進度、中止 |
| 工作單 | /jobs | 設定每位表演者的日期／次數目標 |
| 表演者 | /performers | 新增／編輯表演者資料與證件圖 |
| 歷史 | /history | 過去每一筆登記的結果 |
| 設定 | /settings | 檔案位置（唯讀，不用設定） |
畫面最上面一列有一個小圓點：灰色＝閒置，亮綠色＝執行中。
第一次啟動要做的事：填授權碼（第 4 節）、新增至少一位表演者（第 5 節）。 資料夾（照片、工作單、log）不需要另外設定——就是主程式所在的那個資料夾，子資料夾會自動建立。
4. 授權碼填在哪
operator_ui.py 全部 5 個分頁與 /api/* 路由，「設定」分頁只顯示唯讀路徑）。
實際填法是用記事本開啟主程式資料夾底下的 runtime\license_config.json
（沒有這個檔案就自己新建一個），內容格式如下：
{
"license_key": "把信裡的授權碼貼在這裡"
}
依據：license_client.py 第 20-23 行「設定／狀態檔」說明——
runtime/license_config.json {"base_url", "license_key", "device_token"}，
「base_url／license_key 是人工／出貨時填的；device_token 由 activate() 成功後自動寫回」。
這一步對完全不懂技術的使用者來說偏技術，建議由供應商決定是否在打包時先寫好、
或在操作台加一個填授權碼的畫面。在那個決定之前，請依上面的方式手動填。
填完授權碼、程式重新整理後：
- 操作台右上角會出現一個授權狀態小標籤：
- 授權異常（紅底）：例如「授權異常：查無此授權金鑰」
- 授權 ○○○ · 到期 2026-12-31 · api（綠底）：代表已生效
- 授權檢查每 4 分鐘在背景自動做一次，不用手動按什麼按鈕去「連線」。
授權沒通過的話，「開始」按鈕按下去會直接被拒絕（不只是隱藏按鈕）——這是刻意的設計，不是 bug。
依據：operator_ui.py 第 889-898、1657-1668、1857-1886 行。
5. 新增表演者、上傳街頭藝人證
到「表演者」分頁，按「＋ 新增表演者」。
要填的欄位（operator_ui.py 第 1306-1319 行）：
| 欄位 | 說明 |
|---|---|
| 姓名 | 必填 |
| 登入帳號（本人手機） | 格式要求 09 開頭共 10 碼，例如 0912345678 |
| 登入密碼 | 這是登入政府網站會員中心用的密碼，不是這套軟體的密碼 |
| 街頭藝人證號 | |
| 身分證字號 | |
| 聯絡電話1 | 建議 09 開頭 10 碼 |
| 縣市 / 區 / 地址（路巷號） | |
| 展演項目 | 下拉選單：唱歌／樂器／其他 |
| 街頭藝人證圖 | 上傳圖檔（.jpg .jpeg .png） |
帳號格式檢查：登入帳號沒填 09 開頭 10 碼手機格式，存檔時會跳出
「登入帳號要是 09 開頭 10 碼手機」（operator_ui.py 第 1383 行）。
密碼與身分證字號只寫不讀：每次打開編輯畫面這兩欄都是空的，留空代表不變更，不是「清空」
（operator_ui.py 第 1328-1330 行）。
證件圖上傳規則：
- 大小上限 10MB，超過會回「證件圖超過 10MB」（
operator_ui.py第 651-652 行） - 上傳後檔名會自動改成
<表演者代號>.jpg，之後就算改姓名，系統照樣找得到這張圖 （operator_ui.py第 653、328-330 行）
存檔成功後，表演者清單那張表格會秒更新（不用等 15 秒的快取）。
授權可能限制表演者人數：如果你的授權有設「最多幾位表演者」的上限
（max_performers，0 代表沒有限制），新增到超過上限時會出現
「目前授權最多 N 位表演者（已建立 N 位）。要增加請聯絡供應商。」
（operator_ui.py 第 1637-1648 行）。這個限制只擋新增，不擋你編輯已經建好的資料。
刪除表演者：按「編輯」進去、下方「刪除這位」，會跳確認框
「確定刪除這位表演者的憑證？證件圖不會被刪。」（operator_ui.py 第 1371 行）——
證件圖檔案不會被連帶刪除。
6. 建立工作單
到「工作單」分頁。
新增一筆：選姓名、填日期（格式一定要是 2026/10/14 這種四碼年／二碼月／二碼日，
斜線分隔）、填次數，按「新增」（operator_ui.py 第 1281-1286 行；
日期格式驗證見第 1283 行的規則 /^\d{4}\/\d{2}\/\d{2}$/）。
「次數」的意思要弄清楚：工作單上的次數是「這個日期總共要跑滿幾筆」的目標， 不是你按一次「開始」就會自動跑那麼多。這是刻意的提示文字：
（operator_ui.py 第 1093-1095 行，在「執行」分頁顯示）
工作單表格每一列會即時顯示：已完成 / 剩餘 / 進度條 / 預估還要多久。
修改次數後，畫面上會出現「有未儲存的變更」標籤，一定要按「儲存」才會真的寫進去；
按「放棄變更」可以取消（operator_ui.py 第 1209-1211 行）。
執行中的時候，工作單整頁鎖住不能改（見第 9 節）。
工作單實際存在檔案 data\jobs.json，「設定」分頁可以看到完整路徑
（operator_ui.py 第 1213、69 行）。
7. 執行登記
到「執行」分頁。
- 上方「作用中的表演者」下拉選單選人，按「切換」——這套軟體一次只跑一位表演者， 要換人一定要在這裡切換（提示文字：「一次只跑這一位。要換人請在上面選好再按切換。」）。 如果你的授權有開通多人模式，可以勾選「多人一起排」，同時勾選多位表演者， 用同一組日期／次數一起登記；沒開通的話這個選項會是灰色不能點。
- 選「工作單」下拉（會列出這位表演者的每一筆目標），或直接填「日期」與「這次要跑幾筆」。
- 按「帶入剩餘」可以把選定日期「還沒跑完的次數」自動帶進「這次要跑幾筆」欄位—— 如果已經跑滿了，會提醒你「這筆已經跑滿了」，並把筆數先帶成 1。
- 「單筆失敗重試」：預設 1 次，代表單筆卡住失敗時自動再試幾次。
- 想先看看會跑什麼、不想真的送出，勾選「試算：只列出要跑什麼，不開瀏覽器、不送件」。
- 按「開始」。
按「開始」之前系統會先做這些檢查，任何一項沒過都會直接跳出訊息、不會開始跑：
- 授權是否有效
- 是否已經有另一批在跑
- 是否有其他分頁也開著操作台（多開分頁會鎖死不能按開始）
- Chrome 擴充是否已連線（試算模式不受此限）
- 是否選了作用中的表演者、有沒有上傳證件圖
- 授權的「每日登記上限」是否會被超過
以上任何一項擋下時看到的實際文字，見第 10 節。
依據：operator_ui.py 第 908-933、1046、1093-1124、1657-1780 行。
8. 怎麼看進度、預估還要多久
「執行」分頁上方四張卡片：
| 卡片 | 內容 |
|---|---|
| 狀態 | 執行中 / 閒置（執行中會有橘色呼吸燈號） |
| 本批進度 | 例如 12/40，下面會顯示「這批還要約 X 分（剩 Y 筆）」 |
| 目前步驟 | 目前卡在哪個站別（例如登入、選日期、填表…） |
| 今日成功 | 今天已經成功登記幾筆 |
（operator_ui.py 第 917-923 行）
下方「這位的工作單」表格顯示這位表演者每個日期的已完成／總數／進度條／剩餘／預估還要。
預估時間怎麼算：用「單筆耗時的中位數」乘以「剩餘筆數」，不是用平均——因為單筆耗時 從 28.9 秒到 117.2 秒都出現過，平均會被極端值拉歪，中位數比較穩。 樣本優先用「這位表演者、這個日期」自己的紀錄，不足 3 筆才退回最近 30 筆的整體中位數； 完全沒有樣本時會顯示「—」，不會硬編一個數字給你看。
（operator_ui.py 第 359-388 行 summarise()）
點開「即時日誌（點擊展開）」可以看逐行的執行紀錄，來源可切換「批次」或「單筆細節」
（operator_ui.py 第 958-966 行）。
執行中，整個畫面會進入「唯讀」狀態：工作單、表演者、切換人員全部鎖住不能改， 畫面上會出現一條橘色提示「批次執行中 —— 工作單、表演者、切換人員都暫時鎖住了， 這時候只能看進度與日誌。要改東西請先按「中止」。」就算是別的畫面（例如你重開了程式）啟動的那一批， 一樣會被偵測到、一樣鎖住，訊息會多一句「這批不是從目前這個畫面開始的」。
（operator_ui.py 第 754-756、871-877 行）
9. 怎麼中止
「執行」分頁按「中止」。
- 已經跑完的筆數不會被撤銷，紀錄都留著。
- 中止後可以馬上再按「開始」重新排，不會重複跑已經成功的那幾筆 （工作單的「已完成」數字是照全部歷史紀錄算的，不是只看這一批）。
10. 常見錯誤訊息怎麼判讀
下面每一句都是直接抄自程式碼的實際訊息（不是意譯）。
「執行」分頁按不下去 / 按了跳出訊息
| 看到的訊息 | 意思 | 怎麼辦 |
|---|---|---|
| 授權相關（見下方「授權訊息」表） | 授權沒通過檢查 | 依訊息內容處理，見下表 |
| 已經有一個批次在跑（行程 XXXX）。要重跑請先按「中止」，或等它跑完。 | 有另一批還沒跑完 | 等它跑完，或按「中止」 |
| 偵測到有 N 個分頁開著操作台。請只留一個，把其他的關掉再按開始（關掉之後最多 12 秒就會自動解除）。 | 你開了不只一個操作台分頁 | 關掉多餘分頁，等 12 秒 |
| 引擎沒有回應。（後面會接原因） | WebOP 引擎沒起來 | 重開主程式 |
| Chrome 擴充還沒連上，RPA 沒有瀏覽器可以操作。請到 chrome://extensions →「開發人員模式」打開 →「載入未封裝項目」→ 選本專案的 chrome-extension 資料夾。 | 擴充沒載入或被移除 | 照訊息重新載入擴充（見第 2 節） |
| 多人預約是加值功能，目前授權未開通 | 授權沒開多人模式 | 多人模式目前尚未開放購買 |
| {表演者名} 還沒有證件圖，請先到「表演者」上傳 | 缺證件圖 | 到「表演者」分頁上傳 |
| 尚未選擇作用中的表演者 | 沒切換人 | 到上方選人、按切換 |
| 沒填日期，這位也沒有工作單 | 日期空白且沒有工作單可帶 | 填日期或先建工作單 |
| 目前授權每日上限 N 筆（今日已完成 N 筆，本次要跑 N 筆）。要增加請聯絡供應商。 | 超過每日上限 | 明天再跑，或聯絡供應商 |
（依據：operator_ui.py 第 495-502、1665-1780 行）
授權訊息（右上角小標籤，或「開始」被擋時顯示）
| 訊息 | 意思 |
|---|---|
| 授權模組未就緒 | 程式本身異常，聯絡供應商 |
| 訂閱已於 YYYY-MM-DD 到期，請續訂 | 授權過期，需續訂 |
| 授權請求格式錯誤，請聯絡供應商 | （HTTP 400） |
| 裝置未授權，請重新啟用 | （HTTP 401） |
| 授權已停權，請聯絡供應商 | （HTTP 403） |
| 查無此授權金鑰 | 授權碼填錯或還沒開通 |
| 裝置數已達上限 | 這組授權碼已經在別台電腦用過、額滿了 |
| 授權已過期 | （HTTP 410） |
| 請求太頻繁，請稍後再試 | （HTTP 429） |
| 連不上授權伺服器，請確認網路 | 網路問題 |
（依據：license_client.py 第 388-396、406-424、525-527、580 行）
「開始登記」之後，單筆失敗時，「歷史」分頁「案號 / 原因」欄常見內容
| 原因文字 | 大致意思 |
|---|---|
| 登入失敗 | 帳密或驗證碼一直不過 |
| session 過期 | 中途被系統登出 |
| 該日期不可申請 (quota=...) | 這天額滿或還沒開放（站方每月 1～10 日才開放次月申請） |
| 15s 內沒有可選時段（未登入或該日已申請） | 這天這位可能已經登記過，或連線異常 |
| 填表回傳異常 / 表單驗證未過 | 政府網站表單填寫有問題，通常自動重試會處理 |
| 未進上傳頁 / 證件上傳未完成 | 證件圖上傳失敗，會自動重試 3 輪 |
| 確認框未出現 / 送出後未出現完成頁 | 送出這一步卡住，需人工到政府網站查證 |
| 案件已受理 | 成功 |
| 登入後查核不符！／登入帳號不符 | 安全檢查攔到「案件可能要掛到別人名下」，程式主動中止不送 |
（依據：chiayi_venue_apply.py 內 run_apply() 各
result["detail"] 賦值處，第 1369、1398、1418、1432、1455、1499、1518、1550、
1571、1577、1611、1658、1687、1749、1563-1564 行）
這些訊息的完整版在 log 裡（見第 11 節），「歷史」分頁只顯示前 300 字
（operator_ui.py 第 286 行 DETAIL_MAX = 300）。
11. 出問題要回報時，該給我們什麼
所有紀錄都在主程式資料夾底下的 logs\ 資料夾（operator_ui.py 第 63 行）：
| 檔名規則 | 內容 |
|---|---|
batch_YYYYMMDD_HHMMSS.log | 這一批的流水記錄（人看得懂） |
batch_YYYYMMDD_HHMMSS.jsonl | 這一批每一筆的結構化結果 |
chiayi_apply_YYYYMMDD_HHMMSS.log | 單筆操作的詳細站別記錄（最細） |
operator_YYYYMMDD_HHMMSS.log | 操作台本身的紀錄 |
license_YYYYMMDD_HHMMSS.log | 授權檢查的紀錄 |
（依據：chiayi_batch.py 第 73-74 行、chiayi_venue_apply.py 第 97 行、
operator_ui.py 第 89 行、license_client.py 第 87 行）
回報問題時請提供：
- 出問題那個時間點附近、最新的那幾個
batch_*.log、batch_*.jsonl、chiayi_apply_*.log（照檔名時間戳找） - 「歷史」分頁上那一筆的畫面截圖（或「案號 / 原因」欄的文字）
- 大概發生的時間、當時做了什麼操作
不用整包 logs\ 資料夾都傳，抓最相關的幾個檔案就好——檔名裡的時間戳會告訴我們哪幾份
是同一次執行留下的。