# 產品需求文件 ・ Pearl Academy Quest v4

> 版本 v4.0 ・ 2026-05-22
> 對象:Gipi(院長)/ 大姐(營運長)/ Coffee(學務統籌)/ HR / 工程外包

---

## 0. TL;DR

**問題**:現在的 MA 培訓是師徒制 + Notion 散落筆記,知識破碎、新進淘汰率高、資深疲勞。

**解決方案**:Quest 互動學習平台 ・ 學員端遊戲化(XP / 徽章 / 階段目標)+ 後台 HR / Mentor 三方協作。

**MVP 範圍**:學員端完整 + 後台 CRUD + 模板 + 章節 + 學習日誌 + 思考題批改 + 權限管理。

**目前狀態**:雙 prototype(`v4-prototype.html` 學員端 + `v4-admin-prototype.html` 後台),純前端 + localStorage 雙向同步,可直接 demo。下一步接 Supabase backend。

---

## 1. 使用者角色與權限

| 角色 | 可看到的資料 | 可編輯 |
|---|---|---|
| **學員 (MA)** | 自己的進度 / 階段目標 / 學習日誌 | 自己的學習日誌 / 思考題答案 |
| **Mentor** | 自己帶的學員 | 學員的階段目標 / 批改思考題 / 寫回饋 |
| **主管** | 自部門全部學員 | 看與評,不寫內容 |
| **HR** | 全部學員 + 全部內容 | 學員 CRUD / 模板 / 章節 / 福利 / 公司簡介 / 徽章 |
| **管理員** | 全部 + 權限矩陣 | 所有 + 角色權限 + 使用者帳號 |

權限矩陣可在後台 `/admin/permissions` 編輯。

---

## 2. 學員端功能(v4-prototype.html)

### 2.1 Sidebar 結構

```
🏠 首頁
─────────────────────
[個人資訊卡:頭像/名字/部門/D+N/Lv/XP]
─────────────────────
🏢 公司簡介
🎯 學習目標
📚 學習專區
─────────────────────
📔 學習日誌記錄
```

### 2.2 首頁(Home)

- Hero:早安、D+N、部門 chip、區域 chip
- **🎯 里程碑卡**:下一個階段 + 倒數 + 進度條(點擊進學習目標)
- **🌱 新人 Onboarding 任務**(D ≤ 7 顯示):前 7 天的 6 個必修任務
- **本週小贏**:D+30 前 3 項
- **你的 Mentor**:姓名 / 角色 / 下次 M2M 時間
- **繼續學習**:接續上次未完成關卡
- 🏢 公司簡介 snippet(點進入)
- 🎁 員工福利 snippet(點進入)
- **📔 學習日誌記錄** snippet(顯示已寫篇數 / 卡關未解數)
- **徽章預覽**(8 顆 grid)

### 2.3 公司簡介(三 tab)

1. **🏢 公司介紹**:tagline / 數字 stat / 多個章節內容
2. **🌐 組織結構**:節點圖(點節點看說明)
3. **🎁 員工福利**:福利卡片清單 + 問題找誰問

(後台可編輯所有內容)

### 2.4 學習目標(Stage Goal)

4 個階段(D+30 / D+90 / D+180 / D+365),每階段:
- 階段名 + icon + 日期 + 狀態(進行中 / 已達成 / 即將 / 逾期)
- 考核項目清單(可勾達成、可點展開看細節)
- Mentor 回饋(只在有寫時顯示)

每個考核項目可有:
- 細節內容(HTML 支援標題 / 列表 / 粗斜體 / callout 提示框等)
- 完成連結到(公司簡介 / 員工福利 / 學習專區 / 學習日誌)
- 客製化標籤(顯示「客製」金色 tag)

### 2.5 學習專區(Learning Hub)

- Hero:整體完成率 + 累積 XP + 進度條
- **⭐ 接下來重點學習章節**(自動找下一個未完成且未鎖)
- 所有章節 accordion(點章節大標 expand / collapse 該章節 quest 列表)
- 每個 quest 顯示題型 icon + 完成狀態 + 進入按鈕

### 2.6 關卡題型

| 題型 | 用途 |
|---|---|
| `lesson` 📖 | 課程內容(支援 WYSIWYG 內容 + callout) |
| `choice` 🅰️ | 單選題(四選一 + 答錯遞進提示) |
| `drag` 🗂 | 拖曳分類 |
| `order` 🔢 | 排序 |
| `explore` 🔍 | 探索點擊(點亮所有節點) |
| `reflect` 💭 | **思考題**(自由回答 + 提示 + Mentor 批改) |

