房產剎價學後台系統

1文件摘要

本文件定義「房產剎價學」後台數據系統 v1 的完整需求，整合自業務確認（Yuna）與技術決策（miru）。

系統定位

系統包含兩個面向：

學員端

app.shaprice.ai

學員上傳看房單、繳交作業、查看自己進度、累積分數、追蹤百戶長進度。

管理員後台

artteam.shaprice.ai

Yuna、曹曹、講師審核學員紀錄、匯入看課率、管理達標升等與退費處理。

v1 核心效益

省時間

每天人工下載 Excel + Drive 逐張審核的工作 100% 自動化。

省爭議

計分規則化、可追溯、學員端透明可查，不再因人工錯誤起爭議。

省機會

所有學員行為結構化儲存，建立決策資料庫，為 v2 AI 應用打基礎。

省風險

學員資料離開 Google Drive 公開空間，進入私有 RLS 嚴格隔離環境。

2角色與權限

系統有四種角色，權限嚴格隔離。學員只能看到自己的資料，管理員可看全部但登入需 2FA。

權限項目	學員	管理員	講師	系統 (Cron)
登入後台	✗	✓	✓	✗
登入學員端	✓	✗	✗	✗
上傳看房單 / 作業	✓ (自己)	✗	✗	✗
查看自己分數	✓	✓ (全部)	✓ (全部)	✗
查看別人分數	✗	✓	✓	✗
審核看房單	✗	✓	✗	✗
匯入看課率 Excel	✗	✓	✗	✗
百戶長升等審核	✗	✓	✗	✗
退費標記 / 匿名化	✗	✓	✗	部分（執行匿名化）
系統設定變更	✗	✓	✗	✗
派 Claude 自動修復	✗	✓	✗	✗
編輯 Help Center FAQ	✗	✓	✗	✗
查看 Help Center FAQ	✓	✓	✓	✗

認證機制

學員端

Magic Link (Email 收信點連結)
Google OAuth (Gmail 一鍵登入)
Session 30 天
記住我：是

管理員端

獨立帳密 + 2FA
Session 1 小時
記住我：否
限定 Yuna / 曹曹 email

3計分規則

學員分數來自四個來源，無上限累積。達 1000 分 = 100 間看房後人工審核，正式成為「黑卡百戶長」。

四大計分項

🏠

看房單

+10

每張帶看單

📝

下斡旋

+30

每次（成敗皆計）

🎥

看課率達 55%

+50

達標一次

📚

第一章作業

+50

繳交一次

百戶長晉升流程

開始累積

0 分

→

達 55% 看課

+50 分 / 兌換影片

→

交作業

+50 分

→

累積看房單

每張 +10 分

→

滿 1000 分

100 張帶看單

→

人工審核

管理員確認真實間數

→

⭐ 黑卡百戶長

正式升等

看課率達 55% 的附加福利：學員看課率達 55% + 第一章作業繳交 → 可兌換「仲介小房間談判術」回放影片資格。後台新增一欄記錄該學員的兌換狀態。

看課率閾值可調整

初期設定為 55%，會隨課程影片總數調整。後台「系統設定」頁面提供調整功能，不寫死在程式碼。

計分與資格的雙軌設計

自動計分

每張上傳檔案立刻 +10 分。學員可能因為一物件多張上傳而超出 1000 分。

人工資格

達 1000 分時系統亮警示，管理員後台人工核對實際看房間數，確認滿 100 間才升等百戶長。

4主要功能

v1 範圍：學員端 3 個核心模組、管理員端 8 個核心模組。其他進階功能（行為畫像、流失預警等）排入 v2。

4.1 學員端（app.shaprice.ai）

進度總覽（首頁）

app.shaprice.ai/me

歡迎回來，毛毛同學

看課率

68%

已達 55%

看房紀錄

23

/ 100 間

總分

330

/ 1000 分

百戶長進度

看房單列表

列表顯示：日期、地址、是否下斡旋、分數、狀態（已通過 / 已退回）
點擊任一筆可看大圖（簽名 URL，7 天有效）
不允許刪除，但可更新檔案（覆蓋上傳）

看房單上傳介面

必填欄位：

欄位	類型	說明
看房日期	日期	當天看房日期
物件地址	文字	例如「台北市信義區永春街 12 號」
中華地政房子資訊圖片	圖檔	中華地政系統查詢的房子資訊截圖
是否下斡旋	勾選	勾選後需另上傳斡旋單圖片 (+30 分)
看房照片	圖檔	可勾「沒有照片」（從寬認定）
備註欄	文字	選填

