greebo/svg-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(backend): add publish readiness contract and pricing diagnostics

Browse Source 
add backend readiness contract for publish prechecks

add pricing diagnostics to explain publish-blocking conditions
make publish decisions more explicit and easier to debug for clients
This commit is contained in:
greebo
2026-03-19 20:29:58 +03:00
parent 7b6c12f924
commit 8d4255181b
11 changed files with 251 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
backend/app/services/api_errors.py
View File

@@ -1,40 +1,42 @@
from __future__ import annotations
from fastapi import HTTPException, status
def raise_conflict(*, code: str, message: str, details: dict | None = None) -> None:
def build_error_detail(
*,
code: str,
message: str,
details: dict | None = None,
) -> dict:
payload = {
"code": code,
"message": message,
}
if details:
payload.update(details)
payload["details"] = details
return payload
def raise_conflict(
*,
code: str,
message: str,
details: dict | None = None,
) -> None:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=payload,
detail=build_error_detail(code=code, message=message, details=details),
)
def raise_unprocessable(*, code: str, message: str, details: dict | None = None) -> None:
payload = {
"code": code,
"message": message,
}
if details:
payload.update(details)
def raise_unprocessable(
*,
code: str,
message: str,
details: dict | None = None,
) -> None:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail=payload,
)
def raise_publish_not_ready(*, reason: str, details: dict) -> None:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail={
"code": "publish_not_ready",
"message": reason,
"details": details,
},
detail=build_error_detail(code=code, message=message, details=details),
)

23
backend/app/services/draft_guard.py
View File

@@ -1,3 +1,5 @@
from fastapi import HTTPException, status
from app.repositories.scheme_versions import get_current_scheme_version
from app.repositories.schemes import get_scheme_record_by_scheme_id
from app.services.api_errors import raise_conflict
@@ -27,19 +29,20 @@ async def get_current_draft_context(
)
if version.status != "draft" or scheme.status != "draft":
raise_conflict(
code="draft_not_editable",
message="Current scheme version is not editable because it is not in draft state",
scheme_status=scheme.status,
scheme_version_status=version.status,
actual_scheme_version_id=version.scheme_version_id,
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Current scheme version is not editable because it is not in draft state",
)
if expected_scheme_version_id and expected_scheme_version_id != version.scheme_version_id:
raise_conflict(**build_stale_draft_version_detail(
expected_scheme_version_id=expected_scheme_version_id,
actual_scheme_version_id=version.scheme_version_id,
))
raise_conflict(
code="stale_draft_version",
message="Draft scheme version is stale. Reload current draft state before applying mutation.",
details={
"expected_scheme_version_id": expected_scheme_version_id,
"actual_scheme_version_id": version.scheme_version_id,
},
)
return scheme, version

32
backend/app/services/publish_readiness.py
View File

