Skip to content

README.md

Latest commit

 

History

History
313 lines (226 loc) · 12.4 KB

README.md

File metadata and controls

313 lines (226 loc) · 12.4 KB

haotool Apps

Modern React Applications Monorepo

CI License: GPL-3.0 TypeScript React Vite pnpm

English · 繁體中文

繁體中文

專案概述

haotool Apps 是一個專業的 pnpm Monorepo，包含多個高品質的 React 19 應用程式。所有應用程式共享統一的工程標準、CI/CD 管線和開發工具鏈。

「HAO」取自中文「好」的拼音，我們的核心理念是打造真正的「好工具」。

應用程式

應用 描述 狀態 連結
RateWise 台銀即時匯率換算 PWA，支援 18 種貨幣 Live app.haotool.org/ratewise
NihonName 日本名字產生器，探索皇民化歷史 Live app.haotool.org/nihonname
Quake-School 互動式地震科學教育平台 Live app.haotool.org/quake-school
Park Keeper 停車場導航工具，GPS 指引 + 多語言（i18n） Live app.haotool.org/park-keeper
Split Meow 貓咪主題旅遊帳單分攤計算機，支援費用分類與分享 Live app.haotool.org/split-meow
haotool 專案展示平台，3D 互動首頁 Live app.haotool.org

應用特色

RateWise - 匯率好工具

基於臺灣銀行牌告匯率的即時匯率 PWA 應用，顯示實際買賣價（非中間價）

  • 台銀實際賣出價：顯示真正換匯成本，非市場中間價
  • 18 種貨幣、4 種匯率類型（現金/即期買入賣出）
  • 即時匯率：每 5 分鐘同步臺灣銀行牌告匯率
  • 趨勢圖表：30 天歷史匯率走勢視覺化
  • PWA 支援：可安裝至手機，支援離線使用
  • 收藏管理：自訂常用貨幣快速存取
  • 程序化 SEO：249 個可索引 SEO path（幣對頁 + 金額頁）

NihonName - 皇民化改姓生成器

探索 1940 年代台灣皇民化運動的歷史改姓對照

  • 姓名變換所：查詢歷史上的日式改姓對照
  • 歷史專區：皇民化運動、馬關條約、舊金山和約
  • 諧音梗名字：500+ 趣味諧音日本名
  • 和紙質感 UI：日式傳統美學設計

Quake-School - 地震知識小學堂

互動式地震科學教育網站

  • 地震模擬器：互動式調整規模與深度，即時視覺化影響
  • 分級課程：幼兒園到進階程度的地震知識
  • 知識測驗：互動問答測驗，驗證學習成效
  • 震度視覺化：台灣震度分級圖表
  • 地震波動畫：P 波、S 波視覺化展示

Park Keeper - 停車場導航

GPS 輔助的停車場路徑指引工具

  • GPS 即時定位：指引回到停車位的方向與步數
  • 羅盤導航：設備方向感測器驅動的視覺化方向指示
  • 多語言支援：繁體中文、英文、日文（i18n）
  • Leaflet 地圖整合：停車紀錄與地圖標記

Split Meow - 分帳計算機

貓咪主題的旅遊帳單分攤工具

  • 費用分類標籤：Emoji 分類（餐飲、交通、住宿等）
  • 行程摘要分享：Web Share API + 剪貼簿備援
  • 貓咪互動夥伴：爪印粒子效果 + 慶祝動畫
  • 結清標記：追蹤已結算費用

haotool - 專案平台

3D 互動展示平台，介紹所有專案

  • Three.js 3D 效果：沉浸式視覺體驗
  • 響應式設計：完美適配各種裝置
  • 極致效能：Lighthouse 95+ 全類別

技術棧

類別 技術
框架 React 19.2 + TypeScript 5.9
建置工具 Vite 8.0 + vite-react-ssg
樣式 Tailwind CSS 3.4
測試 Vitest 4.1 + Playwright 1.57
套件管理 pnpm 9.10.0 (Monorepo)
CI/CD GitHub Actions (9 workflows)
部署 Docker + Zeabur / Vercel
安全 Gitleaks CLI + Trivy + SARIF

品質指標

指標 數值
測試數量 1700+
測試覆蓋率 92%+
TypeScript Strict Mode
ESLint 0 警告
Lighthouse 95+ 全類別
CI 管線 9 個 workflow

快速開始

環境需求

  • Node.js: >= 24.0.0
  • pnpm: >= 9.10.0

安裝與開發

# 複製儲存庫
git clone https://github.com/haotool/app.git
cd app

# 安裝依賴
pnpm install

# 啟動所有應用開發模式
pnpm dev

# 或啟動特定應用
pnpm --filter @app/ratewise dev      # RateWise (http://localhost:4173)
pnpm --filter @app/nihonname dev     # NihonName (http://localhost:3002)
pnpm --filter @app/quake-school dev  # Quake-School (http://localhost:3003)
pnpm --filter @app/park-keeper dev   # Park Keeper (http://localhost:3004)
pnpm --filter @app/split-meow dev    # Split Meow (http://localhost:3005)
pnpm --filter @app/haotool dev       # haotool (http://localhost:3000)