第一章作業繳交

學員可在系統內直接上傳作業（取代之前 Google Drive 流程）。允許 docx / pdf 格式。繳交後 +50 分。

4.2 管理員後台（artteam.shaprice.ai）

後台首頁

artteam.shaprice.ai

今日動態

📥 今日上傳	14 筆
⚠️ 待人工審核	3 筆
🎯 達 1000 分候選人	2 位
📊 達 55% 看課率（今日新增）	5 位

主要模組：

學員列表

所有學員、可排序、可搜尋、可過濾組別。

看房單抽查

列出隨機 N 筆或近期 N 筆，逐張標記合格 / 不合格。

異常清單

檔案異常、命名異常、學員無紀錄等異常情況。

看課率匯入

上傳開課快手匯出的 Excel，自動更新所有學員 progress。

百戶長審核

達 1000 分學員清單，逐位人工確認後升等。

退費標記

標記學員為「已退費」狀態，30 天後 cron 自動匿名化。

系統設定

調整看課率閾值（55%）、檔案大小限制、cron 排程等。

客服資訊

LINE @608qpiiq / Email service@shaprice.ai / 0965499173。

5業務流程

系統三大關鍵流程。

流程一：看房單上傳 + 自動計分

1

學員打開上傳頁，填寫必填欄位（日期、地址、地政圖、是否下斡旋、看房照片）。

2

前端驗證：只接受 jpg/jpeg/png/pdf/HEIC；單檔 ≤10MB；單筆紀錄 ≤100 張；每日 ≤100 張。HEIC 上傳後系統自動轉成 JPEG 顯示。

3

檔案上傳到 Supabase Storage，UUID 重新命名，MIME type 後端再驗一次。

4

建立 house_visit 紀錄，attachments 關聯到該紀錄。

5

自動計分：看房單 +10、有斡旋再 +30。寫入 scores 表。

6

學員儀表板立刻更新顯示新分數。

流程二：黑卡百戶長兩階段審核

1

學員累積分數至 1000 分（系統自動計分達標）。

2

後台儀表板亮警示「達 1000 分候選人：X 位」。

3

管理員進入該學員詳情，瀏覽所有看房單 attachments，核對實際看房間數。

4

確認 100 間屬實 → 按「升等為百戶長」按鈕。

5

學員狀態變更為「百戶長」，學員端顯示徽章。

流程三：退費學員 30 天觀察期 + 自動匿名化

1

管理員標記學員為退費，寫入 refund_marked_at。

2

學員無法再登入系統。

3

後台仍可看到完整資料 30 天，誤標可恢復。

4

Cron 每天凌晨檢查 refund_marked_at < NOW() - 30 days AND anonymized_at IS NULL。

5

自動匿名化：姓名 → 「〇〇〇」、email → null、phone → null，保留看房單與分數統計。

6資料模型

v1 必建 8 張表。主鍵採 UUID。所有表使用軟刪除（deleted_at 欄位）。所有時間戳使用 timestamptz 並以 UTC 儲存、台灣時區顯示。

cohorts 期別

idUUID PK

nameTEXT

start_dateDATE

course_unit_countINT

watch_thresholdINT (預設 55)

students 學員主表

idUUID PK

student_noTEXT UNIQUE

cohort_idUUID FK

full_nameTEXT

masked_nameTEXT

email / phoneTEXT

group_nameTEXT

statusENUM

is_hundred_houseBOOL

can_redeem_videoBOOL

refund_marked_atTIMESTAMPTZ

anonymized_atTIMESTAMPTZ

house_visits 看房紀錄

idUUID PK

student_idUUID FK

visit_dateDATE

addressTEXT

has_bidBOOL

has_photoBOOL

noteTEXT

score_visitINT (10)

score_bidINT (0/30)

audit_statusENUM

house_visit_attachments 看房附件

idUUID PK

house_visit_idUUID FK

file_pathTEXT

file_typeENUM

mime_typeTEXT

size_bytesBIGINT

assignments 作業

idUUID PK

student_idUUID FK

assignment_typeTEXT

file_pathTEXT

scoreINT (50)

submitted_atTIMESTAMPTZ

scores 分數彙總

idUUID PK

student_idUUID FK UNIQUE

visit_countINT

bid_countINT

visit_scoreINT

bid_scoreINT

watch_scoreINT (0/50)

