feat: 新增 OCRmyPDF 轉換引擎 (v0.1.14)
## 新功能 - OCRmyPDF 轉換引擎：將掃描版 PDF 轉換為可搜尋 PDF - 支援 7 種語言：en, zh-TW, zh, ja, ko, de, fr - 與 PDFMathTranslate 風格一致的 UI 格式 (pdf-<lang>) - 自動偵測頁面方向並旋轉 - 自動校正傾斜 - 跳過已有文字層的頁面 - 詳細的 5 階段處理進度輸出 ## 建置 - Dockerfile：安裝 ocrmypdf 與 Tesseract OCR 語言包 ## 文件 - 更新 OCR 功能文件 - 文件目錄結構改為中文名稱 ## 測試 - 修復 BabelDOC 和 PDFMathTranslate 測試的 OCR mock - 所有 345 個測試通過
This commit is contained in:
Your Name
parent
f24eec070c
commit
a06df23b1d
53 changed files with 1427 additions and 675 deletions
179
docs/開發指南/專案結構.md
Normal file
179
docs/開發指南/專案結構.md
Normal file
|
|
@ -0,0 +1,179 @@
|
|||
# 專案結構
|
||||
|
||||
本文件說明 ConvertX-CN 的程式碼結構與架構。
|
||||
|
||||
---
|
||||
|
||||
## 目錄結構
|
||||
|
||||
```
|
||||
ConvertX-CN/
|
||||
├── src/ # 前端原始碼
|
||||
│ ├── index.tsx # 主入口
|
||||
│ ├── main.css # 主樣式
|
||||
│ ├── components/ # React 元件
|
||||
│ ├── converters/ # 轉換器定義
|
||||
│ ├── db/ # 資料庫相關
|
||||
│ ├── helpers/ # 工具函數
|
||||
│ ├── i18n/ # 國際化
|
||||
│ ├── icons/ # 圖示元件
|
||||
│ ├── locales/ # 翻譯檔案
|
||||
│ ├── pages/ # 頁面元件
|
||||
│ ├── theme/ # 主題相關
|
||||
│ └── transfer/ # 檔案傳輸
|
||||
├── public/ # 靜態資源
|
||||
├── api-server/ # Rust API Server（選用）
|
||||
│ ├── src/ # Rust 原始碼
|
||||
│ ├── docs/ # API 文件
|
||||
│ └── tests/ # 測試
|
||||
├── docs/ # 文件
|
||||
├── tests/ # 測試
|
||||
├── scripts/ # 腳本
|
||||
├── data/ # 資料目錄（runtime）
|
||||
├── Dockerfile # Docker 建構檔
|
||||
├── compose.yaml # Docker Compose
|
||||
└── package.json # Node.js 依賴
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技術棧
|
||||
|
||||
### 前端
|
||||
|
||||
| 技術 | 用途 |
|
||||
| ----------- | -------- |
|
||||
| Bun | Runtime |
|
||||
| Elysia | Web 框架 |
|
||||
| React | UI 元件 |
|
||||
| TailwindCSS | 樣式 |
|
||||
| TypeScript | 類型安全 |
|
||||
|
||||
### 後端 (Web UI)
|
||||
|
||||
| 技術 | 用途 |
|
||||
| ------ | -------- |
|
||||
| Bun | Runtime |
|
||||
| Elysia | Web 框架 |
|
||||
| SQLite | 資料庫 |
|
||||
|
||||
### API Server（選用）
|
||||
|
||||
| 技術 | 用途 |
|
||||
| ------------- | -------- |
|
||||
| Rust | 語言 |
|
||||
| Axum | Web 框架 |
|
||||
| async-graphql | GraphQL |
|
||||
|
||||
---
|
||||
|
||||
## 核心模組
|
||||
|
||||
### src/converters/
|
||||
|
||||
定義所有轉換器的設定與格式支援。
|
||||
|
||||
```
|
||||
converters/
|
||||
├── main.ts # 轉換器主邏輯
|
||||
├── types.ts # 類型定義
|
||||
├── ffmpeg.ts # FFmpeg 設定
|
||||
├── imagemagick.ts # ImageMagick 設定
|
||||
├── libreoffice.ts # LibreOffice 設定
|
||||
├── pandoc.ts # Pandoc 設定
|
||||
├── calibre.ts # Calibre 設定
|
||||
└── ...
|
||||
```
|
||||
|
||||
### src/i18n/
|
||||
|
||||
國際化模組，支援 65 種語言。
|
||||
|
||||
```
|
||||
i18n/
|
||||
├── index.ts # i18n 初始化
|
||||
└── service.ts # 語言服務
|
||||
```
|
||||
|
||||
### src/locales/
|
||||
|
||||
翻譯檔案，每個語言一個 JSON 檔案。
|
||||
|
||||
```
|
||||
locales/
|
||||
├── en.json # 英文
|
||||
├── zh-TW.json # 繁體中文
|
||||
├── zh-CN.json # 簡體中文
|
||||
├── ja.json # 日文
|
||||
└── ...
|
||||
```
|
||||
|
||||
### src/transfer/
|
||||
|
||||
檔案傳輸模組，處理上傳與下載。
|
||||
|
||||
```
|
||||
transfer/
|
||||
├── upload.ts # 上傳邏輯
|
||||
├── download.ts # 下載邏輯
|
||||
└── chunked.ts # 分段傳輸
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Server 結構
|
||||
|
||||
```
|
||||
api-server/
|
||||
├── src/
|
||||
│ ├── main.rs # 入口
|
||||
│ ├── lib.rs # 模組定義
|
||||
│ ├── config.rs # 設定
|
||||
│ ├── auth.rs # JWT 認證
|
||||
│ ├── engine.rs # 引擎管理
|
||||
│ ├── conversion.rs# 轉換邏輯
|
||||
│ ├── rest.rs # REST API
|
||||
│ ├── graphql.rs # GraphQL API
|
||||
│ ├── models.rs # 資料模型
|
||||
│ └── error.rs # 錯誤處理
|
||||
├── tests/
|
||||
│ ├── api_tests.rs
|
||||
│ ├── graphql_tests.rs
|
||||
│ └── integration_tests.rs
|
||||
└── docs/
|
||||
├── API_SPEC.md
|
||||
└── ARCHITECTURE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 資料流
|
||||
|
||||
### 檔案轉換流程
|
||||
|
||||
```
|
||||
1. 使用者上傳檔案
|
||||
↓
|
||||
2. 儲存到 data/uploads/
|
||||
↓
|
||||
3. 呼叫對應轉換器
|
||||
↓
|
||||
4. 輸出到 data/output/
|
||||
↓
|
||||
5. 使用者下載結果
|
||||
```
|
||||
|
||||
### 檔案傳輸策略
|
||||
|
||||
| 檔案大小 | 傳輸方式 | 說明 |
|
||||
| -------- | -------- | ------------ |
|
||||
| ≤ 10MB | 直接傳輸 | 單一請求完成 |
|
||||
| > 10MB | 分段傳輸 | 5MB chunks |
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [本地開發](本地開發.md)
|
||||
- [貢獻指南](貢獻指南.md)
|
||||
- [測試策略](../測試/測試策略.md)
|
||||
207
docs/開發指南/本地開發.md
Normal file
207
docs/開發指南/本地開發.md
Normal file
|
|
@ -0,0 +1,207 @@
|
|||
# 本地開發
|
||||
|
||||
本文件說明如何在本地環境進行 ConvertX-CN 開發。
|
||||
|
||||
---
|
||||
|
||||
## 環境需求
|
||||
|
||||
- **Node.js** 20+ 或 **Bun** 1.0+
|
||||
- **Docker**（用於測試）
|
||||
- **Git**
|
||||
|
||||
### 可選
|
||||
|
||||
- **Rust** 1.75+（開發 API Server）
|
||||
- 轉換工具（FFmpeg、ImageMagick 等）
|
||||
|
||||
---
|
||||
|
||||
## 快速開始
|
||||
|
||||
### 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 run dev
|
||||
```
|
||||
|
||||
開啟 `http://localhost:3000`
|
||||
|
||||
---
|
||||
|
||||
## 開發工具
|
||||
|
||||
### 程式碼格式化
|
||||
|
||||
```bash
|
||||
# Prettier
|
||||
bun run format
|
||||
|
||||
# ESLint
|
||||
bun run lint
|
||||
```
|
||||
|
||||
### 類型檢查
|
||||
|
||||
```bash
|
||||
bun run typecheck
|
||||
```
|
||||
|
||||
### 建構
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 目錄說明
|
||||
|
||||
| 目錄 | 說明 |
|
||||
| ------------- | ---------- |
|
||||
| `src/` | 前端原始碼 |
|
||||
| `public/` | 靜態資源 |
|
||||
| `api-server/` | API Server |
|
||||
| `tests/` | 測試檔案 |
|
||||
| `docs/` | 文件 |
|
||||
| `scripts/` | 腳本 |
|
||||
|
||||
---
|
||||
|
||||
## 常見開發任務
|
||||
|
||||
### 新增轉換器
|
||||
|
||||
1. 在 `src/converters/` 建立新檔案
|
||||
2. 定義輸入/輸出格式
|
||||
3. 在 `src/converters/main.ts` 註冊
|
||||
|
||||
```typescript
|
||||
// src/converters/myconverter.ts
|
||||
export const myConverter: Converter = {
|
||||
id: "myconverter",
|
||||
name: "My Converter",
|
||||
inputFormats: ["abc", "xyz"],
|
||||
outputFormats: ["pdf", "txt"],
|
||||
convert: async (input, output, format) => {
|
||||
// 轉換邏輯
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 新增翻譯
|
||||
|
||||
1. 在 `src/locales/` 新增或修改翻譯檔
|
||||
2. 在 `src/i18n/index.ts` 註冊（如果是新語言）
|
||||
|
||||
```json
|
||||
// src/locales/xx.json
|
||||
{
|
||||
"title": "ConvertX-CN",
|
||||
"upload": "上傳",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### 修改樣式
|
||||
|
||||
TailwindCSS 設定在 `tailwind.config.js`。
|
||||
|
||||
```bash
|
||||
# 重新生成 CSS
|
||||
bun run build:css
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Server 開發
|
||||
|
||||
### 環境設定
|
||||
|
||||
```bash
|
||||
cd api-server
|
||||
```
|
||||
|
||||
### 建構
|
||||
|
||||
```bash
|
||||
cargo build
|
||||
```
|
||||
|
||||
### 執行
|
||||
|
||||
```bash
|
||||
cargo run
|
||||
```
|
||||
|
||||
### 測試
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker 開發
|
||||
|
||||
### 建構本地映像
|
||||
|
||||
```bash
|
||||
docker build -t convertx-cn-dev .
|
||||
```
|
||||
|
||||
### 使用本地映像
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx-cn-dev
|
||||
# ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 偵錯
|
||||
|
||||
### 前端偵錯
|
||||
|
||||
使用瀏覽器開發者工具（F12）。
|
||||
|
||||
### 後端偵錯
|
||||
|
||||
```bash
|
||||
# 詳細日誌
|
||||
DEBUG=* bun run dev
|
||||
```
|
||||
|
||||
### API Server 偵錯
|
||||
|
||||
```bash
|
||||
RUST_LOG=debug cargo run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [專案結構](project-structure.md)
|
||||
- [貢獻指南](contribution.md)
|
||||
- [測試策略](../testing/test-strategy.md)
|
||||
192
docs/開發指南/貢獻指南.md
Normal file
192
docs/開發指南/貢獻指南.md
Normal file
|
|
@ -0,0 +1,192 @@
|
|||
# 貢獻指南
|
||||
|
||||
感謝您有興趣貢獻 ConvertX-CN！本文件說明如何參與專案開發。
|
||||
|
||||
---
|
||||
|
||||
## 貢獻方式
|
||||
|
||||
### 🐛 回報問題
|
||||
|
||||
1. 前往 [GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues)
|
||||
2. 點擊 "New Issue"
|
||||
3. 選擇適當的 Issue 模板
|
||||
4. 填寫詳細資訊
|
||||
|
||||
### 💡 功能建議
|
||||
|
||||
1. 先搜尋是否已有類似提議
|
||||
2. 開一個新的 Issue 說明您的想法
|
||||
3. 等待討論與回饋
|
||||
|
||||
### 🔧 提交程式碼
|
||||
|
||||
1. Fork 專案
|
||||
2. 建立功能分支
|
||||
3. 進行修改
|
||||
4. 提交 Pull Request
|
||||
|
||||
---
|
||||
|
||||
## 開發流程
|
||||
|
||||
### 1. Fork 與 Clone
|
||||
|
||||
```bash
|
||||
# Fork 專案後
|
||||
git clone https://github.com/YOUR_USERNAME/ConvertX-CN.git
|
||||
cd ConvertX-CN
|
||||
```
|
||||
|
||||
### 2. 建立分支
|
||||
|
||||
```bash
|
||||
# 功能分支
|
||||
git checkout -b feature/my-feature
|
||||
|
||||
# 修復分支
|
||||
git checkout -b fix/bug-description
|
||||
```
|
||||
|
||||
### 3. 安裝依賴
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
### 4. 進行修改
|
||||
|
||||
遵循現有的程式碼風格與結構。
|
||||
|
||||
### 5. 測試
|
||||
|
||||
```bash
|
||||
# 執行測試
|
||||
bun run test
|
||||
|
||||
# 檢查格式
|
||||
bun run lint
|
||||
bun run format:check
|
||||
```
|
||||
|
||||
### 6. 提交
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: add new feature"
|
||||
```
|
||||
|
||||
### 7. 推送與 PR
|
||||
|
||||
```bash
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
|
||||
然後在 GitHub 上建立 Pull Request。
|
||||
|
||||
---
|
||||
|
||||
## Commit 訊息規範
|
||||
|
||||
使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：
|
||||
|
||||
| 類型 | 說明 |
|
||||
| -------- | ------------------ |
|
||||
| feat | 新功能 |
|
||||
| fix | 修復 Bug |
|
||||
| docs | 文件修改 |
|
||||
| style | 格式調整 |
|
||||
| refactor | 重構 |
|
||||
| test | 測試相關 |
|
||||
| chore | 雜項（建構、工具） |
|
||||
|
||||
**範例：**
|
||||
|
||||
```
|
||||
feat: add Japanese OCR support
|
||||
fix: resolve login redirect issue
|
||||
docs: update deployment guide
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 程式碼規範
|
||||
|
||||
### TypeScript
|
||||
|
||||
- 使用 ESLint 與 Prettier
|
||||
- 類型定義盡量明確
|
||||
- 避免 `any`
|
||||
|
||||
### Rust（API Server）
|
||||
|
||||
- 使用 `rustfmt` 格式化
|
||||
- 使用 `clippy` 檢查
|
||||
|
||||
### 文件
|
||||
|
||||
- 使用 Markdown
|
||||
- 繁體中文為主
|
||||
|
||||
---
|
||||
|
||||
## Pull Request 指南
|
||||
|
||||
### PR 標題
|
||||
|
||||
使用 Conventional Commits 格式。
|
||||
|
||||
### PR 描述
|
||||
|
||||
- 說明修改的目的
|
||||
- 列出主要變更
|
||||
- 附上相關 Issue 連結
|
||||
|
||||
### 檢查清單
|
||||
|
||||
- [ ] 已測試功能正常
|
||||
- [ ] 已通過 lint 檢查
|
||||
- [ ] 已更新相關文件（如需要）
|
||||
- [ ] Commit 訊息符合規範
|
||||
|
||||
---
|
||||
|
||||
## 貢獻領域
|
||||
|
||||
### 歡迎的貢獻
|
||||
|
||||
- 🐛 Bug 修復
|
||||
- 🌐 翻譯改進
|
||||
- 📖 文件完善
|
||||
- ✨ 新功能
|
||||
- ⚡ 效能優化
|
||||
- 🧪 測試覆蓋
|
||||
|
||||
### 貢獻翻譯
|
||||
|
||||
1. 複製 `src/locales/en.json`
|
||||
2. 重命名為語言代碼 `xx.json`
|
||||
3. 翻譯所有文字
|
||||
4. 在 `src/i18n/index.ts` 註冊
|
||||
5. 提交 PR
|
||||
|
||||
---
|
||||
|
||||
## 社群
|
||||
|
||||
- 📝 [GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues)
|
||||
- 💬 [GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions)
|
||||
|
||||
---
|
||||
|
||||
## 行為準則
|
||||
|
||||
請遵守 [Contributor Covenant](https://www.contributor-covenant.org/) 行為準則。
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [專案結構](專案結構.md)
|
||||
- [本地開發](本地開發.md)
|
||||
- [測試策略](../測試/測試策略.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue