17 lines
2.7 KiB
Markdown
17 lines
2.7 KiB
Markdown
|
# 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.
|