Your Name 394dcbec1a Refactor documentation for improved clarity and consistency

- 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.

2026-01-25 16:10:07 +08:00

9.1 KiB

Raw Blame History

開發與貢獻指南

歡迎參與 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 註冊新語言

發布流程

版本號規則

遵循 Semantic Versioning：

MAJOR.MINOR.PATCH
MAJOR：不相容的 API 變更
MINOR：向下相容的新功能
PATCH：向下相容的 Bug 修復

發布步驟

更新 CHANGELOG.md
更新版本號
建立 Release Tag
CI 自動建構並發布 Docker Image

9.1 KiB Raw Blame History Unescape Escape

開發與貢獻指南

目錄

專案結構

技術棧

前端 / Web Server

API Server（選用）

本地開發環境

前置需求

設定步驟

開發指令

API Server 開發

分支策略

主要分支

功能分支

分支命名規範

測試流程

測試類型

執行測試

測試覆蓋率

新增測試

提交規範

Commit Message 格式

Type 類型

範例

提交前檢查

Pull Request 流程

提交 PR 前

PR 範本

審核流程

程式碼風格

TypeScript / JavaScript

主要規範

範例

Rust

新增轉換器

步驟

國際化

新增翻譯

新增語言

發布流程

版本號規則

發布步驟

9.1 KiB

Raw Blame History