# 開發與貢獻指南 歡迎參與 ConvertX-CN 的開發！本文件說明專案結構、開發流程與貢獻規範。 --- ## 目錄 - [專案結構](#專案結構) - [本地開發環境](#本地開發環境) - [分支策略](#分支策略) - [測試流程](#測試流程) - [提交規範](#提交規範) - [Pull Request 流程](#pull-request-流程) - [程式碼風格](#程式碼風格) --- ## 專案結構 ``` 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 ### 設定步驟 1. **Clone 專案** ```bash git clone https://github.com/pi-docket/ConvertX-CN.git cd ConvertX-CN ``` 2. **安裝依賴** ```bash # 使用 Bun bun install # 或使用 npm npm install ``` 3. **啟動開發伺服器** ```bash bun dev ``` 4. **開啟瀏覽器** 訪問 `http://localhost:3000` ### 開發指令 | 指令 | 說明 | |------|------| | `bun dev` | 啟動開發伺服器（熱重載） | | `bun build` | 建構生產版本 | | `bun test` | 執行測試 | | `bun lint` | 執行 Linter | | `bun format` | 格式化程式碼 | ### API Server 開發 ```bash cd api-server cargo run ``` --- ## 分支策略 ### 主要分支 | 分支 | 用途 | |------|------| | `main` | 穩定版本，用於發布 | | `develop` | 開發分支，接受 PR | ### 功能分支 建立新功能時，從 `develop` 分支建立： ```bash 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/` | 端對端測試 | ### 執行測試 ```bash # 執行所有測試 bun test # 執行特定測試 bun test tests/converters/ # 執行 E2E 測試 bun run test:e2e ``` ### 測試覆蓋率 ```bash bun test --coverage ``` ### 新增測試 為新功能撰寫測試： ```typescript // 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 格式 ``` ():