全 12 是「中華民國童軍第12次全國大露營」簡稱。

藉由中華民國童軍第12次全國大露營（以下簡稱大露營）的辦理，呈現我國新世代童軍的創意與活力，透過大露營的宣傳和活動，鼓勵全國青少年能親近大自然，讓童軍活動受到全國青少年的喜愛，提供國內外童軍交流互動平臺，以促進我國童軍和世界各國童軍的互動交流，強化童軍實作技能，提升童軍合作學習，以發揮童軍運動精神。

在白天有提供給童軍伙伴跑站的活動，其中我的任務是在其中做一份簽到簽退系統。讓工作坊可以提供給學員打卡，除了回報給學員的分團支外，也提供紀錄、展示等用途（笑）。

真的做了好久阿，去年年末到現在。這算是一份發願，看能不能給自己一個交代，於是最後產出了這份專案。

內容包含：原始碼、技術結構、優化清單、部署介紹。

無論如何也算是得償所願吧，接下來看有誰要接下去做了。

其中有許多需要優化修改的地方，參考這裡。

可怕的是在活動前開始感冒，營隊幾天就咳嗽幾天，至今鼻涕和喉嚨還不太安分。而待在家參與活動這幾天，貢獻算是遠端提供協助並定時提供紀錄報告。於是趁這段時間寫了一份紀錄。

— 寫於 2024-07-13 至 2024-07-16 , 板橋—

Hi, this is Jerry.

這個系統做得有點坎坷，需求和規劃並非一帆風順，而童軍運動也不是有給付薪水的工作（笑），針對吃程式設計這行飯的前後端人手似乎不太好找。這次的實作算是花費了 2024 上半年的很多時間，從一開始需求不清晰到開始找大流量的結構、研究比較服務、前端到後端實作在到配套規劃，中間也是吵吵鬧鬧的，所幸算是還拿的出來一個堪用的東西。未來如果童軍伙伴有需要使用，可以參考部署流程架設，或是想要自己實作的話，也可以抽換裡面的結構來做。 

就希望這個作品當作一個拋磚引玉的作用吧。希望玩童軍的程式設計師都能有錢、有餘裕再回頭貢獻。

規劃階段

這系統原本是從 2023 年底以票務股開始，後來票務股給其他伙伴負責，轉變以數位系統實作為主。原本資訊混亂不清的時候，有滿多各種考慮和作法。

這是開會筆記，滿多廢話的：https://docs.google.com/document/d/1htCP7UVHd2ug3Fjpj6QJhn2q84CZnRYljaCYXn-KxWo/edit?usp=sharing

後來隨著資料明確，約 2024 年年初開始明確系統的用例，和大致上的需求規格，當時規劃的規格式：

1. 參與工作坊的學員+其他人人數需滿足 8000 人規格
2. 工作坊約 100 個以上。
3. 4 天活動、一天活動 4 場。
4. 場地（走馬賴）網路環境正常
5. 配套規劃：網路壞掉、下雨、設備壞掉、操作有問題
6. 工作坊有些不熟悉 3C 產品的伙伴，儘量減少操作錯誤的機會。

於是開始規劃數位系統的結構和用法，因為預算有限，所以針對高併發的需求採用 cloudflare 的服務，後台系統使用現有的 production server 架設 LEMP 結構的前後端分離網站。製作有幾個目標：

1. 降低未來前端、後端與第三方服務的耦合，使用 Restful API 溝通。
   1. 未來其他伙伴開發可以使用自己熟悉的語言替換。
   2. 服務有更好的替代方案也可以儘量以最少的修改替換。
2. 不會與全 12 的活動過度綁定，更換為其他活動可以儘量最少的修改。
3. 能夠防呆的 UX 設計就儘量做上。

最後決定最佳解是：

1. Cloudflare 付費方案（每月 5 美元），於六月底開始，預計七月中結束停用。
2. Production Server 因原本內有現有服務運行，所以先調整規格，活動結束後再確認是否需調降。
3. 現場運作後台的伙伴之外，配套規劃中安排

最後除了程式之外，也產出一份包含配套方案的單項計畫書：

該單項包含了針對活動前幾天可能天氣炎熱、下雨等配套再另外調整，例如考慮到紙本潮濕等規劃用手機拍攝照片，再另行處理等動作。

題外話，有一件令人費解的事情： Cloudflare Worker Service 提供免費的即時監控功能，在活動前以及撰寫本文的當下（2024-07-13) ，除了伺服器發出的同步流量支外，會查到來自非台南地區的流量（高雄、台中、台北）。

2024-07-13

全 12 運作第三天，今天休息，結束前兩天活動。

有幾個狀況：

