From 5569a2446c1a29d956473f8a98485a7f532053b9 Mon Sep 17 00:00:00 2001 From: ronload <91997734+ronload@users.noreply.github.com> Date: Tue, 14 Apr 2026 22:39:47 +0800 Subject: [PATCH 1/2] docs: add README, CONTRIBUTING, and MIT LICENSE --- CONTRIBUTING.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 21 +++++++++++++++ README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 164 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3ac110a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# 貢獻指南 + +感謝你有興趣參與 Zipkit 的開發！以下說明如何開始。 + +## 環境需求 + +- [Node.js](https://nodejs.org/) 20+ +- [pnpm](https://pnpm.io/) 10+ + +## 開始開發 + +```bash +# Fork 並 clone 專案 +git clone https://github.com//zipkit.git +cd zipkit + +# 安裝依賴 +pnpm install + +# 啟動開發伺服器 +pnpm dev +``` + +## 開發流程 + +1. 從 `main` 分支建立新分支，分支名稱應簡潔描述變更內容 +2. 進行修改 +3. 確認通過檢查： + ```bash + pnpm lint + pnpm format:check + pnpm build + ``` +4. 提交變更並推送至你的 fork +5. 建立 Pull Request + +## Commit 規範 + +本專案使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： + +``` +(): +``` + +常用 type： + +| Type | 說明 | +| --- | --- | +| `feat` | 新功能 | +| `fix` | 修復問題 | +| `refactor` | 重構（不影響功能） | +| `style` | 格式調整（不影響邏輯） | +| `build` | 建置系統或依賴變更 | +| `ci` | CI 設定變更 | +| `docs` | 文件更新 | + +## Pull Request 規範 + +- 標題簡潔明確，使用 Conventional Commits 格式 +- 說明變更的目的與做法 +- 確保 CI 檢查全部通過 + +## 程式碼風格 + +- TypeScript strict mode +- ESLint + Prettier 自動格式化 +- 提交前請執行 `pnpm lint` 和 `pnpm format:check` + +## 回報問題 + +如果發現 bug 或有功能建議，歡迎透過 [Issues](https://github.com/ronload/zipkit/issues) 回報。 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4f9dbc7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 LUO YONG NENG + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..53893a3 --- /dev/null +++ b/README.md @@ -0,0 +1,72 @@ +# Zipkit + +台灣地址英譯與 3+3 郵遞區號查詢工具。 + +輸入中文地址，即時取得 UPU 格式英譯地址與六碼郵遞區號。純前端運作，所有資料皆為預先產生的靜態 JSON，無需後端 API。 + +## 功能 + +- 縣市、鄉鎮市區、路街逐級選擇 +- 巷、弄、號、樓、室明細輸入 +- 即時產出英譯地址（UPU 格式） +- 六碼郵遞區號（3+3）查詢 +- 一鍵複製結果 + +## 技術棧 + +- [Next.js](https://nextjs.org/) 16 (App Router) +- [React](https://react.dev/) 19 +- [Tailwind CSS](https://tailwindcss.com/) 4 +- [shadcn/ui](https://ui.shadcn.com/) +- [TypeScript](https://www.typescriptlang.org/) 5 +- [pnpm](https://pnpm.io/) 套件管理 + +## 快速開始 + +```bash +# 安裝依賴 +pnpm install + +# 啟動開發伺服器 +pnpm dev +``` + +瀏覽器開啟 `http://localhost:3000` 即可使用。 + +## 指令 + +| 指令 | 說明 | +| --- | --- | +| `pnpm dev` | 啟動開發伺服器 | +| `pnpm build` | 正式環境建置 | +| `pnpm lint` | 執行 ESLint 檢查 | +| `pnpm format` | 格式化程式碼 | +| `pnpm etl` | 從原始資料重新產生靜態 JSON | + +## 專案結構 + +``` +src/ + app/ # Next.js App Router 頁面 + components/ # UI 元件 + hooks/ # React hooks（地址狀態管理） + lib/ # 工具函式（郵遞區號比對、資料載入） +scripts/ + etl.ts # ETL 資料轉換腳本 + raw/ # 原始郵政資料（不納入版本控制） +public/ + data/ # 預先產生的靜態 JSON +``` + +## 資料來源 + +本專案使用以下第三方開源資料： + +- **地址中英對照** -- [donma/TaiwanAddressCityAreaRoadChineseEnglishJSON](https://github.com/donma/TaiwanAddressCityAreaRoadChineseEnglishJSON) + 提供台灣縣市、鄉鎮市區、路街的中英文對照資料（`CityCountyData.json`、`AllData.json`）。 +- **3+3 郵遞區號範圍** -- [中華郵政 3+3 郵遞區號查詢](https://www.post.gov.tw/post/internet/Download/index.jsp?ID=2292) + 提供各地址區段對應的六碼郵遞區號範圍資料（`rall1.txt`）。 + +## 授權 + +本專案採用 [MIT License](LICENSE) 授權。 From 5a8844c502af57a403719dc104df421ab17cec42 Mon Sep 17 00:00:00 2001 From: ronload <91997734+ronload@users.noreply.github.com> Date: Tue, 14 Apr 2026 22:42:01 +0800 Subject: [PATCH 2/2] style(docs): format docs --- CONTRIBUTING.md | 18 +++++++++--------- README.md | 14 +++++++------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ac110a..21cd51a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,15 +44,15 @@ pnpm dev 常用 type： -| Type | 說明 | -| --- | --- | -| `feat` | 新功能 | -| `fix` | 修復問題 | -| `refactor` | 重構（不影響功能） | -| `style` | 格式調整（不影響邏輯） | -| `build` | 建置系統或依賴變更 | -| `ci` | CI 設定變更 | -| `docs` | 文件更新 | +| Type | 說明 | +| ---------- | ---------------------- | +| `feat` | 新功能 | +| `fix` | 修復問題 | +| `refactor` | 重構（不影響功能） | +| `style` | 格式調整（不影響邏輯） | +| `build` | 建置系統或依賴變更 | +| `ci` | CI 設定變更 | +| `docs` | 文件更新 | ## Pull Request 規範 diff --git a/README.md b/README.md index 53893a3..f926bbf 100644 --- a/README.md +++ b/README.md @@ -35,13 +35,13 @@ pnpm dev ## 指令 -| 指令 | 說明 | -| --- | --- | -| `pnpm dev` | 啟動開發伺服器 | -| `pnpm build` | 正式環境建置 | -| `pnpm lint` | 執行 ESLint 檢查 | -| `pnpm format` | 格式化程式碼 | -| `pnpm etl` | 從原始資料重新產生靜態 JSON | +| 指令 | 說明 | +| ------------- | --------------------------- | +| `pnpm dev` | 啟動開發伺服器 | +| `pnpm build` | 正式環境建置 | +| `pnpm lint` | 執行 ESLint 檢查 | +| `pnpm format` | 格式化程式碼 | +| `pnpm etl` | 從原始資料重新產生靜態 JSON | ## 專案結構