assignment_scoreINT (0/50)

total_scoreINT

course_progress 看課進度

idUUID PK

student_idUUID FK

completed_unitsINT

total_unitsINT (84)

progress_percentDECIMAL

reached_thresholdBOOL

sync_jobs 匯入歷程

idUUID PK

sourceTEXT

statusENUM

records_syncedINT

error_msgTEXT

repair_tasks 自動修復任務

idUUID PK

sourceENUM (admin/issue/dispatch)

statusENUM

providerclaude_code

billing_modesubscription_session

repository_urlTEXT

base_branchTEXT

repair_branch_nameTEXT

pull_request_urlTEXT

bug_report_idUUID FK

github_issue_urlTEXT

titleTEXT

error_summaryTEXT

stack_traceTEXT

workflow_run_idTEXT

failure_reasonTEXT

關聯設計

7系統架構

前後分離。Next.js 兩個獨立專案、Supabase 統一資料層、Vercel 自動部署、Sentry + Vercel Analytics 雙監控。

技術選型

層級	選用
前端框架	Next.js 15 (App Router)
UI 元件	shadcn/ui + Tailwind CSS 4
資料庫	Supabase Postgres
檔案儲存	Supabase Storage
排程	Vercel Cron / Supabase Edge Function
部署	Vercel + GitHub Actions
監控	Sentry + Vercel Analytics
Migration	Supabase CLI

8安全與隱私

學員個資 + 房屋資訊都是敏感資料，採多層防護。

🔐 認證

學員：Supabase Auth + Magic Link + Google OAuth
管理員：獨立帳密 + 2FA
白名單機制：行政維護版 Excel 為主
退費學員自動鎖定登入

🛡️ RLS（嚴格隔離）

學員只能 read/write 自己的 row
管理員後端用 service_role 繞過
service_role key 只放在 Server 環境
所有表都有 RLS policy

📁 檔案安全

允許：jpg / jpeg / png / pdf / HEIC
禁止：html / js / svg / exe / zip
MIME type 後端驗證
UUID 重命名
簽名 URL TTL：7 天
單檔 ≤ 10MB / 單筆 ≤ 100 張
每位學員每日上傳上限 100 張

🤖 反爬蟲

robots.txt 拒絕所有索引
X-Robots-Tag: noindex
不公開列出學員清單

🔒 個資打碼

學員看別人：中間字〇
學員看自己：完整姓名
管理員：可看完整，留 audit log

🗑️ 退費清理

標記退費 → 30 天觀察期
30 天後 cron 自動匿名化
姓名 → 〇〇〇 / email → null
保留統計資料

🔑 環境變數分級

Production / Preview / Development 獨立
Vercel Sensitive Environment Variables
Service Role Key 不出現在前端
Sentry token / OAuth secret 只放 Server

💾 備份策略

Supabase 內建每日自動備份
每天 10:00 雙備份到 Google Drive
備份檔案加密

開課快手 API 整合

Teachify API

端點	`https://teachify.io/admin/graphql`
認證	Header: `X-Teachify-API-Key`
儲存位置	Vercel Environment Variable (Sensitive)
變數名稱	`TEACHIFY_API_KEY`
取得方式	開課快手後台 → API Keys → 建立新 token
使用場景	v2 階段串接，v1 過渡期靠 Excel 匯入

9部署與監控

CI/CD 流程

本地開發

npm run dev

→

Git Push

到 GitHub

→

GH Actions

跑測試 + Lint

→

Preview 部署

PR 獨立 URL

→

Merge 到 main

人工 review

→

Vercel Production

自動部署

環境配置

環境	用途	網址	資料庫
Development	本地開發	localhost:3000	Local Supabase
Preview	PR 預覽	*-preview.vercel.app	Supabase Preview Branch
Production	正式上線	app.shaprice.ai / artteam.shaprice.ai	Supabase Prod

監控配置

Sentry

錯誤捕捉、Stack trace、Email 警報。免費版每月 5,000 個錯誤。

Vercel Analytics

頁面流量、Web Vitals 效能指標、Real User Monitoring。

Supabase Logs

資料庫慢查詢、Auth 失敗、RLS 違規嘗試。

10自動修復系統（Auto Repair Agent）

當系統收到 bug report、GitHub Issue、CI failed event，或使用者在後台手動點擊「派 Claude 自動修」時，自動啟動 AI 修復流程，產生診斷報告、修復分支與 Pull Request，協助開發者快速處理問題。MVP 階段不允許 AI 自動 merge，只能建立 Pull Request 由人類審核合併。

