flutter_learning/AGENTS.md

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.