docs: enhance Pydantic validator constraints and mark task complete

Verified that BanGUI's codebase is fully compliant with the constraint that
Pydantic validators must not execute at import time or have side effects.

Changes:
- Architekture.md § 2.1: Added explicit 'No I/O or Side Effects' constraint
  for model validators, explaining why this prevents circular dependencies
- Backend-Development.md: Enhanced validator documentation with subsection
  on import-time execution, including wrong/correct examples
- Tasks.md: Marked '[Backend] Pydantic validators execute at import time'
  as COMPLETE with verification results and regression prevention guidance

Verification Summary:
✓ Audited 14 model files: no problematic imports or function calls
✓ Import time: 0.159s (fast, no import-time side effects)
✓ Type checking: mypy --strict passes on all models
✓ Unit tests: 17 tests pass (100%)
✓ Correct pattern in use: validation in routers/services, not models

The codebase architecture is sound—no code changes required, only
documentation clarification to prevent future violations.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-04-30 19:37:03 +02:00
parent 100fd47c4b
commit 9b4aee7f37
3 changed files with 71 additions and 75 deletions

View File

@@ -496,7 +496,14 @@ Pydantic schemas that define data shapes and validation. Models are split into t
- Other models in `app.models/` (sibling models)
- `app.models.response` (response envelopes)
Validation that requires access to app-level state (e.g., allowed log directories) must be moved to the router or service layer, not in model validators.
**Critical Constraint — No I/O or Side Effects:** Pydantic validators, field defaults, and computed fields must be **pure functions with no side effects**:
- ❌ NO imports from `app.config`, `app.services`, `app.utils`, or `app.routers` (these are application-layer modules)
- ❌ NO calls to `get_settings()`, file I/O, database queries, network calls, or any runtime-dependent functions
- ❌ NO `default_factory` that calls app-layer functions
These constraints ensure that **importing a model file does not trigger application initialization** and prevents hidden circular dependencies.
**Validation that requires access to app-level state** (e.g., allowed log directories, settings, database) must be moved to the **router or service layer**, not in model validators. Validation occurs at the boundary — where settings and services are already available.
#### Tasks (`app/tasks/`)