核心架構

Provider 決策

MVP 採用 Claude Code GitHub Action 作為主要修復執行器，原因：

可透過 CLAUDE_CODE_OAUTH_TOKEN 使用開發者既有 Claude Pro / Max 訂閱額度
不預設使用 Anthropic API key
不產生額外 AI API token 計費
可直接整合 GitHub Issue、Pull Request 與 GitHub Actions workflow
適合單人開發者、自用後台與自動修復 PR 流程

Codex 暫不作為 MVP 預設 provider：目前 GitHub Action / server-side 自動觸發模式通常需要 OPENAI_API_KEY，會產生 OpenAI API billing。未來可保留 Codex provider 擴充，但必須在 UI 明確標示 billing mode，不得預設宣稱 0 額外費用。

Billing Policy

Auto Repair Agent MVP 必須使用 subscription-based Claude Code execution，預設規則：

✓ 允許

使用 CLAUDE_CODE_OAUTH_TOKEN
消耗 Claude Pro / Max 訂閱額度與 rate limit / cap

✗ 禁止

使用 ANTHROPIC_API_KEY
使用 OPENAI_API_KEY
啟用 API billing fallback
未經明確設定與 UI 提示切換到 API 計費 provider

若 Claude 訂閱 cap 不足、token 失效或 GitHub Action 執行失敗，repair task 必須進入 failed 狀態並顯示原因。

觸發來源

MVP 支援

後台 /admin/bug-reports 點擊「派 Claude 自動修」
GitHub Issue webhook
GitHub Actions workflow dispatch

未來可擴充

CI failed webhook
Sentry / log service error webhook
內部 API endpoint 觸發
定期掃描未處理 bug reports

核心流程（11 步）

1

使用者在 /admin/bug-reports 點擊「派 Claude 自動修」

2

系統建立 repair task（status = queued）

3

系統整理 bug report 內容、錯誤摘要、stack trace、重現步驟與相關路由

4

系統觸發 GitHub Actions workflow（status = triggering）

5

GitHub Actions 使用 CLAUDE_CODE_OAUTH_TOKEN 啟動 Claude Code（status = running）

6

Claude Code 建立修復 branch

7

Claude Code 分析問題、修改程式碼並視需要新增測試

8

Claude Code 執行允許的驗證指令（lint、typecheck、test）

9

Claude Code 建立 Pull Request（status = pr_created）

10

系統回寫 repair task 狀態、PR URL、修復摘要與失敗原因

11

使用者人工審核 PR 並決定是否合併

修復權限限制

Claude Code 不得直接 merge PR。

✓ 預設允許

建立新 branch
修改允許範圍內的程式碼
新增或修改測試
執行專案允許的驗證指令
建立 Pull Request
在 PR 內留下修復摘要、測試結果與風險說明

✗ 預設禁止

直接 merge PR
修改 .env、secret、credential 相關檔案
修改 GitHub Actions secrets
刪除 migration
直接修改 production database
執行 destructive shell command
關閉 lint、typecheck、test 或安全檢查
在 log、PR、issue comment 中輸出 CLAUDE_CODE_OAUTH_TOKEN

Repair Task 資料模型（TypeScript）

type RepairTaskStatus =
  | "queued"
  | "triggering"
  | "running"
  | "pr_created"
  | "failed"
  | "cancelled";

type RepairTaskSource =
  | "admin_bug_report"
  | "github_issue"
  | "github_workflow_dispatch";

type RepairAgentProvider = "claude_code";

type RepairBillingMode = "subscription_session";

interface RepairTask {
  id: string;
  source: RepairTaskSource;
  status: RepairTaskStatus;
  provider: RepairAgentProvider;
  billingMode: RepairBillingMode;
  repositoryUrl: string;
  baseBranch: string;
  repairBranchName: string | null;
  pullRequestUrl: string | null;
  bugReportId?: string;
  githubIssueUrl?: string;
  title: string;
  errorSummary: string;
  stackTrace?: string;
  reproductionSteps?: string;
  workflowRunId?: string;
  failureReason?: string;
  createdAt: string;
  updatedAt: string;
}

GitHub Secrets 設定

Repo 必須設定以下 GitHub Actions secret：

CLAUDE_CODE_OAUTH_TOKEN

取得流程：

1

在本機 terminal 執行 claude setup-token

2

瀏覽器開啟 Claude.ai 授權頁

