feat(mpuniapp): 实现用户端网络拦截器与 API 客户端基础契约 (Task 06)

2026-09-20 17:28:43 +08:00
--- a/mpuniapp/common/api.uts
+++ b/mpuniapp/common/api.uts
@@ -0,0 +1,45 @@
+/**
+ * OmniCard AI (CRMmp) - 用户端面向微官网与名片的核心 API 客户端
+ * 严格遵循 AGENTS.md 规范与 uts 强类型约束
+ */
+
+import {
+  CardPortalDetail,
+  LeadEntity,
+  RadarTrack,
+  SubmitLeadParams,
+  RecordRadarTrackParams,
+} from './types.uts';
+import { httpGet, httpPost } from './request.uts';
+
+/**
+ * 获取微官网与名片公开聚合详情 (包含 Hero、Bento 块、多语言与品牌 VI)
+ *
+ * @param cardIdOrSlug 名片主键 ID 或自定义短链标识
+ */
+export function fetchPortalCard(cardIdOrSlug: string): Promise<CardPortalDetail> {
+  return httpGet<CardPortalDetail>('/card/portal/info', {
+    id: cardIdOrSlug,
+  });
+}
+
+/**
+ * 提交无摩擦潜客留资 / 互换名片数据
+ *
+ * @param leadData 潜客留资信息
+ */
+export function submitLead(leadData: SubmitLeadParams): Promise<LeadEntity> {
+  return httpPost<LeadEntity>('/crm/lead/submit', leadData);
+}
+
+/**
+ * 记录访客实时雷达轨迹足迹 (停留时长、滚动深度、浏览块等)
+ *
+ * @param trackData 轨迹行为数据
+ */
+export function recordRadarTrack(trackData: RecordRadarTrackParams): Promise<RadarTrack> {
+  return httpPost<RadarTrack>('/crm/radar/track', trackData);
+}
+
+export * from './types.uts';
+export * from './request.uts';
--- a/mpuniapp/common/request.uts
+++ b/mpuniapp/common/request.uts
@@ -0,0 +1,207 @@
+/**
+ * OmniCard AI (CRMmp) - 用户端网络请求底层封装与统一拦截器
+ * 严格遵循 AGENTS.md 规范与 uts 强类型规范，一套代码兼顾 App 与 Web/H5
+ */
+
+import { ApiResponse } from './types.uts';
+
+let currentBaseUrl: string = 'http://127.0.0.1:9000/api';
+// #ifdef H5
+currentBaseUrl = '/api';
+// #endif
+
+let currentTimeout: number = 10000;
+
+export function getBaseUrl(): string {
+  return currentBaseUrl;
+}
+
+export function setBaseUrl(url: string): void {
+  currentBaseUrl = url;
+}
+
+export function getRequestTimeout(): number {
+  return currentTimeout;
+}
+
+export function setRequestTimeout(timeout: number): void {
+  currentTimeout = timeout;
+}
+
+export function getAuthToken(): string {
+  try {
+    const val = uni.getStorageSync('token');
+    return val != null ? String(val) : '';
+  } catch (e) {
+    return '';
+  }
+}
+
+export function setAuthToken(token: string): void {
+  try {
+    uni.setStorageSync('token', token);
+  } catch (e) {}
+}
+
+export function clearAuthToken(): void {
+  try {
+    uni.removeStorageSync('token');
+  } catch (e) {}
+}
+
+export function getTenantId(): string {
+  try {
+    const val = uni.getStorageSync('tenant_id');
+    return val != null ? String(val) : '';
+  } catch (e) {
+    return '';
+  }
+}
+
+export function setTenantId(tenantId: string): void {
+  try {
+    uni.setStorageSync('tenant_id', tenantId);
+  } catch (e) {}
+}
+
+export type RequestMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+export interface RequestConfig {
+  url: string;
+  method?: RequestMethod;
+  data?: any;
+  header?: Record<string, any>;
+  timeout?: number;
+}
+
+/**
+ * 构建完整的请求 URL
+ */
+function buildFullUrl(url: string): string {
+  if (url.startsWith('http://') || url.startsWith('https://')) {
+    return url;
+  }
+  const base = getBaseUrl().replace(/\/+$/, '');
+  const path = url.startsWith('/') ? url : `/${url}`;
+  return `${base}${path}`;
+}
+
+/**
+ * 统一处理未授权 / 401 状态
+ */
+function handleUnauthorized(message: string): void {
+  clearAuthToken();
+  uni.showToast({
+    title: message || '登录状态已失效，请重新登录',
+    icon: 'none',
+  });
+  uni.reLaunch({
+    url: '/pages/common/login',
+  });
+}
+
+/**
+ * 网络请求底层统一封装
+ */
+export function request<T>(config: RequestConfig): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const method = config.method || 'GET';
+    const fullUrl = buildFullUrl(config.url);
+    const timeout = config.timeout != null ? config.timeout : getRequestTimeout();
+
+    // 默认请求头配置
+    const headers: Record<string, any> = {
+      'content-type': 'application/json',
+    };
+
+    // 自动挂载 Authorization 与 x-tenant-id
+    const token = getAuthToken();
+    if (token) {
+      headers['Authorization'] = token.startsWith('Bearer ') ? token : `Bearer ${token}`;
+    }
+
+    const tenantId = getTenantId();
+    if (tenantId) {
+      headers['x-tenant-id'] = tenantId;
+    }
+
+    // 显式传入的 header 具有更高优先级
+    if (config.header) {
+      Object.assign(headers, config.header);
+    }
+
+    uni.request({
+      url: fullUrl,
+      method: method as any,
+      data: config.data,
+      header: headers,
+      timeout: timeout,
+      success: (res: any) => {
+        const statusCode = res.statusCode != null ? res.statusCode : 200;
+        const resBody = res.data;
+
+        // 1. 处理 HTTP 401 或业务 code 401
+        if (statusCode === 401 || (resBody != null && resBody.code === 401)) {
+          const msg = (resBody && resBody.message) ? resBody.message : '登录状态已失效，请重新登录';
+          handleUnauthorized(msg);
+          reject(new Error(msg));
+          return;
+        }
+
+        // 2. 处理非 200 的 HTTP 异常状态
+        if (statusCode < 200 || statusCode >= 300) {
+          const errorMsg = (resBody && resBody.message) ? resBody.message : `网络请求错误 (${statusCode})`;
+          uni.showToast({
+            title: errorMsg,
+            icon: 'none',
+          });
+          reject(new Error(errorMsg));
+          return;
+        }
+
+        // 3. 处理 Cool-Admin 标准业务状态 (code === 1000 为成功)
+        if (resBody != null && typeof resBody === 'object' && 'code' in resBody) {
+          const apiRes = resBody as ApiResponse<T>;
+          if (apiRes.code === 1000) {
+            resolve(apiRes.data !== undefined ? apiRes.data : (apiRes as unknown as T));
+          } else {
+            const failMsg = apiRes.message || '请求处理失败';
+            uni.showToast({
+              title: failMsg,
+              icon: 'none',
+            });
+            reject(new Error(failMsg));
+          }
+          return;
+        }
+
+        // 4. 其它直接返回的数据格式
+        resolve(resBody as T);
+      },
+      fail: (err: any) => {
+        const errMsg = (err && err.errMsg) ? err.errMsg : '网络连接异常，请重试';
+        uni.showToast({
+          title: '网络连接异常，请重试',
+          icon: 'none',
+        });
+        reject(new Error(errMsg));
+      },
+    });
+  });
+}
+
+export function httpGet<T>(url: string, data?: any, header?: Record<string, any>): Promise<T> {
+  return request<T>({ url, method: 'GET', data, header });
+}
+
+export function httpPost<T>(url: string, data?: any, header?: Record<string, any>): Promise<T> {
+  return request<T>({ url, method: 'POST', data, header });
+}
+
+export function httpPut<T>(url: string, data?: any, header?: Record<string, any>): Promise<T> {
+  return request<T>({ url, method: 'PUT', data, header });
+}
+
+export function httpDelete<T>(url: string, data?: any, header?: Record<string, any>): Promise<T> {
+  return request<T>({ url, method: 'DELETE', data, header });
+}
--- a/mpuniapp/common/types.uts
+++ b/mpuniapp/common/types.uts
@@ -0,0 +1,119 @@
+/**
+ * OmniCard AI (CRMmp) - 用户端跨端核心数据契约与 TypeScript / UTS 类型体系
+ * 严格遵循 AGENTS.md 规范与出海 SaaS 契约，与 backend / admin 镜像对齐
+ */
+
+export type CardStatus = 'draft' | 'published' | 'archived';
+
+export type BentoBlockType = 'hero' | 'case' | 'article' | 'social' | 'video' | 'form';
+
+export type BentoColSpan = 1 | 2;
+
+export type BentoRowSpan = 1 | 2;
+
+export interface BentoBlockPublic {
+  id: number | string;
+  cardId: number | string;
+  type: BentoBlockType;
+  colSpan: BentoColSpan;
+  rowSpan: BentoRowSpan;
+  sortOrder: number;
+  title?: string;
+  content?: string;
+  mediaUrl?: string;
+  linkUrl?: string;
+  metaJson?: string | Record<string, any>;
+}
+
+export interface BrandKit {
+  logoUrl: string;
+  primaryColor: string;
+}
+
+export interface CardPortalDetail {
+  id: number | string;
+  slug?: string;
+  name: string;
+  title: string;
+  company: string;
+  slogan?: string;
+  avatarUrl?: string;
+  phone?: string;
+  email?: string;
+  whatsapp?: string;
+  linkedin?: string;
+  timezone?: string;
+  audioPronunciationUrl?: string;
+  themeCode?: string;
+  status: CardStatus;
+  bentoBlocks: BentoBlockPublic[];
+  brandKit?: BrandKit;
+  cachedAt?: number;
+}
+
+export type LeadStatus = 'new' | 'contacted' | 'hot' | 'won' | 'archived';
+
+export type LeadSource = 'nfc' | 'qr' | 'link' | 'ai_chat';
+
+export interface LeadEntity {
+  id: string | number;
+  tenantId?: string | number;
+  cardId: string | number;
+  visitorId?: string;
+  name: string;
+  company?: string;
+  phone?: string;
+  email?: string;
+  status: LeadStatus;
+  intentScore: number;
+  source: LeadSource;
+  notes?: string;
+}
+
+export interface SubmitLeadParams {
+  cardId: string | number;
+  name: string;
+  company?: string;
+  phone?: string;
+  email?: string;
+  source?: string;
+  notes?: string;
+  visitorId?: string;
+  [key: string]: any;
+}
+
+export type TouchType = 'nfc' | 'qr' | 'link';
+
+export interface RadarTrack {
+  id: string | number;
+  tenantId?: string | number;
+  cardId: string | number;
+  visitorId: string;
+  ip?: string;
+  country?: string;
+  city?: string;
+  touchType: TouchType;
+  stayDurationMs: number;
+  scrollDepth: number;
+  viewedBlocks: string[];
+  createdAt?: string | Date;
+}
+
+export interface RecordRadarTrackParams {
+  cardId: string | number;
+  visitorId: string;
+  touchType?: string;
+  stayDurationMs?: number;
+  scrollDepth?: number;
+  viewedBlocks?: string[];
+  ip?: string;
+  country?: string;
+  city?: string;
+  [key: string]: any;
+}
+
+export interface ApiResponse<T> {
+  code: number;
+  message: string;
+  data: T;
+}