{"id":51132763,"url":"https://github.com/john-data-chen/sveltekit-starter-kit","last_synced_at":"2026-06-25T14:30:51.102Z","repository":{"id":362592923,"uuid":"1256760859","full_name":"john-data-chen/sveltekit-starter-kit","owner":"john-data-chen","description":"A production-grade SvelteKit starter kit built around a real multi-user expense tracker, demonstrating technical decision-making, quality engineering, and AI-assisted development practices. Built with Svelte 5 (runes mode), TypeScript, Tailwind CSS v4, and Prisma ORM + PostgreSQL.","archived":false,"fork":false,"pushed_at":"2026-06-19T23:06:31.000Z","size":1289,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T01:06:31.944Z","etag":null,"topics":["agentic-workflow","ai-assisted-development","cicd","context-engineering","github-actions","harness-engineering","neon","orm","playwright","postgresql","prisma","prompt-engineering","svelte","sveltekit","tailwindcss","typescript","vercel","vitest"],"latest_commit_sha":null,"homepage":"https://sveltekit-starter-kit.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/john-data-chen.png","metadata":{"files":{"readme":"README-cht.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-02T04:18:41.000Z","updated_at":"2026-06-19T23:06:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/john-data-chen/sveltekit-starter-kit","commit_stats":null,"previous_names":["john-data-chen/sveltekit-starter-kit"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/john-data-chen/sveltekit-starter-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/john-data-chen%2Fsveltekit-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/john-data-chen%2Fsveltekit-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/john-data-chen%2Fsveltekit-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/john-data-chen%2Fsveltekit-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/john-data-chen","download_url":"https://codeload.github.com/john-data-chen/sveltekit-starter-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/john-data-chen%2Fsveltekit-starter-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34780124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflow","ai-assisted-development","cicd","context-engineering","github-actions","harness-engineering","neon","orm","playwright","postgresql","prisma","prompt-engineering","svelte","sveltekit","tailwindcss","typescript","vercel","vitest"],"created_at":"2026-06-25T14:30:50.108Z","updated_at":"2026-06-25T14:30:51.090Z","avatar_url":"https://github.com/john-data-chen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SvelteKit: 多人(家庭)共享線上記帳本 | 包含人工智慧輔助工程流程的完整入門套件\n\n[![codecov](https://codecov.io/gh/john-data-chen/sveltekit-starter-kit/graph/badge.svg?token=9Mdwd8ibQs)](https://codecov.io/gh/john-data-chen/sveltekit-starter-kit)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=john-data-chen_sveltekit-starter-kit\u0026metric=alert_status\u0026token=6c61941d26a0ba1e36bc438f28dba039c8e3700d)](https://sonarcloud.io/summary/new_code?id=john-data-chen_sveltekit-starter-kit)\n[![CI](https://github.com/john-data-chen/sveltekit-starter-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/john-data-chen/sveltekit-starter-kit/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n這是一個產品級別的 SvelteKit starter kit，以真實可用的多使用者 **線上記帳本** 為核心，所有帳號都可以新增支出、收入，並查看統計資訊。而管理帳號可以看到所有帳號的交易紀錄。\n這展示技術決策、品質工程，以及 AI 輔助開發的實作方式。技術棧包含 Svelte 5（runes mode）、TypeScript、Tailwind CSS v4、Prisma ORM 與 PostgreSQL。\n\n本專案刻意聚焦於產品團隊在意的能力：型別化、模組化的 **TypeScript / Node.js**；有意識的 **API、資料流與 RBAC** 設計；搭配 ORM 驅動 **schema migration** 與執行時驗證的 **PostgreSQL**；**AI 輔助（Harness）工程**；以及具紀律、可驗證的交付。\n\n英文版本請見 **[README.md](./README.md)**。\n\n**[Live Demo](https://sveltekit-starter-kit.vercel.app/login)** — 按下 **以 Email 繼續** 即可用已建立的使用者登入。\n\n\u003e 🚀 **下一代延伸專案 — [ultra-light-monorepo](https://github.com/john-data-chen/ultra-light-monorepo)**\n\u003e 本 starter kit 進化為前後端分離的 **monorepo** 架構，並針對 **Vercel Remote Cache** 優化 CI/CD 部署。兩個作品集專案共同呈現一條清晰的成長軌跡：從聚焦、產品級的全端應用，邁向可擴展、快取最佳化的 monorepo 平台。\n\n\u003e **框架敏捷性展示 — [Next.js Kanban Board](https://github.com/john-data-chen/next-dnd-starter-kit)**\n\u003e 以 Next.js App Router、Zustand 與 MongoDB 打造的產品級看板。AI 輔助工程實現快速框架切換與高速交付。證明了框架敏捷性與 AI 驅動的品質。\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"./src/lib/assets/screenshots/login.png\" alt=\"免密碼 email 登入畫面，已預填 demo account\" width=\"140\"\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"./src/lib/assets/screenshots/dashboard.png\" alt=\"Dashboard 顯示月收入、支出、結餘與純 CSS 類別 donut chart\" width=\"140\"\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"./src/lib/assets/screenshots/transactions.png\" alt=\"交易紀錄清單，包含類別與月份篩選，以及編輯與刪除操作\" width=\"140\"\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"./src/lib/assets/screenshots/add-new-record.png\" alt=\"新增交易表單，包含類型、類別、金額、日期與備註欄位\" width=\"140\"\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"./src/lib/assets/screenshots/admin.png\" alt=\"管理員 Governance 介面：逐使用者交易筆數、所有成員的總收入與支出，以及近期活動稽核軌跡\" width=\"140\"\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"./src/lib/assets/screenshots/api-docs.png\" alt=\"Expense Tracker API 的 Scalar UI：OpenAPI 3.1 規範，含 cookie 驗證、client libraries 與 List transactions endpoint\" width=\"140\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003e登入畫面\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003e儀表板\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003e交易紀錄清單\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003e新增交易\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003e管理員介面\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003eAPI 文件\u003c/b\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n| 指標           | 結果                                                                                       |\n| -------------- | ------------------------------------------------------------------------------------------ |\n| Test Coverage  | 見上方 **codecov** badge，95+% 由 Vitest（unit + integration）量測                         |\n| Code Quality   | 見上方 **SonarQube Quality Gate** badge（Security、Reliability、Maintainability，全 A 級） |\n| Lighthouse     | Production 環境儀表板 Lighthouse 評分 — **全 90+ 分）**                                    |\n| E2E Validation | Playwright 跨瀏覽器驗證(Chrome / Safari / Edge / Mobile Chrome / Mobile Safari)            |\n| CI/CD Pipeline | Gemini PR Review + GitHub Actions → SonarQube + Codecov → Vercel（自動部署到 Production）  |\n\n---\n\n## 生產環境 Lighthouse 儀表板審查\n\n\u003cimg src=\"./src/lib/assets/screenshots/dashboard-lighthouse-score.png\" alt=\"儀表板 Lighthouse 審查：全部 90+ 項得分\" width=\"460\"\u003e\n\n---\n\n## 技術決策\n\n### 架構\n\n評估過引入第三方 UI 元件庫，最終選擇建立內部的 Svelte 5 primitives 層 — 理由：維持極少依賴的原則、無依賴成本的抽象化、符合無障礙標準（a11y-correct）的原生 `\u003cdialog\u003e`，以及利用 Svelte 5 snippets 達到純 HTML 屬性傳遞（不需透過 bind prop-drilling）。\n\n| 類型          | 選擇                                           | 理由                                                                                  |\n| ------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Framework     | SvelteKit 2 + Svelte 5（runes）                | 精細的響應性、極簡樣板、SSR + 表單操作                                                |\n| Styling       | Tailwind CSS v4（Vite plugin）                 | 公用優先、零執行時間，透過 v4 Vite plugin 加速建置                                    |\n| Database      | Prisma ORM + PostgreSQL                        | 宣告式 schema 作為唯一真相來源；型別安全的 generated client、內建 migrations          |\n| DB Driver     | `pg`（經 `@prisma/adapter-pg`）                | Prisma v7 driver-adapter 工作流；快速 pooled driver，適合 Vercel Node serverless 服務 |\n| Auth          | Password-less email + signed `httpOnly` cookie | 不儲存密碼；使用最小且清楚的 session model                                            |\n| Authz/RBAC    | 路由層級的權限守衛（`requireAdmin`）           | 基於資料庫使用者角色（`admin` 與 `member`）的嚴格存取控制                             |\n| Rate Limiting | 記憶體內的 fixed-window 限流（登入 + API）     | 簡易的防暴力破解/濫用；生產環境會改用 Vercel KV / Redis                               |\n| Security      | Nonce CSP + HSTS + 強化的回應標頭              | 縱深防禦；僅 Scalar `/api/docs` 放寬 CSP，dev 模式移除 CSP 以支援 Vite HMR            |\n| Validation    | Zod（server-side schemas）                     | 在 form action 邊界做執行時驗證 — 編譯檢查交給 TS，輸入檢查交給 Zod                   |\n| REST API      | 完整的 CRUD API + JSON 回應封裝                | 分離的 REST 層以利外部系統整合或手機端應用呼叫                                        |\n| API Docs      | Scalar UI + Zod 4 原生 OpenAPI 匯出            | 直接由 Zod 模型動態產生的零阻力互動式 API 文件                                        |\n| Tables        | `@tanstack/table-core`                         | Headless，無 UI 依賴，將排序狀態同步至 URL 並且純粹使用 Svelte 元件渲染               |\n| Charts        | Pure CSS donut                                 | 不引入圖表套件，減少打包體積並保留完整控制                                            |\n| i18n          | Paraglide JS（`@inlang/paraglide-js`）         | 類型安全、tree-shakeable 翻譯；支援英文與繁體中文                                     |\n| Deploy        | `@sveltejs/adapter-vercel`（Node serverless）  | `pg` TCP driver 需要 Node runtime                                                     |\n\n### 品質保證\n\n| 類型              | 工具       | 理由                                             |\n| ----------------- | ---------- | ------------------------------------------------ |\n| Unit/Integration  | Vitest     | 比 Jest 更快，原生 ESM，與 Vite 生態整合佳       |\n| E2E               | Playwright | 跨瀏覽器支援，比 Cypress 更輕量                  |\n| Static Analysis   | SonarQube  | 在 CI 中執行 quality gates 程式碼 bad smell 檢查 |\n| Coverage Tracking | Codecov    | 自動整合 PR coverage                             |\n\n**Testing Strategy:**\n\n- Unit tests 聚焦查詢邏輯、驗證、貨幣 格式化 / 解析\n- E2E tests 驗證重要流程（登入、transaction CRUD）\n- 每次推送/PR 都會先運行整個 pipeline，由 Gemini 進行初審，然後開發者再複查。只有兩次審核都通過後才會合併（免費伺服器效能不足，因此 CI 只執行單元測試，端對端測試在本機上執行）。\n\n### Developer Experience\n\n| 工具                    | 用途                                                     |\n| ----------------------- | -------------------------------------------------------- |\n| oxlint                  | Rust-based JS/TS linter，比 ESLint 快 50-100 倍          |\n| oxfmt                   | Rust-based formatter，處理 JS/TS/CSS/HTML/JSON/MD/Svelte |\n| ESLint（Svelte）        | 專門處理 `.svelte` 檔案的 lint（啟用 content-hash 快取） |\n| Vite                    | 近乎即時的 HMR 與快速建置                                |\n| Husky + lint-staged     | pre-commit 品質檢查                                      |\n| commitlint + Commitizen | Conventional commits，維持乾淨 commit history            |\n\n### 架構決策紀錄 (ADR)\n\n| 決策                                                         | 原因                                                                                                                                                                                                                                                                                                             |\n| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 保留 `svelte.config.js`，不將所有設定整合到 `vite.config.ts` | SvelteKit ≥ 2.62.0 可使用 `sveltekit()` 將 `svelte.config.js` 內容整合到 `vite.config.ts`，但 `svelte-check`、`eslint-plugin-svelte` 與 IDE (VS Code..etc) 仍需讀取 `svelte.config.js` 取得強制 runes 設定。新做法必須放棄原先默認的設定，推翻慣例也許會讓其他接手的開發者感到疑惑，權衡利弊後決定使用原先做法。 |\n| 自建 Svelte 5 UI primitives，不用元件庫                      | 更少依賴、更小 bundle、原生 a11y（`\u003cdialog\u003e`/`\u003cselect\u003e`）、乾淨的 runes/snippets                                                                                                                                                                                                                                 |\n| Vercel Node 用 pooled `pg` TCP driver（非 Edge）             | 可靠連線池、免 proxy、本機 Docker 跑相同 Postgres                                                                                                                                                                                                                                                                |\n| Zod schema = 單一真相來源                                    | 一份 schema → 驗證 + TS 型別 + OpenAPI 3.1；零落差                                                                                                                                                                                                                                                               |\n\n---\n\n## 功能\n\n- **Password-less email login** — 內建三個帳號（`john@example.com` (Admin)、`sophia@example.com` (Member)、`mark@example.com` (Member)）；表單預填 `john@example.com`，按一次即可登入。`userId` 會存放在 signed `httpOnly` session cookie。\n- **角色與權限 (Roles \u0026 Permissions)** — \"member\"（預設）只能看見並操作自己的記帳資料；\"admin\" 則可存取 `/admin` 管理介面，總覽所有使用者的平台使用狀況（Governance）。\n- **稽核日誌 (Audit Log)** — 紀錄使用者變更（新增、修改、刪除），顯示於管理員 Governance 介面中。\n- **Transactions CRUD** — 可新增、查看、編輯、刪除收入/支出紀錄（數目、類型、類別、日期、備註）。\n- **Sortable data-tables (TanStack)** — 交易清單與管理員報表皆採用 TanStack Table 實作排序功能，並且排序狀態會與 URL 同步。\n- **List \u0026 filter** — 可依 類型 與 月份 篩選交易紀錄；查詢條件會保存在 URL。\n- **Dashboard** — 顯示當月收入、支出、結餘，以及以 原生CSS 製作的類型圓環圖 (無依賴圖表庫，支援大/小切換)。\n- **REST API + OpenAPI 互動文件** — 提供完整的 CRUD endpoints (`/api/transactions`, `/api/stats`)，重度利用 Zod 模型來動態對應出即時的 OpenAPI 3.1 規範。同時於 `/api/docs` 掛載了 Scalar UI 以供互動式探索。\n- **Per-user data isolation** — 每個查詢都會以登入使用者做限制；使用者只能看到自己的資料。\n- **Schema migration 與驗證** — PostgreSQL schema 以 Prisma Migrate 做版本控管（`db:migrate`），所有不可信輸入都在邊界經由 Zod 驗證；單一 schema 同時是型別、驗證與 OpenAPI 規範的唯一真相來源。\n- **限流 (Rate limiting)** — best-effort 記憶體內 fixed-window 限流：登入每 IP 每分鐘上限 10 次，已驗證的 API 寫入每 IP 每分鐘上限 100 次，超過時回傳 `429` 並附上 `Retry-After` header。（serverless 環境下應改用 Vercel KV / Upstash Redis 讓多實例共享狀態。）\n- **安全強化 (Security hardening)** — 每個 HTML 回應都帶有 nonce-based Content-Security-Policy，以及 `X-Content-Type-Options`、`X-Frame-Options: DENY`、`Referrer-Policy`、`Permissions-Policy`；production 另啟用 `Strict-Transport-Security`。僅 Scalar `/api/docs` 頁面放寬 CSP，dev 模式則移除 CSP 以支援 Vite HMR。\n- **API 分頁 (Pagination)** — `GET /api/transactions` 接受 `limit`（預設 20，上限 100）與 `offset`，並回傳 `{ data, pagination: { total, limit, offset } }` 封裝。\n- **Currency** — 僅支援 TWD，金額以整數儲存，不使用小數。\n- **i18n** — 英文與繁體中文（Paraglide JS）。\n- **Theme switching** — 淺色 / 深色 / 系統。\n- **Responsive design** — 手機小螢幕排版優先，也支援電腦大螢幕排版。\n- **Web analytics** — 全站注入 Vercel Web Analytics（`@vercel/analytics`），提供注重隱私、不使用 cookie 的流量洞察。\n- **SEO 與可被搜尋性** — 登入著陸頁提供在地化的 meta description（`seo_description`）、canonical URL、theme-color、Open Graph 與 Twitter Card 標籤，以及 JSON-LD `WebApplication` 結構化資料；並從 `static/` 提供 `sitemap.xml` 與 `robots.txt` 的 `Sitemap:` 指令。\n\nCategory 固定定義於 `src/lib/categories.ts`；session cookie 使用 `.env` 中的 `SESSION_SECRET` 簽章。\n\n---\n\n## 角色與權限 (Roles \u0026 Permissions) / Governance\n\n應用程式強制執行基於資料庫角色的資料權限邊界。這正是企業系統（ERP / BPM / 內部後台工具）所仰賴的存取控制與監督樣式：role-based access control、逐使用者資料隔離、稽核軌跡（audit trail），以及僅供讀取的治理／合規檢視。\n\n- **成員 (Member)**：只能存取自己的儀表板與交易紀錄。資料在查詢層級即做到單一使用者隔離。\n- **管理員 (Admin)**：視為受信任的合規/治理稽核員。受到伺服器端 `requireAdmin` 守衛保護的 `/admin` 總覽介面僅供讀取。為了方便平台監督，設計上允許管理員在稽核日誌 (Audit Trail) 中看見單筆紀錄細節（例如單筆交易金額與分類）。\n\n管理員 Governance 介面彙整逐使用者活動（交易筆數、所有成員的總收入／支出），並搭配新增／修改／刪除事件的稽核軌跡 — 這正是企業後台工具（ERP／BPM／內部系統）所需的跨使用者監督與合規可視性。\n\n---\n\n## REST API 與 OpenAPI 文件\n\n**[Live API 文件 →](https://sveltekit-starter-kit.vercel.app/api/docs)** — 互動式 OpenAPI 3.1 參考文件（Scalar UI）。\n\n獨立的 REST 層（`/api/transactions`、`/api/stats`）提供完整 CRUD，含 cookie-based 驗證、逐使用者資料隔離、分頁與 `429` 限流 — 這正是前端、行動端或外部系統整合會串接的 API／資料流／權限邊界。每個 endpoint 的請求／回應形狀都以單一 **Zod schema** 定義（唯一真相來源），同時驅動執行時驗證與 `/api/openapi.json` 的即時 OpenAPI 3.1 規範，並透過 `/api/docs` 的 Scalar 呈現。文件由 schema 產生，因此永遠不會與實作脫節。\n\n---\n\n## 駕馭工程 (Harness Engineering)\n\n這個專案採用 Human-in-the-Loop 的 AI 協作方式。AI 工具不只是產生程式碼，而是被用來提高 **架構槓桿、品質保證與開發速度**。\n\nAI agent 是受治理的協作開發者，而非可自行 commit 的自動程式。\n\n- **Human-in-the-loop** — 每個指令與變更都經審查；不自行執行。\n- **Prompt 與 task template** — 每個 session 先定好角色、可動範圍與通過標準（lint／build／check／tests）。\n- **Context 管理** — 範圍限縮在 `src/`；可重用的已提交 skills；離線參考文件。\n- **Skill 與 task 拆解** — 唯讀規劃 → 人工審查 → 單步執行 → 逐步驗證。\n- **生成邊界控制** — Zod 強制 I/O contract；測試 mock PostgreSQL／第三方；HSTS／CSP 依 `dev` 與 prod 切換。\n- **Session handoff** — task 與 session log 讓任何模型從中斷處包含但不限於 token 或 session 耗盡 / 不可預期的崩潰 接手。\n- **交付紀律** — 每次變更都明確掌握需求、風險與影響範圍，並須通過上線前驗證（lint／build／check／tests）才能合併。\n\n### 可衡量的影響\n\n透過將 AI 整合到技術堆疊中，本專案實現了以下目標：\n\n- **速度**：樣板程式碼和標準模式的實現速度提升 5-10 倍，借助 Gemini Code Assist 將 PR 審查時間縮短 30-40%。\n- **品質**：透過 AI 產生的測試框架，實現更高的測試覆蓋率（80% 以上）。以及 Gemini Code Assist 的 PR 審查，從而減少 bug 和程式碼異味。\n- **學習**：透過 AI 指導的實現，快速掌握新工具（Svelte、Sveltekit、Prisma 等）。\n- **成本**：利用 AI 代理的技能減少程式碼迭代次數並遵循最佳實踐，從而降低成本。\n- **專注**：將工程時間從語法開發轉移到系統架構和使用者體驗。\n\n### AI Agent Skills（`.agents/skills/`）\n\nSkills 會提交到 repo，並透過 `AGENTS.md` / `CLAUDE.md` 提供給 AI assistants。每個 skill 都封裝了特定工作流與專案慣例。\n\n| Skill                                                                                                                                 | 職責                                                                                        |\n| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| [caveman（全域使用者 skill，未提交）](https://github.com/juliusbrussee/caveman)                                                       | 所有任務預設啟用：精簡輸出以降低 token 用量（僅限文字；程式碼/commit/PR 維持正常）          |\n| [karpathy-guidelines](https://github.com/forrestchang/andrej-karpathy-skills)                                                         | 降低 LLM 程式碼錯誤：明確假設、優先簡單方案、手術刀式修改、目標導向循環                     |\n| [doc-coauthoring](https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring)                                              | 文件共筆的 3 階段工作流程（上下文 → 精煉 → 讀者測試），本 README 由此技能與作者共同協作產生 |\n| **session-handoff (my private skill)**                                                                                                | 維護 `ai-docs/tasks.md` + `ai-docs/session-log.md`，讓跨模型/跨 session 接手時沒有資訊斷層  |\n| [prisma official AI guide](https://www.prisma.io/docs/ai)（cli、client-api、database-setup、postgres、driver-adapter-implementation） | Prisma ORM 工作流：CLI 指令、client API、provider 設定、Prisma Postgres、driver adapters    |\n| [svelte-code-writer](https://svelte.dev/docs/ai/skills)                                                                               | 用於在建立/編輯任何 `.svelte` 檔案時尋找技術文件和進行程式碼分析的 CLI 工具                 |\n| [svelte-core-bestpractices](https://svelte.dev/docs/ai/skills)                                                                        | 編寫快速、健壯、現代的 Svelte 程式碼的指南。                                                |\n\n### MCP（Model Context Protocol）Servers\n\nMCP 讓 AI 工具可直接和開發基礎設施互動，從而消除上下文切換 (人工介入) 的 token 開銷。\n\n| Server                                                                       | Integration Point | Workflow Enhancement                                                              |\n| ---------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------- |\n| [svelte-mcp](https://svelte.dev/docs/ai/mcp)                                 | Svelte docs       | 官方 Svelte 5 / SvelteKit docs、examples、code autofixing（已提交於 `.mcp.json`） |\n| [context7](https://github.com/upstash/context7)                              | Documentation     | 提供 AI agents version-accurate 的即時 library docs                               |\n| [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Browser state     | 讓 AI agents 透過 DevTools Protocol 檢查與驗證正在執行的 app                      |\n\n### AI Guidelines（`AGENTS.md` / `CLAUDE.md`）\n\n這些檔案是 AI 輔助開發的專案工作守則，包含主要驗證流程（`pnpm lint` → `pnpm build` → `pnpm check`）、常用指令，以及不同任務應使用的 skills/MCP servers。AI 在修改此專案前應先讀取這些指引。\n\n人機協作開發流程：\n\n```mermaid\ngraph TD\n    A[AI Code Generation] --\u003e B[Local Verification \u003cbr\u003e lint / build / typecheck]\n    B --\u003e C[User Confirmation]\n    C --\u003e D[Vitest Unit Tests]\n    D --\u003e E[Playwright Browser E2E Tests]\n    E --\u003e F[Git Commit \u0026 Push]\n    F --\u003e G[CI GitHub Actions]\n    G --\u003e H[SonarQube Quality Gate / Codecov]\n    H --\u003e I[Production Deployment to Vercel]\n```\n\n---\n\n## Quick Start\n\n### Requirements\n\n- Node.js \u003e= 24\n- pnpm 11.5+\n- Docker / OrbStack（本機 PostgreSQL）\n\n### Setup\n\n```bash\npnpm install\n\n# Environment — set DATABASE_URL + SESSION_SECRET\ncp .env.example .env\n\n# Database\npnpm db:start          # Start PostgreSQL via Docker (compose.yaml)\npnpm db:migrate        # Apply migrations to the local DB\npnpm db:seed           # Seed 3 demo users + sample transactions\n\n# Run\npnpm dev               # Development server\npnpm test              # Unit tests\npnpm test:e2e          # E2E tests (needs a seeded DB + dev server)\npnpm build             # Production build\n```\n\n`.env.example` 的預設 `DATABASE_URL` 與 `compose.yaml` 相符。請將 `SESSION_SECRET` 設成一段足夠長的隨機字串 (如使用指令 `openssl rand -base64 32` 產生)，用來簽署 session cookie。接著開啟 dev server（預設 `http://localhost:5173`），按下 **以 Email 繼續** 即可用 `john@example.com` 登入。\n\n### Commands\n\n```bash\npnpm dev           # Start dev server\npnpm build         # TypeScript compile + Vite build\npnpm preview       # Preview production build\npnpm lint          # oxlint --fix (JS/TS) + eslint（Svelte，啟用快取）\npnpm format        # oxfmt --write .\npnpm test          # vitest run\npnpm test:coverage # vitest run --coverage\npnpm test:e2e      # Playwright e2e\npnpm check         # svelte-kit sync + svelte-check\npnpm commit        # git-cz (commitizen with commitlint)\npnpm db:start      # docker compose up (PostgreSQL)\npnpm db:generate   # prisma generate\npnpm db:migrate    # prisma migrate dev\npnpm db:push       # prisma db push\npnpm db:seed       # Seed demo users + sample transactions\n```\n\n### 測試架構\n\n- **雙專案模式**: `server`（Node.js，後端工具與 API）與 `client`（JSDOM，Svelte 元件與 runes）。\n- **命名規範**:\n  - `*.spec.ts`: 於 `server` 環境執行。\n  - `*.svelte.spec.ts`: 於 `client`（JSDOM）環境執行。\n- **常用指令**:\n  - `pnpm test`: 執行所有 Vitest 單元測試。\n  - `pnpm test:coverage`: 執行測試覆蓋率（門檻 \u003e=80%）。\n  - `pnpm test:e2e`: 執行 Playwright 瀏覽器 E2E 測試。\n- **元件測試範例**:\n  ```ts\n  import { render, screen } from \"@testing-library/svelte\";\n  import Button from \"./Button.svelte\";\n  render(Button, { props: { children: () =\u003e \"Click\" } });\n  expect(screen.getByRole(\"button\", { name: \"Click\" })).toBeTruthy();\n  ```\n\n---\n\n## Project Structure\n\n```text\n.\n├── .agents/skills/              # Repo 專用 AI skills，由 AGENTS.md / CLAUDE.md 使用\n│   ├── doc-coauthoring/         # 文件共筆 workflow\n│   ├── prisma-*/                # Prisma ORM 慣例（cli、client-api、database-setup、postgres、driver-adapter）\n│   ├── karpathy-guidelines/     # Surgical change 與驗證紀律\n│   ├── session-handoff/         # (private, 未提交) 維護 ai-docs/tasks.md + session-log.md\n│   ├── svelte-code-writer/      # Svelte MCP/CLI 查詢與 autofix workflow\n│   └── svelte-core-bestpractices/\n├── .codex/                      # Codex AI configuration\n├── .github/workflows/ci.yml     # GitHub Actions：install、test、Codecov、SonarQube\n├── .husky/                      # Git hooks（pre-commit, commit-msg）\n├── .opencode/                   # OpenCode AI configuration\n├── .vscode/                     # VS Code settings + extension recommendations\n├── ai-docs/                     # AI task template、task plan、session log\n├── prisma/                      # Prisma schema + generated SQL migrations\n├── e2e/\n│   ├── expense.spec.ts          # Playwright login + transaction CRUD happy path\n│   └── sort.spec.ts             # Playwright 排序 + URL 狀態 e2e 檢查\n├── messages/                    # Paraglide source messages\n│   ├── en.json                  # 英文翻譯檔\n│   └── zh-tw.json               # 繁體中文翻譯檔\n├── src/\n│   ├── app.d.ts                 # SvelteKit app types（App.Locals.user）\n│   ├── app.html                 # HTML shell，包含 Paraglide lang/dir placeholders\n│   ├── hooks.server.ts          # Session lookup、locale middleware、theme class injection\n│   ├── lib/\n│   │   ├── assets/              # Favicon 與 README screenshots\n│   │   ├── components/          # CategoryChart, LocaleSwitcher, ThemeToggle, TransactionForm\n│   │   │   └── ui/              # 自建 Svelte 5 primitives：Button、ConfirmDialog、Field\n│   │   ├── server/\n│   │   │   ├── db/\n│   │   │   │   ├── admin.ts     # Admin-only 查詢（跨使用者統計資料）\n│   │   │   │   ├── audit.ts     # 稽核日誌查詢\n│   │   │   │   ├── index.ts     # 使用 DATABASE_URL 的 Prisma client（pg adapter）\n│   │   │   │   ├── queries.ts   # User-scoped CRUD + dashboard aggregates\n│   │   │   │   ├── schema.ts    # 由 generated Prisma client 衍生的 app-level 型別\n│   │   │   │   ├── schema.spec.ts\n│   │   │   │   └── seed.ts      # Demo users 與 transactions\n│   │   │   ├── auth.ts          # HMAC-signed httpOnly session cookie\n│   │   │   ├── guards.ts        # requireUser protected-route helper\n│   │   │   ├── login.ts         # Password-less email lookup\n│   │   │   ├── session.ts       # Cookie -\u003e database-backed SessionUser resolver\n│   │   │   ├── api.ts           # REST API 回應包裝與身分驗證守衛\n│   │   │   ├── rate-limit.ts    # 記憶體內 fixed-window 限流（登入 + API）\n│   │   │   ├── openapi.ts       # 動態從 Zod 產生 OpenAPI 3.1 規範\n│   │   │   ├── schemas.ts       # 共用的 Zod 定義 (表單與 API 共用)\n│   │   │   └── validation.ts    # Action 驗證邏輯，底層依賴 schemas.ts\n│   │   ├── table/               # TanStack 排序：與 URL 同步的 sorted-table store\n│   │   │   └── sorted-table.svelte.ts\n│   │   ├── categories.ts        # 固定 category keys + localized labels\n│   │   ├── constants.ts         # App name、demo email、pageTitle helper\n│   │   ├── date.ts              # YYYY-MM / YYYY-MM-DD helpers\n│   │   ├── index.ts             # lib barrel re-exports\n│   │   ├── money.ts             # TWD integer formatting/parsing\n│   │   ├── theme.svelte.ts      # Client theme store（light / dark / system）\n│   │   ├── theme.ts             # Server-safe theme constants and helpers\n│   │   └── transaction.ts       # Transaction form value types\n│   ├── routes/\n│   │   ├── admin/               # 管理員專用的 Governance 介面，顯示所有使用者的統計摘要\n│   │   ├── api/                 # REST endpoints\n│   │   │   ├── docs/            # Scalar API 參考文件 UI\n│   │   │   ├── openapi.json/    # 動態產生的 OpenAPI 3.1 規範\n│   │   │   ├── stats/           # 供儀表板使用的彙總 REST endpoint\n│   │   │   └── transactions/    # 用於交易紀錄 CRUD 的 REST endpoints\n│   │   ├── login/               # Password-less email sign-in page/action + route spec\n│   │   ├── logout/              # Sign-out action\n│   │   ├── transactions/\n│   │   │   ├── [id]/edit/       # Edit form load/action，含 ownership check\n│   │   │   ├── new/             # Create form load/action\n│   │   │   └── +page.*          # List/filter page + delete action\n│   │   ├── +layout.server.ts    # Auth guard 與所有頁面的 user data\n│   │   ├── +layout.svelte       # App shell、nav、locale/theme controls、logout form\n│   │   ├── +page.server.ts      # Dashboard monthly stats loader\n│   │   ├── +page.svelte         # Dashboard UI 與 pure-CSS category chart\n│   │   └── layout.css           # Tailwind v4 import 與 global styles\n│   └── *.spec.ts                # 與 source modules colocated 的 unit/integration specs\n├── static/\n│   ├── robots.txt               # 爬蟲規則 + sitemap 指令\n│   └── sitemap.xml              # 供搜尋引擎使用的公開 sitemap\n├── .env.example                 # DATABASE_URL + SESSION_SECRET template\n├── .mcp.json                    # Svelte MCP server registration\n├── .npmrc                       # pnpm/node package manager settings\n├── .oxfmtrc.json                # oxfmt formatter config\n├── .oxlintrc.json               # oxlint JS/TS lint rules\n├── AGENTS.md                    # 此 repo 的 AI agent instructions\n├── LICENSE                      # MIT license\n├── README.md                    # English README\n├── README-cht.md                # 繁體中文 README\n├── commitlint.config.mjs        # Conventional commit config\n├── compose.yaml                 # Local PostgreSQL service\n├── prisma.config.ts             # Prisma CLI config（schema 路徑 + datasource URL）\n├── eslint.config.js             # Svelte files 的 ESLint config\n├── package.json                 # Scripts、dependencies、lint-staged、engines\n├── playwright.config.ts         # Cross-browser e2e configuration\n├── pnpm-lock.yaml               # Locked dependency graph\n├── pnpm-workspace.yaml          # pnpm workspace 與 minimum-release-age policy\n├── project.inlang/              # Paraglide / inlang i18n 專案設定\n├── skills-lock.json             # Locked AI skill/plugin metadata\n├── sonar-project.properties     # SonarQube project configuration\n├── svelte.config.js             # SvelteKit config、Vercel adapter、forced runes mode\n├── tsconfig.json                # TypeScript config，extends generated SvelteKit config\n└── vite.config.ts               # Vite plugins：Tailwind、SvelteKit、Paraglide；Vitest config\n```\n\n---\n\n## 新世代工具採用\n\n這個專案會持續評估新興工具，並根據可量測的效益決定是否採用。\n\n### Oxlint（Rust-based Linter）\n\n| 面向        | 說明                                                            |\n| ----------- | --------------------------------------------------------------- |\n| Status      | **Production** — 已啟用 JS/TS linting                           |\n| Performance | 比 ESLint 快 50-100 倍                                          |\n| Scope       | ESLint 檢查 `.svelte`（基於內容雜湊快取）；JS/TS 由 oxlint 處理 |\n\n[Oxlint](https://oxc.rs/docs/guide/usage/linter.html)\n\n### Oxfmt（Rust-based Formatter）\n\n| 面向        | 說明                                                  |\n| ----------- | ----------------------------------------------------- |\n| Status      | **Production** — 格式化 JS/TS/CSS/HTML/JSON/MD/Svelte |\n| Performance | 約比 Prettier 快 30 倍，冷啟動幾乎即時                |\n| Scope       | 格式化所有支援的檔案，包含 `.svelte`                  |\n\n[Oxfmt](https://oxc.rs/docs/guide/usage/formatter)\n\n---\n\n## Live Demo Constraints\n\n| 面向         | 目前狀態                                                             | Production 建議               |\n| ------------ | -------------------------------------------------------------------- | ----------------------------- |\n| **Hosting**  | Vercel free tier                                                     | Paid tier / 多區域 deployment |\n| **Database** | Free-tier Neon                                                       | 根據地區優化的 DB             |\n| **Data**     | 預先建立的 Demo 資料；示範帳號由訪客共用，但每個帳號的資料仍彼此隔離 | 真實帳號隔離                  |\n\nDemo 使用免費等級以降低成本。Production 應根據真實使用者地區補上適當的地區性優化。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohn-data-chen%2Fsveltekit-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohn-data-chen%2Fsveltekit-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohn-data-chen%2Fsveltekit-starter-kit/lists"}