tiennm99/thptqg2017

mirror of https://github.com/tiennm99/thptqg2017.git synced 2026-05-24 06:26:05 +00:00

Files

T

tiennm99 d14de5e1a6 docs: expand README, add architecture / deployment / data-pipeline docs

- README: live-site URLs, features, scripts, project layout, quickstart
- docs/system-architecture.md: data flow, 3-variant deploy mechanism,
  schema, parse-quirk matrix, score-tier model, admission-block model,
  frontend key behaviors (deep-link, share, keyboard shortcuts)
- docs/data-pipeline.md: source Excel shape, score regex, why three
  parsers, overflow-sheet gotcha, audit tooling, refresh flow
- docs/deployment-guide.md: CI workflow, adding a new variant, rollback,
  GH Pages file-size note
- docs/README.md: index for the docs dir

2026-04-14 23:25:51 +07:00

2.4 KiB

Raw Permalink Blame History

Deployment Guide

Deploys to GitHub Pages via .github/workflows/deploy.yml. Every push to main rebuilds and redeploys all 3 variants.

What the workflow does

Checkout, setup Node 20, npm ci
npm run build:db:all — builds 3 SQLite DBs (main, old, old2)
Gzip each DB at level 9
npm run build:all — builds 3 Vite bundles into dist/, dist/old/, dist/old2/
Remove uncompressed .db files from dist/ (only .gz ships)
actions/upload-pages-artifact + actions/deploy-pages

Total CI time ≈ 4–6 min (DB build dominates).

Resulting URLs

https://<user>.github.io/thptqg2017/
https://<user>.github.io/thptqg2017/old/
https://<user>.github.io/thptqg2017/old2/

Local reproduction

npm ci
npm run build:db:all
gzip -kf -9 public/thptqg2017.db public-old/thptqg2017.db public-old2/thptqg2017.db
npm run build:all
npx serve dist    # or any static server

Adding a new variant

Drop source Excel files into a new data-vN/ folder
Add public-vN/ to .gitignore patterns for the .db + .db.gz
Copy scripts/build-database-old.js → scripts/build-database-vN.js; update SRC_DIR / DB_PATH; adjust parse logic for the new quirks (multi-sheet? blank rows? numeric guard?)

Add variant to VARIANT_CONFIG in vite.config.js:

vN: { base: "/thptqg2017/vN/", publicDir: "public-vN", outDir: "dist/vN" }

Add build:db:vN and build:vN npm scripts; wire them into build:db:all and build:all
Update .github/workflows/deploy.yml — add gzip step + rm step for the new DB

Notes

DB gzip is non-cacheable across deploys — every rebuild produces a new .db.gz (not byte-identical due to SQLite page shuffling). First-visit users pay the 47 MB download; subsequent visits hit browser cache until the next deploy.
GitHub Pages file size limit: individual files ≤ 100 MB. Main gzipped DB is ~47 MB — safe. Uncompressed 159 MB DB would not fit; that's why we ship .gz and the frontend decompresses via DecompressionStream.
No server-side compression assumption. The app reads the .gz file directly (not Content-Encoding: gzip). GH Pages does not reliably gzip on-the-fly for arbitrary paths; shipping pre-gzipped bytes is deterministic.

Rollback

Deploys are stateless snapshots. To rollback, revert the commit on main and push — the next workflow rebuilds the older state. There's no state to migrate.

2.4 KiB Raw Permalink Blame History Unescape Escape