LMS Features Skill

Browse Gradebook、Course Kanban、Communications、Statistics Module、MAP Analytics、Teacher Schedule Last Updated: 2025-12-29

Browse Gradebook 架構

功能概述

監控全校班級的成績輸入進度：

Class-Based 視圖：每班一行（84 班），取代舊版 exam-based（1000 筆）
LT/IT/KCFS 進度欄：顯示三種課程的成績輸入完成率
狀態篩選：On Track / Behind / Not Started
年級篩選：G1-G6

資料結構

interface ClassProgress {
  class_id: string;
  class_name: string;
  grade: number;
  student_count: number;
  lt_progress: number;      // 0-100%
  it_progress: number;      // 0-100%
  kcfs_progress: number;    // 0-100%
  lt_teacher: string | null;
  it_teacher: string | null;
  kcfs_teacher: string | null;
  overall_status: 'on_track' | 'behind' | 'not_started';
}

進度計算

// 每個課程的進度 = 已輸入成績數 / (學生數 × expected_total)
// LT/IT: 從 gradebook_expectations 表取得，預設 13
// KCFS: 依年級 (G1-2: 4, G3-4: 5, G5-6: 6)
const progress = (scores_entered / (student_count * expected_total)) * 100;

// 狀態判定
if (lt >= 80 && it >= 80 && kcfs >= 80) return 'on_track';
if (lt > 0 || it > 0 || kcfs > 0) return 'behind';
return 'not_started';

批次查詢（重要）

因應 Supabase max_rows 限制（10,000），使用兩階段並行查詢：

// Stage 1: 取得 exam IDs（依 term 過濾）
const { data: exams } = await supabase
  .from('exams')
  .select('id, course_id')
  .in('course_id', courseIds)
  .eq('term', filters.term);

// Stage 2: 分批並行查詢 scores
const EXAM_BATCH_SIZE = 500;
const batches = chunk(examIds, EXAM_BATCH_SIZE);
const batchResults = await Promise.all(
  batches.map(batch =>
    supabase.from('scores')
      .select('exam_id')
      .in('exam_id', batch)
      .not('score', 'is', null)
  )
);

// Aggregate by course_id

效能: ~100-150ms，可處理 26,000+ scores

Course Kanban 架構

功能概述

課程層級的任務看板：

Kanban 三欄：To Do / In Progress / Done
拖曳排序：使用 @dnd-kit/core
課程隔離：綁定 course_id，教師只看自己的任務

資料表

