# Repository Guidelines

## Project Structure & Module Organization

This is a Vue 3 and Express quiz application about Dart and Flutter; it is not a Flutter SDK project. The Express API and production static server live in `server.js`. The Vue client is under `web/`: views belong in `web/src/views/`, shared browser utilities in `web/src/`, and global styles in `web/src/styles/theme.css`. `questions.json` is the application database, while `scripts/data/` contains import sources and `scripts/` contains maintenance utilities. Vite writes production assets to the generated, ignored `dist/` directory. Root `index.html` is a legacy artifact; the active entry is `web/index.html`.

## Build, Test, and Development Commands

- `npm install` installs the pinned dependencies from `package-lock.json`.
- `npm run dev` starts Express and Vite together; browse via Vite at `http://localhost:5173`.
- `npm run build` bundles `web/` into `dist/`.
- `npm start` serves the built client and API on `PORT` (default `3031`).
- `node scripts/verify-questions.js` validates question fields, answer indexes, explanations, and difficulty values.
- `node scripts/fix-escaping.js` normalizes stored HTML escaping in place; restart the server afterward.

Keep `vite.config.js`'s `/api` proxy aligned with the Express `PORT` when changing local ports.

## Coding Style & Naming Conventions

Use two-space indentation. Follow existing JavaScript style: CommonJS in `server.js` and `scripts/`, ES modules and Vue `<script setup>` in `web/`. Name Vue components and views in PascalCase (`QuizView.vue`), functions and variables in camelCase, and CSS classes in kebab-case. Reuse tokens and shared classes from `theme.css`; keep view-only CSS scoped. UI text, comments, and API errors should remain Simplified Chinese. Preserve the escaping contract in `web/src/htmlUtil.mjs` for authored HTML.

## Testing Guidelines

No unit-test framework or coverage threshold is configured. Before submitting, run `npm run build` and `node scripts/verify-questions.js`. Manually exercise quiz selection, offline answer grading, admin login, and question CRUD when those paths change. Never edit `questions.json` while the server is running: the next API write can overwrite external changes.

## Commit & Pull Request Guidelines

Recent history favors short, imperative Conventional Commit subjects such as `chore: change default port to 3031`; use `feat:`, `fix:`, `chore:`, or `docs:` with a focused description. Keep commits single-purpose. Pull requests should explain behavior and data-shape changes, list verification commands, link relevant issues, and include screenshots for visible UI changes. Document new environment variables and avoid committing `.env`, credentials, `node_modules/`, or `dist/`. Replace the default admin credentials in deployed environments.