3

同意授權

4

terminal 輸出 OAuth token

5

設定 GitHub repo Secret：Settings → Secrets and variables → Actions → New repository secret

後台 UI 需求

/admin/bug-reports 需提供「派 Claude 自動修」按鈕。

artteam.shaprice.ai/admin/bug-reports

#1278 學員上傳 HEIC 時頁面崩潰

2026-05-13 14:32 · 報告人：00172 張O葆

狀態：running · Workflow Run：github.com/.../actions/runs/12345

目前使用 Claude Code，將消耗你的 Claude Pro / Max 訂閱額度，不會使用 API key 計費。

按鈕行為

點擊後建立 repair task
顯示目前狀態：queued / triggering / running / pr_created / failed
顯示 GitHub Actions workflow run URL
若成功，顯示 Pull Request URL
若失敗，顯示 failure reason
同一個 bug report 在已有 running task 時，不得重複觸發
可在 failed 狀態後重新觸發

MVP 範圍

✓ 第一版支援

後台手動觸發自動修復
GitHub Actions workflow dispatch
Claude Code GitHub Action
CLAUDE_CODE_OAUTH_TOKEN
repair task 狀態追蹤
Pull Request URL 回寫
failure reason 回寫
禁止自動 merge

✗ 第一版不支援

Codex provider
OpenAI API provider
Anthropic API key provider
自動 merge
多 agent 並行修復
production incident 自動回滾
自動修改 production database
自動處理 billing fallback

成功標準

使用者可以在 /admin/bug-reports 點擊「派 Claude 自動修」
系統可以建立 repair task
GitHub Actions 可以成功啟動 Claude Code
Claude Code 可以建立修復 branch 與 Pull Request
repair task 可以回寫 PR URL 或失敗原因
整個流程不需要 ANTHROPIC_API_KEY 或 OPENAI_API_KEY
修復流程不會產生額外 AI API token 計費

11引導系統（Onboarding & Help Center）

為「學員」與「新助理」兩種對象提供漸進式引導，分三層：首次登入 Tour、Inline 提示、Help Center 知識庫。學員端與助理端兩套引導系統物理分離，分別運作。

三層引導架構

層級	是什麼	觸發時機	例子
L1 First-time Tour 首次教學	全螢幕 5-8 步驟引導	第一次登入自動跳出	「歡迎！這是你的進度卡 → 這是上傳按鈕」
L2 Inline Hint 隨手提示	UI 元件旁的 `?` 圖示	使用者主動點	「達 55% 是什麼意思？」
L3 Help Center 幫助中心	獨立的 /help 頁，含 FAQ + SOP	隨時可進	完整知識庫，可搜尋

11.1 學員端引導（app.shaprice.ai）

First-time Tour（5 步）

1

歡迎「房產剎價學學員系統，你的學習進度都會記錄在這」

2

進度卡解釋看課率、看房紀錄、總分各代表什麼，指向頁面三大數字

3

達標規則百戶長 = 100 間或 1000 分（任一達成）

4

上傳看房單指向上傳按鈕，示範必填欄位

5

哪裡找幫助指向右上 Help Center 入口、提及客服 LINE

Inline Hint 位置（學員端）

進度條旁：「為什麼是 55%？」
「下斡旋」勾選旁：「下斡旋 +30 分，需附斡旋單照片」
「沒有照片」勾選旁：「從寬認定，但整筆紀錄都沒照片可能被退回」
第一次上傳：滑鼠停在表單上會出現逐欄提示

學員 Help Center（路由 `/me/help`）

5 個分類：

📊 計分規則

看房單、下斡旋、看課率、作業如何計分；百戶長如何認定。

📤 上傳指南

該拍哪些照片、什麼角度、上傳格式（jpg/png/pdf/HEIC）。

↩️ 退回處理

看房單被退回的常見原因、如何重新上傳。

🎬 兌換影片

看課率 55% + 第一章作業 = 可兌換「仲介小房間談判術」回放。

⚙️ 帳號管理

登入方式、忘記密碼、聯絡客服。

11.2 新助理引導（artteam.shaprice.ai）

Onboarding（8 步）

1

歡迎 + 權限說明你目前的權限範圍與限制

2

後台首頁動態列怎麼讀今日上傳、待審核、達標候選人

3

學員列表搜尋、過濾、排序、進入學員詳情

4

看房單抽查 SOP怎麼判合格/退回，退回時要不要附原因

5

