Files
youtube-generator/docs/i18n/vi/DEVELOPMENT.md
T
poli0981andClaude Opus 5.5 5a9e7e83de ci(qodana): add Qodana for TypeScript and Rust
A Qodana workflow with one job per Qodana Cloud project:
- typescript: Qodana for JS in native mode, on the runner's Node 26 and
  node_modules (qodana.yaml, project yt-ts-js, QODANA_TOKEN_TS_JS);
- rust: Qodana for Rust, Early Access, in Docker on src-tauri/
  (src-tauri/qodana.yaml, project yt-rust, QODANA_TOKEN_RUST). Its
  bootstrap installs what rust.yml installs; a stand-in dist/index.html
  lets generate_context!() expand.

Both use qodana.recommended with a quality gate of zero problems and
analyse the whole project on every run. A tokens job skips the analysis
for Dependabot and fork PRs, which get no secrets; the token reaches only
the scan step, never `npm ci`. Annotations and artifacts, no PR comment.
Failures reach Discord through notify-ci-failure.yml.

Docs: TECH-SPEC (workflow table, Qodana notes), DEVELOPMENT (+ vi),
CONTRIBUTING, CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 10:21:18 +07:00

23 KiB
Raw Blame History

Hướng dẫn phát triển

Lưu ý dịch thuật: Tiếng Anh là phiên bản chính (docs/DEVELOPMENT.md). Bản tiếng Việt này có thể chậm cập nhật một vài commit.

Hướng dẫn này bao gồm cách cài đặt YTDescGen để phát triển cục bộ trên Windows, macOS hoặc Linux. Ứng dụng là một web app Vite/React, kèm vỏ Tauri (tùy chọn) cho desktop và Android. Bản web chạy tại ytgenerator.stream thông qua một Cloudflare Worker — xem HOSTING.md.

Cấu hình máy tham chiếu

Cấu hình máy đã dùng để phát triển và phát hành dự án:

Thành phần Thông số
OS Windows 11 Pro (24H2 trở lên)
CPU x86-64 hiện đại — 6 nhân trở lên có AVX2 (Intel gen 11 / AMD Zen 3 hoặc mới hơn)
GPU Rời hoặc tích hợp — backend WebView2 của Tauri chạy thoải mái trên iGPU
RAM Tối thiểu 16 GB, khuyến nghị 32 GB để chạy song song typecheck + dev server
Lưu trữ 5 GB trống cho node_modules + target/ Cargo sau khi build Tauri đầy đủ
Màn hình Tối thiểu 1920×1080; layout mobile đã test đến 360×640

macOS và Linux đều dùng được để phát triển. Build release Tauri được cross-compile hoặc chạy trên CI riêng — xem PACKAGING.md.

Toolchain

Cài theo thứ tự:

Công cụ Phiên bản Lý do
Node.js 26 — đúng phiên bản trong .node-version CI, các workflow release và Cloudflare Workers Builds đều đọc .node-version, và package.json khai báo engines.node >= 26. Dùng nvm hoặc fnm (fnm đọc được .node-version).
npm 11, đi kèm Node 26 Dự án dùng npm; pnpm và yarn chưa test.
Rust stable, >= 1.90 Bắt buộc cho bản build Tauri desktop và Android (Tauri 2.12 cần Rust 1.90). Cài qua rustup; profile mặc định đã có sẵn rustfmt và clippy.
Python 3.12 Tùy chọn — chỉ cần cho một số tooling Tauri trên Windows.
Tauri prerequisites theo OS Xem https://v2.tauri.app/start/prerequisites/.

Windows

  • Cài Visual Studio Build Tools 2022 với workload "Desktop development with C++" (bắt buộc cho tauri-build).
  • Cài WebView2 Runtime (Windows 11 thường đã có sẵn).
  • Bật long path: git config --global core.longpaths true.

macOS

  • Cài Xcode Command Line Tools: xcode-select --install.

Linux

  • Cài Tauri prerequisites theo từng distro — libwebkit2gtk-4.1-dev, libappindicator3-dev, v.v. Xem docs Tauri ở link trên.

Cấu hình IDE

Quy trình tham chiếu dùng JetBrains 2026.x (WebStorm hoặc RustRover) làm IDE chính, VS Code cho chỉnh sửa nhanh.