### 2.7 學習日誌記錄(modal)

雙 tab:
- **📒 今日學習記錄**:心情(😀 / 😐 / 😩)+ 自由文字 → +5 XP
- **⚠️ 卡關點紀錄**:分類 + 描述 → Mentor 12 hr 內回應

### 2.8 能力認定(c5)

完成所有可學習關卡後展示。簡約樣式:白底卡 + 邊框 + 數字統計 + 文字祝賀,**不用大金色 cert mark**。

---

## 3. 後台功能(v4-admin-prototype.html)

### 3.1 Sidebar

```
🏠 Dashboard
──── 人員管理 ────
👥 學員管理
🧑‍🏫 Mentor 配對
──── 內容管理 ────
📋 Onboarding 模板
📚 章節 / 關卡
🏢 公司簡介
🎁 員工福利
🏆 徽章
──── 營運 ────
📔 學習日誌
──── 系統管理(admin only) ────
🔐 權限管理
```

頂部 ☰ 按鈕可隱藏 sidebar(編輯內容時全寬)。

### 3.2 Dashboard

- 在學人數 / 卡關待回 / 本週活躍 / W1 主線完成 4 個 stat card
- 「本週應關注」:紅黃綠燈警示清單
- 學員進度概覽表

### 3.3 學員管理

- 列表(姓名 / 梯次 / 部門 / Mentor / 進度 / XP / 徽章 / 最後活動 / 狀態)
- 搜尋 / 篩選(部門 / Mentor / 狀態)
- ➕ 新增學員(含入職日)
- 學員 detail(5 個 Tab):
  - 📇 基本資料
  - 📈 進度
  - 🎯 學習目標(切換模板 / 客製化每項)
  - 📔 學習日誌
  - 📝 HR 備註
- 「👤 以此學員身份登入」連結到 `v4-prototype.html?learnerId=xxx`

### 3.4 Mentor 配對

- Mentor 卡片(姓名 / 等級 / capacity / 平均回應時間)
- 配對拖拉(指派學員)
- 新增 / 編輯 Mentor

### 3.5 Onboarding 模板

- 列表(部門 / 區域 keyword / 使用學員數)
- 編輯模板(icon / 名稱 / 部門 / keyword chip / 4 個階段考核項目)
- 每個項目可:
  - 拖曳排序
  - 開「📝 細節」modal(WYSIWYG 編輯內容 + 完成連結)
  - 標客製
  - 刪除 / 新增
- 模板 CRUD:新增 / 複製 / 刪除

### 3.6 章節 / 關卡

- 章節樹(左)+ 關卡編輯器(右)
- **📚 章節管理**:加 / 刪 / 改章節 / 切換鎖定
- **➕ 新增關卡**:簡化 modal(只需名稱 + 章節 + 題型)
- 關卡編輯器:
  - Subtitle / Title
  - Scene / Task / Explain
  - 題型專屬 payload 編輯器(拖曳排序)
  - XP / 發布狀態
  - 刪除關卡

### 3.7 公司簡介 / 員工福利

- 公司簡介:tagline / 數字 / 多章節(可加減)
- 員工福利:項目 CRUD(icon / 名稱 / 描述 / 條件)
- 兩者皆即時同步學員端

### 3.8 徽章

- 4 群組:Onboarding / Lv1 / Lv2 / 進階
- CRUD modal(icon / 名稱 / 群組 / target / desc / reward)

### 3.9 學習日誌(後台收件匣)

三 tab:
- ⚠️ **卡關紀錄**(學員端 surface 來的)
- 📒 **今日學習**(學員寫的學習日誌)
- ✍️ **思考題批改**(學員思考題回應,有「參考解答」只給 mentor 看)

### 3.10 權限管理(admin only)

- 角色 × 權限矩陣(管理員 / HR / 主管 / Mentor × 8 項權限)
- 使用者列表 + 新增使用者 modal

### 3.11 WYSIWYG 編輯器

關卡 lesson 內容 / 模板項目細節 / Mentor 批改回饋 / 公司簡介章節 等場合都用 WYSIWYG。

**工具列**:
- 段落樣式(H2 / H3 / H4 / 段落 / 引用 / 程式塊)
- B / I / U / S(粗 / 斜 / 底 / 刪)
- • / 1.(無序 / 有序清單)
- 🔗 超連結
- ― 分隔線
- **設計規格**:💡 提示 / ⚠️ 警告 / ✅ 重點 / 📋 規格 / 📝 待辦 callout
- 🟡 / 🔵 重點色高亮
- ↶ / ↷ 復原 / 重做

存 HTML、學員端直接渲染。

---

