ArenaMate · 架構整合報告 · 2026-07-23

教練系統三方架構:現況全解析與整合方案

學員、教練、場館三方——加上你(平台)是第四方。這份報告基於今天對整個 codebase 的四路探勘(畫面層、金流結算、合約請假、決策文件),告訴你:哪些已經建成、哪些要改、哪些你還沒想到。

學員 教練 場館 平台(你)
CHAPTER 1

現況總覽:你的系統已經蓋到哪裡

先講結論:你規劃的七大系統,大盤約 65% 已經存在於 codebase——7-21 課程七批(S25–S31 測試全綠)與 7-22 開課平台四批把地基打得比你記憶中更完整。真正的工作是「整合+補缺口」,不是重蓋。

本章重點:綠色=已建成且測試通過;黃色=有骨架但有缺口;紅色=整個沒有。下表每格都有探勘佐證,不是印象分數。
系統學員端教練端場館端平台端(你)
1 金流coach_ledger 單一總帳 已建成 綠界網頁收銀台+課包 已建成 記帳本+月結算單 已建成 館帳本+撥款確認 有骨架 撥款主控台,缺對帳四件套
2 合約arena_coach_agreements 快照非合約 只有退款政策快照 已建成 版本化簽署 v1 已建成 核准即蓋章 場館↔平台無合約;參數全硬編碼
3 課程模板→開課→報名→點名 缺推薦 行事曆+成長頁有;推薦引擎無 已建成 模板精靈+工作室四區 缺月曆行銷 列表有;公開月曆頁無 部分 每堂不同價不支援
4 介紹分級評分三張星制評價表 星制 你要的貼紙制=整組要翻 履歷完整 品牌頁全公開+證照到期 依賴星制 低評警示吃 1–5 星 行為指標評級引擎無
5 預約佔位鏈+私教時段 已建成 報名流+私教約課 已建成 主動約場開課(佔位) 邀約太輕 只能提醒,不能協商 部分 代課預指定+顯示缺
6 請假4h 時限+流課 cron 已建成 每堂請假 4h 把關 已建成 缺席全退記警×2 停權 公休不連鎖 公休擋新建、不處置已排課 學程券暫緩 踩禮券法規
7 招募場館徵教練 單向 只有教練申請場館 招募貼文 marketplace 整個沒有 媒合曝光機制無
+廣告單方系統 雛形 名師駐館(PR≥80 地圖曝光) 雛形 課程廣告卡 推廣位規則未正式化
CHAPTER 2

金流之旅:一筆 3,000 元的完整旅程

範例:6 堂系列課、每堂學費 500、每堂場地費 100、館抽成 0%(現制預設)。這是 J3 測試劇本實測過的真實數字:最終教練 2,100、場館 600、平台 300。按「下一步」跟著錢走。

學員
付款人
綠界
金流閘道
平台總帳
coach_ledger
教練
收學費
場館
收場地費
分錄對象金額類型狀態
教練+2,700學費分成(3,000 − 平台費)尚未產生
平台+300服務費 10%(開課時蓋章快照)尚未產生
場館+600場地費(每堂 100,銷課時記)尚未產生
教練−600付場地費(per-slot 快照)尚未產生
鐵則(已內建):費率不可由 client 傳(server trigger 蓋章);冪等靠 DB 約束;已撥款分錄動不了,退款函數誠實回報而非假裝成功。
CHAPTER 3

課程生命週期:從開課到撥款的時間軸

每個節點點開看細節與參與方。紅點是支線(出事時走的路)、黃點是有缺口要補的地方。

開課

教練建課:模板 → 場地 → 時段 → 送審

開課精靈三步:選模板(sessions 逐堂 title/content/minutes)→ 選包場(rental_fee×時數,佔場地)或場邊教學(sideline_fee,不佔場)→ 月曆點空閒時段。送審即建 pending 佔位場次,開課當下平台費 10% 與館抽成被 trigger 蓋章凍結。
審核

館方審核:核准佔場 / 3 個工作天沒回自動釋出

