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

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

backend/app/schemas/pricing_diagnostics.py

@@ -1,27 +1,13 @@
 from pydantic import BaseModel
 
 
-class PricingExplainMatchedRule(BaseModel):
-    matched_rule_level: str
-    matched_target_ref: str
-    pricing_category_id: str
-    amount: str
-    currency: str
-
-
-class PricingExplainResponse(BaseModel):
+class PricingCoverageResponse(BaseModel):
     scheme_id: str
     scheme_version_id: str
-    seat_id: str | None
-    element_id: str | None
-    sector_id: str | None
-    group_id: str | None
-    row_label: str | None
-    seat_number: str | None
-    has_price: bool
-    reason_code: str
-    reason_message: str
-    matched_rule: PricingExplainMatchedRule | None
+    total_seats: int
+    priced_seats: int
+    unpriced_seats: int
+    coverage_percent: float
 
 
 class UnpricedSeatItem(BaseModel):
@@ -36,17 +22,31 @@ class UnpricedSeatItem(BaseModel):
     reason_message: str
 
 
-class UnpricedSeatsResponse(BaseModel):
+class UnpricedSeatListResponse(BaseModel):
     scheme_id: str
     scheme_version_id: str
     total: int
     items: list[UnpricedSeatItem]
 
 
-class PricingCoverageSummaryResponse(BaseModel):
+class ExplainMatchedRule(BaseModel):
+    matched_rule_level: str
+    matched_target_ref: str
+    pricing_category_id: str
+    amount: str
+    currency: str
+
+
+class ExplainSeatPriceResponse(BaseModel):
     scheme_id: str
     scheme_version_id: str
-    total_seats: int
-    priced_seats: int
-    unpriced_seats: int
-    coverage_percent: float
+    seat_id: str
+    element_id: str | None
+    sector_id: str | None
+    group_id: str | None
+    row_label: str | None
+    seat_number: str | None
+    has_price: bool
+    reason_code: str
+    reason_message: str
+    matched_rule: ExplainMatchedRule | None

backend/app/schemas/publish_readiness.py

@@ -1,11 +1,54 @@
 from pydantic import BaseModel
 
 
+class PublishReadinessValidationSummary(BaseModel):
+    sectors_count: int
+    groups_count: int
+    seats_count: int
+    priced_seats_count: int
+    unpriced_seats_count: int
+    duplicate_seat_ids_count: int
+    seats_with_missing_contract_count: int
+    is_publishable: bool
+
+
+class PublishReadinessPricingCoverage(BaseModel):
+    total_seats: int
+    priced_seats: int
+    unpriced_seats: int
+    coverage_percent: float
+
+
+class PublishReadinessSnapshot(BaseModel):
+    available: bool
+    categories_count: int
+    rules_count: int
+
+
+class PublishReadinessFlags(BaseModel):
+    validation_publishable: bool
+    snapshot_available: bool
+    require_full_pricing_coverage: bool
+    full_pricing_coverage: bool
+    pricing_gate_passed: bool
+    is_ready_to_publish: bool
+
+
 class PublishReadinessResponse(BaseModel):
     scheme_id: str
     scheme_version_id: str
     status: str
-    validation_summary: dict
-    pricing_coverage: dict
-    snapshot: dict
-    readiness: dict
+    validation_summary: PublishReadinessValidationSummary
+    pricing_coverage: PublishReadinessPricingCoverage
+    snapshot: PublishReadinessSnapshot
+    readiness: PublishReadinessFlags
+
+
+class SchemePublishActionResponse(BaseModel):
+    scheme_id: str
+    scheme_version_id: str
+    status: str
+    current_version_number: int
+    published_at: str | None
+    pricing_snapshot: dict
+    validation_summary: PublishReadinessValidationSummary