guzhi/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

FastAPI backend code lives in app/: routers under app/api/v1, orchestration in app/controllers, schemas/models in app/schemas and app/models, and shared helpers in app/utils. Config defaults stay in app/settings/config.py, migrations in migrations/, and the service boots through run.py. Frontend assets reside in web/ with source code in web/src, static files in web/public, and build toggles in web/settings; deployment collateral sits in deploy/.

Build, Test, and Development Commands

• make install (uv) or pip install -r requirements.txt prepares backend deps; pnpm i handles web/.
• make start / python run.py launches the API against db.sqlite3; cd web && pnpm dev starts the SPA; pnpm build prepares production assets.
• make check runs Black+isort in check mode plus Ruff; make format applies fixes; make lint is Ruff-only.
• make test loads .env variables into the shell and executes pytest -vv -s; target files with pytest tests/api/test_x.py -k keyword.
• Database maintenance: make migrate (generate Aerich migrations), make upgrade (apply), make clean-db (reset SQLite + migrations).

Coding Style & Naming Conventions

Python follows Black (120 columns), isort’s Black profile, and Ruff; keep modules snake_case and Pydantic models PascalCase. Vue code respects the repo ESLint + UnoCSS presets, uses TypeScript script blocks, and keeps component directories kebab-case; run pnpm lint or pnpm lint:fix as needed.

Testing Guidelines

Back-end features need pytest coverage mirroring the app layout—e.g., tests/api/v1/test_users.py for router logic and async tests following the patterns in test_dynamic_default.py. Seed deterministic data via fixtures instead of the shared db.sqlite3, and document any .env flags a test requires. Frontend changes should gain vitest or Playwright checks under web/tests before UI regressions reach main.

Commit & Pull Request Guidelines

Stick to Conventional Commit prefixes already present (feat:, refactor:, debug:) and keep subject lines imperative with optional scopes (feat(api):). Each PR must summarize changes, list verification commands, reference related issues, and attach UI screenshots/GIFs when touching web/. Run make check and relevant tests locally, avoid committing web/dist or SQLite WAL files, and prefer small, reviewable diffs.

Security & Configuration Tips

Secrets belong in .env, which app/settings/config.py loads automatically; rotate SECRET_KEY, JWT parameters, and database credentials before deployment. Swap the Tortoise connection from SQLite to MySQL/PostgreSQL by editing the provided templates and running make migrate && make upgrade. Lock down CORS (CORS_ORIGINS) before exposing the API publicly.