核准 → 佔位轉 confirmed(場地正式被課程佔用)+教練合約自動蓋館方章。退回或逾時 → 佔位釋出。缺口:「3 個工作天」硬編碼在 SQL。
上架

曝光:場館頁翻卡、找教練上課、(缺)公開月曆行銷頁

現況曝光面:場館頁課程列表+翻面卡、櫃檯「找教練上課」、教練品牌頁(全公開)。缺口:你要的「場館月曆行銷頁」沒有——內部課表月曆(GymCalendarView)已存在,改造+anon 公開即可,不用重寫。
報名

學員報名:政策快照 → 綠界繳費 → 三方分帳

報名當下退款政策快照(refund_policy_snapshot)=輕合約雛形。繳費走第 2 章的分帳鏈。候補(waitlist)遞補已存在。缺口:報名頁沒顯示「如果教練請假,誰代課」。
截止

報名截止:registration_deadline(預設首堂前 24h)

唯一做對參數化的地方:預設 −24h 可被 DB 欄位覆蓋。截止後擋報名。
支線

流課決策:未達門檻 → 教練三選一 → 24h 沒決定自動取消全退

截止時未達 min_enrollment:通知教練決策卡(照開/延期 3 天再招生/取消退費)。24 小時無決定 → cron 自動取消+全額退。注意:cron 這條腿在 prod 還沒被真實流課案例驗證過。
上課

上課週期:前日提醒 → 當日膠囊 → 點名 → 銷課

cron 每小時掃 24h 內開始的堂次推播學員;教練主控台當日倒數膠囊;逐堂點名(attendance jsonb);銷課觸發該堂分錄 releasable+場地費分錄。
支線

請假網:學員 4h 時限 / 教練缺席全退記警 / 代課

學員:開始前 4h 內不可請假(server 把關),請假通知教練。教練缺席:該堂全體退費+記警,累 2 次自動停權。代課:slot 級指定+跨館代課池撈人。缺口:「遲到 15 分視同缺席」只寫在合約文字,程式沒有閘門,全靠人工按。
支線

場館公休:擋新建,但不連鎖處置已排課

arena_gym_closures(日期範圍+範圍 all/courts+原因)已存在,單一 Gate 全系統吃(開課/揪團/賽事/預約都會被擋)。缺口:它只擋「新建」——已排定的課堂遇到颱風公休,沒有自動連鎖(改期/代課/退款批次決策)。
課後

課後:評價(7 天內限出席者)→ 課後總結 → 成長頁

現況全星制(1–5 星,低分留言僅館方+教練+本人可見)。學員成長頁:技能曲線+作業打卡 streak+影片回饋 v1。你的新方向:轉正向貼紙制——第 6 章我會挑戰這個設計。
結算

月結 15 日:聚批 → 平台撥款 → 對方確認入戶

上月完課分錄按 released_at 聚成撥款批;你在撥款主控台實匯後標記;館方/教練確認入戶記銀行收入,閉環。
CHAPTER 4

合約網與參數:三方其實是四方

你說「三方都要有專屬工具」——但收服務費、定規則、管總帳的你就是第四方。合約不是三份,是一張 4 節點 6 邊的網。點圖上的線看每一邊的現況。

平台 場館 教練 學員

點左圖任一條線

實線綠=已有簽署機制;虛線黃=有雛形但不是正式合約;點線紅=整個沒有;淡點灰=隱含關係(不需簽署)。

你的鐵則「數字不硬編碼」——現況體檢

探勘結果:除了報名截止一個欄位,其他全部硬編碼。「遲到 15 分」甚至只存在於合約文字,程式根本沒有這個閘門。