CREATE TABLE course_tasks (
  id UUID PRIMARY KEY,
  course_id UUID REFERENCES courses(id),
  teacher_id UUID REFERENCES users(id),
  title TEXT NOT NULL,
  description TEXT,
  status TEXT DEFAULT 'todo',  -- 'todo' | 'in_progress' | 'done'
  due_date DATE,
  position INTEGER DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

Communications 架構

功能概述

課程層級的家長通訊追蹤：

LT 課程：電話通訊追蹤（semester_start / midterm / final）
IT/KCFS 課程：學生備忘功能

權限控制

| 角色 | 可見課程 | 可編輯 | |------|----------|--------| | Teacher | 自己任課的課程 | 是 | | Head Teacher | 自己 track 類型的課程 | 否（唯讀） | | Admin | 所有課程 | 是 | | Office Member | 所有課程 | 否（唯讀） |

Statistics Module

頁面結構

/browse/stats/
├── page.tsx           # 總覽 Dashboard
├── classes/page.tsx   # 班級統計
├── students/page.tsx  # 學生統計
├── grades/page.tsx    # 年級統計
├── teachers/page.tsx  # 教師統計
├── courses/page.tsx   # 課程統計
├── exams/page.tsx     # 考試統計
└── trends/page.tsx    # 趨勢分析

GlobalFilterBar

全域篩選系統，支援：

學年選擇：2025-2026 / 2026-2027
Term 選擇：Term 1-4

interface GlobalFilters {
  academicYear: string;   // '2025-2026'
  term: number | null;    // 1-4 或 null（全部）
}

Four-Term 學期系統

| Term | 名稱 | Semester | |------|------|----------| | 1 | Fall Midterm（秋季期中） | 1 (Fall) | | 2 | Fall Final（秋季期末） | 1 (Fall) | | 3 | Spring Midterm（春季期中） | 2 (Spring) | | 4 | Spring Final（春季期末） | 2 (Spring) |

XLSX 匯出

所有統計頁面支援 XLSX 匯出：

import * as XLSX from 'xlsx';

function exportToXLSX(data: any[], filename: string) {
  const ws = XLSX.utils.json_to_sheet(data);
  const wb = XLSX.utils.book_new();
  XLSX.utils.book_append_sheet(wb, ws, 'Data');
  XLSX.writeFile(wb, `${filename}.xlsx`);
}

圖表類型

使用 Recharts：

BarChart：班級/年級比較
LineChart：趨勢分析
PieChart：分佈統計
AreaChart：累積進度
RadarChart：多維度比較
ScatterChart：相關性分析

Class Context Tabs

導航結構

/class/[classId]/
├── overview     # 班級總覽（含 Kanban）
├── gradebook    # 成績簿
├── students     # 學生名冊
└── communications  # 通訊記錄

Tab 元件

// components/os/ClassContextTabs.tsx
const tabs = [
  { id: 'overview', label: 'Overview', path: `/class/${classId}` },
  { id: 'gradebook', label: 'Gradebook', path: `/class/${classId}/gradebook` },
  { id: 'students', label: 'Students', path: `/class/${classId}/students` },
  { id: 'communications', label: 'Communications', path: `/class/${classId}/communications` },
];

共用元件

PageHeader

interface PageHeaderProps {
  title: string;
  subtitle?: string;
  breadcrumbs?: { label: string; href?: string }[];
  actions?: React.ReactNode;
}

DataTable

interface DataTableProps<T> {
  data: T[];
  columns: ColumnDef<T>[];
  searchable?: boolean;
  filterable?: boolean;
  exportable?: boolean;
}

StatusBadge

type Status = 'on_track' | 'behind' | 'not_started' | 'completed';

const statusColors = {
  on_track: 'bg-green-500',
  behind: 'bg-yellow-500',
  not_started: 'bg-gray-500',
  completed: 'bg-blue-500',
};

MAP Analytics Module (v1.54.0)

功能概述

NWEA MAP Growth 數據分析系統：

學生頁面 MAP Tab：G3-G6 學生的 MAP 分析（G1-2 無 MAP 測驗）
Benchmark Classification：E1/E2/E3 分級
Growth Index：Fall → Spring 成長指數
Goal Areas：閱讀/語言能力目標領域分析
Lexile Level：閱讀等級追蹤

資料表

-- MAP 測驗成績
CREATE TABLE map_assessments (
  id UUID PRIMARY KEY,
  student_number TEXT NOT NULL,        -- 學號
  student_id UUID REFERENCES students(id),
  grade INTEGER NOT NULL,              -- 測驗時年級
  course TEXT NOT NULL,                -- 'Reading' | 'Language Usage'
  rit_score INTEGER NOT NULL,          -- RIT 分數（100-350）
  lexile_score TEXT,                   -- Lexile（Reading only，如 '1190L'）
  term_tested TEXT NOT NULL,           -- 'Fall 2024-2025' 格式
  academic_year TEXT NOT NULL,
  map_term TEXT NOT NULL,              -- 'fall' | 'winter' | 'spring' (distinct from ELA term 1-4)
  rapid_guessing_percent DECIMAL(5,2), -- 快速猜測百分比
  UNIQUE(student_number, course, term_tested)
);

-- 目標領域分數
CREATE TABLE map_goal_scores (
  id UUID PRIMARY KEY,
  assessment_id UUID REFERENCES map_assessments(id),
  goal_name TEXT NOT NULL,             -- 如 'Informational Text'
  goal_rit_range TEXT                  -- 如 '161-170'
);

Benchmark Classification（E1/E2/E3 分級）

使用兩科平均判定學生程度：

// 平均分 = (Language Usage RIT + Reading RIT) / 2
// 使用「測驗年級」的門檻判定（不是當前年級）

// G3 門檻
const G3_THRESHOLDS = { E1: 206, E2: 183 };
// G4 門檻
const G4_THRESHOLDS = { E1: 213, E2: 191 };
// G5 門檻
const G5_THRESHOLDS = { E1: 218, E2: 194 };
// G6：無分級（畢業年級）

// 判定邏輯
if (avg >= threshold.E1) return 'E1';
if (avg >= threshold.E2) return 'E2';
return 'E3';

Growth Index（成長指數）

// 成長指數 = 實際成長 / 期望成長
const growthIndex = actualGrowth / expectedGrowth;

// 判定
if (growthIndex >= 1.0) return 'Above Expected';
if (growthIndex >= 0.8) return 'Near Expected';
return 'Below Expected';

學生頁面 MAP Tab 元件

路徑：app/(lms)/student/[id]/page.tsx

// 只有 G3-G6 學生顯示 MAP Tab
{studentGrade >= 3 && (
  <StudentMapAnalysisTab studentId={studentId} grade={studentGrade} />
)}

元件位置：components/map/student/

StudentBenchmarkStatus.tsx - Benchmark 狀態卡
StudentGrowthIndex.tsx - 成長指數卡
StudentGoalAreas.tsx - 目標領域強弱項
StudentLexileLevel.tsx - Lexile 閱讀等級
StudentBenchmarkHistory.tsx - Benchmark 歷史圖表
StudentPeerComparison.tsx - 同儕比較

API 層

lib/api/map-student-analytics.ts  - 學生層級 MAP 分析
lib/api/map-analytics.ts          - 學校層級 MAP 統計
lib/map/benchmarks.ts             - Benchmark 分級邏輯
lib/map/norms.ts                  - NWEA 國家常模
lib/map/goals.ts                  - 目標領域定義
lib/map/lexile.ts                 - Lexile 解析與分類

Lexile 閱讀等級

// Lexile 格式
'1190L'   // 標準格式
'BR400L'  // Beginning Reader 格式

// 七個等級
const LEXILE_BANDS = [
  { range: 'BR', label: 'Beginning Reader' },
  { range: '0-200', label: 'Early Reader' },
  { range: '200-400', label: 'Developing' },
  { range: '400-600', label: 'Intermediate' },
  { range: '600-800', label: 'Fluent' },
  { range: '800-1000', label: 'Advanced' },
  { range: '1000+', label: 'Proficient' },
];

權限控制

| 角色 | 查看範圍 | |------|----------| | Admin | 全校學生 | | Office Member | 全校學生（唯讀）| | Head Teacher | 管轄年級學生 | | Teacher | 自己班級學生 |

Teacher Schedule System (v1.56.0)

功能概述

教師課表系統，支援週視圖和今日視圖：

Weekly View：5x8 格狀課表（週一到週五，8 節課）
Today View：垂直列表，適合手機
Click-to-Navigate：點擊課程直接進入點名或課程頁面
Current Period Highlight：當前節次高亮顯示

頁面路徑

/schedule              # 教師課表頁面

課程類型與顏色

| 類型 | 顏色 | 點擊行為 | |------|------|----------| | English | 藍色 (bg-blue-500) | → 點名頁面 | | KCFS | 翡翠綠 (bg-emerald-500) | → 課程頁面 | | EV | 紫色 (bg-purple-500) | → 課程頁面 |

資料表

-- 課表項目
timetable_entries (
  teacher_email, teacher_name, day, period,
  class_name, course_type, course_id, academic_year
)

-- 節次時間
timetable_periods (
  period_number, start_time, end_time
)

權限控制

| 角色 | 可見範圍 | |------|----------| | Teacher | 自己的課表 | | Head Teacher | 自己的課表 | | Admin | 自己的課表 |

資料統計 (2025-2026)

English: 1,064 筆 (100% 有 course_id)
KCFS: 167 筆 (100% 有 course_id)
EV: 56 筆 (不需 course_id)

Attendance System (v1.56.0)

功能概述

課程點名系統，從課表點擊進入：

點名頁面：顯示課程學生列表
狀態選擇：P (出席) / L (遲到) / A (缺席) / S (病假)
行為標籤：正向/負向行為記錄
批次儲存：自動儲存點名狀態

頁面路徑

/class/[classId]/attendance    # 點名頁面（從課表進入）

點名狀態

| 代碼 | 英文 | 顏色 | |------|------|------| | P | Present | 綠色 | | L | Late | 黃色 | | A | Absent | 紅色 | | S | Sick | 藍色 |

權限控制

| 角色 | 可見範圍 | |------|----------| | Teacher | 自己的課程 | | Head Teacher | 自己的課程 | | Admin | 所有課程 |

資料表

-- 點名記錄
attendance (
  student_id, course_id, date, period,
  status, recorded_by, note
)

-- 行為標籤
behavior_tags (
  name, name_zh, type, icon, sort_order
)

-- 學生行為記錄
student_behaviors (
  student_id, course_id, tag_id, date, recorded_by
)

lms-features

LMS Features Skill

Browse Gradebook 架構

功能概述

資料結構

進度計算

批次查詢（重要）

相關檔案

Course Kanban 架構

功能概述

資料表

相關檔案

Communications 架構

功能概述

權限控制

相關檔案

Statistics Module

頁面結構

GlobalFilterBar

Four-Term 學期系統

XLSX 匯出

圖表類型

Class Context Tabs

導航結構

Tab 元件

共用元件

PageHeader

DataTable

StatusBadge

MAP Analytics Module (v1.54.0)

功能概述

資料表

Benchmark Classification（E1/E2/E3 分級）

Growth Index（成長指數）

學生頁面 MAP Tab 元件

API 層

Lexile 閱讀等級

權限控制

Teacher Schedule System (v1.56.0)

功能概述

頁面路徑

課程類型與顏色

資料表

相關檔案

權限控制

資料統計 (2025-2026)

Attendance System (v1.56.0)

功能概述

頁面路徑

點名狀態

相關檔案

權限控制

資料表