WriteAhead Sprint 4

WriteAhead Sprint 4 工程分析報告

閱讀時間約 12 分鐘

WriteAhead Sprint 4 工程分析報告

日期：2026-02-06 Sprint：SCRUM Sprint 4 (尚未開始) 工作項目：6 個 User Story

摘要

Sprint 4 聚焦於數據分析與監控功能的開發，包含前台數據頁、後台監控系統、操作紀錄，以及批閱點數系統。建議優先完成 SCRUM-49 (操作紀錄) 和 SCRUM-67/68 (數據抽取)，SCRUM-251 (批閱點數) 因涉及 LTRUST 整合，需跨團隊協調，建議排在最後。

Codebase 概覽

WriteAhead 專案 (英文寫作批閱平台)

角色Codebase技術棧
前台前端writeahead-webNuxt 3 + Vue 3 + Pinia + Tailwind
後台前端writeahead-admin-webNuxt 4 + Vue 3 + Ant Design Vue
後端 APIwriteahead-main-apiCodeIgniter 4 (PHP 8.1+) + MySQL

LTRUST 專案 (外部身份認證與點數系統)

角色Codebase備註
前台前端ltutor-web-
前台後端ltutor-admin-web-
後端 (統一前後台)ltutor-main-api提供點數扣除、訂閱服務 API

專案關係

WriteAhead 專案
├── writeahead-web        (前台前端)
├── writeahead-admin-web  (後台前端)
└── writeahead-main-api   (後端 API)
         │
         │ HTTP API 整合 (認證、點數扣除)
         ▼
LTRUST 專案
├── ltutor-web            (前台前端)
├── ltutor-admin-web      (前台後端)
└── ltutor-main-api       (後端統一)

一、User Story 總覽

Key名稱難度工作量主要挑戰
SCRUM-36前台－數據頁⭐⭐⭐中雷達圖實作、無圖表庫
SCRUM-43後台－數據監控與管理⭐⭐⭐⭐大完整監控系統、多圖表
SCRUM-67核心數據抽取⭐⭐⭐中SQL 效能、10+ 指標計算
SCRUM-68圖表數據抽取⭐⭐中時間序列聚合
SCRUM-49後台－操作紀錄⭐⭐小後端已完成，僅需前端
SCRUM-251批閱點數實作⭐⭐⭐⭐⭐大LTRUST 整合、交易一致性

二、各 User Story 詳細分析

SCRUM-36：前台－數據頁

Parent: SCRUM-11 (前台－資訊分析頁)

功能需求

  • 篩選面板：時間 (7日/30日/全部)、題型、議題、得分範圍
  • 統計卡片：已批改題數、平均做題時間、平均字數、平均得分
  • 雷達圖：四維評分 (文法/字彙/內容/組織)，最大值 5，顯示至小數第一位

工程師待辦

前端 (writeahead-web):

1. 安裝圖表庫：npm install echarts vue-echarts
2. 實作頁面：app/pages/analysis.vue (已預留)
3. 建立 composables：useStatistics.ts, useStatisticsApi.ts
4. 建立組件：
   - components/statistics/FilterPanel.vue
   - components/statistics/SummaryCards.vue
   - components/statistics/RadarChart.vue

後端 (writeahead-main-api):

1. 擴展 StatisticsController::summary()
2. 新增 getCategoryAvgScores() - 解析 ai_score JSON 計算四維平均

關鍵挑戰

挑戰解決方案
無圖表庫安裝 ECharts + vue-echarts
SSR 兼容<ClientOnly> 包裹圖表組件
JSON 欄位查詢MySQL JSON_EXTRACT 函數
空資料處理顯示引導提示，避免 NaN

SCRUM-43：後台－數據監控與管理

Parent: SCRUM-14 (後台－數值管理頁)

功能需求

時間篩選：全部 / 1日 / 1月 / 1年 / 自定義

核心數據 (10+ 指標)：

指標計算方式
活躍人數期間內登入帳號數
做題總數全體做題累計
平均做題數總做題數 ÷ 活躍人數
平均得分總得分 ÷ 總做題數
平均解題時間總做題時間 ÷ 總做題數
題目平均使用數總批改數 ÷ 題庫總題數
題目最大/最小使用數統計各題使用次數
新增未批改總數期間內未批改題目數
平均未批改數總未批改數 ÷ 活躍人數

圖表：活躍人數表、做題總數表、做題數表、未批改總數表

工程師待辦

前端 (writeahead-admin-web):

