qzl
58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
# Backend Domain Rules
|
|
|
|
This file governs `backend/**` only. Keep it minimal, enforceable, and non-duplicative.
|
|
|
|
## Scope & Precedence
|
|
|
|
- Inherits root `AGENTS.md` and workspace runtime rules.
|
|
- If rules conflict, apply the stricter one.
|
|
- Keep backend-only constraints here; do not duplicate root routing logic.
|
|
|
|
## Runtime & Commands
|
|
|
|
- Python commands must use `uv` (`uv run`, `uv add`).
|
|
- Backend startup/shutdown must use `./infra/scripts/app.sh`.
|
|
- Check runtime logs from `./logs/*.log`.
|
|
|
|
## Code Quality Baseline
|
|
|
|
- Do not bypass lint/type gates (`ruff`, `basedpyright`).
|
|
- Use project logging (`core.logging`), never `print()` in runtime code.
|
|
- HTTP errors must follow RFC 7807 (`application/problem+json`).
|
|
|
|
## HTTP Error Contract (Must)
|
|
|
|
- Backend must construct error payload using RFC7807 fields plus stable extension fields: `code` and optional `params`.
|
|
- `code` must be machine-readable `UPPER_SNAKE_CASE`; do not use free-text `detail` as the only contract.
|
|
- Error code registry source of truth: `docs/protocols/common/http-error-codes.md`.
|
|
- Any create/modify/deprecate of error codes must update `docs/protocols/common/http-error-codes.md` in the same change.
|
|
- Keep response media type as `application/problem+json`.
|
|
- Long-term layering target: HTTP transport details stay in routers/global handlers; service/repository/dependencies should raise domain errors (`ApiProblemError` or domain-specific exceptions), not `HTTPException`.
|
|
- When refactoring existing code, prefer replacing `HTTPException` in service/repository/dependencies with `ApiProblemError` while preserving status/code semantics.
|
|
|
|
## Configuration & Secrets
|
|
|
|
- Read env only through `core.config.settings` (`Settings` / `config`).
|
|
- Do not use `os.getenv`/manual env parsing in backend runtime.
|
|
- Never hardcode keys/tokens/passwords.
|
|
|
|
## Architecture Rules
|
|
|
|
- Use `schema -> repository -> service` layering.
|
|
- Repository: CRUD + query composition only; no auth decisions, no transaction boundary.
|
|
- Service: authz + business logic + transaction boundary.
|
|
- `owner_id` must come from verified JWT (`sub`), never from client payload.
|
|
|
|
## Schema & Contract Rules
|
|
|
|
- Schema-first for new/changed data contracts.
|
|
- Strong typing required at boundaries (Pydantic/dataclass); avoid weak untyped payload contracts.
|
|
- Protocol/data contract changes must stay aligned with `docs/protocols/`.
|
|
|
|
|
|
## Testing
|
|
|
|
- Follow TDD for feature/bugfix work when practical.
|
|
- Prioritize regression tests for changed logic/contracts.
|
|
- Real DB tests must use `settings.test.*`; never hardcode test credentials.
|