Files
poli0981andClaude Fable 5.2 0e0e442de5 chore: maintenance mode, Qodana analysis; 4.6.1 (#188) [skip-discuss]
The project moves to maintenance mode (stable, feature-complete): docs, templates and badges (EN + VI). Qodana analysis in CI for the TypeScript / JavaScript, Python and Rust projects, with the findings of its first reports fixed. Version 4.6.1.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 21:44:32 +07:00

13 KiB

Môi trường phát triển

Bản dịch từ bản tiếng Anh cập nhật ngày 2026-11-11 (English source revision 2026-11-11). Nếu có khác biệt, bản tiếng Anh được ưu tiên. Bản gốc: dev_env.md.

Bộ công cụ Maintainer dùng để viết và kiểm thử code trong repo này, và cách chạy từng phần trên máy. Bạn không cần cài đặt giống hệt mới đóng góp được — công cụ nào tương thích với các toolchain yêu cầu đều dùng được. Tài liệu này nhằm giúp tái lập môi trường.

IDE

JetBrains 2026.x (dòng trả phí):

  • PyCharm — pipeline Python (scripts/, các wrapper trong bash/).
  • WebStorm — webapp/ (React + TypeScript + Vite, Cloudflare Worker).
  • RustRover — webapp/src-tauri/ (shell native Tauri 2).

VS Code, Sublime, vim, v.v. đều dùng tốt; repo không chứa gì đặc thù của JetBrains.

TypeScript 7 (bản tsc mà npm run build chạy) là binary native, không có tsserver. Trong VS Code, cài extension TypeScript Native Preview (TypeScriptTeam.native-preview) để dùng language server của TS 7. Trong WebStorm, dùng chế độ hỗ trợ TypeScript 7 hoặc trỏ Languages & Frameworks → TypeScript tới webapp/node_modules/@typescript/old (TypeScript 6.0, báo cùng các lỗi).

Toolchain ngôn ngữ

Stack Yêu cầu Dùng cho
Python 3.15 (.github/python-version) Pipeline dữ liệu (scripts/) và test của nó
Node.js 26+ (CI dùng webapp/.node-version) Web app, admin app, Worker, phần front end của Tauri
npm đi kèm Node.js Dependency (npm ci theo package-lock.json)
Wrangler dependency của dự án (npx wrangler) Worker chạy local, D1 local, deploy
Rust stable (qua rustup) Chỉ để build Tauri desktop / Android
Git bản gần đây Lịch sử repo, commit và tag có chữ ký

Build Android còn cần Android Studio, SDK / NDK và JDK 17 hoặc 21 — xem webapp/TAURI.md.

Pipeline Python

Cài đặt

python -m venv .venv
# kích hoạt: .venv\Scripts\activate (Windows) · source .venv/bin/activate (macOS / Linux)
pip install -r requirements-dev.txt

Python 3.15 mặc định đọc và ghi file dưới dạng UTF-8 (UTF-8 mode, PEP 686), nên trên Windows không cần đặt PYTHONUTF8=1 nữa.

Hai file requirements ghim mọi package kèm hash; pip kiểm tra hash khi cài. Muốn thêm hoặc đổi một dependency, sửa requirements.in hoặc requirements-dev.in rồi compile lại lock bằng pip-tools — lệnh nằm ở đầu mỗi file .in (chạy bằng Python 3.14, bản Dependabot đọc được; CLAUDE.md, gotcha 40).

Kiểm tra (giống python-ci.yml)

pytest                                   # tests/ — truy cập mạng bị chặn (tests/conftest.py)
ruff check scripts tests webapp/scripts  # lint (cấu hình ở pyproject.toml gốc)
ruff format --check scripts tests        # định dạng (bỏ --check để áp dụng)
vulture                                  # code chết
python scripts/validate.py               # kiểm tra mọi file dữ liệu catalog

pytest --cov --cov-report=xml đo thêm coverage và ghi coverage.xml, giống workflow SonarQube Cloud (sonarcloud.yml).

Thử scrape thật

Các lệnh này gửi request thật tới itch.io:

# thêm URL một game vào scripts/temp_link.json, rồi:
python scripts/update_info.py --out patch.json
python scripts/apply_patch.py patch.json

# hoặc kiểm tra lại vài game đã có trong catalog:
python scripts/refresh.py --out patch.json --budget 5
python scripts/apply_patch.py patch.json

Các scanner không bao giờ ghi thẳng vào catalog: chúng xuất ra một patch theo URL, và apply_patch.py áp dụng patch đó rồi chạy validate.py. Chạy local sẽ thay đổi data_game/, scripts/*.json và scripts/state/ trong working tree của bạn — đừng đưa những thay đổi đó vào PR code; trên main, các workflow pipeline cập nhật catalog. Xem CLAUDE.md để nắm tổng quan tầng dữ liệu.

Web app

cd webapp
npm ci
npm run dev          # app công khai ở http://localhost:5173 có HMR; /data (gói + JSON) dựng từ ../data_game
npm run build        # tsc -b + vite build → webapp/dist/ (app, /admin/, /data/pack + JSON cũ, sitemap.xml)
npm run preview      # chạy bản build production (không có Worker)

Ảnh bìa (/img), form Suggest (/api/suggest) và API admin là route của Worker. Vite proxy /api và /img sang Worker ở cổng 8787, nên hãy chạy cả Worker (mục tiếp theo); không có Worker thì phần còn lại của app vẫn chạy nhưng ảnh bìa không tải được.

Worker (local)

Trong terminal thứ hai:

cd webapp
npm run build                                            # Worker phục vụ dist/ làm static assets
npx wrangler d1 migrations apply freeitchgames --local   # tạo database review queue local
npx wrangler dev                                         # http://localhost:8787 (giống npm run cf:dev)

Vẫn dùng http://localhost:5173 cho app; http://localhost:8787 phục vụ bản build gần nhất, nên hãy build lại khi muốn nó hiện thay đổi của bạn. Mọi thứ chạy local (workerd); dữ liệu D1, R2 và cache local nằm trong webapp/.wrangler/ (đã gitignore — xóa thư mục này để làm lại từ đầu). Chạy lại lệnh migrations sau khi thêm file vào worker/migrations/ (không bao giờ sửa một migration đã được áp dụng).

.dev.vars

Cấu hình local đặt trong webapp/.dev.vars (định dạng dotenv, đã gitignore). Giá trị ở đây cũng ghi đè các vars trong wrangler.jsonc khi chạy local. Một file điển hình:

DEV_ADMIN_EMAIL=you@example.com
SITE_ORIGIN=http://localhost:5173
TURNSTILE_SITEKEY=1x00000000000000000000AA
TURNSTILE_SECRET=1x0000000000000000000000000000000AA
# Chỉ khi muốn thử cổng xác minh qua `npx wrangler dev` (http://localhost:8787):
# GATE_SECRET=<32+ ký tự ngẫu nhiên, ví dụ `openssl rand -hex 32`>
Key Loại Tác dụng
DEV_ADMIN_EMAIL chỉ local, tùy chọn Vào admin mà không cần Cloudflare Access. Chỉ có hiệu lực khi host là localhost, 127.0.0.1 hoặc [::1]; bị bỏ qua ở mọi nơi khác
ADMIN_EMAILS secret Danh sách email admin (phân cách bằng dấu phẩy), được kiểm tra sau Access. Không cần khi chạy local với DEV_ADMIN_EMAIL
TURNSTILE_SECRET secret Form Suggest và cổng xác minh, đi cùng var TURNSTILE_SITEKEY
GATE_SECRET secret Ký cookie của cổng xác minh (32+ ký tự). Thiếu nó thì cổng tắt. Khi chạy local, đặt SITE_ORIGIN=http://localhost:8787 và mở site qua wrangler dev; ở đó cookie tên fig_gate (không có Secure)
GATE_BOT_TOKEN secret Giá trị mà Transform Rule của zone gửi kèm cho bot đã xác minh (32+ ký tự). Bắt buộc trên production, không cần trên localhost
GH_APP_PRIVATE_KEY secret Private key của GitHub App cho các thao tác ghi của admin — file PEM đúng như GitHub tải về (PKCS#1) hoặc PKCS#8, đi cùng var GH_APP_ID và GH_APP_INSTALLATION_ID
SITE_ORIGIN ghi đè var Form Suggest và cổng xác minh chỉ nhận POST có Origin trùng với giá trị này

Tính năng nào thiếu cấu hình sẽ trả về 503; trang công khai không cần cấu hình nào trong số này. Hai giá trị Turnstile ở trên là test key luôn-thành-công của Cloudflare (Turnstile testing); không bao giờ dùng chúng trên production. npm run cf:types bỏ qua .dev.vars (nó đọc file rỗng types.env), nên secret local không bao giờ lọt vào worker-configuration.d.ts được commit.

Form Suggest

Với file ở trên, D1 local đã migrate và cả hai server đang chạy, http://localhost:5173/suggest sẽ gửi đề xuất vào review queue local.

Admin

Khi đã đặt DEV_ADMIN_EMAIL, mở http://localhost:5173/admin/ (Vite, hot reload) hoặc http://localhost:8787/admin/ (bản đã build, giống production). Không có cấu hình GitHub App thì admin chỉ đọc: các thao tác ghi vào repo trả về 503. Khi đặt GH_APP_ID, GH_APP_INSTALLATION_ID và GH_APP_PRIVATE_KEY, việc duyệt và chỉnh sửa sẽ thành commit thật vào repo GITHUB_REPO (mặc định là repo công khai) — hãy trỏ GITHUB_REPO sang một bản fork đã cài App của bạn.

Cron (khám phá qua RSS)

npx wrangler dev --test-scheduled
# rồi mở http://localhost:8787/__scheduled

Lệnh này chạy scheduled() một lần: nó đọc một feed RSS thật của itch.io vào queue local, rồi làm các việc bảo trì queue. Hãy dùng hạn chế.

Kiểm tra web app (giống webapp-ci.yml)

cd webapp
npm run check:tauri                    # crate Tauri và package npm tương ứng cùng major.minor
npm run cf:types -- --check            # worker-configuration.d.ts khớp với wrangler.jsonc
npm run lint                           # ESLint
npm run knip                           # file / export / dependency không dùng
npm test                               # Vitest: app + Worker; test D1 khởi động một workerd local
npx tsc -b                             # chỉ kiểm tra kiểu (npm run build cũng chạy bước này)
npm run build
npm run cf:check                       # wrangler deploy --dry-run: kiểm tra cấu hình Worker, không deploy gì

npm run test:coverage chạy test kèm coverage v8 và ghi coverage/lcov.info, giống workflow SonarQube Cloud (sonarcloud.yml).

Qodana (JetBrains) cũng phân tích code trong CI (qodana.yml: TypeScript / JavaScript, Python và Rust, mỗi phần có qodana.yaml riêng). Nó cần token của project nên không có lệnh chạy cục bộ ở đây; các inspection tương tự có sẵn trong WebStorm, PyCharm và RustRover.

Sau khi sửa wrangler.jsonc, chạy npm run cf:types và commit file worker-configuration.d.ts vừa được tạo lại.

App desktop và Android (Tauri)

cd webapp
npm run tauri:dev    # cửa sổ native + HMR
npm run tauri:build  # bộ cài native

Các app đọc các gói catalog trực tiếp từ https://freeitchgames.win/data/pack và tải ảnh bìa từ img.itch.zone, nên cần internet nhưng không cần Worker local (code đổi định dạng gói chỉ chạy được trong tauri:dev khi website có định dạng đó đã được deploy). Yêu cầu theo nền tảng (WebView2 trên Windows 10, Xcode CLT trên macOS, libwebkit2gtk-4.1-dev trên Debian/Ubuntu) và cách build Android có trong webapp/TAURI.md.

Test trên mobile

Thay đổi UI web đụng tới layout responsive, điều hướng hoặc bảng dữ liệu phải được smoke-test trên thiết bị iOS thật trước khi tag release; APK Android được duyệt trên các thiết bị Android. Xem pc_spec.md để biết các thiết bị test.

Deploy (Maintainer)

Cloudflare Workers Builds deploy mỗi lần push lên main (thư mục gốc webapp, build npm run build, deploy npx wrangler deploy). Migration D1 được áp dụng thủ công (npx wrangler d1 migrations apply freeitchgames --remote), secret được đặt bằng npx wrangler secret put <NAME>, và npx wrangler deploy --env staging deploy Worker staging. Chi tiết: webapp/README.md.

Git hygiene

  • Chỉ tag release từ origin/main (xem quy trình release).
  • Commit và tag release của Maintainer được ký trên máy local (commit.gpgsign=true, git tag -s).
  • Không bao giờ commit webapp/dist/, webapp/.wrangler/, webapp/.dev.vars, webapp/src-tauri/target/, webapp/src-tauri/gen/, keystore Android, hay bất kỳ secret nào (key của GitHub App, secret Turnstile, token Access). webapp/src-tauri/Cargo.lock có được commit.

Xem thêm