1. 安裝圖表庫：npm install echarts vue-echarts
2. 建立頁面：app/pages/statistics/index.vue
3. 建立組件：
   - components/statistics/time-filter.vue
   - components/statistics/core-metrics.vue
   - components/statistics/chart-selector.vue
   - components/statistics/time-series-chart.vue

後端 (writeahead-main-api):

現有端點：POST /admin/statistics/getStatistics (已實作)
需擴展：圖表數據端點 (見 SCRUM-68)

關鍵挑戰

挑戰解決方案
大量計算分批查詢，避免單次過重
效能問題預設「月」範圍 + 快取
圖表切換一次請求，前端切換顯示

SCRUM-67：核心數據抽取

Parent: SCRUM-14

工程師待辦

後端 (writeahead-main-api):

檔案：app/Models/Admin/StatisticsModel.php

需優化/新增方法：
- getActiveUsersCount() - 已有
- getTotalAnswersCount() - 已有
- getQuestionUsageStats() - 需擴展 (max, min, avg)
- getUnreviewedStats() - 需新增

建議索引：

CREATE INDEX idx_answer_created_review ON answer(created_at, is_review);
CREATE INDEX idx_answer_user_email ON answer(user_email);
CREATE INDEX idx_logs_user_logins_created ON logs_user_logins(created_at);

關鍵挑戰

挑戰解決方案
JSON 欄位解析MySQL JSON_EXTRACT
大數據量查詢加索引 + 分頁 + 快取
除以零問題max(divisor, 1) 或 NULLIF

SCRUM-68：圖表數據抽取

Parent: SCRUM-14

工程師待辦

後端:

新增端點：POST /admin/statistics/getChartData
新增方法：getTimeSeriesData($type, $start, $end, $groupBy)

SQL 範例：

-- 按日聚合活躍用戶數
SELECT DATE(created_at) as date, COUNT(DISTINCT user_email) as value
FROM logs_user_logins
WHERE created_at BETWEEN ? AND ?
GROUP BY DATE(created_at)
ORDER BY date;

關鍵挑戰

挑戰解決方案
空日期填充日期序列 LEFT JOIN
大數據點按月聚合或限制 365 點

SCRUM-49：後台－操作紀錄

Parent: SCRUM-14

功能需求

篩選條件：使用者名稱、EMAIL、角色、操作類型、模組名稱、操作內容、日期區間

列表欄位：角色、使用者名稱、操作帳號、IP、操作類型、模組名稱、功能名稱、操作內容、日期時間

工程師待辦

前端 (writeahead-admin-web):

1. 建立頁面：app/pages/system/logs/index.vue
2. 建立組件：
   - components/system/log/filter.vue
   - components/system/log/table.vue (唯讀，無編輯/刪除)
3. 建立 composables：useActivityLogList.ts, useActivityLogApi.ts

後端:

已完成！
端點：POST /admin/activityLog/list
檔案：
- app/Controllers/Admin/ActivityLogController.php
- app/Models/Admin/ActivityLogModel.php
- app/Services/ActivityLogService.php

關鍵挑戰

挑戰解決方案
後端已完成主要工作在前端
複雜篩選使用現有 FilterCard 模式
長文本顯示ellipsis + Tooltip

SCRUM-251：批閱點數實作

功能需求

  • 批閱扣點機制
  • LTRUST 整合 (訂閱制服務)
  • 資料統計 / 財會對帳

工程師待辦

後端 (writeahead-main-api):

1. 完成 LtrustService::deductPoints() - 已定義但未實作
2. 新增批閱扣點流程：
   - 檢查點數 → 呼叫評分 API → 扣除點數 → 記錄交易
3. 新增財會 API：
   - POST /admin/points/transactions
   - POST /admin/points/summary
4. (選擇性) 訂閱制表：user_subscriptions

前端 (writeahead-web):

優化點數不足提示 UX：顯示剩餘點數、購買連結

扣點流程設計

前端送出批閱 → 檢查點數 (本地) → 呼叫評分 API
                    │                    │
                    ▼                    ▼
              點數不足             評分成功
              回傳購買URL               │
                                        ▼
                                  扣除點數 (LTRUST)
                                        │
                           ┌────────────┴────────────┐
                           ▼                         ▼
                      扣點成功                   扣點失敗
                      記錄交易                   標記待處理
                      更新本地                   通知管理員

關鍵挑戰

挑戰解決方案
LTRUST API 規格需與 LTRUST 團隊確認
交易一致性DB Transaction + 補償機制
併發超扣SELECT FOR UPDATE 或樂觀鎖
訂閱制邏輯需 PM 確認訂閱方案

