8.4 KiB
8.4 KiB
開發與貢獻指南
歡迎參與 ConvertX-CN 的開發！本文件說明專案結構、開發流程與貢獻規範。
目錄
專案結構
ConvertX-CN/
├── src/ # 前端原始碼
│ ├── index.tsx # 主入口
│ ├── main.css # 主樣式
│ ├── components/ # React 元件
│ ├── converters/ # 轉換器定義
│ ├── db/ # 資料庫相關
│ ├── helpers/ # 工具函數
│ ├── i18n/ # 國際化
│ ├── icons/ # 圖示元件
│ ├── locales/ # 翻譯檔案
│ ├── pages/ # 頁面元件
│ ├── theme/ # 主題相關
│ └── transfer/ # 檔案傳輸
│
├── api-server/ # Rust API Server（選用）
│ ├── src/ # Rust 原始碼
│ │ ├── main.rs # 入口點
│ │ ├── auth.rs # 認證模組
│ │ ├── config.rs # 設定模組
│ │ ├── conversion.rs # 轉換邏輯
│ │ ├── graphql.rs # GraphQL 端點
│ │ └── rest.rs # REST 端點
│ ├── docs/ # API 文件
│ └── tests/ # 測試
│
├── docs/ # 專案文件
├── tests/ # 測試
│ ├── converters/ # 轉換器測試
│ ├── e2e/ # 端對端測試
│ └── transfer/ # 傳輸測試
│
├── scripts/ # 腳本
│ ├── download-models.sh # 下載模型
│ ├── install-fonts.sh # 安裝字型
│ └── verify-*.sh # 驗證腳本
│
├── public/ # 靜態資源
├── data/ # 資料目錄（runtime）
│
├── Dockerfile # 一般版建構檔
├── Dockerfile.lite # Lite 版建構檔
├── Dockerfile.full # Full 版建構檔
├── compose.yaml # Docker Compose
├── package.json # Node.js 依賴
├── tsconfig.json # TypeScript 設定
└── biome.json # Linter 設定
技術棧
前端 / Web Server
| 技術 | 用途 |
|---|---|
| Bun | JavaScript Runtime |
| Elysia | Web 框架 |
| React | UI 元件 |
| TailwindCSS | 樣式框架 |
| TypeScript | 類型安全 |
| SQLite | 資料庫 |
API Server（選用）
| 技術 | 用途 |
|---|---|
| Rust | 語言 |
| Axum | Web 框架 |
| async-graphql | GraphQL |
| tokio | 非同步運行時 |
本地開發環境
前置需求
- Node.js 20+ 或 Bun 1.0+
- Docker（用於測試）
- Git
設定步驟
-
Clone 專案
git clone https://github.com/pi-docket/ConvertX-CN.git cd ConvertX-CN -
安裝依賴
# 使用 Bun bun install # 或使用 npm npm install -
啟動開發伺服器
bun dev -
開啟瀏覽器
訪問
http://localhost:3000
開發指令
| 指令 | 說明 |
|---|---|
bun dev |
啟動開發伺服器（熱重載） |
bun build |
建構生產版本 |
bun test |
執行測試 |
bun lint |
執行 Linter |
bun format |
格式化程式碼 |
API Server 開發
cd api-server
cargo run
分支策略
主要分支
| 分支 | 用途 |
|---|---|
main |
穩定版本，用於發布 |
develop |
開發分支，接受 PR |
功能分支
建立新功能時，從 develop 分支建立：
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name
分支命名規範
| 類型 | 格式 | 範例 |
|---|---|---|
| 功能 | feature/描述 |
feature/add-pdf-watermark |
| 修復 | fix/描述 |
fix/login-redirect-issue |
| 文件 | docs/描述 |
docs/update-api-docs |
| 重構 | refactor/描述 |
refactor/improve-converter-perf |
測試流程
測試類型
| 類型 | 位置 | 說明 |
|---|---|---|
| 單元測試 | tests/ |
測試個別函數 |
| 整合測試 | tests/converters/ |
測試轉換器 |
| E2E 測試 | tests/e2e/ |
端對端測試 |
執行測試
# 執行所有測試
bun test
# 執行特定測試
bun test tests/converters/
# 執行 E2E 測試
bun run test:e2e
測試覆蓋率
bun test --coverage
新增測試
為新功能撰寫測試：
// tests/converters/ffmpeg.test.ts
import { describe, it, expect } from 'bun:test';
import { convertVideo } from '@/converters/ffmpeg';
describe('FFmpeg Converter', () => {
it('should convert MP4 to WebM', async () => {
const result = await convertVideo('input.mp4', 'webm');
expect(result.success).toBe(true);
});
});
提交規範
Commit Message 格式
<type>(<scope>): <subject>
<body>
<footer>
Type 類型
| Type | 說明 |
|---|---|
feat |
新功能 |
fix |
修復 Bug |
docs |
文件更新 |
style |
程式碼風格（不影響功能） |
refactor |
重構（不新增功能或修復） |
perf |
效能優化 |
test |
新增或修改測試 |
chore |
建構或輔助工具變動 |
範例
feat(converter): 新增 AVIF 格式支援
- 在 ImageMagick 轉換器新增 AVIF 輸入/輸出
- 更新格式支援列表
Closes #123
fix(auth): 修復登入後重導向問題
當 HTTP_ALLOWED=false 且使用 HTTP 存取時，
Cookie 無法正確設定導致登入失敗。
修復方式：在設定 Cookie 前檢查協議。
Fixes #456
提交前檢查
# 執行 Linter
bun lint
# 執行測試
bun test
# 格式化程式碼
bun format
Pull Request 流程
提交 PR 前
- 確保程式碼通過所有測試
- 確保程式碼符合風格規範
- 更新相關文件
- 撰寫清楚的 PR 描述
PR 範本
## 變更描述
簡述這個 PR 做了什麼。
## 變更類型
- [ ] 新功能
- [ ] Bug 修復
- [ ] 文件更新
- [ ] 重構
- [ ] 其他
## 測試
描述如何測試這些變更。
## 相關 Issue
Closes #123
## 截圖（如適用）
審核流程
- 提交 PR 到
develop分支 - 等待 CI 通過
- 請求 Review
- 根據回饋修改
- 合併
程式碼風格
TypeScript / JavaScript
使用 Biome 進行 Linting 和格式化：
# 檢查
bun lint
# 格式化
bun format
主要規範
- 使用 2 空格縮排
- 使用單引號
- 不使用分號（除非必要）
- 使用
const/let，避免var - 使用箭頭函數
範例
// ✅ 正確
const formatConverter = (name: string): string => {
return name.toLowerCase()
}
// ❌ 錯誤
function formatConverter(name) {
return name.toLowerCase();
}
Rust
遵循 Rust 官方風格指南：
cargo fmt --check
cargo clippy
新增轉換器
步驟
-
在
src/converters/建立新檔案 -
定義轉換器：
// src/converters/myconverter.ts import { Converter } from './types' export const myConverter: Converter = { name: 'myconverter', inputFormats: ['xyz', 'abc'], outputFormats: ['pdf', 'png'], convert: async (input, output, options) => { // 轉換邏輯 } } -
在
src/converters/main.ts註冊 -
新增測試
-
更新文件
國際化
新增翻譯
-
在
src/locales/找到對應語言檔案 -
新增翻譯字串：
{ "converter.newFeature": "新功能說明" } -
在所有語言檔案中新增相同的 Key
新增語言
-
在
src/locales/建立新的語言檔案 -
在
src/i18n/index.ts註冊新語言
發布流程
版本號規則
MAJOR.MINOR.PATCH- MAJOR：不相容的 API 變更
- MINOR：向下相容的新功能
- PATCH：向下相容的 Bug 修復
發布步驟
- 更新
CHANGELOG.md - 更新版本號
- 建立 Release Tag
- CI 自動建構並發布 Docker Image