qzl
131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
# Quality Guidelines
|
|
|
|
> Code quality standards for backend development.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Backend quality gates are centered around:
|
|
|
|
1. Static checks (`ruff`, `basedpyright`) via pre-commit
|
|
2. Pytest suites under `backend/tests`
|
|
3. Layering and contract discipline from `backend/AGENTS.md`
|
|
|
|
Evidence:
|
|
|
|
- `.pre-commit-config.yaml` (`basedpyright` + `ruff`, scoped to `^backend/`)
|
|
- `pyproject.toml` (`pytest` config, test paths, live marker)
|
|
- `backend/AGENTS.md` (layering, logging, error contract, DB and env rules)
|
|
|
|
---
|
|
|
|
## Forbidden Patterns
|
|
|
|
### 1) Error swallowing
|
|
|
|
- Forbidden by project rule: do not catch/log and silently continue.
|
|
- Root rule source: `AGENTS.md`.
|
|
|
|
Legacy examples to avoid extending:
|
|
|
|
- `backend/src/v1/users/dependencies.py` (`_verify_user_with_supabase`) catches broad exceptions and returns `None` fallback.
|
|
- `backend/src/services/base/service_interface.py` (`initialize_registered_services` / `close_registered_services`) catches broad exceptions and continues lifecycle flow.
|
|
|
|
### 2) Runtime `print()` usage
|
|
|
|
- Backend runtime must use `core.logging`, not `print()`.
|
|
- Rule source: `backend/AGENTS.md`.
|
|
|
|
### 3) Unstructured HTTP error contracts
|
|
|
|
- Business/API errors must not rely only on free-text `detail`; use stable `code` (+ optional `params`).
|
|
- Sources:
|
|
- `backend/AGENTS.md`
|
|
- `docs/protocols/common/http-error-codes.md`
|
|
|
|
### 4) Reading env by ad-hoc `os.getenv` in runtime
|
|
|
|
- Runtime configuration must go through `core.config.settings`.
|
|
- Source: `backend/AGENTS.md` and implementation in `backend/src/core/config/settings.py`.
|
|
|
|
---
|
|
|
|
## Required Patterns
|
|
|
|
### Layering discipline
|
|
|
|
- Use `schema -> repository -> service` flow.
|
|
- Repository: query/CRUD + `flush`; no transaction ownership.
|
|
- Service: authz/business rules + commit/rollback boundary.
|
|
|
|
Evidence:
|
|
|
|
- `backend/src/v1/todo/repository.py` vs `backend/src/v1/todo/service.py`
|
|
- `backend/src/v1/schedule_items/repository.py` vs `backend/src/v1/schedule_items/service.py`
|
|
- `backend/src/core/db/session.py` docs explicitly state caller (service) owns commit/rollback
|
|
|
|
### Typed boundary models
|
|
|
|
- Prefer Pydantic models with strict extras handling for API/request contracts.
|
|
- Evidence across schemas:
|
|
- `backend/src/v1/todo/schemas.py`
|
|
- `backend/src/v1/schedule_items/schemas.py`
|
|
- `backend/src/v1/users/schemas.py`
|
|
|
|
### Protocol alignment
|
|
|
|
- If API contract changes (error codes/data formats), update corresponding `docs/protocols/**` docs in same change.
|
|
- Source: root `AGENTS.md` + backend rules.
|
|
|
|
---
|
|
|
|
## Testing Requirements
|
|
|
|
Observed baseline:
|
|
|
|
- Unit tests: `backend/tests/unit/**`
|
|
- Integration tests: `backend/tests/integration/**`
|
|
- Live e2e tests separated by marker `live`: `backend/tests/e2e/README-live.md`
|
|
|
|
Pytest setup evidence:
|
|
|
|
- `pyproject.toml`
|
|
- `testpaths = ["backend/tests"]`
|
|
- `markers = ["live: ..."]`
|
|
|
|
Practical expectations for backend changes:
|
|
|
|
- Add/adjust tests for changed behavior where possible (especially contract/business logic).
|
|
- Keep live tests opt-in unless task explicitly requires real dependency runs.
|
|
|
|
---
|
|
|
|
## Code Review Checklist
|
|
|
|
Use this checklist for backend PR review:
|
|
|
|
1. **Layering**
|
|
- Router stays thin (`backend/src/v1/*/router.py`)
|
|
- Service owns transaction and business decisions
|
|
- Repository does not own commit/rollback
|
|
2. **Error contract**
|
|
- Responses align with RFC7807 + stable `code`
|
|
- New/changed codes reflected in `docs/protocols/common/http-error-codes.md`
|
|
3. **Logging**
|
|
- Uses `core.logging.get_logger`
|
|
- No raw sensitive values in logs
|
|
4. **Config/secrets**
|
|
- Reads configuration via `core.config.settings`
|
|
- No hardcoded secrets
|
|
5. **Tests and checks**
|
|
- Relevant pytest scope updated if behavior changed
|
|
- `ruff` + `basedpyright` remain passing for backend scope
|
|
|
|
---
|
|
|
|
## Uncertainties (documented, not invented)
|
|
|
|
- Backend runtime still contains some legacy fallback exception patterns in specific infra/dependency paths (for example in `backend/src/v1/users/dependencies.py` fallback helper). New code should avoid expanding these patterns unless explicitly required.
|
|
- No dedicated, repository-wide automated rule currently enforces every layering guideline; enforcement is primarily pre-commit + review discipline.
|