fs-lawrisk/docs/guides/AGENTS.md

# Repository Guidelines
## 必须使用中文回复我
## Project Structure & Module Organization
- `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).

## Build, Test, and Development Commands
- 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`.

## Coding Style & Naming Conventions
- 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.

## Testing Guidelines
- 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.

## Commit & Pull Request Guidelines
- 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.

## Security & Configuration Tips
- 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.
docs: track AGENTS.md in docs/guides/ - Move AGENTS.md from root to docs/guides/ - Keep development guidelines with other documentation - Ensures consistent documentation structure 2025-11-18 17:10:03 +08:00			`# Repository Guidelines`
			`## 必须使用中文回复我`
			`## Project Structure & Module Organization`
chore: reorganize directory structure and clean up root directory 2025-12-20 11:25:34 +08:00			- `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).
docs: track AGENTS.md in docs/guides/ - Move AGENTS.md from root to docs/guides/ - Keep development guidelines with other documentation - Ensures consistent documentation structure 2025-11-18 17:10:03 +08:00
			`## Build, Test, and Development Commands`
chore: reorganize directory structure and clean up root directory 2025-12-20 11:25:34 +08:00			- 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`.
docs: track AGENTS.md in docs/guides/ - Move AGENTS.md from root to docs/guides/ - Keep development guidelines with other documentation - Ensures consistent documentation structure 2025-11-18 17:10:03 +08:00
			`## Coding Style & Naming Conventions`
chore: reorganize directory structure and clean up root directory 2025-12-20 11:25:34 +08:00			`- 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.
docs: track AGENTS.md in docs/guides/ - Move AGENTS.md from root to docs/guides/ - Keep development guidelines with other documentation - Ensures consistent documentation structure 2025-11-18 17:10:03 +08:00
			`## Testing Guidelines`
chore: reorganize directory structure and clean up root directory 2025-12-20 11:25:34 +08:00			- 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.
docs: track AGENTS.md in docs/guides/ - Move AGENTS.md from root to docs/guides/ - Keep development guidelines with other documentation - Ensures consistent documentation structure 2025-11-18 17:10:03 +08:00
			`## Commit & Pull Request Guidelines`
chore: reorganize directory structure and clean up root directory 2025-12-20 11:25:34 +08:00			- 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.

			`## Security & Configuration Tips`
			- 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.`