## 4. 資料模型(prototype localStorage / 未來 Supabase)

### 4.1 核心 Entity

| Table | 主要欄位 |
|---|---|
| **learner** | id / name / email / department / region / startDate / mentor / templateId / supervisor / jobBrief / photoEmoji |
| **mentor** | id / name / role / capacity / students[] / avgResponseHr |
| **chapter** | id / title / tag / color / locked / order |
| **quest** | id / chapter / type / payload(jsonb) / xp / published |
| **badge** | id / icon / name / group / target / desc / reward / check_rule |
| **onboarding_template** | id / name / icon / department / regionKeywords[] / goals(d30/d90/d180/d365) |
| **stage_goal_override** | learner_id × stage_code → items[] (個人客製) |
| **learner_state** | done[] / xp / earnedBadges[] / stageGoals / reflectAnswers / learnLog |
| **surface** | learner_id / content / category / status / mentorReply / replyAt |
| **company_info** | tagline / sections / orgStructure |
| **benefits** | items[] |
| **user_account** | name / email / roleId(admin/hr/manager/mentor) / roleName |
| **permission** | role × actions matrix |

### 4.2 localStorage Key 規範(目前 prototype)

| Key | 內容 |
|---|---|
| `pa-v4-state-{learnerId}` | 學員個人狀態(per-learner) |
| `pa-v4-current` | 當前選擇的 learnerId |
| `pa-v4-admin-quests-edits` | 章節 / 關卡編輯 |
| `pa-v4-admin-chapters-edits` | 章節清單 |
| `pa-v4-admin-templates` | 模板 |
| `pa-v4-admin-badges-edits` | 徽章 |
| `pa-v4-admin-company` | 公司簡介 |
| `pa-v4-admin-benefits` | 員工福利 |
| `pa-v4-admin-learners-edits` | 學員清單 |
| `pa-v4-admin-mentors-edits` | Mentor 清單 |
| `pa-v4-admin-surfaces` | 卡關 surface inbox |
| `pa-v4-admin-permissions` | 權限矩陣 |
| `pa-v4-admin-users` | 使用者帳號 |
| `pa-v4-admin-role` | 當前後台角色 |
| `pa-v4-admin-sidebar-collapsed` | sidebar 收合狀態 |

---

## 5. 雙向同步機制(prototype)

學員端 boot 時 merge:
- `pa-v4-admin-quests-edits` → QUESTS(append 新預設)
- `pa-v4-admin-chapters-edits` → CHAPTERS
- `pa-v4-admin-badges-edits` → BADGES(check function 自動補回)
- `pa-v4-admin-templates` → ONBOARDING_TEMPLATES
- `pa-v4-admin-learners-edits` → LEARNERS

學員端寫的 surface / reflect 答案後台收件匣即時看到。

---

## 6. 未來 v5+ Roadmap

| 版本 | 內容 |
|---|---|
| v5 | 接 Supabase backend + 真實 auth |
| v6 | 績效考核 + 留任預警 + 跨梯比較 |
| v7 | 前後測系統(9 訊號 S1-S9 量化) |
| v8 | 招募評分卡(基於 3 梯資料訓練) |
| v9+ | Lv3 / Lv4 內容 + AI 老師 + 對外輸出 |

詳見 `ROADMAP.md`。

---

## 7. 不在 MVP(v4)範圍

| 項目 | 為何 |
|---|---|
| 真實 auth(SSO) | prototype 用前端切換角色 |
| 真實寄信(magic link) | prototype 用 toast 模擬 |
| 真實 LINE Bot 接卡點 | prototype 在學員端寫 |
| 績效考核打分 | 文化未養成 |
| 360 度回饋 | 學員未到階段 |
| 真實業績 KPI 接通 | IT 工程量大 |

---

## 附錄 A · 9 個篩選訊號 S1-S9

從訪談洞察整理,Lv2 培訓設計與招募評分卡的瞄準標的:

| # | 訊號 | 強度 |
|---|---|---|
| S1 | 邊界感 | ★★★ 一票否決 |
| S2 | 文書邏輯 | ★★★ |
| S3 | 不可抗力應變 + Guts | ★★★ |
| S4 | 動機真實性 | ★★ |
| S5 | 價值觀對齊 | ★★ |
| S6 | 可被帶 ≠ 等餵 | ★ |
| S7 | 資訊不完整下做結構化判斷 | ★★★ |
| S8 | 流程意識 / SOP 思維 | ★★ |
| S9 | 商業敏感度 | ★★ → ★★★ |

詳細定義見 `~/.claude/skills/chicha-pearl-academy/SKILL.md`(顧問內部文件)。