chore: bootstrap trellis workspace and sync deployment settings

2026-04-20 17:15:50 +08:00
parent 0842e04c39
commit eeed737949
82 changed files with 16522 additions and 11 deletions
@@ -0,0 +1,130 @@
+# 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.