Git × GitHub × Vercel：從自己的電腦到公開網址

# 課程規則（程式設計三）

這份檔案放在專案根目錄，Antigravity 每次對話都會遵守。

## 工作方式
- 每次開始工作前，先讀 PROJECT.md，依照裡面的頁面、資料表與驗收標準實作。
- 一次只做一條功能。完成後停下來，告訴我怎麼手動測試，等我確認再做下一條。
- 只修改和這次任務相關的檔案，不要重寫整個專案，也不要順手改其他功能。
- 用繁體中文說明你做了什麼、改了哪些檔案，以及每個檔案改動的原因。

## 程式品質
- SQL 一律使用參數（SQLite 用 ?，Postgres 用 %s），不可以用字串拼接或 f-string 組 SQL。
- 使用者輸入一定要在伺服器端檢查，不能只靠網頁表單。
- 測試失敗時，先說明原因；不要為了讓測試通過而修改測試的預期結果。

## 安全
- 不要要求我把密碼、token、API 金鑰貼到對話框。需要登入時，告訴我要在瀏覽器或終端機做什麼，由我自己完成。
- 金鑰與資料庫連線字串只放在 .env 或 Vercel 的環境變數，.env 必須列在 .gitignore。
- 不要執行 git push --force、git reset --hard，也不要刪除 GitHub 儲存庫或 Vercel 專案。
- 專案資料夾只放虛構或範例資料。

---
name: git-save
description: 建立 Git 存檔點（commit）。當使用者說「存檔」「commit」「建立存檔點」，或一條功能已經對過答案、要保存目前進度時使用。
---

# 建立存檔點

依照下列順序執行，每一步都用繁體中文回報結果。

1. 執行 `git status`，列出這次有哪些檔案被新增、修改或刪除。
2. 檢查是否有不該存檔的檔案：`.env`、`.venv/`、`instance/`、`__pycache__/`、資料庫檔（`*.db`）。如果出現在待存檔清單中，先停下來告訴我，並建議加入 `.gitignore`，不要存檔。
3. 如果專案有 `tests/` 資料夾，執行 `python -m pytest -q`。有測試失敗就停下來說明原因，不要存檔。
4. 用一兩句話摘要這次的改動，請我確認存檔訊息。訊息格式：`功能N：功能名稱` 或 `修正：問題描述`。
5. 執行 `git add -A` 與 `git commit -m "<訊息>"`。
6. 如果 PROJECT.md 有「功能進度」，把完成的項目打勾，並一起存檔。
7. 最後執行 `git log --oneline -5` 給我看。

不要執行 `git push`；要推上 GitHub 請使用 github-publish skill。

---
name: github-publish
description: 把專案推上 GitHub。當使用者說「推上 GitHub」「push」「備份到 GitHub」「建立 GitHub 儲存庫」時使用。第一次推送會建立新的儲存庫，之後只推送新的存檔點。
---

# 推上 GitHub

使用 GitHub CLI（gh）。全程不可以要求使用者提供密碼或 token。

## 1. 檢查登入狀態
執行 `gh auth status`。
- 如果顯示未登入：停下來，請使用者自己在終端機執行 `gh auth login`（選 GitHub.com → HTTPS → Login with a web browser），完成後再繼續。不要替使用者執行登入。
- 如果找不到 gh 指令：請使用者到 https://cli.github.com 安裝，安裝後重新開啟 Antigravity。

## 2. 推送前檢查
- `git status` 必須是乾淨的（所有修改都已存檔）；如果不是，先請使用者用 git-save 存檔。
- 確認 `.gitignore` 排除 `.env`、`.venv/`、`instance/`、`__pycache__/`、`*.db`。
- 用 `git ls-files` 確認沒有任何 .env 或金鑰檔已經被追蹤。若有，停下來說明怎麼移除，不要推送。

## 3. 推送
- 執行 `git remote -v`。
- **還沒有遠端（第一次）**：詢問使用者儲存庫名稱與 Public／Private，然後執行
  `gh repo create <名稱> --<public 或 private> --source=. --remote=origin --push`
- **已經有遠端**：執行 `git push`。

## 4. 回報
- 執行 `gh repo view --json url -q .url` 取得儲存庫網址，告訴使用者。
- 如果這個儲存庫已連結 Vercel，提醒使用者：推送後 Vercel 會自動開始部署，大約 1 分鐘後到 Vercel 的 Deployments 頁面確認狀態。

禁止：`git push --force`、刪除或改名遠端儲存庫、修改其他人的儲存庫。

---
name: vercel-deploy-check
description: 部署到 Vercel 之前的檢查清單，以及部署後的線上驗收。當使用者說「準備上線」「部署到 Vercel」「上線前檢查」，或部署失敗需要找原因時使用。
---

# Vercel 上線前檢查

逐項檢查，用表格回報每一項的結果（通過／未通過／不適用）與修正建議。未經使用者同意，不要自行修改檔案。

## A. 靜態網站（只有 HTML／CSS／JS）
1. 根目錄有 `index.html`。
2. 網頁中的連結與圖片都使用相對路徑，而且檔名大小寫和實際檔案一致（Vercel 主機會區分大小寫）。

## B. Flask 網站
1. 入口檔是根目錄的 `app.py`（或 index.py、main.py），裡面有名為 `app` 的 Flask 物件。
2. `requirements.txt` 列出所有用到的套件（至少 flask；使用 Postgres 時要有 psycopg）。
3. 圖片、CSS 等靜態檔案放在 `public/` 資料夾。
4. **資料庫**：Vercel 主機上的檔案是暫時的，SQLite 寫入的資料會消失。
   - 程式要能在環境變數 `DATABASE_URL` 存在時連線到 Postgres（Neon），不存在時使用本機 SQLite。
   - 列出 SQLite 與 Postgres 語法不同的地方：參數符號 ? 與 %s、自動編號欄位、日期函式、ROUND(AVG(...)) 需要轉成 numeric。
5. 本機執行 `python -m pytest -q` 全部通過。

## C. 安全
1. `.env`、`.venv/`、`instance/`、`*.db` 都在 `.gitignore` 中，而且 `git ls-files` 中看不到它們。
2. 程式碼中沒有寫死任何密碼、token、連線字串；一律從環境變數讀取。
3. 說明哪些環境變數要到 Vercel 專案的 Settings → Environment Variables 設定（Neon 由 Marketplace 加入時會自動設定 DATABASE_URL）。

## D. 部署後驗收
部署完成後，請使用者提供網址，然後列出要在瀏覽器手動確認的項目：
- 首頁能打開，資料有顯示（代表資料庫連線成功）。
- 新增一筆資料後重新整理，資料仍在（代表寫入的是雲端資料庫，不是暫時檔案）。
- 用手機打開一次。
- 失敗時，請使用者到 Vercel 專案的 Deployments → 點該次部署 → Logs，把錯誤訊息貼給你分析。

---
name: my-skill
description: （一句話說明這個 skill 做什麼，以及「什麼時候」要使用它。AI 只看這一句決定要不要用，所以要寫出使用者可能會說的話，例如：當使用者說「整理週誌」時使用。）
---

# （skill 的名稱）

## 目的
（這個 skill 要解決什麼重複發生的問題？）

## 步驟
1. （第一步要做什麼、執行什麼指令、讀哪個檔案）
2. （第二步）
3. （怎麼回報結果：表格、清單，或一句話）

## 什麼時候要停下來問我
- （例如：要刪除檔案之前、測試失敗時）

## 禁止
- （例如：不可以修改 tests/ 裡的檔案）