f96456ed29
- Standardize on `sensor.sensor_id` throughout components and stores - Add average and max CO2 metrics to sensor store and HomeView - Improve type safety for sensors, actions, and API calls - Update AGENTS.md with repository guidelines - Refine settings store types and utility functions - Add WindowWithAuth interface for auth store access - Minor bug fixes and code cleanup
2.7 KiB
Repository Guidelines
Project Structure & Module Organization
The Vue 3 frontend lives under src/. main.ts wires the router and Pinia, while App.vue hosts global layout. Page-level views sit in src/views/ (e.g. AnalyticsView.vue), with shared widgets under src/components/. Pinia logic is grouped in src/stores/ (one file per domain such as energy.ts or room.ts), and API/WebSocket helpers in src/services/. Reusable hooks belong in src/composables/. Static files and icons stay in public/ or src/assets/. Keep demo tooling like test-websocket.html at the repo root; production builds land in dist/.
Build, Test, and Development Commands
Run npm install once after cloning. npm run dev starts Vite locally; use npm run dev-server when you need LAN access. npm run build performs a type-safe production build (calls npm run type-check plus vite build). npm run preview serves the built bundle. Execute npm run test:unit for Vitest suites, npm run lint for ESLint (auto-fix enabled), and npm run format to apply Prettier to src/.
Coding Style & Naming Conventions
Follow the ESLint + Prettier flat config: 2-space indentation, single quotes in TS, and script setup in Vue SFCs when practical. Name Vue files in PascalCase (EnergyOverviewCard.vue), stores in camelCase (energy.ts exporting useEnergyStore), and composables with the use prefix. Keep Tailwind utility classes readable by grouping per concern. Avoid unchecked console.log; prefer the logging helpers already present in stores.
Testing Guidelines
Vitest with the jsdom environment powers unit tests; place suites alongside features in src/**/__tests__/ using *.spec.ts. Mock API and WebSocket calls by leveraging Pinia store injection or vi.mock('../services/api'). Every new store action or view-level computed branch should gain coverage. Run npm run test:unit -- --run --coverage before opening a PR if you add complex domain logic.
Commit & Pull Request Guidelines
Commits use short, imperative summaries without prefixes (see git log). Keep subject lines under ~70 characters and include the affected area, e.g., Refine room status badges. Squash fixups locally rather than pushing noisy history. PRs should link to Jira/GitHub issues when relevant, include screenshots or GIFs for UI changes, list test commands run, and call out backend dependencies (e.g., new API fields).
Environment & Configuration
Frontend defaults to http://localhost:8000; override with VITE_API_BASE_URL in a .env.local. Document new environment flags in README.md. Never commit real credentials—use the provided TypeScript definitions in env.d.ts to keep variable access typed.