1. 後台系統在現場只有宗翰有權限，不過宗翰太忙了，後續請沈俊達沈校長協助操作後台。
2. 第一天發現一個 bug：工作坊登入以後，簽到一次離開再回來，場次的選項會消失。
   1. 發現是尚未測試出來的 bug ，已修復。
   2. 這 bug 在開發時，和後續大家一起測試時都沒發現，會需要檢討以後開發與測試的流程。
3. 工作坊工作人員訓練量不夠，有人並非工作人員，或是工作人員並非參與前期測試和教育訓練。導致訓練不足，第一天時操作狀況頻發。
4. 「簽出」這個詞彙不是正確的，應該要是「簽退」；「營本部」這個詞彙應該要改成「組本部」。這也是測試的時候沒有發現的狀況，「簽出」有被工作人員誤會成「登出」的動作。
5. 工作坊時間安排，學員進場時間不一定，導致如果只有 1 人的工作坊，簽到和活動會兼顧不來。
   1. 按原規劃：如果找不到人支援，前後放時作為緩衝在一起開始會比較好。
   2. 原則上有遇到簽到問題，可以先用紙本簽到，有空時再操作。
   3. 沈校長也提議：先把學員護照收起來，中間空檔在再掃描送出。結束時歸還護照。
6. 老闆面板（展示簽到人數的網頁）有一度統計數字壞掉。
   1. 該網頁是活動組長委外請人協助，後續溝通完成修復。 按：此為因為添加了測試用工作坊的關係，測試工作坊不顯示於系統導致壞掉。
7. 參觀旅行有一位工作坊工作人員無法掃描學員編號的 QR Code，但透過提供現場 QR Code 的照片來測試掃描正常。可能是手機問題，當下提供幾個作法：
   1. 換台手機掃描。
   2. 先紙本簽到，事後有空時輸入編號。
   3. 手動輸入編號。
8. 會有需要定時匯出簽到簽退資料的需求。

另外也有一些和規劃不同的改動：

1. 榮譽卡和簽退的行為重疊，後續取消簽退動作。
   1. 影響到系統部分判斷的流程。但不難處理，統計上已調整不特別判斷指定單一條件。
2. 改為榮譽卡作為領榮譽章標準，不從系統上撈資料。
3. 有部分工作坊不願意配合簽到簽退，第一天晚上即改為不強制操作。
   1. 可能會影響到即時追蹤（包括老闆面板）的需求。
   2. 未來如果依然有統計需要，必須要透過規範讓工作坊確實執行。

於是經過兩天活動，系統作了一些修改：

1. 修復工作坊網頁場次的 bug。
2. 修復工作坊紀錄可能會出現空的學員編號問題。
3. 修復後台操作時發現的 bug。
4. 修改老闆面板、學員場次統計的簽退條件，改為有紀錄（無論只有簽到還是簽退）就納入紀錄。
5. 修改擷取頁面。
   1. 場次簽到簽退會有重複、簽錯的行為，必須要開啟指定四個場次時間的頁面。
   2. 改為不指定日期，依照當前日期判斷。
   3. 活動結束關閉，早上再開啟。
   4. 這操作必須要優化才行。

大部分都是第一天活動出現的狀況，第二天活動運作較為正常。除掃描問題以外大多為偵測到簽錯場次的行為。簽錯場次問題可考慮以下修復步驟：

1. 查找資料庫，找到錯誤的紀錄場次與工作坊編號。並且查找錯誤的紀錄應正常屬於哪些場次。
2. 於資料庫中查找正確的場次，確認該工作坊是否有補輸入學員編號。
3. 登入 Cloudflare 後台 KV 頁面，確認該筆 KV 欄位（ key 值：signMWS_{{工作坊}}_{{場次}} ），點開 json 檔案確認要移除的資料。
   1. 只需移除不需添加，添加資料於後台動作即可。
4. 如果工作坊於正確場次沒有輸入學員編號。
   1. 於資料庫中把錯誤場次的紀錄修改為正確場次即可。
   2. 後台操作中補輸入正確場次的學員資料。 並確認資料庫刪除錯誤場次的資料。
5. 如果工作坊已經有補簽到（部分的）學員編號。
   1. 於資料庫中刪除錯誤的資料，修改沒有補簽的學員場次。
   2. 後台操作中補輸入正確場次的學員資料。 並確認資料庫刪除錯誤場次的資料。

2024-07-14

活動倒數第二天。明天就先收工。

目前看起來結構算是穩定，吧？今天理解沒錯的話，應該工作人員操作也會上手了，先撇除掉操作錯誤的選項，針對數字有問題的內容做確認調整。