合約參數拍板值現況存放
學員請假時限首堂前 4 小時SQL interval '4 hours'
流課決策窗截止後 24 小時SQL interval '24 hours' ×3 處
報名截止首堂前 24 小時registration_deadline 可覆蓋(唯一做對的)
教練遲到判缺席15 分鐘只在合約文字,無程式閘門
月結撥款日每月 15 日Dart Gate now.day<15
缺席停權門檻記警 ×2Dart 常數 strikes>=2
佔位釋出3 個工作天SQL v_workdays>=3
退款三段7 天前全退/72h 前 50%/之後不退政策 key+快照(半參數化)
平台費10%(課程)/5%(賽事)開課時 trigger 蓋章快照(正確典範)

解法:合約參數三層解析+報名快照

平台費快照已經示範了正確做法——把同一套 pattern 推廣到所有參數。Gate 一律吃解析後的參數,不再讀常數。

第 1 層:平台預設(arena_policy_params)

請假 4h、流課窗 24h、遲到 15 分、月結 15 日、停權 ×2、佔位 3 工作天……全部搬進 DB,改規則不用改 code。

第 2 層:場館合約覆蓋

場館跟平台簽的開站條款可以談不同參數(例:這個館的月結日、抽成上限)。

第 3 層:課程覆蓋

單一課程可再覆蓋(例:這門課報名截止提早 3 天)——registration_deadline 已經是這層的活例。

學員報名 → enrollment_terms_snapshot

報名當下把解析後的完整參數快照進報名紀錄=「學員↔教練輕合約」。之後平台改規則不溯及既有報名(費率快照已驗證這套 pattern 可行)。

CHAPTER 5

七大系統對照:現況 → 要怎麼改

每張卡:三方各自的工具現況、缺什麼、我的提案。點開看。

學員
  • 綠界網頁收銀台(App Store 免 IAP)
  • 課包/月卡(pass 引擎)
  • 私教約課原子建單
教練
  • 記帳本(held/releasable/paid 分組)
  • 月結算單+一鍵複製對帳文字
  • 現場收款 offline 記帳
場館
  • 館帳本(分錄自動鏡射)
  • 場地費 per-slot 精準入帳
  • 撥款確認入戶
缺口
  • 應付餘額無統一數字——「總共欠教練多少」要人工把兩個畫面加總
  • 無合約分成總表——費率散在每筆快照,看不到全局
  • 對帳是手動填總額相減——沒有逐筆綠界單號勾稽,少匯一筆抓不到
  • 無平台全域損益表;分帳公式 SQL/Dart 雙真相源靠人工鏡像
提案
  • 平台總帳 v2:應付彙總 view+合約總表+綠界對帳 CSV 匯入逐筆勾稽+未匹配警報
  • 分帳公式加 golden test 守門(SQL vs Dart 同輸入同輸出)
學員
  • 現況:報名時退款政策快照(非簽署)
  • 目標:enrollment_terms_snapshot 輕合約
教練
  • 現況:版本化簽署 v1(含 7 類條款)
  • 核准時館方自動蓋章
場館
  • 現況:對平台完全沒有合約
  • 目標:arena_gym_agreements 開站條款
缺口
  • 4 節點 6 邊只做了 1 邊正式合約(見第 4 章)
  • 參數幾乎全硬編碼(見第 4 章體檢表)
  • 教練↔平台條款混在教練合約,未拆
提案
  • 批α:arena_policy_params 三層解析+報名快照(最優先,其他系統都踩在它上面)
  • 補「遲到 15 分自動判缺席」程式閘門(合約寫了、程式要真的執行——你的原話:真的用這個數字判斷)
學員
  • 我的課程+行事曆+完成率(學程出席 ≥60% 解鎖)
  • 成長頁:技能曲線/打卡 streak/影片回饋
  • 缺:課程推薦引擎
教練
  • 模板庫(逐堂 title/content/minutes+拖拉群組)
  • 開課精靈三步+一鍵續開
  • 缺:每堂不同價(現在課程層單一價)
場館
  • 課程列表卡+翻面卡+審核流
  • 內部課表月曆已有(課綠/賽金/揪藍/休灰)
  • 缺:公開月曆行銷頁
