77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# 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`
|