# AGENTS GUIDE

This repository is a Vue 2 + Vite SPA with Element UI. Keep changes small, follow existing patterns, and avoid refactors during fixes.

## Quick Facts
- Framework: Vue 2.6 (Options API)
- Build tool: Vite 5
- UI: Element UI 2
- Router: Vue Router 3
- Node: 22.x (see package.json)
- No automated tests currently

## Commands (local)
- Install: `yarn install`
- Dev server: `yarn dev`
- Build: `yarn build`
- Preview build: `yarn preview`
- Lint: `yarn lint`

## Single-Test / Focused Runs
- There is no test runner configured (no Jest/Vitest scripts).
- If you add tests later, document the single-test command here.

## CI / Workflows
- Build on push to `master` and `dev`: `.github/workflows/build.yml` runs `yarn install` + `yarn build`.
- Docker build+push on `master`: `.github/workflows/docker-build-push.yml`.

## Repository Layout
- `src/main.js`: app bootstrap, plugin setup, Vue mount
- `src/router/index.js`: router (history mode)
- `src/views/Subconverter.vue`: main screen
- `src/components/`: UI components
- `src/composables/`: shared logic
- `src/services/`: API adapters
- `src/utils/`: utility helpers
- `src/config/`: env-backed constants and option lists
- `src/icons/svg`: SVG sprite inputs
- `services/`: docker compose stack

## Code Style (Observed + ESLint)
- Indentation: 2 spaces
- Quotes: single quotes are preferred in most files
- Semicolons: not used (`semi: 0`)
- Vue component names: single-word allowed (`vue/multi-word-component-names: off`)
- Console/debugger: forbidden in production (`no-console`, `no-debugger`)

## Imports & Modules
- Use ES modules (`import`/`export`).
- Prefer absolute alias `@` for `src/` (see `vite.config.js`).
- Keep import groups readable: core libs, local config/utils, services, components.
- Dynamic import only used for route lazy-load.

## Vue Patterns
- Options API is used across components.
- Component file structure: `<template>`, `<script>`, `<style>`.
- Keep reactive state in `data()`; derived state in `computed`.
- Use composables from `src/composables/` for shared logic.

## Services & Error Handling
- Service classes in `src/services/*Service.js` handle API calls.
- Prefer explicit error messages with `Error` instances.
- UI errors are surfaced with `this.$message.*` or `this.$notify`.
- Silent failures are acceptable only when UX demands it (e.g., backend version fetch).

## Validation
- Use validators from `src/utils/validators.js` for user-facing checks.
- Return `{ valid, message }` or booleans; avoid throwing for validation flow.

## Environment Variables
- Use `import.meta.env` with `VITE_` prefix.
- Key constants live in `src/config/constants.js`.
- Do not commit local env files (`.env.local`, `.env.*.local`).

## Icons
- SVG sprites via `vite-plugin-svg-icons` and `src/icons/svg`.
- Use `<svg-icon icon-class="name" />`.

## Storage
- Local storage helpers live in `src/utils/storage.js`.
- TTL-based caching is already implemented; reuse it.

## Linting
- ESLint config: `.eslintrc.js`.
- If you add new rules, keep consistent with current minimal setup.

## Formatting
- No Prettier config present; rely on ESLint and existing style.
- Keep formatting consistent with nearby code.

## Git Hygiene
- Do not commit `dist/`, `node_modules/`, `.env.local`, `.env.*.local`.
- Avoid adding generated files.

## Frontend Safety
- Avoid adding inline styles unless already used in nearby code.
- Prefer Element UI components and existing patterns.
- Keep UX messages consistent with existing language (mostly Chinese UI strings).

## Performance Notes
- Do not introduce heavy deps; prefer existing utilities.
- Keep network calls centralized in `src/services`.

## Example Patterns
- Router lazy-load: `component: () => import('../views/Subconverter.vue')`
- Service class: `export class BackendService { static async ... }`
- Composable: `export function useSubscription() { return { ... } }`

## Cursor / Copilot Rules
- No Cursor rules found (`.cursor/rules`, `.cursorrules` absent).
- No Copilot instructions found (`.github/copilot-instructions.md` absent).

## If You Add Tests Later
- Document the runner and single-test command here.
- Keep test files near the logic or under a dedicated `tests/` folder.

## Suggested Manual Checks
- `yarn lint`
- `yarn build`
- Run dev server and smoke the main screen

## Notes for Agents
- Follow existing patterns and minimize scope.
- No large refactors unless explicitly requested.
- Avoid introducing TypeScript or new tooling without approval.