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

137
backend/app/api/routes/pricing_diagnostics.py
View File

@@ -1,4 +1,4 @@
from fastapi import APIRouter, Depends
from fastapi import APIRouter, Depends, HTTPException, status
from app.core.config import settings
from app.repositories.pricing import find_effective_price_rule
@@ -6,34 +6,22 @@ from app.repositories.scheme_seats import get_scheme_version_seat_by_seat_id, li
from app.repositories.scheme_versions import get_current_scheme_version
from app.repositories.schemes import get_scheme_record_by_scheme_id
from app.schemas.pricing_diagnostics import (
PricingCoverageSummaryResponse,
PricingExplainMatchedRule,
PricingExplainResponse,
ExplainMatchedRule,
ExplainSeatPriceResponse,
PricingCoverageResponse,
UnpricedSeatItem,
UnpricedSeatsResponse,
UnpricedSeatListResponse,
)
from app.security.auth import require_api_key
router = APIRouter()
def _build_unpriced_reason(*, seat_id: str | None) -> tuple[str, str]:
if not seat_id:
return (
"missing_seat_id",
"Seat has no seat_id, so price resolution is impossible.",
)
return (
"no_price_rule",
"No effective price rule was found for this seat.",
)
@router.get(
f"{settings.api_v1_prefix}/schemes/{{scheme_id}}/pricing/coverage",
response_model=PricingCoverageSummaryResponse,
response_model=PricingCoverageResponse,
)
async def get_pricing_coverage_summary(
async def get_pricing_coverage(
scheme_id: str,
role: str = Depends(require_api_key),
):
@@ -60,13 +48,15 @@ async def get_pricing_coverage_summary(
sector_id=seat.sector_id,
)
priced_seats += 1
except Exception:
except HTTPException as exc:
if exc.status_code != status.HTTP_404_NOT_FOUND:
raise
unpriced_seats += 1
total_seats = len(seats)
coverage_percent = round((priced_seats / total_seats) * 100, 2) if total_seats else 0.0
coverage_percent = round((priced_seats / total_seats) * 100, 2) if total_seats else 100.0
return PricingCoverageSummaryResponse(
return PricingCoverageResponse(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
total_seats=total_seats,
@@ -78,7 +68,7 @@ async def get_pricing_coverage_summary(
@router.get(
f"{settings.api_v1_prefix}/schemes/{{scheme_id}}/pricing/unpriced-seats",
response_model=UnpricedSeatsResponse,
response_model=UnpricedSeatListResponse,
)
async def get_unpriced_seats(
scheme_id: str,
@@ -94,34 +84,47 @@ async def get_unpriced_seats(
items: list[UnpricedSeatItem] = []
for seat in seats:
if seat.seat_id:
try:
await find_effective_price_rule(
scheme_id=scheme.scheme_id,
if not seat.seat_id:
items.append(
UnpricedSeatItem(
seat_record_id=seat.seat_record_id,
seat_id=seat.seat_id,
group_id=seat.group_id,
element_id=seat.element_id,
sector_id=seat.sector_id,
group_id=seat.group_id,
row_label=seat.row_label,
seat_number=seat.seat_number,
reason_code="missing_seat_id",
reason_message="Seat has no seat_id, so price resolution is not possible.",
)
continue
except Exception:
pass
reason_code, reason_message = _build_unpriced_reason(seat_id=seat.seat_id)
items.append(
UnpricedSeatItem(
seat_record_id=seat.seat_record_id,
seat_id=seat.seat_id,
element_id=seat.element_id,
sector_id=seat.sector_id,
group_id=seat.group_id,
row_label=seat.row_label,
seat_number=seat.seat_number,
reason_code=reason_code,
reason_message=reason_message,
)
)
continue
return UnpricedSeatsResponse(
try:
await find_effective_price_rule(
scheme_id=scheme.scheme_id,
seat_id=seat.seat_id,
group_id=seat.group_id,
sector_id=seat.sector_id,
)
except HTTPException as exc:
if exc.status_code != status.HTTP_404_NOT_FOUND:
raise
items.append(
UnpricedSeatItem(
seat_record_id=seat.seat_record_id,
seat_id=seat.seat_id,
element_id=seat.element_id,
sector_id=seat.sector_id,
group_id=seat.group_id,
row_label=seat.row_label,
seat_number=seat.seat_number,
reason_code="no_price_rule",
reason_message="No effective price rule was found for this seat.",
)
)
return UnpricedSeatListResponse(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
total=len(items),
@@ -131,9 +134,9 @@ async def get_unpriced_seats(
@router.get(
f"{settings.api_v1_prefix}/schemes/{{scheme_id}}/pricing/explain/{{seat_id}}",
response_model=PricingExplainResponse,
response_model=ExplainSeatPriceResponse,
)
async def explain_pricing_for_seat(
async def explain_seat_price(
scheme_id: str,
seat_id: str,
role: str = Depends(require_api_key),
@@ -149,19 +152,18 @@ async def explain_pricing_for_seat(
)
if not seat.seat_id:
reason_code, reason_message = _build_unpriced_reason(seat_id=seat.seat_id)
return PricingExplainResponse(
return ExplainSeatPriceResponse(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
seat_id=seat.seat_id,
seat_id=seat_id,
element_id=seat.element_id,
sector_id=seat.sector_id,
group_id=seat.group_id,
row_label=seat.row_label,
seat_number=seat.seat_number,
has_price=False,
reason_code=reason_code,
reason_message=reason_message,
reason_code="missing_seat_id",
reason_message="Seat has no seat_id, so price resolution is not possible.",
matched_rule=None,
)
@@ -172,7 +174,14 @@ async def explain_pricing_for_seat(
group_id=seat.group_id,
sector_id=seat.sector_id,
)
return PricingExplainResponse(
matched_rule = ExplainMatchedRule(
matched_rule_level=matched_rule_level,
matched_target_ref=rule["target_ref"],
pricing_category_id=rule["pricing_category_id"],
amount=str(rule["amount"]),
currency=rule["currency"],
)
return ExplainSeatPriceResponse(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
seat_id=seat.seat_id,
@@ -184,17 +193,13 @@ async def explain_pricing_for_seat(
has_price=True,
reason_code="ok",
reason_message="Effective price rule resolved successfully.",
matched_rule=PricingExplainMatchedRule(
matched_rule_level=matched_rule_level,
matched_target_ref=rule["target_ref"],
pricing_category_id=rule["pricing_category_id"],
amount=str(rule["amount"]),
currency=rule["currency"],
),
matched_rule=matched_rule,
)
except Exception:
reason_code, reason_message = _build_unpriced_reason(seat_id=seat.seat_id)
return PricingExplainResponse(
except HTTPException as exc:
if exc.status_code != status.HTTP_404_NOT_FOUND:
raise
return ExplainSeatPriceResponse(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
seat_id=seat.seat_id,
@@ -204,7 +209,7 @@ async def explain_pricing_for_seat(
row_label=seat.row_label,
seat_number=seat.seat_number,
has_price=False,
reason_code=reason_code,
reason_message=reason_message,
reason_code="no_price_rule",
reason_message="No effective price rule was found for this seat.",
matched_rule=None,
)

13
backend/app/api/routes/publish.py
View File

@@ -67,25 +67,16 @@ async def get_draft_publish_readiness(
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,
)
return PublishReadinessResponse(
scheme_id=scheme.scheme_id,
scheme_version_id=version.scheme_version_id,
status=version.status,
validation_summary=readiness["validation_summary"],
pricing_coverage=readiness["pricing_coverage"],
snapshot=readiness["snapshot"],
readiness=readiness["readiness"],
)
return PublishReadinessResponse(**readiness)
@router.get(f"{settings.api_v1_prefix}/schemes/{{scheme_id}}/draft/publish-preview", response_model=PublishPreviewResponse)
async def get_publish_preview(
scheme_id: str,
baseline_scheme_version_id: str | None = Query(default=None),
refresh: bool = Query(default=False),
expected_scheme_version_id: str | None = Query(default=None),
refresh: bool = Query(default=False),
role: str = Depends(require_api_key),
):
scheme, version = await get_current_draft_context(

22
backend/app/api/routes/schemes.py
View File

@@ -18,6 +18,7 @@ from app.repositories.schemes import (
rollback_scheme_to_version,
unpublish_scheme,
)
from app.schemas.publish_readiness import SchemePublishActionResponse
from app.schemas.scheme_registry import (
SchemeCurrentResponse,
SchemeDetailResponse,
@@ -33,6 +34,7 @@ from app.schemas.scheme_versions import (
SchemeVersionListResponse,
)
from app.security.auth import require_api_key
from app.services.api_errors import raise_conflict
from app.services.publish_service import publish_current_draft_scheme
from app.services.scheme_validation import build_scheme_validation_report
@@ -146,13 +148,14 @@ async def create_next_scheme_version_endpoint(
current_version_number=current_scheme.current_version_number,
)
if expected_current_scheme_version_id and expected_current_scheme_version_id != current_version.scheme_version_id:
from fastapi import HTTPException, status
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail={
"code": "stale_current_version",
"message": "Current scheme version changed. Reload scheme state before creating a new version.",
if (
expected_current_scheme_version_id
and expected_current_scheme_version_id != current_version.scheme_version_id
):
raise_conflict(
code="stale_current_version",
message="Current scheme version changed. Reload scheme state before creating a new version.",
details={
"expected_scheme_version_id": expected_current_scheme_version_id,
"actual_scheme_version_id": current_version.scheme_version_id,
},
@@ -212,7 +215,10 @@ async def get_publish_validation(scheme_id: str, role: str = Depends(require_api
}
@router.post(f"{settings.api_v1_prefix}/schemes/{{scheme_id}}/publish")
@router.post(
f"{settings.api_v1_prefix}/schemes/{{scheme_id}}/publish",
response_model=SchemePublishActionResponse,
)
async def publish_scheme_endpoint(
scheme_id: str,
expected_scheme_version_id: str | None = Query(default=None),