houseplan-card/docs/specs/042-backend-engineering-quality.md

# ТЗ #42 — Измеряемое инженерное качество backend

- Issue: https://github.com/Matysh/houseplan-card/issues/42
- Приоритет: P2
- Статус ТЗ: ready for implementation by incremental gates
- Тип: infra/tests, без изменения успешных пользовательских сценариев

## Цель

Зафиксировать честное покрытие, строгую типизацию и стабильный error contract
backend integration без массового formatting rewrite.

## Coverage

- Добавить pinned `pytest-cov`; CI запускает Python 3.13 HA harness и pure tests
  одним coverage combine workflow.
- Baseline публикуется по каждому `custom_components/houseplan/*.py` с branch
  coverage. Первое включение не скрывает skipped HA tests.
- Gate вводится ступенями: не ниже baseline → 90% → минимум 95% executable
  lines и согласованный branch threshold. Generated/frontend bundle исключён.
- `coverage.xml` artifact и human summary; новые/изменённые строки требуют 100%
  либо documented pragma для unreachable defensive branch.

## Typing

Pyright/mypy strict включается per-module allowlist:

1. `validation.py`, `store.py`, auth/const;
2. websocket request/result boundaries;
3. repairs/diagnostics/system_health;
4. trails/runtime.

HA dynamic APIs изолируются typed Protocol/adapter, а не `Any` по всему модулю.
Allowlist только уменьшается.

## Lint/format

Ruff (или один выбранный tool) с narrow rule set: errors/imports/bugbear и
format-check только для новых/затронутых Python файлов. Отдельный mechanical
PR может нормализовать остальное; feature diff не содержит repo-wide rewrite.

## WebSocket error contract

Все user-facing failures имеют stable code enum, safe developer message и
optional structured details без персональных данных. Frontend mapping ru/en
не сравнивает английские message strings. Unknown code получает общий fallback.

## Quality Scale docs

Добавить troubleshooting, examples и проверить manifest/quality_scale claims.
Нельзя отмечать rule выполненным только наличием файла — acceptance следует HA
rule text и CI evidence.

## Приёмка

- CI нельзя пройти с silently skipped HA harness;
- coverage ≥95% executable lines после staged rollout;
- strict module allowlist и lint gates зелёные;
- WS tests проверяют code + frontend localization;
- docs examples исполняемы/проверяемы;
- изменения tooling не меняют stored data/runtime result.