建置與測試

# 建置所有應用
pnpm build

# 執行測試
pnpm test

# TypeScript 檢查
pnpm typecheck

# ESLint 檢查
pnpm lint

版本與發版

# 每個 PR 都要建立 changeset，描述使用者可見影響
pnpm changeset

# release PR 由 GitHub Actions 自動建立
pnpm changeset:status

Release workflow 以 pnpm changeset:version 作為版本 SSOT，並由 scripts/get-release-metadata.mjs --changed 產生 release tag 與 GitHub release 清單。禁止手動修改版本號、手動編輯 CHANGELOG，或在 CI 內直接呼叫 pnpm changeset tag 建 tag；CI 內部 tag push 會以 HUSKY=0 單次推送，避免重複觸發 pre-push hook。

正式站部署由 Zeabur production deployment 接 GitHub main。合併一般 PR 後若會再合併 changesets release PR，需先確認較早的 production deployment 已完成，避免舊 SHA 在 release SHA 之後才變成 active，造成正式站版本回退。Release 後以 app-version、GitHub deployment status 與 live precache 驗證作為完成證據。

專案結構

haotool-app/
├── apps/
│   ├── ratewise/         # 匯率換算工具
│   ├── nihonname/        # 日本名字產生器
│   ├── quake-school/     # 地震知識小學堂
│   ├── park-keeper/      # 停車場導航工具
│   ├── split-meow/       # 貓咪分帳計算機
│   ├── haotool/          # 專案展示平台
│   └── shared/           # 共用模組
├── docs/                 # 文檔
├── scripts/              # 自動化腳本
├── .github/
│   └── workflows/        # CI/CD 管線
│       ├── ci.yml                      # 主要 CI 流程
│       ├── release.yml                 # 版本發布
│       ├── seo-audit.yml               # SEO 審查
│       ├── seo-production.yml          # 生產環境 SEO
│       ├── update-committed-seo-files.yml # SEO 產出物同步
│       ├── update-historical-rates.yml # 歷史匯率更新
│       ├── update-latest-rates.yml     # 最新匯率更新
│       ├── update-moneybox-rates.yml   # MoneyBox 匯率更新
│       └── update-seo-rate-examples.yml # SEO 範例匯率更新
├── package.json          # Monorepo 根配置
├── pnpm-workspace.yaml   # pnpm workspace 配置
└── tsconfig.base.json    # 共用 TypeScript 配置

文檔

文檔 描述
AGENTS.md Agent 工具與工作流程
LINUS_GUIDE.md Linus 風格開發指南
CONTRIBUTING.md 貢獻指南
CODE_OF_CONDUCT.md 行為準則
SECURITY.md 安全政策
COMMIT_CONVENTION.md 提交規範

貢獻

歡迎提交 Issue 和 Pull Request！請先閱讀 貢獻指南。

授權

本專案採用 GPL-3.0 授權。

團隊

English

Overview

haotool Apps is a professional pnpm Monorepo containing multiple high-quality React 19 applications. All applications share unified engineering standards, CI/CD pipelines, and development toolchains.

"HAO" comes from the Chinese word "好" (good). Our core philosophy is to build truly good tools.

Applications

App Description Status Link
RateWise Taiwan Bank exchange rate PWA, 18 currencies Live app.haotool.org/ratewise
NihonName Japanese name generator, historical exploration Live app.haotool.org/nihonname
Quake-School Interactive earthquake science education Live app.haotool.org/quake-school
Park Keeper Parking lot navigator with GPS compass + i18n Live app.haotool.org/park-keeper
Split Meow Cat-themed trip expense splitter with share + emoji Live app.haotool.org/split-meow
haotool Project showcase with 3D interactive homepage Live app.haotool.org

Tech Stack

  • Framework: React 19.2 + TypeScript 5.9
  • Build: Vite 8.0 + vite-react-ssg
  • Styling: Tailwind CSS 3.4
  • Testing: Vitest 4.1 + Playwright 1.57
  • Package Manager: pnpm 9.10.0 (Monorepo)
  • CI/CD: GitHub Actions (9 workflows)
  • Deployment: Docker + Zeabur / Vercel
  • Security: Gitleaks CLI + Trivy + SARIF

Quick Start

# Clone repository
git clone https://github.com/haotool/app.git
cd app

# Install dependencies
pnpm install

# Start development
pnpm dev

Release

Every PR must include a changeset. GitHub Actions creates the release PR with pnpm changeset:version; release tags and GitHub releases are generated from scripts/get-release-metadata.mjs --changed.

Production is deployed by Zeabur from GitHub main. Before merging a release PR right after another main PR, confirm the earlier production deployment has finished so an older SHA cannot become active after the release SHA.

License

This project is licensed under GPL-3.0.

Built with ❤️ by haotool

Website · GitHub · Threads