專案管理儀表板 | Wayne Interactive English

專案總覽

韋恩互動美語 · 商業上線前準備狀態

🔴

4

緊急待辦

🟡

19

重要待辦

✅

6

已完成

📅

~12週

預估上線時程

各領域完成度

🔒 安全性（API Key、帳號安全）10%

☁️ GCP 遷移5%

📚 內容擴充（單字庫、題目）20%

👩‍🏫 教師管理功能35%

⚖️ 法律合規（條款、仿題標示）90%

🤖 AI 功能（批改、對話）70%

目前階段

正式商轉版 — 安全清理完成，已移除測試帳號與自動補帳邏輯

已完成：測試頁面清理、法律頁面、仿題標示、AI 批改升級、CF Worker Proxy、單字庫擴充（2,300+字）、商轉安全清理

下一步：前端支援新 CEFR 分類（elementary.json / phrases.json）

正式上線前 ❗必做

✅ 刪除 admin/admin 預設帳號（已完成）

✅ 移除 ensureAccounts() 自動補帳號（已完成）

⛔ API Key 移至 GCP Cloud Run Proxy

⛔ 強制密碼強度驗證（8位+大小寫+數字）

上線路線圖

預計 12 週完成全部準備工作，正式商業運轉

6月

7月

8月

9月

法律合規

✅ 完成

測試頁清理

✅ 完成

API Key 限制設定

進行中

GCP 環境建立

Week 2-5

API Proxy 部署

Week 4-6

單字庫擴充

Week 2-8

教師功能強化

Week 5-10

安全性強化

Week 7-8

QA & 壓測

Week 10-12

🚀 正式上線

🚀

Phase 1（已完成）

法律合規、測試頁清理、仿題標示、AI 批改升級、footer 法律連結

Phase 2（進行中）

GCP 環境建立、API Proxy 部署、API Key HTTP 限制設定、帳號安全強化

Phase 3（待開始）

單字庫擴充（1200字/7000字）、教師功能強化、QA 壓力測試、正式上線

安全性待辦

正式上線前必須完成的安全強化項目

🔴 上線前必做（Critical）

0/4 完成

刪除 admin/admin 預設帳號

admin.html → 刪除帳號。重大安全漏洞：任何人知道此預設帳號即可取得管理員權限。

admin.html tables/users

🔴 Critical

移除 ensureAccounts() 自動補帳號邏輯

index.html 中的自動補帳號功能僅限測試期使用。正式上線前刪除，防止非預期帳號被自動建立。

index.html JS 邏輯

🔴 Critical

API Key 移至後端 Proxy（GCP Cloud Run）

目前 Gemini API Key 暴露於前端 JS，任何人可用 DevTools 查看並盜用。需部署 Cloud Run Proxy 後移除前端 Key。

4個檔案 GCP 依賴

🔴 Critical

強制密碼強度驗證

admin.html 新增帳號時加入密碼強度檢查：至少 8 字元、含大寫+小寫+數字，拒絕常見弱密碼（如 "123456", "password"）。

admin.html

🔴 高

🟡 近期執行（重要）

0/3 完成

Google Cloud Console：設定 API Key HTTP Referrer 限制

在 GCP Console → Credentials → 限制 Key 只接受來自你的網域的請求。即使 Key 被複製也無法從其他網站使用。可立即執行，不需 GCP 後端

立即可做 GCP Console

🟠 高

設定 Gemini API 每日配額上限 + 帳單警報

GCP Console → Generative Language API → 配額，設定每日請求上限。帳單 → 建立預算警報（$1 USD 即通知），防止意外費用。

立即可做

🟠 高

登入失敗次數限制（防暴力破解）

在 index.html doLogin() 加入連續失敗計數（localStorage），5次失敗後鎖定 10 分鐘，顯示倒數計時。

index.html

🟡 中

GCP 遷移步驟

從 Genspark 靜態環境遷移至 GCP 完整後端架構

📌 遷移原則：循序漸進，先建 Proxy → 再遷資料庫 → 最後遷前端。每個步驟獨立可回滾。

① 前置準備

0/3 完成

建立 GCP 專案

前往 console.cloud.google.com → 新增專案「wayne-english-prod」。啟用計費帳號，設定$10/月預算警報。

Step 1

啟用必要 API

啟用：Cloud Run API、Cloud Build API、Secret Manager API、Artifact Registry API、Cloud SQL API（後期）。

# 一次啟用所有需要的 API
gcloud services enable run.googleapis.com \
  cloudbuild.googleapis.com \
  secretmanager.googleapis.com \
  artifactregistry.googleapis.com

