394dcbec1a
- Updated tables for service ports, environment variables, HTTP status codes, and error codes to enhance readability. - Streamlined JavaScript examples for file conversion and added comments for better understanding. - Enhanced troubleshooting section with clearer formatting and additional explanations. - Improved licensing section with detailed requirements and third-party component licenses. - Organized the document structure for better navigation and accessibility.
459 lines
9.1 KiB
Markdown
459 lines
9.1 KiB
Markdown
# 開發與貢獻指南
|
||
|
||
歡迎參與 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 格式
|
||
|
||
```
|
||
<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
|
||
```
|
||
|
||
### 提交前檢查
|
||
|
||
```bash
|
||
# 執行 Linter
|
||
bun lint
|
||
|
||
# 執行測試
|
||
bun test
|
||
|
||
# 格式化程式碼
|
||
bun format
|
||
```
|
||
|
||
---
|
||
|
||
## Pull Request 流程
|
||
|
||
### 提交 PR 前
|
||
|
||
1. 確保程式碼通過所有測試
|
||
2. 確保程式碼符合風格規範
|
||
3. 更新相關文件
|
||
4. 撰寫清楚的 PR 描述
|
||
|
||
### PR 範本
|
||
|
||
```markdown
|
||
## 變更描述
|
||
|
||
簡述這個 PR 做了什麼。
|
||
|
||
## 變更類型
|
||
|
||
- [ ] 新功能
|
||
- [ ] Bug 修復
|
||
- [ ] 文件更新
|
||
- [ ] 重構
|
||
- [ ] 其他
|
||
|
||
## 測試
|
||
|
||
描述如何測試這些變更。
|
||
|
||
## 相關 Issue
|
||
|
||
Closes #123
|
||
|
||
## 截圖（如適用）
|
||
```
|
||
|
||
### 審核流程
|
||
|
||
1. 提交 PR 到 `develop` 分支
|
||
2. 等待 CI 通過
|
||
3. 請求 Review
|
||
4. 根據回饋修改
|
||
5. 合併
|
||
|
||
---
|
||
|
||
## 程式碼風格
|
||
|
||
### TypeScript / JavaScript
|
||
|
||
使用 Biome 進行 Linting 和格式化：
|
||
|
||
```bash
|
||
# 檢查
|
||
bun lint
|
||
|
||
# 格式化
|
||
bun format
|
||
```
|
||
|
||
### 主要規範
|
||
|
||
- 使用 2 空格縮排
|
||
- 使用單引號
|
||
- 不使用分號（除非必要）
|
||
- 使用 `const` / `let`，避免 `var`
|
||
- 使用箭頭函數
|
||
|
||
### 範例
|
||
|
||
```typescript
|
||
// ✅ 正確
|
||
const formatConverter = (name: string): string => {
|
||
return name.toLowerCase();
|
||
};
|
||
|
||
// ❌ 錯誤
|
||
function formatConverter(name) {
|
||
return name.toLowerCase();
|
||
}
|
||
```
|
||
|
||
### Rust
|
||
|
||
遵循 Rust 官方風格指南：
|
||
|
||
```bash
|
||
cargo fmt --check
|
||
cargo clippy
|
||
```
|
||
|
||
---
|
||
|
||
## 新增轉換器
|
||
|
||
### 步驟
|
||
|
||
1. 在 `src/converters/` 建立新檔案
|
||
|
||
2. 定義轉換器：
|
||
|
||
```typescript
|
||
// 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) => {
|
||
// 轉換邏輯
|
||
},
|
||
};
|
||
```
|
||
|
||
3. 在 `src/converters/main.ts` 註冊
|
||
|
||
4. 新增測試
|
||
|
||
5. 更新文件
|
||
|
||
---
|
||
|
||
## 國際化
|
||
|
||
### 新增翻譯
|
||
|
||
1. 在 `src/locales/` 找到對應語言檔案
|
||
|
||
2. 新增翻譯字串：
|
||
|
||
```json
|
||
{
|
||
"converter.newFeature": "新功能說明"
|
||
}
|
||
```
|
||
|
||
3. 在所有語言檔案中新增相同的 Key
|
||
|
||
### 新增語言
|
||
|
||
1. 在 `src/locales/` 建立新的語言檔案
|
||
|
||
2. 在 `src/i18n/index.ts` 註冊新語言
|
||
|
||
---
|
||
|
||
## 發布流程
|
||
|
||
### 版本號規則
|
||
|
||
遵循 [Semantic Versioning](https://semver.org/)：
|
||
|
||
- `MAJOR.MINOR.PATCH`
|
||
- MAJOR：不相容的 API 變更
|
||
- MINOR：向下相容的新功能
|
||
- PATCH：向下相容的 Bug 修復
|
||
|
||
### 發布步驟
|
||
|
||
1. 更新 `CHANGELOG.md`
|
||
2. 更新版本號
|
||
3. 建立 Release Tag
|
||
4. CI 自動建構並發布 Docker Image
|
||
|
||
---
|
||
|
||
[⬆️ 回到頂部](#開發與貢獻指南) | [📚 回到目錄](00-專案總覽.md)
|