提案
  • 每堂價:加 coach_course_slots.price——但要連動三處:分帳逐堂按價比例分割、退款按堂價算、pass 銷課按堂價;不是加一個欄位就完
  • 月曆行銷頁:改造既有 GymCalendarView+anon RPC+web 版(複製教練品牌頁 coach.html 的成功 pattern),不重寫
  • 推薦 v1 用規則:同教練/同館/同類型/程度階梯。協同過濾(上過這課的人也上)等數據量夠再上——冷啟動期做了也是空轉
學員
  • 現況:教練評學員已存在(但也是星制)
  • 目標:收集正向貼紙(準時/配合度),負向不公開
教練
  • 履歷:12 類專長+細項定價+證照(到期 cron 提醒)
  • 品牌頁全公開+教練目錄
  • 目標:貼紙牆取代星等
場館
  • course-only 館徽章=教練數/開課中/評價
  • 低評警示(<3.0 通知館方)——拔星制會弄瞎它
提案
  • 對外=正向貼紙牆(雙向;重用現成徽章元件);三張星制表轉唯讀歷史
  • 對內=行為指標(完課率/續約率/退款率/請假率)餵館方警示+你的推銷決策——行為比意見誠實,也解決貼紙通膨問題
  • 教練評學員:正向公開、負向只進教練私人筆記+平台風控(防報復、防衝突)
學員
  • 報名流完整(快照+繳費+候補)
  • 私教:未來 14 天可約時段
  • 缺:報名頁顯示代課安排
教練
  • 主動約場開課:佔位鏈完整(包場/場邊兩模式)
  • 私教時段管理(weekday+slot+價格)
  • 缺:接受場館邀約的協商流
場館
  • 核准=自動佔場;逾時自動釋出
  • 邀教練排課=只能發提醒通知(太輕)
  • 營運月曆:場地色點+標暫停
提案
  • 邀約升級成協商流:場館發邀約(帶時段+建議模板)→ 教練接受 → 自動生課程草稿進審核——把你說的「館方問教練、教練答應、用模板開課」做成一條龍
  • 代課改分級制:課程級預指定(報名頁顯示)+沒指定的 fallback 跨館代課池(池子已存在)+有指定的掛「代課保障」徽章當行銷加分
學員
  • 每堂請假 4h server 把關+通知教練
  • 處置現制=記請假不退費
教練
  • 缺席=該堂全退+記警×2 停權
  • 代課 slot 級+跨館池
  • 流課三選一決策卡+24h cron
場館
  • 臨時公休已有(日期範圍+原因,全系統 Gate)
  • 缺:公休後已排課的連鎖處置
提案
  • 公休連鎖 orchestrator:宣告公休 → 列出受影響堂次 → 館方批次決策卡(整批改期/代課/退款)+自動通知三方
  • 學員請假處置 v1 =補課 credit(同課程內補堂);「學程券」暫緩——它是儲值性質,踩禮券履約保證法規(第 6 章詳述)
現況
  • 只有教練→場館單向申請(申請通知館方幹部;館主自動成為本館教練)
  • 廣告雛形:名師駐館(PR≥80 地圖曝光)+課程廣告卡
提案
  • 招募輕做:arena_gym_recruit_posts(我的場地/特色/要什麼教練)+教練應徵 → 復用既有 coach_apply 核准流,不另起爐灶
  • 廣告正式化:推廣位規則透明(付費位與自然排序分開標示)——排序黑箱會蝕掉三方信任
CHAPTER 6

你沒想到的:16 條拷問

你叫我 grill 你——這章每一條都是你的規劃沒覆蓋、或我認為方向要修的。紅=法遵炸彈(會出事)、黃=金流蟲洞(會漏錢)、藍=制度與架構(會後悔)。

嚴重法遵炸彈:現在不排程,出事就來不及

拷問:平台替眾多教練代收學費=代理收付。規模化踩《電子支付機構管理條例》門檻;綠界條款可能禁止個人帳戶做平台聚合;個人帳戶還有月額度上限。現在能動 ≠ 能長大。