滿有趣的是因為第一天晚上先取消了不強制簽退的動作，所以後面的工作坊單一場次的紀錄，有些會只有簽到，有些會只有簽退，也有些會想要兩個都做但是有一次簽錯場次。 這對統計並沒有很大的影響，但是對老闆面板的展示數量的 API 倒是有差，主要糾結在時間跨度很大的工作坊（參觀旅行）在展示數字上即便往後的場次也要照常顯示，而一般單純沒有該場次的工作坊，如果沒有簽出（或是取消簽出判斷），就很容易被當作是有跨度需求的工作坊，而顯示在其中。

這個規劃可以看成是一個規則怪譚的遊戲，一個人玩真的不太好玩。嘗試把他列出來，邀請有興趣的伙伴可以試試看如果先規劃藍圖，能夠畫到多細，得以滿足所有規則和規格。

—

場景（需求規格）：

1. 工作坊： 100-140 個。
2. 場次數量：切分成 4 個場次，上午 2 場，中午休息，下午 2 場。
3. 使用人數： 8000 人。
4. 活動 5 天，中間休息 1 天。
5. 目的：統計參與人數、展示正在活動（簽到）人數。
6. 必要功能：
   1. 簽到、簽退。
   2. 後台匯出統計完成一定場次以上數量的學員。
   3. 需要有一個展示頁面展示當前於各個工作坊的活動中的學員人數。

功能：

1. 工作坊
   1. 簽到與簽退：輸入工作坊編號、場次編號、學員編號送出。
      1. 紀錄以下欄位：簽到/簽退、當前時間、工作坊編號、場次編號、學員編號。
   2. 讓工作坊自行檢查是否輸入正確。
2. 後台
   1. 簽到簽出資料查詢。
      1. 查得到對應學員、工作坊資料。
   2. 指定條件的簽出簽到資料匯出。
      1. 必要搜尋欄位：場次編號、工作坊編號、學員編號。
   3. 編輯簽到簽出資料
      1. 必要可編輯的欄位：場次編號、工作坊編號、學員編號。
   4. 指定條件的學員匯出。
      1. 滿足滿 N 個活動完成的學員，做為獎章頒發依據之一。

規則：

1. 未必所有工作坊一天都是 4 個場次。以下列舉狀況：
   1. 30 個工作坊他們是整天的活動，所以只會有一個場次簽到。
   2. 有工作坊場次不會連續。
   3. 工作坊會有臨時關閉與臨時開啟的狀況。
2. 簽到簽出速度 / 流程儘量快。
3. 因腹地廣闊，學員移動速度有限，可能會陸陸續續到工作坊，差距最長約 30 分鐘。
4. 需要解決/修復資料與確認配套的狀況：
   1. 發現某個工作坊應該有資料卻沒有資料。
   2. 發現某個工作坊數量異常多或異常少。
   3. 不熟悉操作（通常發生在第一天）導致速度太慢影響活動時長。
   4. 場次可能會輸入錯誤。（填錯場次）
   5. 學員可能會輸入錯誤。（學員跑錯場）
   6. 設備、載具有狀況等無法正常使用系統。
5. 現場網絡環境與流量頻寬的承載量未知是否能承載學員上網。
6. 活動的各項決議可能導致確認完整規格離第一次測試時間約 1-2 個月。
7. 工作坊現場活動的人數需有一個展示頁面。
   1. 必要欄位：工作坊、工作坊活動人數、當前日期、天氣。

—

有興趣可以可以規劃看看。

2024-07-15

活動倒數最後一天（對我來說）。營期幾天就感冒了幾天，結束我要去吃火鍋。

這樣的系統目標是放在商業運作，我還是那個理念，無論怎麼想，有獲利的營運有機會是進步的動力。然而這套系統離商業運作還有一段路要走。觀察下來應該要克服幾點：

1. 專業團隊組成

我一直認為軟體設計一個人製作如果不是用時間和財力去堆積的話，成果有限。我認為技術團隊可以透過現有的服務或是外包來搭配，像是購買版型套版來減輕或是取代美術需要製作的工作時數、快取服務架設成本太高則找適合的雲端服務來頂著。但是其實這取代不了團隊最核心的優勢就是從不同角度的討論和溝通，以及互相 cover，我會認為如果團隊組建得宜，同樣的開發時間和同樣的需求，應該會做得更加細緻而且體驗更好。

2. 使用者溝通訓練 vs. UX 規劃

這應該不能算是一種糾結，簡單講是因為自己不是專業於 UX 設計的人，導致這塊表現平平甚至不佳，所以某種程度上只能寄情於希望給使用者的訓練能夠完善，這滿好笑的。總歸是能力不足，解決方式還是看能不能團隊中有企劃能夠針對活動內容做設計調整吧。

