feat: add 6 truth-layer route modules to CRUD service (#129)

* feat: add 6 truth-layer route modules to CRUD service (#105)

Co-authored-by: Cataldir <29005497+Cataldir@users.noreply.github.com>

* style: format truth-layer route modules for CI

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Cataldir <29005497+Cataldir@users.noreply.github.com>
Co-authored-by: Ricardo Cataldi <rcataldi@microsoft.com>

Author: Copilot

apps/crud-service/src/crud_service/main.py

@@ -16,15 +16,21 @@
     acp_checkout,
     acp_payments,
     acp_products,
+    audit_trail,
     auth,
     cart,
     categories,
     checkout,
+    completeness,
     health,
     orders,
     payments,
     products,
+    proposed_attributes,
     reviews,
+    schemas_registry,
+    truth_attributes,
+    ucp_products,
     users,
     webhooks,
 )
@@ -154,6 +160,14 @@ async def global_exception_handler(_request, exc):
 app.include_router(returns.router, prefix="/api/staff/returns", tags=["Staff Returns"])
 app.include_router(shipments.router, prefix="/api/staff/shipments", tags=["Staff Shipments"])
 
+# Truth-layer routes
+app.include_router(truth_attributes.router, prefix="/api", tags=["Truth Attributes"])
+app.include_router(proposed_attributes.router, prefix="/api", tags=["Proposed Attributes"])
+app.include_router(schemas_registry.router, prefix="/api", tags=["Schemas Registry"])
+app.include_router(completeness.router, prefix="/api", tags=["Completeness"])
+app.include_router(audit_trail.router, prefix="/api", tags=["Audit Trail"])
+app.include_router(ucp_products.router, prefix="/api", tags=["UCP Products"])
+
 
 @app.get("/")
 async def root():

apps/crud-service/src/crud_service/routes/__init__.py

@@ -2,21 +2,28 @@
 
 from crud_service.routes import (
     acp_products,
+    audit_trail,
     auth,
     cart,
     categories,
     checkout,
+    completeness,
     health,
     orders,
     payments,
     products,
+    proposed_attributes,
     reviews,
+    schemas_registry,
+    truth_attributes,
+    ucp_products,
     users,
     webhooks,
 )
 
 __all__ = [
     "acp_products",
+    "audit_trail",
     "health",
     "auth",
     "users",
@@ -27,5 +34,10 @@
     "checkout",
     "payments",
     "reviews",
+    "completeness",
+    "proposed_attributes",
+    "schemas_registry",
+    "truth_attributes",
+    "ucp_products",
     "webhooks",
 ]

apps/crud-service/src/crud_service/routes/audit_trail.py

@@ -0,0 +1,72 @@
+"""Audit trail routes — immutable audit log for product truth-layer changes."""
+
+from crud_service.repositories.base import BaseRepository
+from fastapi import APIRouter, HTTPException, Query, status
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class AuditRepository(BaseRepository):
+    """Repository for audit events."""
+
+    def __init__(self):
+        super().__init__(container_name="audit_events")
+
+
+audit_repo = AuditRepository()
+
+
+class AuditEventResponse(BaseModel):
+    """Response model for a single audit event."""
+
+    id: str
+    entity_id: str
+    action: str
+    actor: str | None = None
+    field_name: str | None = None
+    old_value: object = None
+    new_value: object = None
+    confidence: float | None = None
+    source_model: str | None = None
+    timestamp: str | None = None
+    metadata: dict | None = None
+
+
+@router.get("/audit/{entity_id}", response_model=list[AuditEventResponse])
+async def get_audit_trail(
+    entity_id: str,
+    action: str | None = Query(None, description="Filter by action type"),
+    limit: int = Query(50, le=200, description="Maximum number of events to return"),
+):
+    """Get the audit trail for a specific product."""
+    items = await audit_repo.query(
+        query="SELECT * FROM c WHERE c.entity_id = @entity_id",
+        parameters=[{"name": "@entity_id", "value": entity_id}],
+        partition_key=entity_id,
+    )
+    if action:
+        items = [i for i in items if i.get("action") == action]
+    return [AuditEventResponse(**item) for item in items[:limit]]
+
+
+@router.get("/audit", response_model=list[AuditEventResponse])
+async def query_audit_events(
+    action: str | None = Query(None, description="Filter by action type (e.g. enrichment)"),
+    actor: str | None = Query(None, description="Filter by actor (user or system)"),
+    entity_id: str | None = Query(None, description="Filter by entity ID"),
+    limit: int = Query(50, le=200, description="Maximum number of events to return"),
+):
+    """Query audit events across all products with optional filters."""
+    if entity_id:
+        raise HTTPException(
+            status_code=status.HTTP_307_TEMPORARY_REDIRECT,
+            detail="Use /audit/{entity_id} for entity-scoped queries",
+            headers={"Location": f"/api/audit/{entity_id}"},
+        )
+    items = await audit_repo.query(query="SELECT * FROM c")
+    if action:
+        items = [i for i in items if i.get("action") == action]
+    if actor:
+        items = [i for i in items if i.get("actor") == actor]
+    return [AuditEventResponse(**item) for item in items[:limit]]

apps/crud-service/src/crud_service/routes/completeness.py

@@ -0,0 +1,96 @@
+"""Completeness routes — product completeness scoring reports."""
+
+from crud_service.repositories.base import BaseRepository
+from fastapi import APIRouter, HTTPException, Query, status
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class CompletenessRepository(BaseRepository):
+    """Repository for completeness reports."""
+
+    def __init__(self):
+        super().__init__(container_name="completeness_reports")
+
+
+completeness_repo = CompletenessRepository()
+
+
+class GapDetail(BaseModel):
+    """Details of a single missing or incomplete field."""
+
+    field_name: str
+    required: bool = True
+    reason: str | None = None
+
+
+class CompletenessReportResponse(BaseModel):
+    """Response model for a product completeness report."""
+
+    id: str
+    entity_id: str
+    score: float
+    required_fields: int
+    completed_fields: int
+    gaps: list[GapDetail] = []
+    category_id: str | None = None
+    schema_version: str | None = None
+    generated_at: str | None = None
+
+
+class CompletenessSummaryResponse(BaseModel):
+    """Aggregate completeness statistics."""
+
+    total_products: int
+    average_score: float
+    fully_complete: int
+    needs_enrichment: int
+    critical_gaps: int
+
+
+@router.get("/completeness/summary", response_model=CompletenessSummaryResponse)
+async def get_completeness_summary():
+    """Aggregate completeness statistics across all products."""
+    items = await completeness_repo.query(query="SELECT * FROM c")
+    if not items:
+        return CompletenessSummaryResponse(
+            total_products=0,
+            average_score=0.0,
+            fully_complete=0,
+            needs_enrichment=0,
+            critical_gaps=0,
+        )
+    total = len(items)
+    scores = [i.get("score", 0.0) for i in items]
+    avg_score = sum(scores) / total
+    fully_complete = sum(1 for s in scores if s >= 1.0)
+    needs_enrichment = sum(1 for s in scores if 0.70 <= s < 1.0)
+    critical_gaps = sum(1 for s in scores if s < 0.70)
+    return CompletenessSummaryResponse(
+        total_products=total,
+        average_score=avg_score,
+        fully_complete=fully_complete,
+        needs_enrichment=needs_enrichment,
+        critical_gaps=critical_gaps,
+    )
+
+
+@router.get("/completeness/{entity_id}", response_model=CompletenessReportResponse)
+async def get_completeness_report(
+    entity_id: str,
+    limit: int = Query(1, le=10, description="Number of recent reports to return"),
+):
+    """Get the latest completeness report for a product."""
+    items = await completeness_repo.query(
+        query="SELECT * FROM c WHERE c.entity_id = @entity_id",
+        parameters=[{"name": "@entity_id", "value": entity_id}],
+        partition_key=entity_id,
+    )
+    if not items:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"No completeness report found for entity '{entity_id}'",
+        )
+    # Return most recent (last inserted)
+    return CompletenessReportResponse(**items[-1])