Step 2

將 Gemini API Key 存入 Secret Manager

不將 Key 寫在程式碼中，改用 Secret Manager 安全儲存。Cloud Run 部署時自動注入環境變數。

echo -n "AIzaSy..." | gcloud secrets create GEMINI_API_KEY \
  --data-file=- --replication-policy=automatic

Step 3

② Cloud Run AI Proxy 部署

0/3 完成

撰寫 Node.js Proxy 服務

建立 Express.js 服務，接收前端 POST 請求 → 驗證來源 → 呼叫 Gemini API → 返回結果。包含 CORS 限制、速率限制、錯誤處理。

// proxy/index.js 核心架構
const rateLimit = new Map();  // 簡易速率限制
app.post('/api/gemini', async (req, res) => {
  const ip = req.ip;
  // 5 RPM per IP（對應 gemini-2.5-flash 免費限制）
  if (isRateLimited(ip)) return res.status(429).json({error:'too many requests'});
  const result = await callGemini(req.body.prompt, req.body.maxTokens);
  res.json({ text: result });
});

Step 4

部署至 Cloud Run（asia-east1）

選擇台灣最近的區域 asia-east1（台灣），最小化延遲。設定最小實例數=0（節省費用），最大=3。

gcloud run deploy wayne-ai-proxy \
  --source ./proxy \
  --region asia-east1 \
  --allow-unauthenticated \
  --min-instances 0 --max-instances 3 \
  --set-secrets GEMINI_API_KEY=GEMINI_API_KEY:latest \
  --memory 256Mi

Step 5

更新前端：改呼叫 Proxy，移除前端 API Key

將 student.html / student2.html / chat.html / elementary.html 中的 GEMINI_API_KEY 替換為 PROXY_URL，刪除所有 Key 字串。

4個檔案需修改

Step 6

③ 前端靜態部署（Cloud Storage + CDN）

0/2 完成

建立 Cloud Storage Bucket + 啟用靜態網站

建立公開 Bucket，上傳所有 HTML/CSS/JS/圖片。設定 index.html 為預設頁面，404.html 為錯誤頁面。綁定自訂網域。