三、建議開發順序

Week 1: SCRUM-49 (快速完成) + SCRUM-67/68 (並行開發)
Week 2: SCRUM-43 (整合 67+68) + SCRUM-36 (獨立進行)
Week 3+: SCRUM-251 (需跨團隊協調 LTRUST)
優先級User Story原因
1SCRUM-49後端已完成，工作量最小
2SCRUM-67 + 68後台基礎數據，可並行
3SCRUM-43整合 67 + 68 成果
4SCRUM-36前台獨立功能
5SCRUM-251最複雜，需協調 LTRUST

四、技術決策

圖表庫選擇

選項優點缺點推薦度
ECharts功能強大、雷達圖支援、中文文檔體積較大⭐⭐⭐⭐⭐
Chart.js輕量雷達圖功能弱⭐⭐⭐
D3.js靈活度高學習曲線陡⭐⭐

結論：採用 ECharts + vue-echarts

效能優化建議

  1. 快取：Redis 快取熱門查詢，TTL 5-15 分鐘
  2. 預計算：每日凌晨計算前一天統計，存入 daily_statistics 表
  3. 分頁限制：圖表最大 365 點，列表每頁 10-20 筆

五、現有可複用資源

Codebase可複用
writeahead-admin-webCommonBaseTableCard, FilterCard, usePagination, CRUD 模式
writeahead-main-apiStatisticsModel, ActivityLogService, UserPointsModel
writeahead-webusePractice 模式可參考建立 useStatistics

關鍵檔案路徑 (相對於各 Codebase 根目錄)

writeahead-web (前台前端):

  • 頁面: app/pages/
  • 組件: app/components/
  • Store: app/stores/
  • Composables: app/composables/
  • Server API: server/api/

writeahead-admin-web (後台前端):

  • 頁面: app/pages/
  • 組件: app/components/
  • 通用組件: app/components/common/
  • Composables: app/composables/
  • 常數: constants/

writeahead-main-api (後端):

  • Controllers: app/Controllers/
  • Models: app/Models/
  • Services: app/Services/
  • LTRUST 整合: app/Services/External/LtrustService.php
  • 統計 Model: app/Models/Admin/StatisticsModel.php
  • 活動日誌: app/Services/ActivityLogService.php

六、風險與待確認事項

  1. SCRUM-251：LTRUST 扣點 API 規格需確認
  2. SCRUM-251：訂閱制服務方案需 PM 確認
  3. 效能：大時間範圍查詢需實測驗證

資料來源

  • Jira: SCRUM Sprint 4 (https://s872250.atlassian.net)
  • Codebase 分析：
    • writeahead-web (前台前端)
    • writeahead-admin-web (後台前端)
    • writeahead-main-api (後端 API)

相關筆記

附錄：AI 分析參照路徑

此區塊供 AI 分析工具直接參照，包含本機絕對路徑

WriteAhead 專案

Codebase絕對路徑
writeahead-web/home/matt/Github/writeahead-web
writeahead-admin-web/home/matt/Github/writeahead-admin-web
writeahead-main-api/home/matt/Github/writeahead-main-api

LTRUST 專案

Codebase絕對路徑
ltutor-web/home/matt/projects/ltutor-web
ltutor-admin-web/home/matt/projects/ltutor-admin-web
ltutor-main-api/home/matt/projects/ltutor-main-api

關鍵檔案絕對路徑

# WriteAhead 後端 - 統計相關
/home/matt/Github/writeahead-main-api/app/Controllers/Admin/StatisticsController.php
/home/matt/Github/writeahead-main-api/app/Models/Admin/StatisticsModel.php
/home/matt/Github/writeahead-main-api/app/Services/ActivityLogService.php
/home/matt/Github/writeahead-main-api/app/Services/External/LtrustService.php
/home/matt/Github/writeahead-main-api/app/Models/Web/UserPointsModel.php

# WriteAhead 前台前端 - 統計相關 (待建立)
/home/matt/Github/writeahead-web/app/pages/analysis.vue
/home/matt/Github/writeahead-web/app/composables/useStatistics.ts
/home/matt/Github/writeahead-web/app/composables/useStatisticsApi.ts

# WriteAhead 後台前端 - 統計/日誌相關 (待建立)
/home/matt/Github/writeahead-admin-web/app/pages/statistics/index.vue
/home/matt/Github/writeahead-admin-web/app/pages/system/logs/index.vue

關係圖譜