gold_land_user/README.md

# 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.