Repository Guidelines

必须使用中文回复我

app.py is the Flask entrypoint; it wires blueprints from lawrisk/api (v1.py legacy, v2.py current) and enables CORS/logging.
lawrisk/services contains business logic and data access (lawrisk_service.py, lawrisk_v2_service.py, licensing_repo.py); keep new services thin and testable.
lawrisk/utils hosts shared helpers (env loading, ingestion/export scripts); favor adding config lookups to env_loader.py.
Static/manual QA tools live in static/ (notably v2_tester.html); SQL/JSON seeds in data/; Jinja templates in templates/.
Tests reside in tests/ plus a few legacy test_*.py scripts in the repo root; mirror module paths when adding new files.
Documentation and prior agent notes are under docs/ (API references, DB guide, deployment notes).

Install deps: pip install -r requirements.txt (Python 3.11+ recommended).
Run the API locally: python app.py (defaults to http://localhost:8000, health check at /healthz).
Lint/format: ruff . and black . before submitting.
Tests: pytest (use pytest -q for faster feedback). For API smoke tests, open static/v2_tester.html or curl the V2 endpoint shown in docs/guides/README.md.

Black defaults (88 cols) and Ruff rules apply; avoid manual wrapping that fights autoformatting.
Packages/files are lowercase with underscores; functions use descriptive verbs (fetch_risk_snapshot), responses stay snake_case.
Add short docstrings on service functions, especially those hitting the database or external AI.
Read configuration via lawrisk.utils.env_loader rather than os.environ directly to keep behavior consistent.

Prefer pytest function tests; place them alongside mirrored package paths (tests/api/test_v2.py, tests/services/test_lawrisk_service.py).
Cover happy paths plus edge cases (missing env vars, empty query results, database/connectivity errors).
When adding Flask routes, include a test client request asserting status, payload shape, and auth behavior.
Keep fixtures deterministic; use small JSON/SQL samples from data/ instead of live services when possible.

Follow the existing Conventional Commit pattern (feat: ..., fix: ..., chore: ...); scope subjects to the domain (e.g., feat: enhance v2 permit filter).
Group one logical change per commit; avoid mixing formatting-only changes with functional updates.
PRs should state intent, summarize testing (pytest, manual curls, screenshots of payload diffs), and link any issue/task. Call out config/env expectations for reviewers.

Copy .env locally and set DB creds (PG_*, LIC_PG_*), FLASK_SECRET_KEY, and DashScope keys before running anything beyond unit tests.
Never hardcode secrets or connection strings; prefer env variables read through env_loader.
Guard new endpoints with existing auth middleware and log sensitive operations at INFO, not DEBUG, to avoid leaking payloads.