3. 儲存結構調整

這塊應該多花一些時間規劃的，像是把 KV 換成 D1，或是 KV 設計的結構上有成本考量、開發考量以及功能考量，但真的運用在活動時，覺得可能換成 D1 也許是用錢來換命的好方法。然而也可以考慮自架伺服器的方式，最大的難點應該是如何實作快取服務了，我想快取的資料還是用拉取的方式會好一點，無法主動掌控同步時機有點兒危險。

4. 更多的應用

我認為在推廣新的概念新事物上，賣方市場創造應用是很重要的。如果連應用都沒有，挖掘需求的目的就是從一開始就不存在的。可以用到的創意太多了，像是鼓勵工作坊的競爭、鼓勵學員回饋、提供給營報/媒體新聞素材等等，接不只直接的創造了統計分析的需求，甚至會需要因應適合的 KPI 設計，添加了一些新的欄位。而且以數據科學的角度，應該要從這些數據發現：「活動該怎麼改善」這是一個重中之重。

其實很需要人阿。

–

另外機會難得，我得把 Cloudflare Worker 的統計資料抓出來。 

* 不同顏色表示不同版本，營期前半個月之後原則以修復 bug 為主不新增功能，所以看到顏色變化，即是當下有發現問題緊急修復。
* 以小時為單位採樣。

另外我得記得收尾的工作：

1. 整理原始碼，打包開源（記得刪掉沒用的 code）
2. 把 API 文件打出來，提供開發規格。
3. 寫心得。
4. 把 Cloudflare 付費停用。
5. 把擷取頁面的 windows 主機停用。
6. 調降 Production Server 規格。

希望我感冒趕快好。

這篇獻給李宗翰，他真的很辛苦，而且開會時一直被我嗆又要張羅一堆事情。
也感謝沈俊達沈校長營期時大力幫忙，還有許多配合的工作坊伙伴和其他伙伴。

希望軟體圈子文人相輕的文化這時可以發揮功用，看不下去的就出來做吧。

—

2024-07-26 update

整理了一個新解，紀錄一下：

流程上修改

1. 工作坊場次之間預留間格，約是最長路程的 3/2 的時間作為「路程時間」。例如這次活動路程最長約半小時，抓 20 分鐘作為場次與場次之間的緩衝。
2. 訓練工作坊「必須最早簽到時間」為場次開始前 1/2 的路程時間，不得提早。
3. 如無必要，取消簽退動作。

系統上修改

1. 工作坊介面移除場次選項，改為自動判斷。抓取時間作判斷。
2. 工作坊介面移除確認動作，解開單一裝置登入行為（因為不會有循序的問題），即掃即輸入，加快掃描速度。
3. 除了第一場以外，其他時間為場次開始前後 1/2 路程時間判斷。
4. 如果該工作坊沒有上一場的場次，則計算為下一場。
5. 如果超過 10 分鐘沒有連續打卡會跳場次提示的警告。
6. 快取服務如果依然選用 Cloudflare 處理， key 值改為「前綴_場次_工作坊編號_學員編號」，顆粒切更細。
   • 需要修改工作坊的清單介面，採用 list 方式取值。
   • 注意使用上因為大量採用 list 取值，費用可能會增加，需精算。
7. 如果有預算，考慮 Cloudflare 使用 D1 服務作為快取+後台的永久儲存機制，可以實作關連式資料庫，簡化快取服務實作。
   • 注意 D1 服務是付費服務，需確認預算與限制。
8. 如果採用自架的伺服器，請務必考慮到工作坊介面 requests 的峰值數量，或是有需要能夠透過流程或系統實作分流的動作。

判定上/同步處理

1. 場次填錯的話，如果只是需要判定場次數量則不用特別去修復（頂多會填成上一個場次）
2. 同步簽到紀錄行為上，添加一個只能由後台/開發人員動作的「該筆記錄作廢」的 flag 欄位，作為手動處理同步資料作廢用途。
   • 如果作廢的話，資料則不顯示在後台、API 上。
3. 如果需要在意場次：同步簽到上著手，判斷學員編號有同一個場次、不同工作方的簽到時依照簽到時間自動修正
   • 修正使用的邏輯是「作廢舊的且錯誤的紀錄、添加新的正確紀錄」，避免同步錯誤。
4. 同步行為如果依然選用 Cloudflare 實作快取服務，採用 list 操作，抓取「前綴_場次_工作坊編號」動作為佳（考慮 list 長度以及抓取時間的平衡）；如果自架服務，則需考慮同步抓取的資料量大小與完整同步一次的時間做平衡。

以上。

—

最後放一些做封面圖時生成的圖片，滿好看的，有需要請自行取用。