gsutil mb -l asia-east1 gs://wayne-english-web
gsutil web set -m index.html -e 404.html gs://wayne-english-web
gsutil -m cp -r ./* gs://wayne-english-web/

Step 7

設定 Cloud CDN + HTTPS + 自訂網域

Load Balancer → Cloud CDN → Storage Bucket。申請 Google 管理的 SSL 憑證。設定 DNS A record 指向 LB IP。

需要自訂網域

Step 8

GCP 預估月費

$0

Cloud Run Proxy
（免費層：200萬次/月）

~$1

Cloud Storage + CDN
（靜態網頁約 1-2 GB）

~$1-3

Gemini API 費用
（視使用量，免費層外）

口語對話 API 選型建議

目前 chat.html 使用 Gemini Text API 進行口語對話，以下是各方案比較

🏆 推薦方案：保持 Gemini 2.5 Flash（移後端後）
理由：已整合、成本低、中文支援強、台灣學生語境優化佳。升級路徑是 Gemini Live API（WebSocket 即時串流），體驗近似真人對話。

API 方案	費用	延遲	中文支援	整合難度	適合度
Gemini 2.5 Flash現有 ✓ Text 生成模式	免費層：5 RPM 付費：$0.075/M tokens	1-3 秒回合制	⭐⭐⭐⭐⭐	低（已整合）	★★★★★ 最推薦
Gemini Live API升級路徑 ↑ WebSocket 即時串流語音	目前免費（beta）正式版待定	< 0.5 秒即時串流	⭐⭐⭐⭐⭐	中（WebSocket）	★★★★★ 未來升級
OpenAI GPT-4o Realtime API（語音直通）	$0.10/min（語音） 50人×10min/天=$50/月	< 0.3 秒	⭐⭐⭐⭐	高（需後端）	★★★ 成本過高
OpenAI Whisper + GPT-4o STT → LLM 分離架構	$0.006/min(STT)+LLM 約 $15-25/月	1-2 秒	⭐⭐⭐⭐	高（需後端）	★★★ 備選方案
ElevenLabs + GPT 最自然 TTS，搭配 GPT 回覆	$5/月起（TTS）+ LLM	1-2 秒	⭐⭐⭐	高	★★ TTS 體驗佳但成本高
Azure OpenAI 企業級，台灣資料在地化	依用量，無免費層	低延遲	⭐⭐⭐⭐⭐	高（企業申請）	★★★ 規模化後考慮

🏆 短期建議（現在 ~ 3個月）

繼續使用 Gemini 2.5 Flash，但完成以下升級：

API Key 移至 GCP Cloud Run Proxy
在 Proxy 加入 per-user 速率限制
開啟帳單監控，設定 $5/月警報
考慮付費方案（$7/月）解除 RPM=5 限制

🚀 長期建議（3個月後）

升級至 Gemini Live API（WebSocket 串流）：

麥克風音訊直接串流給 Gemini
延遲從 2-3 秒降至 <0.5 秒
更自然的對話節奏（可中斷）
目前 chat.html 已有 WebSocket 框架可升級

內容擴充待辦

單字庫、題目、課綱對應等內容建設計畫

📚 單字庫擴充

0/2 完成

國中單字庫擴充至 1,200 字

目前約 360 字（6組×30字）。需補充至 108課綱國中英語 1,200 核心字。建議分 12 個主題組，每組 100 字，含音標、詞性、中文、英文例句。

現有：360字目標：1,200字 js/db-words.js

完成度30%

🟡 中

高中單字庫擴充至 7,000 字

目前約 180 字（高中部分）。108課綱高中英語核心字彙表共 7,000 字。建議分批加入：先完成 2,000 字（學測重點）→ 再到 4,500 字（指考）→ 最終 7,000 字。

現有：180字目標：7,000字

完成度3%

🟡 中

📝 模擬會考題目擴充

0/2 完成

自製模擬會考題：擴充至 15 套

目前有 9 套（仿109～113年）。補充到 15 套讓學生有更多練習量。所有題目維持「仿XXX年」標示，避免智財權問題。每套含克漏字 15 題 + 閱讀測驗 15 題 + 翻譯 2 題。

現有：9套目標：15套

🔵 低

國小英語題目擴充（elementary.html）

新增更多主題單字組（目前 4 大類 40+ 字），建議擴充至 10 大類 200+ 字。新增更多聽寫單字（目前各年段 25 字 → 50 字）。

🔵 低

🎯 課程內容強化

0/2 完成

學測作文題庫擴充（student.html）

目前作文批改需手動輸入，建議加入 20 個常見學測作文題目（圖表說明文、看圖寫作、意見論述），讓學生選題後直接練習。

🔵 低

口語練習情境擴充（chat-select.html）

目前 6 個情境（日常/旅遊/餐廳/飯店/購物/緊急）。建議新增：求職面試、電話訂位、看醫生、學校生活 4 個情境，覆蓋更多 108 課綱溝通情境。

🔵 低

教師管理功能待辦

強化 teacher.html 教師儀表板，讓老師能更有效管理班級

現有功能：班級總覽、學生進度、發送訊息、本週任務、學習報告（35% 完成）。以下為待補強項目。

📊 資料可視化強化

0/2 完成

學生個人學習熱力圖（GitHub 風格）

每個學生頁面加入 GitHub 貢獻圖樣式的學習記錄熱力圖，讓老師一眼看出哪些日期有學習、學習密度如何。使用 activity_log 資料表統計。

teacher.html activity_log

🟡 中

全班成績分布圖（Chart.js）

在班級總覽加入：成績分布長條圖、各模組平均分雷達圖、本週 vs 上週進步率折線圖。讓老師快速掌握全班學習狀況。

🟡 中

🎯 個人化功能

0/2 完成

老師自訂作業派發

老師可在 teacher.html 選擇特定題目/單字組/文法主題，設定截止日期，派發給指定班級或個別學生。學生登入後在 student.html 看到「老師指定作業」提醒。

需新增 homework 資料表

🟡 中

學生弱點分析（AI 輔助）

根據學生答題記錄，用 Gemini 生成個人化弱點報告：「該學生在現在完成式錯誤率 78%，建議加強...」。老師一鍵為全班生成分析報告。

Gemini AI

🔵 低

📤 匯出與通知

0/1 完成

真實 CSV/Excel 匯出功能

目前匯出為假資料（模擬）。實作真實的 CSV 生成：從 activity_log 查詢 → 格式化 → Blob 下載。欄位：學生姓名、模組、分數、時長、日期。

純前端可實作

🟡 中

系統架構圖

現況（Genspark 靜態）與目標（GCP 完整後端）架構對比

⚡ 現況架構（Genspark 靜態環境）

🚀 目標架構（GCP 完整後端）

目標架構優點

API Key 完全不暴露於前端
Cloud CDN 全球加速，台灣延遲 <20ms
Cloud Run 自動擴容，流量高峰不掛機
Secret Manager 金鑰版本管理，可隨時輪替
月費預估 $1-5 USD，幾乎免費

關鍵技術選型說明

前端保持純靜態（HTML/CSS/JS）
資料庫：Tables API（現有）→ 未來 Cloud SQL（若需複雜查詢）
AI Proxy：Node.js + Express（輕量，20行核心程式碼）
部署：Cloud Run（無需管理伺服器）
CDN：Cloud CDN（與 Storage 原生整合）

版本管理方案

在 Genspark 無 Git 環境下的版本管理最佳實踐，以及遷移 GCP 後的正式流程

目前狀況（Genspark 環境）

Genspark 靜態平台無內建版本控制，目前採用手動備份到 versions/ 目錄，但缺乏分支、差異比對、回滾機制。

臨時方案：每次重大功能更新前，手動複製檔案到 versions/YYYY-MM-DD/ 目錄，並在 README.md 記錄變更。

1

目前（Genspark）

手動備份到 versions/ 目錄，README 記錄版本號與變更說明

2

近期（GitHub 導入）

建立 GitHub 私有 Repo，使用 Git 管理所有原始碼版本

3

中期（CI/CD）

GitHub Actions 自動部署：push main → 自動上傳 GCS → CDN 更新

4

長期（藍綠部署）

staging → production 分支，零停機時間部署，自動回滾

① 現在可做：Genspark 手動版本管理規範

📁 目錄命名規範

versions/
├── 2025-04-22/         # 已存在的備份
│   ├── student.html
│   ├── chat.html
│   └── elementary.html
├── 2025-06-08/         # 本次備份（商業運轉準備）
│   └── ...
└── CHANGELOG.md        # 每次備份的變更說明

📋 CHANGELOG 格式範例

## [6.6.0] - 2025-06-08
### 新增
- legal.html：服務條款 + 隱私權政策 + 免責聲明
- project-dashboard.html：專案管理儀表板

### 修改
- student.html：模擬會考標示（仿XXX年）+ 免責聲明橫幅
- index.html：footer 加入法律連結

### 刪除
- fix-login.html, auto-test.html 等 10 個測試頁面

### 安全性
- gemini-2.5-flash 取代 gemini-2.0-flash（配額問題）
- API Key 更換

## [6.5.0] - 2025-04-26
...

版本號規則（語意化版本）： 主版本.功能版本.修補 → 如 6.6.0
主版本（6）：重大架構改變｜功能版本（6）：新功能｜修補（0）：Bug Fix

② 近期：導入 GitHub 版本控制

# 1. 初始化 Git（在本機工作目錄）
git init
git remote add origin https://github.com/你的帳號/wayne-english.git

# 2. 第一次推送所有現有檔案
git add .
git commit -m "feat: initial commit - v6.6.0 商業運轉準備"
git push -u origin main

# 3. 之後每次改動的標準流程
git checkout -b feature/teacher-heatmap  # 建新分支
# ... 開發 ...
git commit -m "feat(teacher): 加入學習熱力圖"
git checkout main
git merge feature/teacher-heatmap
git tag v6.7.0                            # 打版本標籤
git push --tags

🌿 分支策略（推薦）

main

穩定版，隨時可部署，對應 production

develop

開發整合分支，功能完成後 merge main

feature/xxx

單一功能開發分支，完成後 merge develop

hotfix/xxx

緊急 Bug 修復，直接 merge main + develop

③ 中期：GitHub Actions 自動部署 CI/CD

# .github/workflows/deploy.yml
name: Deploy to GCS
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: google-github-actions/auth@v1
        with:
          credentials_json: ${{ secrets.GCP_SA_KEY }}
      - name: Upload to Cloud Storage
        run: |
          gsutil -m rsync -r -d \
            --exclude "versions/*" \
            --exclude "*.md" \
            . gs://wayne-english-web/
      - name: Invalidate CDN Cache
        run: gcloud compute url-maps invalidate-cdn-cache wayne-lb --path="/*"

緊急回滾方案

🟡 Genspark 環境（現在）

1. 開啟 versions/YYYY-MM-DD/
2. 複製舊版檔案覆蓋現有檔案
3. 在 README 記錄回滾原因
⏱ 約需 5-10 分鐘手動操作

🟢 GCP + GitHub 環境（未來）

# 一行指令回滾到上個版本
git revert HEAD --no-edit
git push
# Actions 自動重新部署
# ⏱ 約 2-3 分鐘完成