2.7 KiB
Repository Guidelines
必须使用中文回复我
Project Structure & Module Organization
app.py boots the Flask service and loads blueprints from lawrisk/, whose subpackages mirror the request flow: api/ (v1/v2 routes), services/ (retrieval logic, PostgreSQL access, DashScope orchestration), middleware/, and utils/ for ingestion/export helpers. Static assets for manual QA live in static/, while data/ stores exported JSON/SQL snapshots used by the ingestion scripts. Formal specs, API references, and prior agent notes are in docs/. Python tests (pytest) belong under tests/; favor mirroring the module paths (e.g., tests/api/test_v2.py).
Build, Test, and Development Commands
Install dependencies with pip install -r requirements.txt from a Python 3.11+ shell. Launch the server via python app.py, which binds to http://localhost:8000 and exposes /healthz. Run the lightweight regression suite with pytest. Format and lint before submitting using black . and ruff .; both read pyproject.toml defaults so no extra flags are needed. For manual API smoke tests, open static/v2_tester.html in a browser or send curl requests as shown in README.md.
Coding Style & Naming Conventions
Use Black’s default 88-column formatting and Ruff-compatible imports; never hand-wrap lines differently. Modules, packages, and files are lowercase with underscores (lawrisk_service.py). Public functions favor descriptive verbs (fetch_risk_snapshot). Prefer dataclass-like dicts for payloads, and keep API responses snake_case to match existing endpoints. Add concise docstrings for service-layer functions that hit external systems. Configuration should be read through lawrisk.utils.env_loader rather than os.environ directly.
Testing Guidelines
Pytest is the standard; each new feature should include a focused unit test plus, when feasible, a service-level test hitting the Flask test client. Name tests after the behavior under check (test_query_returns_ranked_risks). Use fixtures for sample licenses/risk tables to keep tests deterministic. Aim to cover error paths (missing env vars, DashScope failures) because they are the common regressions. Run pytest -q locally before opening a PR, and attach logs when failures are environment-specific.
Commit & Pull Request Guidelines
Follow the existing Conventional Commit style (feat: …, fix: …, chore: …). Limit commits to one logical change and reference the affected domain in the subject when possible (e.g., feat: enhance v2 risk scoring). PRs should describe intent, summarize testing (pytest, manual curl, etc.), and link to any tracking issue or checklist. Include screenshots or JSON snippets when adjusting responses so reviewers can verify payload diffs quickly.