JetBrains (WebStorm / RustRover / IntelliJ Ultimate)

  • Bật plugin Tailwind CSS.
  • Bật plugin i18next (hoặc dùng src/i18n/locales/_schema.json để autocomplete).
  • Settings → Languages → TypeScript → giữ TypeScript service đi kèm IDE. node_modules/typescript không phải trình biên dịch: đó là npm alias của @typescript/typescript6, tức API TypeScript 6.0 mà typescript-eslint dùng. Dự án typecheck bằng TypeScript 7 (tsc, từ @typescript/native) — npm run typecheck là chuẩn.
  • Settings → Code Style → Prettier → Run on save ({src,tests,scripts,worker,build-plugins}/**/*.{ts,tsx,css} — đúng các file mà npm run format xử lý).

VS Code

Extension đề xuất (không có .vscode/extensions.json được commit — cài thủ công):

  • dbaeumer.vscode-eslint
  • esbenp.prettier-vscode
  • bradlc.vscode-tailwindcss
  • rust-lang.rust-analyzer (nếu động vào src-tauri/)
  • tauri-apps.tauri-vscode

Chạy lần đầu

# 1. Clone
git clone https://github.com/poli0981/youtube-generator.git
cd youtube-generator

# 2. Cài web dependencies
npm install

# 3. Chạy web dev server
npm run dev
# → http://localhost:5173

Dev server chỉ chạy riêng app: không có cổng Turnstile, không có analytics. Muốn chạy Worker phục vụ bản web, xem mục Cloudflare Worker (chạy cục bộ) bên dưới.

Nhánh và Pull Request

  • Tạo nhánh từ main (feat/…, fix/…, docs/…, chore/…) và mở pull request vào main. Không có nhánh dài hạn nào khác, và mỗi lần merge vào main đều deploy bản web.
  • Tiêu đề PR theo định dạng commit type(scope): message; CI có kiểm tra.
  • Mỗi PR đều chạy job check (xem bên dưới), dependency-review, workflow-lint, reuse và pr-title; hai job Rust lint-and-test và cargo-deny chạy khi có thay đổi trong src-tauri/.
  • Sau check, job sonarcloud gửi mã nguồn và báo cáo coverage lên SonarCloud (cấu hình trong sonar-project.properties) và fail khi quality gate fail: code mới phải đạt hạng A, mọi security hotspot đã được review, trùng lặp tối đa 3 % và coverage tối thiểu 80 %. PR từ fork và từ Dependabot bỏ qua job này — chúng không có SONAR_TOKEN — còn main được phân tích sau mỗi lần merge.
  • Workflow Qodana chạy JetBrains Qodana trên mọi PR và mọi lần push vào main: Qodana for JS cho cả repo (qodana.yaml) và Qodana for Rust cho src-tauri/ (src-tauri/qodana.yaml). Cả hai fail khi có bất kỳ lỗi nào. Giống SonarCloud, PR từ fork và từ Dependabot bỏ qua phân tích vì không có token Qodana. Đây không phải check bắt buộc.

Quy định đầy đủ: CONTRIBUTING.md.

Lệnh thường dùng

Phát triển và build

