X10 — add-mock-recommendation-adapter

[HsienW]

Labels: second-stage, layer-3, backend
Milestone: Second Stage - Layer 3: Recommendation Framework
Dependencies: X9

---

Build a Mock Adapter to Validate the Recommendation Framework

Goal

Validate the entire recommendation framework (X9) with the simplest possible Mock Domain. Prove the framework is genuinely business-decoupled.

Scope

• backend/: Mock Domain Adapter — only 3 properties: category, color, price
• backend/: Mock Product Catalog — 10–20 rows in PostgreSQL
• backend/: Mock Hard Negative Dataset — deliberately construct similar-but-business-conflicting cases

Mock Domain Design

Construct a Hard Constraint conflict scenario:

• A1: category=X, color=red ✅
• A2: category=X, color=blue ✅
• A3: category=Y, color=red ❌

When the user specifies category=X, A3 shares the same color (vector-similar) but conflicts on the Hard Constraint category. It must be excluded:

{
  "eligible": false,
  "reasonCode": "HARD_CONSTRAINT_CONFLICT",
  "field": "category",
  "expected": "X",
  "actual": "Y"
}

• backend/: Full-chain integration test (DomainRoute → Intent → Constraint → Gate → Card)

Acceptance

• Hard Constraint conflict → correctly excluded (eligible=false)
• Full chain runs without any real business attributes
• Swapping in a different Mock Adapter → framework behavior is consistent
• Integration test covers: DomainRoute → Intent → Constraint → Gate → Card
• npm run lint && npm run test && npm run build all pass

Dependencies

• Requires X9 Domain Framework
• Requires Docker PostgreSQL (already configured)