看課率匯入 SOP每週一/四從開課快手後台匯出 Excel、上傳流程

6

百戶長升等審核1000 分候選人怎麼核對實際間數、升等流程

7

退費標記30 天觀察期意義、誤標如何恢復

8

找不到答案時聯絡 miru / Yuna 的方式

Inline Hint 位置（助理端）

每個後台模組標題旁有 ? 開模組說明
危險動作前彈確認對話框（退費標記、升等百戶長、刪除 FAQ）
關鍵指標旁標示「這個數字怎麼算」

助理 Help Center（路由 `/artteam/help`）

6 個分類：

📋 模組 SOP

每個後台模組的詳細操作手冊。

✅ 看房單審核標準

合格/不合格的判定原則、邊界案例。

📊 看課率匯入流程

從開課快手匯出 Excel 到後台上傳的步驟、失敗排查。

⭐ 百戶長審核

1000 分達標後的人工核對流程、實際間數判定。

💸 退費處理

退費標記流程、30 天觀察期意義、誤標恢復。

🚨 緊急情況

學員系統異常、資料錯誤、緊急聯絡資訊。

11.3 再看一次教學

每位學員 / 助理都有「教學重新開始」按鈕：

學員端：右上角頭像下拉 → 「重看教學」
助理端：右上角頭像下拉 → 「重看教學」
可選「完整 tour」或「跳到特定章節」
重看不會影響 onboarding_progress 完成狀態

11.4 資料模型

學員端與助理端兩套物理分離的表，共 4 張：

student_onboarding_progress 學員教學進度

idUUID PK

student_idUUID FK

tour_idTEXT (例 first_login_v1)

current_stepINT

completed_atTIMESTAMPTZ

skippedBOOL

last_viewed_atTIMESTAMPTZ

student_help_articles 學員 FAQ

idUUID PK

categoryENUM (scoring/upload/...)

titleTEXT

contentTEXT (Markdown)

order_indexINT

publishedBOOL

created_byUUID (管理員)

updated_atTIMESTAMPTZ

admin_onboarding_progress 助理教學進度

idUUID PK

admin_idUUID FK

tour_idTEXT

current_stepINT

completed_atTIMESTAMPTZ

skippedBOOL

last_viewed_atTIMESTAMPTZ

admin_help_articles 助理 FAQ

idUUID PK

categoryENUM (sop/audit/...)

titleTEXT

contentTEXT (Markdown)

order_indexINT

publishedBOOL

created_byUUID (管理員)

updated_atTIMESTAMPTZ

11.5 後台 FAQ 編輯介面

管理員可在 artteam.shaprice.ai/admin/help 編輯兩套 FAQ。

artteam.shaprice.ai/admin/help

📊 計分規則 · 看房單怎麼算分

已發佈 · 順序 1 · 更新於 2026-05-10

📤 上傳指南 · 該拍哪些照片

已發佈 · 順序 2 · 更新於 2026-05-12

編輯介面功能

切換「學員端」/「助理端」兩個 FAQ 集合
CRUD：新增、編輯、刪除（軟刪除）、複製
拖曳排序：直接拖卡片改 order_index
草稿 / 發佈兩種狀態（草稿不會出現在前台）
Markdown 編輯器 + 即時預覽
編輯後即時生效（不用重新部署）

11.6 技術選型

用途	選用	說明
First-time Tour	`react-joyride`	步驟引導、遮罩、高亮目標元素
Inline Hint	自製 Tooltip（Tailwind）	輕量、可控、跟著主題色
Markdown 編輯器	`@uiw/react-md-editor`	Markdown + 即時預覽
Markdown 顯示	`react-markdown`	安全渲染（防 XSS）

11.7 MVP 範圍

✓ v1 完整支援

學員 5 步 First-time Tour
助理 8 步 Onboarding
學員端 Inline Hints（4 個主要位置）
助理端 Inline Hints（各模組標題、危險動作確認）
學員 Help Center 5 個分類
助理 Help Center 6 個分類
「重看教學」按鈕（學員 + 助理）
後台 FAQ 編輯介面（CRUD + 拖曳排序 + 預覽）
編輯後即時生效

✗ v1 不做

影片教學（v2 補）
AI 對話幫助（v3 規畫）
多語介面（外國學員不多）
分眾推送個人化引導
引導完成度統計 dashboard
A/B 測試不同教學流程

11.8 成功標準

