[huangji6693-max]

Summary

Closes #362

Implements platform-side fiat transaction limits, rolling-window velocity controls, and KYC-tier enforcement across manual and scheduled fiat on-ramp/off-ramp order creation paths.

Key Changes

• Prisma Schema & Migration:
  • Added enum KycTier { TIER_0 TIER_1 TIER_2 TIER_3 }, model KycProfile, and model FiatLimitPolicy with seeded default tier policies and direction-specific offRampOverrides.
  • Added migration 20261027020000_fiat_limits_kyc_tiers with migration.sql and rollback.sql.
• Pure Evaluation Engine (src/fiat/limits.ts):
  • evaluateFiatOrder({ userId, direction, amount, currency, tier, recentOrders, now, policy, fxRate, fxFeedAvailable, isFrozen }):
    1. Checks AML Transaction Monitoring & Sanctions Screening Pipeline #321 compliance freeze first (compliance_freeze).
    2. Enforces tier_zero, per_txn, rolling 1h velocity_hourly, rolling 24h velocity_daily, rolling 24h daily volume, and rolling 30d / calendar monthly volume.
    3. Reserves headroom for PENDING, PROCESSING, and SETTLED orders immediately; releases headroom on FAILED/REFUNDED as of the failure/refund timestamp without retroactively rewriting prior windows.
    4. Converts cross-currency orders to the policy base currency via the FX feed (rateSource: 'FX_FEED') and fails closed (fx_unavailable) when the FX feed is down.
    5. Attaches limitWarning when post-order utilization exceeds LIMIT_SOFT_WARN_PCT (80%).
  • evaluateScheduledFiatRun: returns skipped_limit on denial and auto-pauses scheduled plans after N = 3 consecutive skipped_limit runs.
• Service & API Routes (src/fiat/service.ts, src/routes/fiat.ts, src/routes/kyc.ts, src/routes/admin.ts):
  • Wired evaluateFiatOrder into createFiatOrder (returns 403 fiat_limit_exceeded on denial; attaches limitWarning and emits fiat.limit.approaching on soft warning) and added executeScheduledFiatOrder.
  • Added GET /api/v1/fiat/limits returning caller's tier, per-window limit/used/remaining, and nextResetAt.
  • Added POST /api/v1/kyc/verify and signature-verified POST /api/v1/kyc/webhook/:provider.
  • Added GET/PUT /api/v1/admin/fiat/limit-policies and POST /api/v1/admin/users/:id/kyc-tier (requires reviewNote, audit-logged).
• Documentation & Tests:
  • Added docs/FIAT_LIMITS.md, updated docs/openapi.yaml and docs/API_KEYS.md.
  • Added unit tests (tests/unit/fiat/limits.test.ts) and integration tests (tests/integration/fiat-limits.integration.test.ts).