要做:公司主體+平台級金流方案(綠界平台商或 TapPay marketplace)排進 roadmap 時間表,以教練數/月流水設觸發門檻,不要等被停權。

拷問:遲到 15 分判缺席、記警停權、平台定退款政策——每條規則都在增加「僱傭認定」風險。被認定的話,勞健保、資遣費全部追溯。

要做:有意識保留承攬特徵:教練自主定價(你已做對)、平台規則定位為「交易市場規範」而非「工作紀律」、合約措辭請律師過。這也是場館↔平台合約要正式化的理由之一。

拷問:你想拿學程券當停課補償——發券=預收履約義務=禮券定型化契約+履約保證(跟你已知的 NT$5,000 信託同族法規)。

要做:暫緩。補償用「同課程補課 credit」(非儲值、不跨課程流通)或直接退款。真要做券,法遵先行。

拷問:教練/場館/平台的運動傷害責任分配,現在的合約完全沒寫。第一次出事就是第一次定義,那時是法院幫你定。

要做:合約加責任條款+要求教練投保公共意外責任險。反過來想:平台團保可以做成「留住教練的黏著服務」——成本變武器。

拷問:出席、作業、影片、技能曲線——這些個資的歸屬(學員本人?教練?平台?)沒有定義。教練跳槽帶走名單,你擋不擋得住、該不該擋?

要做:合約定義:學員數據歸學員本人,教練取得「服務期間使用權」;匯出/刪除權責寫進條款。

中度金流蟲洞:設計上會漏錢的地方

拷問:學員跟教練熟了就現金私下交易,躲 10% 平台費。你現有的現場收款記帳工具正好幫他們把這筆帳記得舒舒服服。

要做:防外逃靠價值不靠抓:金流保障(先付款後上課的爭議仲裁)、履歷與評價只累積在平台內交易、月結算單報稅便利、保險(G4)。把「留在平台的理由」做成明確的價值主張清單,逐項落地。

拷問:偷來的卡買課包 → 轉讓 → 另一帳戶退款=洗錢通道。拍板「6 個月可轉讓」時沒想這層。

要做:轉讓後不可退款、限轉 1 次、轉讓冷卻期+風控記號(同裝置/異常頻率)。規則進 pass 引擎的 Gate,不是靠客服人眼。

拷問:這是代管資金。帳上如果不能逐筆證明「每一塊錢屬於誰」,出糾紛時你說不清,稅務也說不清。

要做:平台總帳 v2 的逐筆勾稽(第 5 章 SYS1 提案)不只是方便你對帳——它是資金保管的自證能力。應付餘額 view=你隨時知道「代管中的錢」總額。

方向制度與架構:現在轉向還便宜

拷問:好評通膨之下,爛教練照樣一牆貼紙,新學員無從分辨;而且現有「低評警示館方」吃 1–5 星,拔掉星制警報就死了。

要做:雙軌:對外貼紙牆(你要的正向體驗)+對內行為指標(完課率/續約率/退款率/請假率)做品質信號。行為數據不會說謊,也不用得罪人。

拷問:學員看得到自己被評低分=衝突與報復性互評。你要的是篩選訊號,不是紛爭製造機。

要做:學員只看得到自己收集的正向成就;負向觀察只進教練私人筆記+平台風控。訊號留給需要的人,體驗留給學員。

拷問:沒有教練隨時養著一個 stand-by 備援。硬性要求=開課精靈多一個填不出來的必填欄=放棄開課。

要做:分級:課程級指定(選填)→ 沒指定 fallback 跨館代課池(已存在)→ 有指定的課掛「代課保障」徽章+報名頁顯示(你要的透明感反而變成行銷加分)。

拷問:「上完這課的人也上什麼」需要行為數據量,冷啟動期做協同過濾=空轉。

要做:v1 規則式(同教練/同館/同類型/程度階梯),架構上留好推薦 slot 的介面,數據夠了換引擎不換 UI。

拷問:你列了三方的工具,但「平台方工具」只提了一句記帳。你的對帳、風控、推銷決策、合約管理都是系統,不是 Excel。

