139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
# Child Gold Land — Frontend
|
||
|
||
Vue 3 + Vite + Pinia + TypeScript.
|
||
|
||
## Requirements
|
||
|
||
- **Node.js:** `^22.18.0` or `>=24.12.0` (`package.json` → `engines`)
|
||
- **Pinned for local dev / CI:** `22.18.0` (see `.nvmrc`)
|
||
|
||
```powershell
|
||
nvm install 22.18.0
|
||
nvm use 22.18.0
|
||
```
|
||
|
||
## Backend (sibling repo)
|
||
|
||
API is **required** for login and gameplay. Run Nest backend from `../backend-nest` on port **3000** (separate Git repo: `gold_land_server` on Gitea).
|
||
|
||
## Local development
|
||
|
||
```powershell
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
- App: http://localhost:5174 (`vite.config.ts` — `strictPort: true`)
|
||
- API: requests to `/api/*` are proxied to http://127.0.0.1:3000
|
||
|
||
Optional env: copy `.env.example` to `.env.local` if you need overrides (`VITE_API_URL`).
|
||
|
||
Demo account (when backend `NODE_ENV=development`): username `demo`, password `123456`.
|
||
|
||
## Scripts
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `npm run dev` | Vite dev server (port 5174) |
|
||
| `npm run build` | `vue-tsc` + production build |
|
||
| `npm run preview` | Preview production build |
|
||
| `npm run type-check` | TypeScript check only |
|
||
| `npm run test` | Node unit tests (`test/`) |
|
||
| `npm run test:e2e` | Build backend + Playwright E2E (30 tests) |
|
||
| `npm run test:e2e:ci` | Playwright only (backend must already be built) |
|
||
| `npm run test:e2e:install` | `playwright install chromium` (+ OS deps on Linux: `--with-deps`) |
|
||
| `npm run e2e:prepare` | `npm run build` in backend (`E2E_BACKEND_ROOT`) |
|
||
| `npm run ci:checkout-backend` | Clone backend for CI layout (see E2E contract) |
|
||
|
||
## CI (Gitea Actions)
|
||
|
||
Workflow: [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml) (runs on **push** and **pull_request** when a Gitea **act_runner** is registered — **not verified** on `get.feep.ir` from this repo alone).
|
||
|
||
### Jobs (this repository)
|
||
|
||
| Job | Steps (same as local) |
|
||
|-----|------------------------|
|
||
| **unit** | `npm ci` → `npm run test` → `npm run type-check` → `npm run build` |
|
||
| **e2e** | checkout frontend → clone **pinned** backend → `npm ci` (both) → `e2e:prepare` → `playwright install chromium --with-deps` → `npm run test:e2e:ci` |
|
||
|
||
- **Node:** `22.18.0` (explicit in workflow)
|
||
- **Cache:** npm cache via `actions/setup-node` (optional; job still passes without cache)
|
||
- **Timeouts:** unit 25 min, e2e 45 min
|
||
- **Failure artifacts:** `playwright-report/`, `test-results/` (no tokens, no production DB)
|
||
- **Cleanup:** `npm run e2e:cleanup` runs `always()` after E2E
|
||
|
||
### Local equivalent (unit checks)
|
||
|
||
```powershell
|
||
npm ci
|
||
npm run test
|
||
npm run type-check
|
||
npm run build
|
||
```
|
||
|
||
### Two-repo E2E contract
|
||
|
||
| Item | Value |
|
||
|------|--------|
|
||
| Contract file | [`e2e/backend.contract.json`](e2e/backend.contract.json) |
|
||
| Default backend URL | `https://get.feep.ir/gold_land/gold_land_server.git` |
|
||
| Default ref | `main` (override for reproducibility) |
|
||
| Checkout path (CI) | `backend-nest/` under frontend workspace |
|
||
| Backend build | `npm run build` in that tree (`e2e:prepare`) |
|
||
| E2E backend port | `3010` (`E2E_BACKEND_PORT`) |
|
||
| E2E frontend port | `5190` (`E2E_FRONTEND_PORT`) |
|
||
| Readiness | `GET http://127.0.0.1:3010/health` |
|
||
| Temp DB | SQLite under OS temp (`scripts/e2e-backend.mjs`) — never `data/app.db` |
|
||
|
||
**Pin backend version in CI (required for e2e job):** set repository variable `E2E_BACKEND_REF` to a **commit SHA** (or immutable tag). There is **no** silent fallback to `main`.
|
||
|
||
**Local sibling layout (no clone):**
|
||
|
||
```powershell
|
||
$env:E2E_BACKEND_ROOT = "E:\path\to\backend-nest" # optional; default is ../backend-nest
|
||
npm run test:e2e
|
||
```
|
||
|
||
**Local fallback when Playwright Chromium CDN fails:** `$env:PLAYWRIGHT_CHROME_CHANNEL = "chrome"` (system Chrome). **CI must not rely on this** — use `npx playwright install chromium --with-deps`.
|
||
|
||
### Secrets (names only — never commit values)
|
||
|
||
| Name | Purpose |
|
||
|------|---------|
|
||
| `E2E_BACKEND_CHECKOUT_TOKEN` | Read access to private `gold_land_server` for `git clone` in E2E job |
|
||
|
||
If the backend repo is public, clone may work without a token. If clone fails, the **e2e** job fails; **unit** still runs.
|
||
|
||
### Runner prerequisites (Linux, e.g. `ubuntu-latest` label)
|
||
|
||
- Node **22.18.0**
|
||
- Git
|
||
- Build toolchain for **better-sqlite3** (backend dependency): `build-essential`, `python3` (Playwright `--with-deps` installs browser OS libs; backend `npm ci` still needs native compile on Linux)
|
||
- Sufficient disk for `node_modules` × 2 + Chromium
|
||
|
||
### Not yet verified on a real runner
|
||
|
||
- Gitea Actions enabled and **act_runner** online for `gold_land/gold_land_user`
|
||
- E2E job with private backend clone + `E2E_BACKEND_CHECKOUT_TOKEN`
|
||
- `vars.E2E_BACKEND_REF` / `gitea.run_id` in workflow expressions (Gitea ≥ 1.21; `github.*` aliases may apply)
|
||
|
||
## Optional: start backend + frontend (Windows)
|
||
|
||
```powershell
|
||
pwsh -File ..\backend-nest\scripts\dev-local-stack.ps1
|
||
```
|
||
|
||
Sibling folder layout: `frontend` + `backend-nest`.
|
||
|
||
## Docker / trial deploy
|
||
|
||
`docker-compose.yml` builds frontend + backend for a **trial** stack (nginx + Nest + SQLite volume).
|
||
|
||
See [docs/DEPLOY-TRIAL.md](docs/DEPLOY-TRIAL.md) for architecture, placeholders, HTTPS notes, backup, health, and rollback.
|
||
|
||
Local day-to-day dev usually uses `npm run dev` + backend `npm run dev` or `npm run start`.
|
||
|
||
## Project status doc
|
||
|
||
A workspace-level overview may exist at `../docs/project-status.md` when both repos share a parent folder. That file is **not** part of this Git repo.
|