# AI Agent Guidance for this Repository

## Repository overview
- Backend: `backend/` using FastAPI, Python 3.11+, `uvicorn --reload` for development.
- Frontend: `frontend/` using React 18 + Vite + TypeScript, with Zustand for state.
- Runtime data is stored under `data/` as JSON/files; do not treat it as source code.
- Docker support exists via `docker-compose.yml` and `docs/DOCKER_DEV.md`.

## What an AI coding agent should do first
1. Read `README.md` and `docs/DOCKER_DEV.md` before proposing environment or run commands.
2. Identify whether a change belongs in `backend/` or `frontend/`.
3. Prefer small, incremental edits.
4. When in doubt, ask the user before making large refactors or architectural changes.

## Build / run commands
### Backend local
- `python -m venv venv`
- `venv\Scripts\activate` (Windows)
- `pip install -r backend/requirements.txt`
- `cd backend && python main.py`

### Frontend local
- `cd frontend`
- `npm install`
- `npm run dev`

### Docker development
- `.\scripts\docker-up.ps1`
- `.\scripts\docker-restart.ps1 -Service backend`
- `.\scripts\docker-rebuild.ps1 -Service backend`
- `.\scripts\docker-logs.ps1`
- `docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d`

## Testing and quality checks
- Backend tests live in `backend/tests/`.
- Use `python -m pytest backend/tests` for automated backend test runs.
- Frontend has lint/type-check scripts in `frontend/package.json`:
  - `npm run lint`
  - `npm run type-check`
- Prefer adding or updating tests for bug fixes, new features, and non-trivial behavior changes.
- Keep changes tidy and consistent with the repository's existing style.

## Code conventions and review preferences
- The user prefers code that is:
  - 基本审查过的
  - 规范整洁的
  - 严谨测试覆盖的
- Do not perform sweeping refactors without explicit user approval.
- If a change affects core logic, clearly explain the reason and the hypothesis for the fix.
- For any change, state whether it is:
  - bug fix
  - cleanup/refactor
  - feature addition

## Important paths and domains
- `backend/main.py` — FastAPI app entrypoint
- `backend/api/` — HTTP route definitions
- `backend/services/` — core business logic and domain services
- `backend/models/` — data models and converters
- `backend/utils/` — shared helper modules
- `frontend/src/` — React source code
- `frontend/package.json` — frontend scripts and dependencies
- `docs/DOCKER_DEV.md` — Docker development guidance

## Practical guidance for AI agents
- Avoid editing generated or runtime content in `data/` unless explicitly asked.
- Prefer changes that are easy to reason about and test.
- Use existing test tools rather than inventing new workflows.
- Link to repository docs instead of duplicating long explanations.
- If a requested change is uncertain, ask for clarification rather than guessing.

## References
- `README.md`
- `docs/DOCKER_DEV.md`
- `frontend/package.json`
- `backend/requirements.txt`