@@ -1,5 +1,8 @@
from __future__ import annotations
from fastapi import HTTPException, status
from app.core.config import settings
from app.repositories.scheme_seats import list_scheme_version_seats
from app.repositories.scheme_version_pricing import (
find_effective_snapshot_price_rule,
@@ -13,21 +16,18 @@ async def build_publish_readiness(
*,
scheme_id: str,
scheme_version_id: str,
require_full_pricing_coverage: bool,
) -> dict:
validation = await build_scheme_validation_report(
scheme_id=scheme_id,
scheme_version_id=scheme_version_id,
)
seats = await list_scheme_version_seats(scheme_version_id)
snapshot_categories = await list_scheme_version_snapshot_categories(scheme_version_id)
snapshot_rules = await list_scheme_version_snapshot_rules(scheme_version_id)
snapshot_available = len(snapshot_categories) > 0 or len(snapshot_rules) > 0
priced_seats = 0
unpriced_seats = 0
snapshot_available = bool(snapshot_categories or snapshot_rules)
for seat in seats:
if not seat.seat_id:
@@ -46,23 +46,25 @@ async def build_publish_readiness(
sector_id=seat.sector_id,
)
priced_seats += 1
except HTTPException as exc:
if exc.status_code != status.HTTP_404_NOT_FOUND:
raise
unpriced_seats += 1
except Exception:
unpriced_seats += 1
total_seats = len(seats)
coverage_percent = round((priced_seats / total_seats) * 100, 2) if total_seats else 0.0
validation_publishable = bool(validation["summary"]["is_publishable"])
coverage_percent = round((priced_seats / total_seats) * 100, 2) if total_seats else 100.0
full_pricing_coverage = unpriced_seats == 0
pricing_gate_passed = full_pricing_coverage if require_full_pricing_coverage else True
is_ready_to_publish = (
validation_publishable
and snapshot_available
and pricing_gate_passed
pricing_gate_passed = snapshot_available and (
full_pricing_coverage if settings.publish_require_full_pricing_coverage else True
)
validation_publishable = bool(validation["summary"]["is_publishable"])
return {
"scheme_id": scheme_id,
"scheme_version_id": scheme_version_id,
"status": "draft",
"validation_summary": validation["summary"],
"pricing_coverage": {
"total_seats": total_seats,
@@ -78,9 +80,9 @@ async def build_publish_readiness(
"readiness": {
"validation_publishable": validation_publishable,
"snapshot_available": snapshot_available,
"require_full_pricing_coverage": require_full_pricing_coverage,
"require_full_pricing_coverage": settings.publish_require_full_pricing_coverage,
"full_pricing_coverage": full_pricing_coverage,
"pricing_gate_passed": pricing_gate_passed,
"is_ready_to_publish": is_ready_to_publish,
"is_ready_to_publish": validation_publishable and pricing_gate_passed,
},
}

40
backend/app/services/publish_service.py
View File

@@ -1,9 +1,8 @@
from app.core.config import settings
from app.repositories.audit import create_audit_event
from app.repositories.scheme_version_pricing import replace_scheme_version_pricing_snapshot
from app.repositories.scheme_versions import get_current_scheme_version
from app.repositories.schemes import get_scheme_record_by_scheme_id, publish_scheme
from app.services.api_errors import raise_publish_not_ready
from app.services.api_errors import raise_conflict
from app.services.publish_readiness import build_publish_readiness
@@ -19,8 +18,9 @@ async def publish_current_draft_scheme(
)
if scheme.status != "draft" or version.status != "draft":
raise_publish_not_ready(
reason="Current scheme version is not publishable because it is not in draft state",
raise_conflict(
code="publish_not_ready",
message="Current scheme version is not publishable because it is not in draft state.",
details={
"scheme_status": scheme.status,
"scheme_version_status": version.status,
@@ -29,31 +29,32 @@ async def publish_current_draft_scheme(
)
if expected_scheme_version_id and expected_scheme_version_id != version.scheme_version_id:
raise_publish_not_ready(
reason="Draft scheme version is stale. Reload current draft state before publishing.",
raise_conflict(
code="publish_not_ready",
message="Draft scheme version is stale. Reload current draft state before publishing.",
details={
"expected_scheme_version_id": expected_scheme_version_id,
"actual_scheme_version_id": version.scheme_version_id,
},
)
readiness = await build_publish_readiness(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
)
if not readiness["readiness"]["is_ready_to_publish"]:
raise_conflict(
code="publish_not_ready",
message="Draft scheme does not satisfy publish readiness requirements.",
details={"readiness": readiness["readiness"]},
)
snapshot = await replace_scheme_version_pricing_snapshot(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
)
readiness = await build_publish_readiness(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
require_full_pricing_coverage=settings.publish_require_full_pricing_coverage,
)
if not readiness["readiness"]["is_ready_to_publish"]:
raise_publish_not_ready(
reason="Scheme is not ready to publish",
details=readiness,
)
published_row = await publish_scheme(scheme.scheme_id)
await create_audit_event(
@@ -66,7 +67,6 @@ async def publish_current_draft_scheme(
"status": published_row.status,
"pricing_snapshot": snapshot,
"scheme_version_id": version.scheme_version_id,
"publish_readiness": readiness,
},
)
@@ -77,5 +77,5 @@ async def publish_current_draft_scheme(
"current_version_number": published_row.current_version_number,
"published_at": published_row.published_at.isoformat() if published_row.published_at else None,
"pricing_snapshot": snapshot,
"publish_readiness": readiness,
"validation_summary": readiness["validation_summary"],
}