學員第一次登入自動跳出 Tour，可手動跳過
學員可在右上角頭像下拉「重看教學」
學員可進 /me/help 查看 5 個分類 FAQ
學員端 Inline Hint 在指定 4 個位置可點開說明
管理員第一次登入自動跳出 Onboarding
管理員可進 /artteam/help 查看 6 個分類 SOP
管理員可在 /admin/help 編輯兩套 FAQ
編輯 FAQ 後立即生效，不需要重新部署
學員與助理的 onboarding 進度互不影響

12路線圖

v1 上線是起點。後續依資料累積與業務優先級分階段擴充。

2026-05-13 → 2026-06-01

v1 開發 + 上線（本文件範圍）

學員端核心：登入、上傳、看自己分數。管理員端：審核、看課率匯入、百戶長升等、退費標記。Excel 過渡期，Teachify API 整合放在 v2。

2026-Q3

v2 — 數據自動化 + 行為分析

串接開課快手 API（取代 Excel）、學員行為畫像（時段熱力圖、Streak、回看熱點）、流失預警三色燈、徽章系統、Line OA 自動推送、看房單 OCR 抽查。

2027-Q1+

v3 — AI 預測 + ICP 分析

流失預測模型、個人化課程推薦、ICP 自動發掘、跨期 A/B 測試框架、LTV 預測。

A附錄 — 業務確認紀錄

Yuna 完成業務問卷確認，主要規則整理如下。

計分規則

看房單：每張 +10 分
下斡旋：每次 +30 分（成敗皆計）
看課率達 55%：+50 分（並可兌換「仲介小房間談判術」回放影片）
第一章作業：+50 分（並可兌換「仲介小房間談判術」回放影片）
滿 1000 分 → 人工審核 → 黑卡百戶長
初步審核：系統自動立即加分，人工只在達 1000 分時介入

檔案規則（v1.1 修訂）

允許格式：jpg / jpeg / png / pdf / HEIC（v1.1 新增）
禁止格式：html / js / svg / exe / zip
HEIC 上傳後系統自動轉成 JPEG 顯示

學員資料修正

00370 Alice 卓 → 已退費，標記退費
00391 吳宜霓 → 已退費，標記退費
00803 鄧惠芸 → email 修正為 lilyteng0526@gmail.com
00854 張宇姍 → email 修正為 tonicazoo@gmail.com
11 筆複合 email → 已逐筆指定登入 email（含 00792 凌沛臻 = great013@gmail.com）

名單管理

正式白名單：以「行政維護版 Excel」為主
平台獨有 54 筆：KOL / 工作人員 / 老師朋友
行政版獨有 72 筆：已購課但未兌換的學員（需後台手動加白名單）

流程細節（v1.1 修訂）

必填欄位：看房日期、物件地址、中華地政房子資訊圖片、是否下斡旋、看房照片、備註欄
不允許刪除，只允許更新檔案
所有管理員都能審核所有學員
學員在新系統上傳作業（不走 Google Drive）
看課率每週一、四更新
看課率匯入：所有管理員都可執行（v1.1 修訂：不再限定 Yuna / 巧巧）
系統設定變更：所有管理員都可執行（v1.1 修訂）

客服與管理員

LINE 客服 ID	`@608qpiiq`
客服 Email	`service@shaprice.ai`
客服電話	`0965499173`
管理員 1	Yuna — `x06can1220@gmail.com` — 全權限
管理員 2	曹曹 — `janettsao71@gmail.com` — 全權限

資料保留

退費學員：標記退費 → 30 天觀察期 → 自動匿名化（保留統計資料）
結業學員（黑卡百戶長）：永久保留完整資料

B附錄 — 技術決策紀錄

miru 完成技術架構決策（M1-M22）。