apps/crud-service/src/crud_service/routes/proposed_attributes.py

@@ -0,0 +1,71 @@
+"""Proposed attributes routes — AI-proposed (pending review) product attributes."""
+
+from crud_service.repositories.base import BaseRepository
+from fastapi import APIRouter, HTTPException, Query, status
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class ProposedAttributeRepository(BaseRepository):
+    """Repository for proposed attributes."""
+
+    def __init__(self):
+        super().__init__(container_name="proposed_attributes")
+
+
+proposed_attr_repo = ProposedAttributeRepository()
+
+
+class ProposedAttributeResponse(BaseModel):
+    """Response model for a proposed attribute."""
+
+    id: str
+    entity_id: str
+    field_name: str
+    proposed_value: object
+    status: str = "pending"
+    confidence: float | None = None
+    source_model: str | None = None
+    evidence: list[str] | None = None
+    proposed_at: str | None = None
+    reviewed_at: str | None = None
+    reviewed_by: str | None = None
+    rejection_reason: str | None = None
+
+
+@router.get(
+    "/proposed/attributes/{entity_id}",
+    response_model=list[ProposedAttributeResponse],
+)
+async def get_proposed_attributes(
+    entity_id: str,
+    status_filter: str | None = Query(
+        None, alias="status", description="Filter by status (pending/approved/rejected)"
+    ),
+    limit: int = Query(50, le=200, description="Maximum number of results"),
+):
+    """Get all proposed attributes for a product, with optional status filter."""
+    items = await proposed_attr_repo.query(
+        query="SELECT * FROM c WHERE c.entity_id = @entity_id",
+        parameters=[{"name": "@entity_id", "value": entity_id}],
+        partition_key=entity_id,
+    )
+    if status_filter:
+        items = [i for i in items if i.get("status") == status_filter]
+    return [ProposedAttributeResponse(**item) for item in items[:limit]]
+
+
+@router.get(
+    "/proposed/attributes/{entity_id}/{attribute_id}",
+    response_model=ProposedAttributeResponse,
+)
+async def get_proposed_attribute(entity_id: str, attribute_id: str):
+    """Get a single proposed attribute by ID."""
+    item = await proposed_attr_repo.get_by_id(attribute_id, partition_key=entity_id)
+    if not item:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Proposed attribute '{attribute_id}' not found for entity '{entity_id}'",
+        )
+    return ProposedAttributeResponse(**item)