Initial commit

Author: alvin000009238

.env.example

@@ -0,0 +1,5 @@
+TUNNEL_TOKEN=your_tunnel_token_here
+SECRET_KEY=your_random_secret_string_here
+
+TURNSTILE_SITE_KEY=your_turnstile_site_key_here
+TURNSTILE_SECRET_KEY=your_turnstile_secret_key_here

.github/workflows/deploy.yml

@@ -0,0 +1,74 @@
+name: Deploy to VPS
+
+on:
+  push:
+    branches: [ "main" ]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          
+      - name: Basic Syntax Check
+        run: |
+          python -m py_compile server.py
+          python -m py_compile fetcher.py
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest
+            type=sha,format=long
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Deploy to VPS via SSH
+        uses: appleboy/ssh-action@master
+        with:
+          host: ${{ secrets.VPS_HOST }}
+          username: ${{ secrets.VPS_USERNAME }}
+          key: ${{ secrets.VPS_SSH_KEY }}
+          port: ${{ secrets.VPS_PORT }}
+          script: |
+            # 登入 GHCR
+            echo "${{ secrets.GHCR_PAT }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
+            
+            # 使用明確 SHA tag 更新服務 (避免 latest 不觸發更新的問題)
+            docker service update \
+              --with-registry-auth \
+              --image ghcr.io/${{ github.repository }}:sha-${{ github.sha }} \
+              school_grades_app
+            
+            # 等待更新完成並檢查狀態
+            docker service ps school_grades_app --no-trunc --format "{{.CurrentState}}" | head -1

.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Environment Variables (CRITICAL for security)
+.env
+
+# Application Data & Temporary Files
+grades_raw.json
+shared_grades/
+*.json
+!requirements.txt
+!.env.example
+!package.json
+!manifest.json
+*.md
+!README.md
+# Exclude specific JSONs but allow config templates if any
+
+# Large Files
+*.tar
+*.tar.gz
+
+# Logs
+*.log
+
+# Docker
+.dockerignore
+
+# IDE & OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies (curl for healthcheck)
+RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create necessary directories
+RUN mkdir -p shared_grades
+
+# Expose port
+EXPOSE 5000
+
+# Use gunicorn for production
+CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--timeout", "120", "--workers", "5", "--threads", "4", "server:app"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin000009238
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,94 @@
+# 成績分析平台 - 中大壢中
+
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+> [!IMPORTANT]
+> 本專案為非官方開發之第三方服務，我們與壢中及欣河智慧校園平台無任何直接關聯。
+
+本專案實作了自動化的成績查詢流程，全程透過原生的 HTTP 請求（使用 Python `requests` 模組）與學校系統的 API 介接，免去開啟實際瀏覽器的負擔。由於摒棄了複雜的網站前端渲染，它能提供非常快速且輕量化的連線體驗，並支援取得成績後建立分享連結的功能。
+
+## Table of Contents
+
+- [Background](#background)
+- [Install](#install)
+- [Usage](#usage)
+- [Maintainers](#maintainers)
+- [License](#license)
+
+## Background
+
+此專案開發初衷是為了解決複雜的成績查詢手續。應用程式負責打理自動登入驗證與建立 session，並藉由輕量型 API 接口處理後續的網路請求。這使得使用者能夠透過更為友善直觀的介面，快速查詢個人成績並與他人分享。
+
+## Install
+
+本專案**僅提供本地開發及部署環境教學**。你需要 Python 3.10+ 版本環境才能執行此專案。
+
+### 1. 取得專案原始碼
+
+```bash
+git clone https://github.com/alvin000009238/grades.git
+cd grades
+```
+
+### 2. 環境變數設定
+
+此專案需要設定特定的環境變數，請參考 `.env.example` 建立你自己的 `.env` 檔案。
+
+Linux / macOS:
+```bash
+cp .env.example .env
+```
+
+Windows (PowerShell):
+```powershell
+Copy-Item .env.example .env
+```
+
+編輯 `.env`，設定例如 `SECRET_KEY` 的必要變數。
+
+### 3. 設定 Python 虛擬環境並安裝依賴
+
+強烈建議使用 [venv](https://docs.python.org/3/library/venv.html) 將本專案的依賴隔離於你的全域 Python 環境中：
+
+```bash
+# 建立虛擬環境
+python -m venv venv
+
+# 啟動虛擬環境 (Linux/macOS)
+source venv/bin/activate
+
+# 啟動虛擬環境 (Windows PowerShell)
+.\venv\Scripts\Activate.ps1
+```
+
+接著安裝必要的 Python 套件：
+
+```bash
+# 安裝所有相依套件
+pip install -r requirements.txt
+```
+
+## Usage
+
+確保已經處於虛擬環境中（終端機介面前有 `(venv)` 標示）並且所有依賴都已正確安裝。
+
+啟動 Flask 開發伺服器：
+
+```bash
+python server.py
+```
+
+在你的瀏覽器中開啟 `http://127.0.0.1:5000` 來使用此應用程式。
+
+> [!WARNING]
+> 本應用預設以 `debug=True` 運行於 Flask 的內建伺服器（Development Server），這並不適合直接暴露於公共網路環境，也不適用於生產模式部署。
+
+## Maintainers
+
+[@alvin000009238](https://github.com/alvin000009238)
+
+## License
+
+[MIT](LICENSE) © 2026 alvin000009238

docker-compose.yml

@@ -0,0 +1,34 @@
+services:
+  app:
+    image: ghcr.io/${GHCR_IMAGE:-alvin000009238/school_grades}:latest
+    volumes:
+      - ./shared_grades:/app/shared_grades
+    environment:
+      - PYTHONUNBUFFERED=1
+      - SECRET_KEY=${SECRET_KEY}
+      - TURNSTILE_SITE_KEY=${TURNSTILE_SITE_KEY}
+      - TURNSTILE_SECRET_KEY=${TURNSTILE_SECRET_KEY}
+      - TZ=Asia/Taipei
+
+    deploy:
+      restart_policy:
+        condition: any
+      update_config:
+        order: start-first
+        failure_action: rollback
+        delay: 10s
+    healthcheck:
+      test: [ "CMD", "curl", "-f", "http://localhost:5000/health" ]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+  tunnel:
+    image: cloudflare/cloudflared:latest
+    command: tunnel run
+    environment:
+      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
+    deploy:
+      restart_policy:
+        condition: any