編號	項目	決定
M1	後台 vs 學員端架構	分兩個專案（shaprice-admin + shaprice-app）
M2	學員端網域	app.shaprice.ai（子網域）
M3	Repo / Supabase	shaprice-app + 一個 Production Supabase
M4	學員登入	Magic Link + Google OAuth 雙軌
M5	管理員登入	獨立帳密 + 2FA
M6	Session	學員 30 天 / 管理員 1 小時 / 不記住我
M7	6/1 學員端 UI	進度總覽卡、看房單列表、上傳介面
M8	後台首頁	簡潔版 + 帶看單、看課率動態
M9	主鍵 + 刪除	UUID + 軟刪除
M10	v1 必建表	8 張表
M11	檔案上傳	100 張 / 紀錄、10MB / 檔、不支援影片
M12	Storage	簽名 URL 7 天 / 看房單和作業分開資料夾
M13	達 55% 通知	後台亮警示，團隊手動 LINE
M14	看房單上傳處理	立即計分 + 事後抽查
M15	通過/退回通知	站內訊息
M16	CI/CD	GitHub Actions 跑測試 + Vercel 部署 + Preview Deployment
M17	錯誤監控	Vercel + Sentry 雙裝
M18	Migration	Supabase CLI
M19	學員看自己姓名	顯示完整姓名
M20	RLS 策略	嚴格隔離
M21	退費資料清理	後台按鈕手動清（cron 兜底 30 天後自動匿名）
M22	路徑命名	後台 /artteam / 學員 /me / API 統一 /api/*

引導系統決策（v1.3）

採用三層引導架構：L1 First-time Tour + L2 Inline Hint + L3 Help Center
引導工具：react-joyride（現成函式庫，省開發時間）
影片教學：v1 不做，純文字 + 截圖 SOP；v2 再補影片
FAQ 維護：後台可編輯（Markdown），編輯後即時生效
學員與助理 FAQ 物理分離（兩張獨立表 + 兩個獨立 Help Center）
「重看教學」功能：每位使用者可從頭像下拉選單啟動

Auto Repair Agent 決策（v1.2）

採用 Claude Code GitHub Action 作為 MVP 修復執行器
透過 CLAUDE_CODE_OAUTH_TOKEN 使用開發者 Claude Pro / Max 訂閱額度
禁止使用 ANTHROPIC_API_KEY 與 OPENAI_API_KEY（不產生額外 AI API 計費）
MVP 階段禁止 AI 自動 merge，只能建立 Pull Request 由人類審核
Codex provider 暫不採用（會產生 OpenAI API billing）

額外安全要求

robots.txt 拒絕所有爬蟲索引
除 Supabase 內建備份外，每天 10:00 雙備份到 Google Drive
Vercel 環境變數分級（Production / Preview / Development 獨立）
Service Role Key 不得出現在前端
Supabase service_role、Sentry token、OAuth secret 必須只放 Server 環境
正式機密使用 Vercel Sensitive Environment Variables
限制副檔名：jpg、jpeg、png、pdf、HEIC；禁止：html、js、svg、exe、zip
檢查 MIME type、檔名重新命名為 UUID
單一學員每日上傳量限制 100 張

1文件摘要

系統定位

v1 核心效益

2角色與權限

認證機制

3計分規則

四大計分項

百戶長晉升流程

看課率閾值可調整

計分與資格的雙軌設計

4主要功能

4.1 學員端（app.shaprice.ai）

進度總覽（首頁）

看房單列表

看房單上傳介面

第一章作業繳交

4.2 管理員後台（artteam.shaprice.ai）

後台首頁

5業務流程

流程一：看房單上傳 + 自動計分

流程二：黑卡百戶長兩階段審核

流程三：退費學員 30 天觀察期 + 自動匿名化

6資料模型

關聯設計

7系統架構

技術選型

8安全與隱私

開課快手 API 整合

9部署與監控

CI/CD 流程

環境配置

監控配置

10自動修復系統（Auto Repair Agent）

核心架構

Provider 決策

Billing Policy

觸發來源

核心流程（11 步）

修復權限限制

Repair Task 資料模型（TypeScript）

GitHub Secrets 設定

後台 UI 需求

按鈕行為

MVP 範圍

成功標準

11引導系統（Onboarding & Help Center）

三層引導架構

11.1 學員端引導（app.shaprice.ai）

First-time Tour（5 步）

Inline Hint 位置（學員端）

學員 Help Center（路由 /me/help）

11.2 新助理引導（artteam.shaprice.ai）

Onboarding（8 步）

Inline Hint 位置（助理端）

助理 Help Center（路由 /artteam/help）

11.3 再看一次教學

11.4 資料模型

11.5 後台 FAQ 編輯介面

編輯介面功能

11.6 技術選型

11.7 MVP 範圍

11.8 成功標準

12路線圖

A附錄 — 業務確認紀錄

計分規則

檔案規則（v1.1 修訂）

學員資料修正

名單管理

流程細節（v1.1 修訂）

客服與管理員

資料保留

B附錄 — 技術決策紀錄

引導系統決策（v1.3）

Auto Repair Agent 決策（v1.2）

額外安全要求

學員 Help Center（路由 `/me/help`）

助理 Help Center（路由 `/artteam/help`）