Initial commit: FoFreeXit Phase 1 (Viewer) + Phase 2 (Annotate)

PDF viewer (render/search/text-select/thumbnails/outline) and annotation engine (Highlight/Underline/Strikeout/Square/FreeText/Note) over PDFium + lopdf, with Unicode font embedding for Vietnamese text and undo/redo.
2026-06-17 22:34:06 +07:00
commit 274012f854
52 changed files with 28479 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 04 — Kiến trúc kỹ thuật (khung — sẽ chi tiết hoá sau khi chốt stack)
+
+> Tài liệu này sẽ được hoàn thiện ở đầu Phase 1, sau khi đã chốt ngôn ngữ/framework ở [02-tech-stack.md](02-tech-stack.md).
+
+## Mô hình 2 tầng (học từ Adobe COS/PD và Apache PDFBox)
+
+- **`cos` (Carousel Object System)** — tầng object thấp: `Object`, `Dictionary`, `Array`, `Stream`, `Name`, `Ref`, `XRef`. Đọc/ghi cấu trúc file PDF thô. (Chủ yếu tựa QPDF.)
+- **`pdmodel`** — tầng tài liệu cao: `Document`, `Page`, `Resources`, `ContentStream`, `TextRun`, `ImageObject`, `PathObject`, `Annotation`, `AcroForm`, `Field`. (Tựa PDFium + logic riêng.)
+
+## Các module chính
+- `engine/render` — bọc PDFium render (tile, cache, đa luồng).
+- `engine/text` — gom glyph → run/line/paragraph; chọn/copy; tìm kiếm.
+- `engine/edit` — Page Object Model; sửa text/object; serialize content stream.
+- `engine/font` — FreeType + HarfBuzz: đo width, shaping, subset, substitution.
+- `engine/io` — mở/lưu (incremental + full rewrite via QPDF), repair, linearize, encrypt.
+- `engine/annot` — annotation CRUD + XFDF.
+- `engine/security` — mã hoá, redaction, chữ ký số (PAdES).
+- `engine/form` — AcroForm điền/tạo/flatten.
+- `engine/ocr` — Tesseract + tiền xử lý + tạo lớp text.
+- `engine/convert` — cầu nối LibreOffice headless; PDF→ảnh; PDF→Office.
+- `core-api` — biên giới ổn định (FFI/IPC) cho UI.
+- `app/*` — UI theo framework đã chọn.
+- `cli` — công cụ dòng lệnh cho test/automation (chạy mọi tính năng không cần UI).
+
+## Nguyên tắc
+- Engine **không phụ thuộc UI**; mọi tính năng phải gọi được từ `cli` → test tự động.
+- Edit dùng **command pattern** → undo/redo.
+- Mọi thao tác ghi đều có đường **không phá file gốc** (atomic write / backup).
+
+## Test strategy
+- Unit test cho `cos`/`pdmodel`.
+- Golden/render-hash test cho viewer.
+- Round-trip test cho annotate/organize/form/security.
+- Corpus test (file đời thực, file hỏng, đa ngôn ngữ) + fuzzing parser.
+
+## Hạng mục cần quyết khi vào Phase 1
+- [x] Ngôn ngữ/UI: **Rust + Tauri** (chốt 2026-06-16).
+- [ ] Phân phối PDFium: dùng prebuilt `bblanchon/pdfium-binaries` qua crate `pdfium-render` (chốt version cụ thể đầu Phase 1).
+- [ ] Biên giới core-api: trong Tauri, engine Rust chạy cùng tiến trình; cân nhắc tách tiến trình parser để **sandbox** file không tin cậy (quyết định khi làm hardening).
+- [ ] Bố cục repo (mono-repo Cargo workspace, xem dưới).
+
+## Bố cục repo dự kiến (Rust + Tauri, Cargo workspace)
+```
+FoFreeXit/
+├─ Cargo.toml              # workspace
+├─ crates/
+│  ├─ ff-cos/              # tầng object thấp (cấu trúc PDF)
+│  ├─ ff-pdmodel/          # tầng tài liệu cao (page/text/annot/...)
+│  ├─ ff-engine/           # render/edit/io/font/ocr... (bọc PDFium/QPDF/Tesseract)
+│  └─ ff-cli/              # CLI chạy mọi tính năng không cần UI (để test)
+├─ app/                    # Tauri app
+│  ├─ src-tauri/           # Rust backend (gọi ff-engine)
+│  └─ src/                 # frontend (TS/HTML/CSS, PDF.js viewer)
+├─ tests/                  # integration tests
+├─ corpus/                 # PDF mẫu (thường/scan/mã hoá/hỏng/CJK/Việt/form)
+└─ docs/
+```
+
+## Bước khởi động Phase 1 (gợi ý cho session sau)
+1. Khởi tạo Cargo workspace + crate `ff-cli`, `ff-engine`.
+2. Thêm `pdfium-render` + tải prebuilt PDFium; viết lệnh CLI `render <pdf> <page> <out.png>` → xác nhận engine chạy.
+3. Khởi tạo Tauri app, hiển thị 1 trang PDF render từ engine.
+4. Dựng `corpus/` ban đầu (vài file đa dạng) + test render-hash đầu tiên.