新增錯誤排查與支援文件，提供常見問題解決方案；新增開發與貢獻指南，說明專案結構與開發流程；新增授權說明文件，詳述AGPL-3.0授權條款及第三方元件使用情況。
This commit is contained in:
Your Name
parent
11d751250b
commit
caecb2e001
13 changed files with 3269 additions and 369 deletions
455
docs/07-開發與貢獻指南.md
Normal file
455
docs/07-開發與貢獻指南.md
Normal file
|
|
@ -0,0 +1,455 @@
|
|||
# 開發與貢獻指南
|
||||
|
||||
歡迎參與 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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue