CK Club Hub 建中社團資料庫

目錄

• 專案簡介
• 技術架構
• 快速開始
• 使用說明
• 開發指南
• 部署指南
• 貢獻指南
• 更新日誌
• 聯絡方式

專案簡介

CK Club Hub 建中社團資料庫 是一個現代化的社團資訊整合平台，旨在提供完整且易用的社團查詢體驗，以及完整的 SEO 效果。

專案背景

原先是為了 114 學年度的社團博覽會製作線上社團地圖。在開發過程中發現校網上現有的線上社團介紹網站功能簡陋、使用體驗不佳，因此決定重新製作一個全新的整合介紹網站。

核心功能

此網站整合了活動介紹與攤位地圖等資訊，並提供以下完整功能：

• 完整的社團資訊查詢與篩選 - 支援多條件篩選和全文搜尋
• 社團按讚與收藏功能 - 使用者可個人化管理感興趣的社團
• 社團獨立頁面 - 透過 SEO 優化的獨立頁面，讓社團能有更多被看見的機會
• 互動式社團地圖 - 視覺化呈現社團位置和相關資訊
• 響應式設計 - 支援桌面和行動裝置瀏覽
• 外部資訊整合 - 連結社團官方資源和相關連結
• 主題切換功能 - 支援深色和淺色模式
• 歷年資料封存 - 保留往年的社團資料與攤位地圖，可在頁面上切換年度檢視

專案狀態

• 開發狀態：正式運營中
• 線上網站：https://club.cksc.tw/

技術架構

資料彙整

透過 google 表單搜集彙整資料，並使用正規表達式自動產生對應 Markdown 檔案，並於構建網站時依據檔案生成頁面

匯入腳本為 scripts/import-club-forms.py：

python3 scripts/import-club-forms.py "表單回覆.csv" "社團博覽會網頁製作資訊收集表單 (File responses)"

年度資料結構

每個學年度是一個獨立的 content collection，當年度掛在網站根目錄，往年封存在 /YYYY 之下：

學年度	Collection	資料庫	地圖	社團頁
115（當年度）	src/content/clubs	/clubs	/map	/clubs/[slug]
114（封存）	src/content/clubs2025	/2025/clubs	/2025/map	/2025/clubs/[slug]

• 當年度網址維持不變，封存頁面加上 noindex 並把 canonical 指回當年度頁面，避免稀釋 SEO
• Pagefind 只索引當年度頁面，封存年度的資料庫改用前端關鍵字比對
• 年度定義集中在 src/data/clubYears.ts，攤位配置在 src/data/clubFair.ts
• 社團的 dataYear 欄位代表該筆資料實際由哪一年的表單提供；若小於當年度，頁面會提示內容沿用往年

前端技術

• Astro - 用於實現部分組件、圖片優化等等
• React - 用於建構互動式組件
• Tailwind CSS - 使用其高效的深色模式以及主題色定義
• Pagefind - 靜態全文搜尋解決方案

後端服務

• Firebase - 作為即時資料庫和身份驗證服務
• Google Cloud Functions - 無伺服器運算平台，作為後端統計按讚數量等
• Cloudflare Workers - 邊緣運算服務，實現部分動態路由

部署平台

• Cloudflare Pages - 靜態網站託管和全球 CDN 服務

快速開始

直接訪問線上網站：https://club.cksc.tw/

無需安裝任何軟體，即可立即使用所有功能。

使用說明

網站導覽

網站頂部提供完整導覽列，包含以下頁面：

• 首頁 - 網站主要入口和概覽
• 地圖 - 互動式社團位置地圖
• 資料庫 - 社團搜尋和篩選頁面
• 社團聯展 - 社團聯展活動介紹頁面
• 關於 - 網站資訊和製作團隊

右上角提供主題切換按鈕，可切換深色/淺色模式。

搜尋功能

搜尋頁面特色：

• 頂部搜尋框支援關鍵字查詢
• 多項篩選條件可精確定位目標社團
• 支援「所有社團」和「已收藏社團」檢視模式切換
• 社團卡片右上角提供快速收藏功能

地圖操作

互動式地圖使用方式：

• 使用滑鼠拖拽移動地圖視野
• 滑鼠滾輪縮放地圖比例
• 點擊社團標籤旁的圓圈查看詳細資訊
• 頂部搜尋框可快速定位特定社團位置
• 點擊搜尋結果框中的標題可以自動縮放至當前顯示的社團位置

社團頁面

個別社團頁面功能：

• 右上方操作按鈕包含：
  • 收藏 - 加入不公開的個人收藏清單
  • 按讚 - 將同步至資料庫，需要 Google 帳號驗證
  • 分享 - 依據社團資訊產生分享卡片，提供展示與分享
  • 查看位置 - 直接跳轉至地圖頁面對應位置
• 頁面底部提供意見反饋按鈕，可提交建議或問題回報

開發指南

環境設定

1. 複製儲存庫

git clone https://github.com/jx06T/ck_club.git
cd ck_club

2. 安裝依賴套件

npm install

3. 啟動開發伺服器

npm run dev

開發流程

本專案遵循 Astro 標準開發流程：

• npm run dev - 啟動開發模式
• npm run build - 建置生產版本
• npm run preview - 預覽建置結果

貢獻方式

1. Fork 本專案儲存庫
2. 建立功能分支
3. 提交變更內容
4. 建立 Pull Request

我們歡迎任何形式的貢獻，包括 bug 修復、功能增強和文件改進。

部署指南

生產部署

線上網站使用 Cloudflare Pages 進行部署，具備以下優勢：

• 全球 CDN 加速
• 自動 HTTPS 憑證
• 與 Git 儲存庫整合的自動部署
• 優異的效能表現
• 高額度的免費流量

部署流程會在程式碼推送至主分支時自動觸發。

貢獻指南

專案貢獻者

網頁資料蒐集彙整

• 建中社團執行委員會
• 建中班聯會

網頁製作單位

• 建中電子計算機研究社

更新日誌

開發歷程

• 資料蒐集階段 - 收集各社團基本資訊和相關資料
• 框架建置 - 確立技術架構和專案結構
• 首頁開發 - 實作網站主要入口頁面
• 元件開發 - 建構可重複使用的 UI 元件
• 搜尋頁面 - 實作社團查詢和篩選功能
• 地圖頁面 - 開發互動式地圖介面
• 資料同步 - 同步搜集的資料至網站
• 地圖更新 - 優化地圖顯示和互動體驗
• 按讚功能 - 新增按讚系統以及即時訊息之功能
• 分享功能 - 實作社群分享卡片系統

授權條款

本專案採用 MIT 授權條款。詳細內容請參考 LICENSE 檔案。

授權範圍僅限網站框架與組件，不包含其內文及圖片

聯絡方式

網站開發人員
jx06T: https://github.com/jx06T
Dong-Chen-1031: https://github.com/Dong-Chen-1031

建中班聯會
Instagram: https://www.instagram.com/cksc.80th/