Lệnh Tác dụng
npm run dev Vite dev server, hot reload, chỉ web.
npm run build tsc + bundle web production vào dist/. Bản build web có thêm beacon Web Analytics, /.well-known/security.txt và các trang tĩnh /legal/*; bản build do Tauri CLI chạy thì không có những thứ này.
npm run preview Phục vụ bundle production để kiểm tra (không qua Worker).
npm run cf:dev wrangler dev — Worker đứng trước dist/ tại http://localhost:8787. Xem mục Cloudflare Worker (chạy cục bộ).
npm run tauri:dev Tauri desktop chế độ dev (hoặc npm run tauri dev): chạy npm run dev rồi mở cửa sổ app trỏ vào đó. Sửa frontend thì hot reload; sửa Rust thì app được build lại.
npm run tauri:build Build binary Tauri release cho platform hiện tại.

Kiểm tra

Lệnh Tác dụng
npm run typecheck tsc --noEmit trên src/ — đúng phần Vite build.
npm run typecheck:all Như trên, thêm tests/, scripts/, worker/ và build-plugins/ (tsconfig.check.json) — những thư mục config gốc cố ý bỏ qua. Có từ v0.35.0, khi phát hiện tests và scripts chưa từng được type-check — và lần chạy đầu đã tìm ra ba field bị thiếu âm thầm trong fixture parity editor→engine.
npm run lint ESLint trên src/, tests/, scripts/, worker/ và build-plugins/. Dùng npm run lint:fix để tự sửa.
npm run format Chạy Prettier (ghi file) trên src/, tests/, scripts/, worker/ và build-plugins/ (.ts, .tsx, .css).
npm run format:check Như trên nhưng chỉ kiểm tra. Là cổng CI. Markdown và JSON locale cố ý nằm ngoài phạm vi.
npm run knip Tìm code chết / dependency không dùng. Là cổng CI.
npm run validate:locales Bắt buộc cả 8 locale khớp chính xác với _schema.json. Phải pass trước khi merge PR động đến locale.
npm run test Vitest chế độ watch.
npm run test:run Vitest chạy một lần.
npm run test:coverage Chạy một lần kèm báo cáo coverage vào coverage/ — các tầng logic, SonarCloud đọc lcov.info; fail nếu thấp hơn ngưỡng đặt cho src/engine/ và worker/ trong vitest.config.ts. CI chạy lệnh này.
npm run check:version Kiểm tra cả sáu trường version khớp nhau (package.json, hai chỗ trong package-lock.json, tauri.conf.json, Cargo.toml, Cargo.lock). Đây là thứ duy nhất phát hiện khi bỏ sót một chỗ.
npm run check:tauri Các package npm @tauri-apps/* và các crate Tauri phải cùng major.minor. Tauri CLI sẽ từ chối build nếu lệch, mà CI thì không chạy build Tauri.
npm run check:licenses Mọi package được bundle đều có license nằm trong danh sách cho phép, và THIRD_PARTY_NOTICES.md khớp với những gì đang cài.
npm run check:copyright NOTICE, REUSE.toml và chuỗi copyright của bộ cài (tauri.conf.json) phải ghi đúng năm theo năm của commit HEAD — "2026", rồi "2026-2027" từ commit đầu tiên của năm 2027. Gate của CI (v1.1.0).
npm run check:bundle Chạy sau npm run build: lần tải đầu phải ≤ 280 KB gzip và không chunk JS nào vượt 500 KB (chưa nén).
npm run cf:check wrangler deploy --dry-run: kiểm tra wrangler.jsonc và bundle Worker y như Workers Builds sẽ làm, nhưng không deploy.

Sinh file

Lệnh Tác dụng
npm run generate:locale Tạo khung locale mới từ bản tiếng Anh. --lang <mã>, thêm tùy chọn --copy-english / --force. (Được nhắc đến từ v0.1 nhưng đến v0.35.0 mới thật sự có script.)
npm run generate:third-party Ghi lại THIRD_PARTY_NOTICES.md từ các package đang cài — cần chạy sau khi đổi dependency, nếu không check:licenses sẽ fail.
npm run update:copyright Ghi lại năm bản quyền trong NOTICE, REUSE.toml và tauri.conf.json — cần chạy với commit đầu tiên của năm mới, nếu không check:copyright sẽ fail.
npm run generate:brand Chuyển các SVG thương hiệu trong assets/brand/ thành icon PNG và ảnh preview khi chia sẻ link của bản web, đặt trong public/. Các file PNG được commit. Icon desktop và Android dùng chung logo đó: npx tauri icon assets/brand/logo.svg.

Trước khi mở PR

Chạy đúng những gì job check của CI chạy:

npm run typecheck && npm run typecheck:all
npm run lint && npm run format:check
npm run validate:locales
npm run test:coverage
npm run knip
npm run check:version && npm run check:tauri && npm run check:licenses
npm run check:copyright
npm run build && npm run check:bundle
npm run cf:check

Có động đến src-tauri/? Chạy thêm phần Kiểm tra Rust bên dưới.

Cloudflare Worker (chạy cục bộ)

Bản web được phục vụ bởi một Cloudflare Worker (worker/, cấu hình trong wrangler.jsonc), đứng trước dist/ để lo cổng Turnstile, các security header và các trang /legal công khai. Để chạy cục bộ:

cp .dev.vars.example .dev.vars   # chỉ chứa key TEST công khai của Cloudflare Turnstile
npm run build                    # Worker phục vụ dist/
npm run cf:dev                   # wrangler dev → http://localhost:8787
  • .dev.vars (đã nằm trong .gitignore) chứa các key Turnstile test mà Cloudflare công bố: widget luôn pass, và secret chỉ chấp nhận token giả do chính widget đó tạo ra. Tuyệt đối không ghi secret thật vào file — trên production, TURNSTILE_SECRET được lưu dưới dạng Secret của Cloudflare.
  • Không có .dev.vars thì Worker không có TURNSTILE_SECRET và sẽ fail open: app vẫn tải lên nhưng không qua cổng.
  • Worker phục vụ bản build gần nhất — chạy lại npm run build để thấy thay đổi ở frontend.
  • Test của Worker chạy chung với cả bộ test (tests/worker/).

Deploy, cookie, header, secret và rollback: HOSTING.md.

Build Tauri desktop

Xem PACKAGING.md cho pipeline release đầy đủ. Build cục bộ nhanh:

npm run tauri:build
# Output: src-tauri/target/release/bundle/
#   Windows: bộ cài MSI + NSIS · Linux: deb, rpm, AppImage · macOS: .app + DMG

Build đầu tiên mất khoảng 5–10 phút (Cargo cache rỗng). Build sau đó là incremental.

Vite dev server không theo dõi src-tauri/** và .wrangler/** (server.watch.ignored trong vite.config.ts): khi tauri dev đang chạy, Cargo liên tục ghi lại các file trong src-tauri/target, và việc theo dõi chúng từng làm Vite crash trên Windows với lỗi EBUSY do file .dll bị khóa.

Kiểm tra Rust

Giống các bước của job lint-and-test trong .github/workflows/rust.yml (chạy khi src-tauri/ thay đổi, và hằng tuần):

npm run build          # tauri::generate_context!() nhúng dist/, nên clippy và test cần có bản build
cd src-tauri
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked

Job cargo-deny kiểm tra advisory RustSec, license và nguồn crate theo src-tauri/deny.toml. Chạy cục bộ (sau khi cargo install cargo-deny): cargo deny check advisories licenses sources trong src-tauri/.

Khắc phục sự cố

validate:locales fail sau khi thêm key

Bạn quên cập nhật src/i18n/locales/_schema.json, hoặc còn thiếu ở một trong 8 locale. Schema là nguồn chuẩn; mọi locale phải khớp 100%.

validate:locales fail mà mình không động đến locale

Có người — hoặc một lần merge từ main — đã thêm key vào _schema.json (ví dụ nhãn cho một id mới trong CONTENT_WARNINGS ở src/engine/types.ts) mà chưa có ở mọi locale. Key mới cần có giá trị ở cả 8 locale.

Build Tauri báo link.exe not found (Windows)

Cài Visual Studio Build Tools 2022 + workload Desktop C++, sau đó khởi động lại shell để PATH được cập nhật.

Build Tauri báo pkg-config not found (Linux)

Cài Tauri prerequisites theo distro tại https://v2.tauri.app/start/prerequisites/.

check:tauri fail sau khi cập nhật dependency

Một package npm @tauri-apps/* đã lên minor mới mà crate chưa lên (hoặc ngược lại). Chạy cargo update -p tauri (và các crate plugin mà check:tauri liệt kê) trong src-tauri/, trên cùng nhánh.

check:bundle không tìm thấy dist/index.html

Lệnh này đo bản build — hãy chạy npm run build trước.

npm run cf:dev không hiện cổng Turnstile

Thiếu .dev.vars, nên Worker không có secret và phục vụ app mà không qua cổng. Copy .dev.vars.example thành .dev.vars rồi chạy lại.

npm install chậm / treo

Tắt VPN/proxy doanh nghiệp chặn npm registry. Lock file đã commit; install offline chạy được sau lần install thành công đầu tiên.

Hot reload không bắt được sửa đổi locale

Locale JSON bundle vào lúc build, không được watch. Restart dev server sau khi sửa src/i18n/locales/*.

Từ v0.26, chỉ tiếng Anh nằm trong main chunk; các ngôn ngữ khác là async chunk lazy-load, tải khi dùng lần đầu (xem src/i18n/index.ts và docs/I18N.md). Lời khuyên restart ở trên vẫn áp dụng cho tất cả.

Xem thêm