feat: 增加全平台核心跨端数据契约与 TypeScript 类型体系

backend/test/comm/omni.test.ts

@@ -0,0 +1,170 @@
+import {
+  CardProfile,
+  CardStatus,
+  BentoBlock,
+  BentoBlockType,
+  BentoColSpan,
+  BentoRowSpan,
+  LeadEntity,
+  LeadStatus,
+  LeadSource,
+  RadarTrack,
+  TouchType,
+  NFCRecord,
+  NFCMaterial,
+  NFCStatus,
+  NFCSceneMode,
+  TenantProfile,
+  TenantPlanType,
+  BrandKit,
+} from '../../src/comm/types/omni';
+
+describe('OmniCard AI 核心跨端数据契约与 TypeScript 类型体系测试', () => {
+  it('应正确支持 CardProfile 契约及其字段与状态枚举', () => {
+    const cardStatus: CardStatus = 'published';
+    const card: CardProfile = {
+      id: 'card_1001',
+      tenantId: 'tenant_888',
+      userId: 'user_001',
+      name: 'Alex Rivera',
+      title: 'Global VP of Business Development',
+      company: 'OmniCard Global Ltd.',
+      slogan: 'Empowering global trade with AI',
+      avatarUrl: 'https://cdn.omnicard.ai/avatars/alex.jpg',
+      phone: '+1-555-892-0199',
+      email: 'alex@omnicard.ai',
+      whatsapp: '+15558920199',
+      linkedin: 'https://linkedin.com/in/alex-rivera-global',
+      timezone: 'UTC+8',
+      audioPronunciationUrl: 'https://cdn.omnicard.ai/audio/alex.mp3',
+      status: cardStatus,
+      themeCode: 'corporate_navy',
+    };
+
+    expect(card.id).toBe('card_1001');
+    expect(card.name).toBe('Alex Rivera');
+    expect(card.status).toBe('published');
+    expect(card.themeCode).toBe('corporate_navy');
+  });
+
+  it('应正确支持 BentoBlock 契约与尺寸、网格类型约束', () => {
+    const blockType: BentoBlockType = 'hero';
+    const colSpan: BentoColSpan = 2;
+    const rowSpan: BentoRowSpan = 1;
+
+    const block: BentoBlock = {
+      id: 101,
+      cardId: 1001,
+      type: blockType,
+      colSpan,
+      rowSpan,
+      sortOrder: 0,
+      title: 'Hero Profile',
+      content: 'Leading AI-driven digital identity across MENA and APAC markets.',
+      mediaUrl: 'https://cdn.omnicard.ai/media/hero.png',
+      linkUrl: 'https://omnicard.ai',
+      metaJson: {
+        accentColor: '#0B5CFF',
+        badge: 'Top Speaker',
+      },
+    };
+
+    expect(block.type).toBe('hero');
+    expect(block.colSpan).toBe(2);
+    expect(block.rowSpan).toBe(1);
+    expect(typeof block.sortOrder).toBe('number');
+  });
+
+  it('应正确支持 LeadEntity 潜客线索契约与意向评分、状态流转', () => {
+    const leadStatus: LeadStatus = 'hot';
+    const leadSource: LeadSource = 'nfc';
+
+    const lead: LeadEntity = {
+      id: 'lead_5001',
+      tenantId: 'tenant_888',
+      cardId: 'card_1001',
+      visitorId: 'vis_ae_9921',
+      name: 'Tariq Mansour',
+      company: 'Dubai Energy Holding',
+      phone: '+971-50-1234567',
+      email: 'tariq@dubaienergy.ae',
+      status: leadStatus,
+      intentScore: 92,
+      source: leadSource,
+      notes: 'Met at GITEX 2026. Very interested in enterprise NFC fleet and multi-tenant branding.',
+    };
+
+    expect(lead.status).toBe('hot');
+    expect(lead.intentScore).toBe(92);
+    expect(lead.source).toBe('nfc');
+    expect(lead.company).toBe('Dubai Energy Holding');
+  });
+
+  it('应正确支持 RadarTrack 实时访客足迹契约与时空数据追踪', () => {
+    const touch: TouchType = 'qr';
+    const now = new Date();
+
+    const track: RadarTrack = {
+      id: 'radar_8001',
+      tenantId: 'tenant_888',
+      cardId: 'card_1001',
+      visitorId: 'vis_de_4432',
+      ip: '194.12.88.4',
+      country: 'Germany',
+      city: 'Frankfurt',
+      touchType: touch,
+      stayDurationMs: 185000,
+      scrollDepth: 88,
+      viewedBlocks: ['hero', 'case_energy', 'article_ai_2026'],
+      createdAt: now,
+    };
+
+    expect(track.touchType).toBe('qr');
+    expect(track.country).toBe('Germany');
+    expect(track.stayDurationMs).toBeGreaterThan(0);
+    expect(track.viewedBlocks).toHaveLength(3);
+  });
+
+  it('应正确支持 NFCRecord 实体卡设备台账契约与生命周期状态', () => {
+    const material: NFCMaterial = 'metal';
+    const status: NFCStatus = 'active';
+    const sceneMode: NFCSceneMode = 'business';
+
+    const nfcCard: NFCRecord = {
+      id: 'nfc_9001',
+      uid: '04:7A:B2:8F:1C:6D:80',
+      tenantId: 'tenant_888',
+      cardId: 'card_1001',
+      batchNo: 'BATCH-2026-Q1-METAL',
+      material,
+      status,
+      sceneMode,
+      lastScannedAt: '2026-09-20T14:30:00.000Z',
+    };
+
+    expect(nfcCard.material).toBe('metal');
+    expect(nfcCard.status).toBe('active');
+    expect(nfcCard.sceneMode).toBe('business');
+    expect(nfcCard.uid).toBe('04:7A:B2:8F:1C:6D:80');
+  });
+
+  it('应正确支持 TenantProfile 企业租户与 BrandKit 品牌 VI 契约', () => {
+    const planType: TenantPlanType = 'enterprise';
+    const brandKit: BrandKit = {
+      logoUrl: 'https://cdn.omnicard.ai/brands/omnitech-logo.svg',
+      primaryColor: '#0B5CFF',
+    };
+
+    const tenant: TenantProfile = {
+      id: 'tenant_888',
+      companyName: 'OmniTech Global Inc.',
+      planType,
+      customDomain: 'vip.omnitech.com',
+      brandKit,
+    };
+
+    expect(tenant.planType).toBe('enterprise');
+    expect(tenant.brandKit.primaryColor).toBe('#0B5CFF');
+    expect(tenant.customDomain).toBe('vip.omnitech.com');
+  });
+});