Skip to content

Commit 2d926d0

Browse files
raybirdraybird
committed
docs: update README to reflect 76-event dataset and current feature set
1 parent 4d19cc9 commit 2d926d0

1 file changed

Lines changed: 87 additions & 56 deletions

File tree

‎README.md‎

Lines changed: 87 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,120 @@
11
# CAP-Map 國中會考社會科時空地圖
22

3-
CAP-Map 是一個專門為臺灣國中生設計的互動式學習網站，旨在協助學生準備國中教育會考（CAP）社會科。透過將歷史時間軸與地理空間深度結合，幫助學生建立立體史觀，並強化會考必考的「圖表與地圖判讀能力」。
3+
CAP-Map 是一個專門為臺灣國中生設計的互動式學習網站，旨在協助學生準備國中教育會考（CAP）社會科。透過將歷史時間軸與地理空間深度結合，幫助學生建立跨區域史觀，並強化會考必考的「圖表與地圖判讀能力」。
44

5-
本專案直接延伸自 [jymap](https://github.com/raybird/jymap) 的成熟時空地圖架構，並針對國中會考社會科的教學大綱與考試特性進行教育化增強。
5+
**線上預覽**：[https://raybird.github.io/cap-map/](https://raybird.github.io/cap-map/)
66

77
---
88

9-
## 核心特色
9+
## 資料範圍
1010

11-
1. **時空同步探索（探索模式）**
12-
- **歷史時間軸**：拖曳底部時間軸，地圖上的標記會隨歷史朝代（荷西時期、明鄭時期、清領時期、日治時期等）動態過濾與呈現。
13-
- **空間地圖**：基於 Leaflet 地圖，精確定位歷史事件、戰役與重大地標的地理位置。
14-
2. **會考考點與章節對應**
15-
- 每個歷史事件詳情側邊欄皆標註對應的**會考重要性（高/中/低）**、**教科書對應章節**（如社會科七年級上冊）以及**常見會考題型**（圖表判讀、概念解釋等）。
16-
- 強化歷史（何時發生）、地理（何地發生）與公民（社會制度）三科知識的橫向整合。
17-
3. **地圖圖層切換**
18-
- 提供地形、氣候、行政邊界等主題圖層切換，幫助學生將歷史事件疊加於地理背景之上，強化空間推理與圖像理解。
19-
4. **模糊搜尋與內容發現**
20-
- 整合 Fuse.js，支援快速模糊搜尋歷史事件、地點、相關人物與關鍵字。
11+
目前收錄 **76 筆事件**，涵蓋臺灣史、中國史與世界史三個面向，橫跨西元前 5000 年至 2025 年。
12+
13+
| 分類 | 事件數 | 說明 |
14+
|------|--------|------|
15+
| 歷史 | 76 | 全部事件皆含歷史脈絡 |
16+
| 地理 | 45 | 具有顯著地理空間意義 |
17+
| 公民 | 31 | 涉及政治制度、民主化或公民社會 |
18+
19+
時間軸依八個全球史分期組織：
20+
21+
| 分期 | 年代 | 代表主題 |
22+
|------|------|----------|
23+
| 史前時代 | 5000 BCE – 1000 BCE | 史前文化與早期聚落 |
24+
| 古代文明 | 1000 BCE – 600 CE | 帝國、絲路、早期政權 |
25+
| 中古交流 | 601 – 1399 | 宗教、政權、跨區域交流 |
26+
| 近世交流 | 1400 – 1749 | 大航海、海上貿易、臺灣開發 |
27+
| 近代變革 | 1750 – 1945 | 工業革命、殖民、世界大戰 |
28+
| 戰後秩序 | 1946 – 1990 | 冷戰、戰後重建、兩岸分治 |
29+
| 民主化 | 1991 – 2009 | 政治自由化、民主鞏固 |
30+
| 當代 | 2010 – 今 | 全球化、社會運動、當代議題 |
31+
32+
---
33+
34+
## 核心功能
35+
36+
### 時空同步探索
37+
- **歷史時間軸**：底部橫向拖曳軸，從西元前 5000 年延伸至 2025 年，以 10px/年比例呈現。點擊分期色帶可快速過濾對應時代的事件。
38+
- **互動地圖**：基於 Leaflet，精確定位每筆事件的地理座標，支援圖層篩選（歷史／地理／公民）。點擊標記後地圖自動飛入並開啟彈出卡片。
39+
40+
### 事件詳情側邊欄
41+
- 顯示事件標題、年代、地點、詳細描述與關鍵字標籤。
42+
- 標註**會考重要性**（高／中／低）、**教科書對應章節**（七上・七下・八上・八下・九上・九下）及常見題型。
43+
- 點擊「相關事件」可直接跳轉至關聯事件。
44+
45+
### 自動出題小測驗
46+
- 每個事件自動生成 3 題選擇題，題型涵蓋：分期判斷、地點辨識、關鍵字配對、時序排列。
47+
- 干擾選項從全資料集動態生成，避免重複。
48+
49+
### 模糊搜尋
50+
- 整合 Fuse.js，對 `title`、`description`、`keywords` 三欄位進行模糊比對（threshold 0.3）。
51+
52+
### 行動版適應佈局
53+
- 桌機：側邊欄從右側滑入（380px）。
54+
- 手機（≤480px）：側邊欄以底部 Sheet 呈現（佔 62vh），地圖自動偏移確保焦點標記出現在可見區域中央。
2155

2256
---
2357

2458
## 技術棧
2559

26-
* **前端框架**：Angular 18 (SPA)
27-
* **狀態管理**：NgRx Store / Effects
28-
* **地圖引擎**：Leaflet (與 `@types/leaflet`)
29-
* **搜尋引擎**：Fuse.js (模糊搜尋)
30-
* **UI 樣式**：Angular Material / Custom CSS
60+
| 層次 | 技術 |
61+
|------|------|
62+
| 前端框架 | Angular 20 (NgModule pattern) |
63+
| 狀態管理 | NgRx Store 20（event / map / timeline 三個 slice） |
64+
| 地圖引擎 | Leaflet + @types/leaflet |
65+
| 搜尋引擎 | Fuse.js |
66+
| 樣式 | Custom CSS（Noto Sans TC / Noto Serif TC） |
3167

3268
---
3369

3470
## 專案結構
3571

3672
```text
37-
├── .github/workflows/ # GitHub Actions 自動化部署工作流 (Deploy to GitHub Pages)
38-
├── docs/ # 專案文件與設計規格書
39-
│ └── superpowers/specs/ # 會考時空地圖設計規格書
40-
└── webapp/ # Angular 前端專案目錄
41-
├── public/ # 靜態資源 (包含 favicon.ico 與候選圖檔)
42-
└── src/
43-
└── app/
44-
├── core/ # 核心模組與資料結構
45-
├── store/ # NgRx 狀態管理 (Actions, Reducers, Selectors, Effects)
46-
├── services/ # 事件載入與時間軸服務
47-
└── features/ # 核心元件 (地圖、時間軸、搜尋、側邊欄等)
73+
cap-map/
74+
├── .github/workflows/deploy.yml # 自動部署至 GitHub Pages
75+
├── docs/ # 設計規格書
76+
└── webapp/ # Angular 應用程式
77+
├── public/assets/data/
78+
│ ├── events.json # 76 筆事件資料
79+
│ └── timeline.json # 8 個分期定義
80+
├── scripts/
81+
│ └── validate-events.mjs # 資料驗證腳本（npm run test:data）
82+
└── src/app/
83+
├── store/ # NgRx actions / reducers / selectors
84+
├── services/ # EventService / TimelineService / QuizService
85+
├── map-container/ # Leaflet 地圖元件
86+
├── timeline/ # 時間軸元件
87+
├── event-sidebar/ # 事件詳情與測驗側邊欄
88+
├── search-bar/ # 搜尋列
89+
└── layer-control/ # 圖層切換面板
4890
```
4991

5092
---
5193

5294
## 快速開始
5395

54-
### 本地開發步驟
55-
56-
在開始之前，請確保您的系統已安裝 [Node.js](https://nodejs.org/) (建議 v20 以上) 與 `npm`。
96+
```bash
97+
# 1. 複製並進入專案
98+
git clone https://github.com/raybird/cap-map.git
99+
cd cap-map/webapp
57100

58-
1. **複製本儲存庫**：
59-
```bash
60-
git clone https://github.com/raybird/cap-map.git
61-
cd cap-map
62-
```
101+
# 2. 安裝相依套件
102+
npm install
63103

64-
2. **進入 `webapp` 目錄並安裝相依套件**：
65-
```bash
66-
cd webapp
67-
npm install
68-
```
104+
# 3. 啟動開發伺服器（http://localhost:4200）
105+
npm start
69106

70-
3. **啟動本地開發伺服器**：
71-
```bash
72-
npm run start
73-
# 或使用 ng serve
74-
```
75-
啟動後，請於瀏覽器中開啟 `http://localhost:4200` 即可進行預覽。
107+
# 4. 驗證事件資料完整性
108+
npm run test:data
109+
```
76110

77111
---
78112

79-
## 部署與發布 (GitHub Pages)
113+
## 部署
80114

81-
本專案已設定 GitHub Actions。當變更被推送（Push）至 `main` 分支時，工作流會自動執行建置並部署至 GitHub Pages：
115+
推送至 `main` 分支後，GitHub Actions 自動建置並發布至 GitHub Pages：
82116

83-
* **網頁預覽網址**：`https://raybird.github.io/cap-map/`
84-
* **部署配置檔**：`.github/workflows/deploy.yml`
117+
- **網址**：`https://raybird.github.io/cap-map/`
118+
- **工作流**：`.github/workflows/deploy.yml`
85119

86-
> [!NOTE]
87-
> **GitHub Pages 設定步驟**：
88-
> 1. 請至您的 GitHub 儲存庫，點選 **Settings** > 側邊欄 **Pages**。
89-
> 2. 在 **Build and deployment** 下方的 **Source**，將下拉選單設定為 **`GitHub Actions`** 即可啟用自動部署。
120+
> **首次啟用**：至儲存庫 **Settings → Pages → Build and deployment**，將 Source 設為 **GitHub Actions**。

0 commit comments

Comments
 (0)