要做:把平台端當第四個使用者設計:總帳 v2、行為指標儀表板、合約總表、風控記號。第 7 章施工批次已排入。

拷問:把 4h 搬進 DB 只做了一半——改了參數,既有報名怎麼辦?溯及既往=糾紛。

要做:平台預設 → 場館覆蓋 → 課程覆蓋,報名當下快照進報名紀錄(費率快照已驗證這套 pattern)。改規則永遠只影響新報名。

拷問:宣告公休後,已排定堂次不會自動改期/退款,得一堂一堂人工處理。颱風天館方最忙的時候給他 30 堂課手動作業?

要做:公休連鎖 orchestrator:受影響堂次清單 → 批次決策卡 → 自動通知。跟流課決策卡同一個設計語言。

拷問:migration 註解自己寫著「改公式兩邊要一起改」——這就是遲早不同步的自白。錢的公式不同步=帳對不上。

要做:golden test 守門:同輸入跑兩邊、輸出必須逐分錄相等,進 CI。長期把 Dart 端降級為顯示用試算,真相只留 server。

CHAPTER 7

施工路線圖:六批+一條法遵平行線

順序有講究:批α(參數中央化)是地基,後面每一批都踩在它上面。每批都按測試先行鐵則走(先寫劇本再實作,flag 開關各跑回歸)。

α

合約參數中央化

arena_policy_params 三層解析+PolicyGates+報名快照;補遲到 15 分程式閘門;場館↔平台開站條款(arena_gym_agreements)。根治「數字硬編碼」。

β

平台總帳 v2(你的對帳工具)

應付餘額統一 view+合約分成總表+綠界對帳 CSV 逐筆勾稽+未匹配警報+分帳 golden test。回應 G8、G13、G16。

γ

評價制度轉貼紙(雙軌)

對外正向貼紙牆(雙向)+對內行為指標儀表板;星制表轉唯讀歷史;低評警示改吃行為指標。回應 G9、G10。

δ

課程增強

每堂價(slots.price+分帳/退款/pass 三處連動)+公開月曆行銷頁(GymCalendarView 改造+anon)+推薦 v1 規則式+報名頁代課顯示。

ε

預約協商+代課保障+公休連鎖

邀約協商流(接受即生課程草稿)+課程級代課指定與徽章+公休連鎖批次決策卡。回應 G11、G15。

ζ

招募 marketplace+廣告正式化

招募貼文+應徵(復用 coach_apply);推廣位規則透明化。輕做。

法遵

平行線(不寫碼,但要排時間表)

公司主體+平台級金流(G1)/承攬合約律師審(G2)/保險與責任條款(G4)/個資歸屬(G5)/課包轉讓風控規則(G7)/學程券暫緩(G3)。

CHAPTER 8

Prototype 計畫:在現有 codebase 上,不傷筋動骨

你說架構解析完成後要一個可操作的 prototype。我建議第一波做這三個——最有感、風險最低、全部 flag 包(關掉即回現狀)。看完報告你挑,或三個都做。

PROTO A

平台總帳 v2 主控台

在現有撥款主控台上加:應付餘額卡、合約總表、對帳勾稽頁(先用假綠界對帳檔演示勾稽與警報)。

你每天要用的工具,最快感受到整合價值。

PROTO B

貼紙評價流

課後評價改貼紙選擇器(雙向),教練品牌頁貼紙牆,館方後台行為指標卡。重用現成徽章元件。

制度翻修先用眼睛驗證,再動資料表。

PROTO C

場館月曆行銷頁

GymCalendarView 改造成公開行銷模式:月曆格顯示可報名課程+價錢+教練,點擊進報名。

對外的臉,場館方最想要的曝光工具。

不傷筋動骨的保證:三個 prototype 都不動 coach_ledger/分帳引擎/既有資料表結構,全部是新畫面+新 flag+(Proto A)新的唯讀彙總 RPC。關 flag 即回現狀。