refactor: 将Data到ViewModel的转换由App转移至Server端

- 将逻辑转移到Server端后，简化前端逻辑

server/api/cms/companyProfile.get.ts

@@ -0,0 +1,7 @@
+import { companyProfileService } from '~~/server/services/cms/companyProfileService';
+
+export default defineEventHandler(async (event) => {
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return companyProfileService.getCompanyProfile(locale);
+});

server/api/cms/companyProfile.ts

@@ -1,24 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/companyProfile.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ company_profile: CompanyProfile }>(
-    query,
-    {
-      locale: locale,
-    }
-  );
-
-  const companyProfile = data?.company_profile;
-
-  return companyProfile;
-});

server/api/cms/contactInfo.get.ts

@@ -0,0 +1,7 @@
+import { contactInfoService } from '~~/server/services/cms/contactInfoService';
+
+export default defineEventHandler(async (event) => {
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return contactInfoService.getContactInfo(locale);
+});

server/api/cms/contactInfo.ts

@@ -1,21 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/contactInfo.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ contact_info: ContactInfo }>(query, {
-    locale: locale,
-  });
-
-  const contactInfo = data?.contact_info;
-
-  return contactInfo;
-});

server/api/cms/documentList.get.ts

@@ -0,0 +1,7 @@
+import { documentService } from '~~/server/services/cms/documentService';
+
+export default defineEventHandler(async (event) => {
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return documentService.getDocumentList(locale);
+});

server/api/cms/documentList.ts

@@ -1,24 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/documentList.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ product_documents: ProductDocument[] }>(
-    query,
-    {
-      locale: locale,
-    }
-  );
-
-  const documents = data?.product_documents;
-
-  return documents;
-});

server/api/cms/homepage.get.ts

@@ -0,0 +1,7 @@
+import { homepageService } from '~~/server/services/cms/homepageService';
+
+export default defineEventHandler(async (event) => {
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return homepageService.getHomepage(locale);
+});

server/api/cms/homepage.ts

@@ -1,21 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/homepage.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ homepage: Homepage }>(query, {
-    locale: locale,
-  });
-
-  const homepage = data?.homepage;
-
-  return homepage;
-});

server/api/cms/product/[id].get.ts

@@ -0,0 +1,13 @@
+import { productService } from '~~/server/services/cms/productService';
+
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, 'id');
+  if (!id)
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Product ID is required',
+    });
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return productService.getProductById(id, locale);
+});

server/api/cms/product/[id].ts

@@ -1,33 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const id = getRouterParam(event, 'id');
-  if (!id)
-    throw createError({
-      statusCode: 400,
-      statusMessage: 'Product ID is required',
-    });
-
-  const query = await loadAssetAsString(
-    'assets/server',
-    'graphql/product.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ products_by_id: Product }>(query, {
-    id: id,
-    locale: locale,
-  });
-
-  const product = data?.products_by_id;
-
-  if (!product || product.status === 'archived') {
-    throw createError({ statusCode: 404, statusMessage: 'Product not found' });
-  }
-
-  return product;
-});

server/api/cms/productList.get.ts

@@ -0,0 +1,6 @@
+import { productService } from '~~/server/services/cms/productService';
+export default defineEventHandler(async (event) => {
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return productService.getProductList(locale);
+});

server/api/cms/productList.ts

@@ -1,21 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/productList.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ products: Product[] }>(query, {
-    locale: locale,
-  });
-
-  const products = data?.products || [];
-
-  return products;
-});

server/api/cms/questionList.get.ts

@@ -0,0 +1,6 @@
+import { questionService } from '~~/server/services/cms/questionService';
+export default defineEventHandler(async (event) => {
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return questionService.getQuestionList(locale);
+});

server/api/cms/questionList.ts

@@ -1,21 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/questionList.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ questions: Question[] }>(query, {
-    locale: locale,
-  });
-
-  const questions = data?.questions || [];
-
-  return questions;
-});

server/api/cms/solution/[id].get.ts

@@ -0,0 +1,14 @@
+import { solutionService } from '~~/server/services/cms/solutionService';
+
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, 'id');
+  if (!id)
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Solution ID is required',
+    });
+
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return solutionService.getSolutionById(id, locale);
+});

server/api/cms/solution/[id].ts

@@ -1,33 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const id = getRouterParam(event, 'id');
-  if (!id)
-    throw createError({
-      statusCode: 400,
-      statusMessage: 'Solution ID is required',
-    });
-
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/solution.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ solutions_by_id: Solution }>(query, {
-    id: id,
-    locale: locale,
-  });
-
-  const solution = data?.solutions_by_id;
-
-  if (!solution || solution.status === 'archived') {
-    throw createError({ statusCode: 404, statusMessage: 'Solution not found' });
-  }
-
-  return solution;
-});

server/api/cms/solutionList.get.ts

@@ -0,0 +1,7 @@
+import { solutionService } from '~~/server/services/cms/solutionService';
+
+export default defineEventHandler(async (event) => {
+  const locale = getHeader(event, 'x-locale') || 'zh-CN';
+
+  return solutionService.getSolutionList(locale);
+});

server/api/cms/solutionList.ts

@@ -1,21 +0,0 @@
-import { directus } from '~~/server/utils/directus';
-import { loadAssetAsString } from '~~/server/utils/serverAssets';
-
-export default defineEventHandler(async (event) => {
-  const query = await loadAssetAsString(
-    'assets:server',
-    'graphql/solutionList.graphql'
-  );
-  if (!query)
-    throw createError({ statusCode: 500, message: 'GraphQL query not found' });
-
-  const locale = getHeader(event, 'x-locale') || 'zh-CN';
-
-  const data = await directus.query<{ solutions: Solution[] }>(query, {
-    locale: locale,
-  });
-
-  const solutions = data?.solutions || [];
-
-  return solutions;
-});

server/mappers/companyProfileMapper.test.ts

@@ -0,0 +1,34 @@
+import { expect, test, describe } from 'vitest';
+import { toCompanyProfileView } from './companyProfileMapper';
+
+/**
+ * 单元测试: companyProfileMapper
+ */
+describe('companyProfileMapper', () => {
+  const baseData: CompanyProfile = {
+    id: 1,
+    translations: [{ id: 10, content: 'This is raw data of company profile' }],
+  };
+
+  test('convert raw data to CompanyProfileView correctly', () => {
+    const rawData: CompanyProfile = {
+      ...baseData,
+    };
+
+    expect(toCompanyProfileView(rawData)).toEqual({
+      id: 1,
+      content: 'This is raw data of company profile',
+    });
+  });
+  test('convert raw data with missing translations', () => {
+    const rawData: CompanyProfile = {
+      ...baseData,
+      translations: [],
+    };
+
+    expect(toCompanyProfileView(rawData)).toEqual({
+      id: 1,
+      content: '',
+    });
+  });
+});

server/mappers/companyProfileMapper.ts

@@ -0,0 +1,17 @@
+/**
+ * 将 Directus 返回的 CompanyProfile 数据转换为 CompanyProfileView 视图模型
+ *
+ * @param raw: 原始的 CompanyProfile 数据
+ * @returns 转换后的 CompanyProfileView 对象
+ *
+ * @example
+ * const view = toCompanyProfileView(rawCompanyProfile);
+ */
+export function toCompanyProfileView(raw: CompanyProfile): CompanyProfileView {
+  const trans = raw.translations?.[0];
+
+  return {
+    id: raw.id,
+    content: trans?.content ?? '',
+  };
+}

server/mappers/contactInfoMapper.test.ts

@@ -0,0 +1,34 @@
+import { describe, test, expect } from 'vitest';
+import { toContactInfoView } from './contactInfoMapper';
+
+/**
+ * 单元测试: contactInfoMapper
+ */
+describe('contactInfoMapper', () => {
+  const baseData: ContactInfo = {
+    id: 1,
+    translations: [{ id: 10, content: 'This is raw data of contact info' }],
+  };
+  test('convert raw data to ContactInfoView correctly', () => {
+    const rawData: ContactInfo = {
+      ...baseData,
+    };
+
+    expect(toContactInfoView(rawData)).toEqual({
+      id: 1,
+      content: 'This is raw data of contact info',
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: ContactInfo = {
+      ...baseData,
+      translations: [],
+    };
+
+    expect(toContactInfoView(rawData)).toEqual({
+      id: 1,
+      content: '',
+    });
+  });
+});

server/mappers/contactInfoMapper.ts

@@ -0,0 +1,17 @@
+/**
+ * 将 Directus 返回的 ContactInfo 数据转换为 ContactInfoView 视图模型
+ *
+ * @param raw: 原始的 ContactInfo 数据
+ * @returns 转换后的 ContactInfoView 对象
+ *
+ * @example
+ * const view = toContactInfoView(rawContactInfo);
+ */
+export function toContactInfoView(raw: ContactInfo): ContactInfoView {
+  const trans = raw.translations?.[0];
+
+  return {
+    id: raw.id,
+    content: trans?.content ?? '',
+  };
+}

server/mappers/documentMapper.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect } from 'vitest';
+import { toProductDocumentView, toDocumentListView } from './documentMapper';
+
+/**
+ * 单元测试: toProductDocumentView
+ */
+describe('toProductDocumentView', () => {
+  const baseData: ProductDocument = {
+    id: 1,
+    file: {
+      id: 'rand-om__-uuid-1234',
+      filename_download: 'document.pdf',
+      filesize: 2048,
+    },
+    translations: [{ id: 10, title: 'Document Title' }],
+  };
+
+  test('convert raw data with fileMeta to ProductDocumentView correctly', () => {
+    const rawData: ProductDocument = { ...baseData };
+    expect(toProductDocumentView(rawData)).toEqual({
+      id: 1,
+      fileId: 'rand-om__-uuid-1234',
+      filename: 'document.pdf',
+      title: 'Document Title',
+      url: '/api/assets/rand-om__-uuid-1234',
+      size: 2048,
+    });
+  });
+
+  test('convert raw data with fileId', () => {
+    const rawData: ProductDocument = {
+      ...baseData,
+      file: 'rand-om__-uuid-1234',
+    };
+
+    expect(toProductDocumentView(rawData)).toEqual({
+      id: 1,
+      fileId: '',
+      filename: '',
+      title: 'Document Title',
+      url: '/api/assets/',
+      size: 0,
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: ProductDocument = {
+      ...baseData,
+      translations: [],
+    };
+    expect(toProductDocumentView(rawData)).toEqual({
+      id: 1,
+      fileId: 'rand-om__-uuid-1234',
+      filename: 'document.pdf',
+      title: '',
+      url: '/api/assets/rand-om__-uuid-1234',
+      size: 2048,
+    });
+  });
+});
+
+/**
+ * 单元测试: toDocumentListView
+ */
+describe('toDocumentListView', () => {
+  const baseData: ProductDocument = {
+    id: 1,
+    file: {
+      id: 'rand-om__-uuid-1234',
+      filename_download: 'document.pdf',
+      filesize: 2048,
+    },
+    translations: [{ id: 10, title: 'Document Title' }],
+    products: [
+      {
+        id: 10,
+        products_id: {
+          id: 1,
+          translations: [{ id: 1, name: 'Product A' }],
+          product_type: {
+            id: 1,
+            translations: [{ id: 1, name: 'Type A' }],
+          },
+        },
+      },
+    ],
+  };
+  test('convert raw data with fileMeta to DocumentListView correctly', () => {
+    const rawData: ProductDocument = { ...baseData };
+    expect(toDocumentListView(rawData)).toEqual({
+      id: 1,
+      fileId: 'rand-om__-uuid-1234',
+      filename: 'document.pdf',
+      title: 'Document Title',
+      url: '/api/assets/rand-om__-uuid-1234',
+      size: 2048,
+      products: [
+        {
+          id: 1,
+          name: 'Product A',
+          type: {
+            id: 1,
+            name: 'Type A',
+          },
+        },
+      ],
+    });
+  });
+});

server/mappers/documentMapper.ts

@@ -0,0 +1,76 @@
+/**
+ * 将 Directus 返回的 Document 数据转换为 ProductDocumentView 视图模型
+ *
+ * @param raw: 原始的 Document 数据
+ * @returns 转换后的 ProductDocumentView 对象
+ *
+ * @example
+ * const view = toProductDocumentView(rawDocument);
+ */
+export function toProductDocumentView(
+  raw: ProductDocument
+): ProductDocumentView {
+  const trans = raw.translations?.[0];
+  const file = isObject<DirectusFile>(raw.file) ? raw.file : undefined;
+  const fileId = file?.id ?? '';
+
+  const url = `/api/assets/${fileId}`;
+
+  return {
+    id: raw.id,
+    fileId: fileId,
+    filename: file?.filename_download ?? '',
+    title: trans?.title ?? '',
+    url: url,
+    size: file?.filesize ?? 0,
+  };
+}
+
+/**
+ * 将 Directus 返回的 Document 数据转换为 DocumentListView 视图模型
+ *
+ * @param raw: 原始的 Document 数据
+ * @returns 转换后的 DocumentListView 对象
+ *
+ * @example
+ * const view = toDocumentListView(rawDocument);
+ */
+export function toDocumentListView(raw: ProductDocument): DocumentListView {
+  const trans = raw.translations?.[0];
+
+  const file = isObject<DirectusFile>(raw.file) ? raw.file : undefined;
+  const fileId = file?.id ?? '';
+
+  const url = `/api/assets/${fileId}`;
+
+  const related_products: DocumentListProduct[] = (raw.products ?? [])
+    .filter(isObject<ProductsProductDocument>)
+    .map((item) => item.products_id)
+    .filter(isObject<Product>)
+    .map((item) => {
+      const productType = isObject<ProductType>(item.product_type)
+        ? ({
+            id: item.product_type.id,
+            name: item.product_type.translations?.[0]?.name ?? '',
+          } satisfies DocumentListProductType)
+        : ({
+            id: -1,
+            name: '',
+          } satisfies DocumentListProductType);
+      return {
+        id: item.id,
+        name: item.translations?.[0]?.name ?? '',
+        type: productType,
+      };
+    });
+
+  return {
+    id: raw.id,
+    fileId: fileId,
+    filename: file?.filename_download ?? '',
+    title: trans?.title ?? '',
+    url: url,
+    size: file?.filesize ?? 0,
+    products: related_products,
+  };
+}

server/mappers/homepageMapper.test.ts

@@ -0,0 +1,95 @@
+import { describe, test, expect } from 'vitest';
+import { toHomepageView } from './homepageMapper';
+
+/**
+ * 单元测试: toHomepageView
+ */
+describe('toHomepageView', () => {
+  test('convert raw data to HomepageView correctly', () => {
+    const rawData: Homepage = {
+      id: 1,
+      carousel: [
+        {
+          id: 1,
+          directus_files_id: {
+            id: 'file-uuid-1',
+          },
+        },
+        {
+          id: 2,
+          directus_files_id: {
+            id: 'file-uuid-2',
+          },
+        },
+      ],
+      recommend_products: [
+        {
+          id: 1,
+          translations: [{ id: 1, name: 'Product 1', summary: 'Summary 1' }],
+          cover: {
+            id: 'cover-file-uuid-1',
+          },
+        },
+        {
+          id: 2,
+          translations: [{ id: 2, name: 'Product 2', summary: 'Summary 2' }],
+          cover: {
+            id: 'cover-file-uuid-2',
+          },
+        },
+      ],
+      recommend_solutions: [
+        {
+          id: 1,
+          translations: [{ id: 1, title: 'Solution 1', summary: 'Summary 1' }],
+          cover: {
+            id: 'cover-file-uuid-1',
+          },
+        },
+      ],
+    };
+
+    expect(toHomepageView(rawData)).toEqual({
+      id: 1,
+      carousel: ['file-uuid-1', 'file-uuid-2'],
+      recommendProducts: [
+        {
+          id: 1,
+          name: 'Product 1',
+          summary: 'Summary 1',
+          cover: 'cover-file-uuid-1',
+        },
+        {
+          id: 2,
+          name: 'Product 2',
+          summary: 'Summary 2',
+          cover: 'cover-file-uuid-2',
+        },
+      ],
+      recommendSolutions: [
+        {
+          id: 1,
+          title: 'Solution 1',
+          summary: 'Summary 1',
+          cover: 'cover-file-uuid-1',
+        },
+      ],
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: Homepage = {
+      id: 1,
+      carousel: [],
+      recommend_products: [{ id: 1, translations: [], cover: null }],
+      recommend_solutions: [{ id: 1, translations: [], cover: null }],
+    };
+
+    expect(toHomepageView(rawData)).toEqual({
+      id: 1,
+      carousel: [],
+      recommendProducts: [{ id: 1, name: '', summary: '', cover: '' }],
+      recommendSolutions: [{ id: 1, title: '', summary: '', cover: '' }],
+    });
+  });
+});

server/mappers/homepageMapper.ts

@@ -0,0 +1,54 @@
+import { isObject } from '../utils/object';
+
+/**
+ * 将 Directus 返回的 Homepage 数据转换为 HomepageView 视图模型
+ *
+ * @param raw: 原始的 Homepage 数据
+ * @returns 转换后的 HomepageView 对象
+ *
+ * @example
+ * const view = toHomepageView(rawHomepage);
+ */
+export function toHomepageView(raw: Homepage): HomepageView {
+  const carousel = (raw.carousel ?? [])
+    .filter(isObject<HomepageFile>)
+    .map((item) => item.directus_files_id)
+    .filter(isObject<DirectusFile>)
+    .map((file) => file.id);
+
+  const products = (raw.recommend_products ?? [])
+    .filter(isObject<Product>)
+    .map((item) => {
+      const trans = item.translations?.[0];
+
+      const cover = isObject<DirectusFile>(item.cover) ? item.cover.id : '';
+
+      return {
+        id: item.id,
+        name: trans?.name ?? '',
+        summary: trans?.summary ?? '',
+        cover: cover,
+      } satisfies HomepageProductView;
+    });
+
+  const solutions = (raw.recommend_solutions ?? [])
+    .filter(isObject<Solution>)
+    .map((item) => {
+      const trans = item.translations?.[0];
+      const cover = isObject<DirectusFile>(item.cover) ? item.cover.id : '';
+
+      return {
+        id: item.id,
+        title: trans?.title ?? '',
+        summary: trans?.summary ?? '',
+        cover: cover,
+      } satisfies HomepageSolutionView;
+    });
+
+  return {
+    id: raw.id,
+    carousel: carousel ?? [],
+    recommendProducts: products ?? [],
+    recommendSolutions: solutions ?? [],
+  };
+}

server/mappers/productMapper.test.ts

@@ -0,0 +1,188 @@
+import { describe, test, expect } from 'vitest';
+import {
+  toProductListView,
+  toProductSpecView,
+  toProductSpecGroupView,
+  toProductView,
+} from './productMapper';
+
+/**
+ * 单元测试: toProductListView
+ */
+describe('toProductListView', () => {
+  test('convert raw data to ProductListView correctly', () => {
+    const rawData: Product = {
+      id: 1,
+      translations: [
+        { id: 10, name: 'Product Name', summary: 'Product Summary' },
+      ],
+      cover: {
+        id: 'cover-file-uuid-1234',
+      },
+      product_type: {
+        id: 1,
+        translations: [{ id: 20, name: 'Type Name' }],
+        sort: 1,
+      },
+    };
+
+    expect(toProductListView(rawData)).toEqual({
+      id: 1,
+      name: 'Product Name',
+      summary: 'Product Summary',
+      cover: 'cover-file-uuid-1234',
+      product_type: {
+        id: 1,
+        name: 'Type Name',
+        sort: 1,
+      },
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: Product = {
+      id: 1,
+      translations: [],
+      cover: {
+        id: 'cover-file-uuid-1234',
+      },
+      product_type: {
+        id: 20,
+        translations: [],
+        sort: 1,
+      },
+    };
+
+    expect(toProductListView(rawData)).toEqual({
+      id: 1,
+      name: '',
+      summary: '',
+      cover: 'cover-file-uuid-1234',
+      product_type: {
+        id: 20,
+        name: '',
+        sort: 1,
+      },
+    });
+  });
+});
+
+/**
+ * 单元测试: toProductSpecView
+ */
+describe('toProductSpecView', () => {
+  test('convert raw data to ProductSpecView correctly', () => {
+    const rawData: ProductSpec = {
+      id: 1,
+      translations: [{ id: 1, key: 'Key', value: 'Value' }],
+    };
+
+    expect(toProductSpecView(rawData)).toEqual({
+      id: 1,
+      key: 'Key',
+      value: 'Value',
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: ProductSpec = {
+      id: 1,
+      translations: [],
+    };
+
+    expect(toProductSpecView(rawData)).toEqual({
+      id: 1,
+      key: '',
+      value: '',
+    });
+  });
+});
+
+/**
+ * 单元测试: toProductSpecGroupView
+ */
+describe('toProductSpecGroupView', () => {
+  test('convert raw data to ProductSpecGroupView correctly', () => {
+    const rawData: ProductSpecGroup = {
+      id: 1,
+      translations: [{ id: 1, name: 'Group Name' }],
+      specs: [
+        { id: 1, translations: [{ id: 1, key: 'Key1', value: 'Value1' }] },
+        { id: 2, translations: [{ id: 2, key: 'Key2', value: 'Value2' }] },
+      ],
+    };
+
+    expect(toProductSpecGroupView(rawData)).toEqual({
+      id: 1,
+      name: 'Group Name',
+      specs: [
+        { id: 1, key: 'Key1', value: 'Value1' },
+        { id: 2, key: 'Key2', value: 'Value2' },
+      ],
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: ProductSpecGroup = {
+      id: 1,
+      translations: [],
+      specs: [],
+    };
+
+    expect(toProductSpecGroupView(rawData)).toEqual({
+      id: 1,
+      name: '',
+      specs: [],
+    });
+  });
+});
+
+/**
+ * 单元测试: toProductView
+ */
+describe('toProductView', () => {
+  test('convert raw data to ProductView correctly', () => {
+    const rawData: Product = {
+      id: 1,
+      translations: [
+        {
+          id: 1,
+          name: 'Product Name',
+          summary: 'Product Summary',
+          description: 'Product Description',
+        },
+      ],
+    };
+
+    expect(toProductView(rawData)).toEqual({
+      id: 1,
+      name: 'Product Name',
+      summary: 'Product Summary',
+      description: 'Product Description',
+      product_type: '',
+      images: [],
+      documents: [],
+      faqs: [],
+      specs: [],
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: Product = {
+      id: 1,
+      translations: [],
+    };
+
+    expect(toProductView(rawData)).toEqual({
+      id: 1,
+      name: '',
+      summary: '',
+      description: '',
+      product_type: '',
+      images: [],
+      documents: [],
+      faqs: [],
+      specs: [],
+    });
+  });
+});

server/mappers/productMapper.ts

@@ -0,0 +1,154 @@
+import { toProductQuestionView } from './questionMapper';
+import { toProductDocumentView } from './documentMapper';
+
+/**
+ * 将Directus返回的ProductType数据转换为ProductTypeView视图模型
+ *
+ * @param raw: 原始的ProductType数据
+ * @returns 转换后的ProductTypeView对象
+ *
+ * @example
+ * const view = toProductTypeView(rawProductType);
+ */
+export function toProductTypeView(raw: ProductType): ProductTypeView {
+  const trans = raw.translations?.[0] ?? { name: '' };
+
+  return {
+    id: raw.id,
+    name: trans.name,
+    sort: raw?.sort ?? 999,
+  };
+}
+
+/**
+ * 将 Directus返回的 Product 数据转换为 ProductListView 视图模型
+ *
+ * @param raw: 原始的 Product 数据
+ * @returns 转换后的 ProductListView 对象
+ *
+ * @example
+ * const view = toProductListView(rawProduct);
+ */
+export function toProductListView(raw: Product): ProductListView {
+  const trans = raw.translations?.[0];
+
+  const type = isObject<ProductType>(raw.product_type)
+    ? toProductTypeView(raw.product_type)
+    : ({
+        id: -1,
+        name: '',
+        sort: 999,
+      } satisfies ProductTypeView);
+
+  const cover = isObject<DirectusFile>(raw.cover) ? raw.cover.id : '';
+
+  return {
+    id: raw.id,
+    product_type: type,
+    name: trans?.name ?? '',
+    summary: trans?.summary ?? '',
+    cover: cover,
+  };
+}
+
+/**
+ * 将 Directus 返回的 ProductSpecGroup 数据转换为 ProductSpecGroupView 视图模型
+ *
+ * @param raw: 原始的 ProductSpecGroup 数据
+ * @returns 转换后的 ProductSpecGroupView 对象
+ *
+ * @example
+ * const view = toProductSpecGroupView(rawSpecGroup);
+ */
+export function toProductSpecGroupView(
+  raw: ProductSpecGroup
+): ProductSpecGroupView {
+  const trans = raw.translations?.[0];
+
+  const specs = raw.specs ?? [];
+
+  return {
+    id: raw.id,
+    name: trans?.name ?? '',
+    specs: specs
+      .filter(isObject<ProductSpec>)
+      .map((item) => toProductSpecView(item)),
+  };
+}
+
+/**
+ * 将 Directus 返回的 ProductSpec 数据转换为 ProductSpecView 视图模型
+ *
+ * @param raw: 原始的 ProductSpec 数据
+ * @returns 转换后的 ProductSpecView 对象
+ *
+ * @example
+ * const view = toProductSpecView(rawSpecGroup);
+ */
+export function toProductSpecView(raw: ProductSpec): ProductSpecView {
+  const trans = raw.translations?.[0];
+
+  return {
+    id: raw.id,
+    key: trans?.key ?? '',
+    value: trans?.value ?? '',
+  };
+}
+
+/**
+ * 将 Directus 返回的 Product 数据转换为 ProductView 视图模型
+ *
+ * @param raw: 原始的 Product 数据
+ * @returns 转换后的 ProductView 对象
+ *
+ * @example
+ * const view = toProductView(rawProduct);
+ */
+export function toProductView(raw: Product): ProductView {
+  const trans = raw.translations?.[0];
+
+  const images = (raw.images ?? [])
+    .filter(isObject<ProductsProductImage>)
+    .map((item) => item.product_images_id)
+    .filter(isObject<ProductImage>)
+    .map((item) => {
+      const image = isObject<DirectusFile>(item.image) ? item.image.id : '';
+      return {
+        id: item.id,
+        image: image,
+        caption: item.translations?.[0]?.caption || '',
+      };
+    });
+
+  const type = isObject<ProductType>(raw.product_type)
+    ? (raw.product_type.translations?.[0]?.name ?? '')
+    : '';
+
+  const specs = (raw.specs ?? [])
+    .filter(isObject<ProductSpecGroup>)
+    .map((item) => toProductSpecGroupView(item));
+
+  const faqs = (raw.faqs ?? [])
+    .filter(isObject<ProductsQuestion>)
+    .map((item) => item.questions_id)
+    .filter(isObject<Question>)
+    .map((item) => toProductQuestionView(item));
+
+  const documents = (raw.documents ?? [])
+    .filter(isObject<ProductsProductDocument>)
+    .map((item) => item.product_documents_id)
+    .filter(isObject<ProductDocument>)
+    .map((item) => toProductDocumentView(item));
+
+  return {
+    id: raw.id,
+    product_type: type,
+    name: trans?.name ?? '',
+    summary: trans?.summary ?? '',
+    images: images,
+    description: trans?.description ?? '',
+    specs: specs,
+    faqs: faqs,
+    documents: documents,
+  };
+}

server/mappers/questionMapper.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'vitest';
+import { toProductQuestionView, toQuestionListView } from './questionMapper';
+
+/**
+ * 单元测试: toProductQuestionView
+ */
+describe('toProductQuestionView', () => {
+  const baseData: Question = {
+    id: 1,
+    translations: [
+      { id: 1, title: 'Question Title', content: 'Question Answer' },
+    ],
+  };
+  test('convert raw data to ProductQuestionView correctly', () => {
+    const rawData: Question = {
+      ...baseData,
+    };
+
+    expect(toProductQuestionView(rawData)).toEqual({
+      id: 1,
+      title: 'Question Title',
+      content: 'Question Answer',
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: Question = {
+      ...baseData,
+      translations: [],
+    };
+
+    expect(toProductQuestionView(rawData)).toEqual({
+      id: 1,
+      title: '',
+      content: '',
+    });
+  });
+});
+
+/**
+ * 单元测试: toQuestionListView
+ */
+describe('toQuestionListView', () => {
+  const baseData: Question = {
+    id: 1,
+    translations: [
+      { id: 1, title: 'Question Title', content: 'Question Answer' },
+    ],
+    products: [
+      {
+        id: 1,
+        products_id: {
+          id: 1,
+          translations: [{ id: 1, name: 'Product Name' }],
+          product_type: {
+            id: 1,
+            translations: [{ id: 1, name: 'Type Name' }],
+          },
+        },
+      },
+    ],
+  };
+
+  test('convert raw data to QuestionListView correctly', () => {
+    const rawData: Question = {
+      ...baseData,
+    };
+
+    expect(toQuestionListView(rawData)).toEqual({
+      id: 1,
+      title: 'Question Title',
+      content: 'Question Answer',
+      products: [
+        {
+          id: 1,
+          name: 'Product Name',
+          type: {
+            id: 1,
+            name: 'Type Name',
+          },
+        },
+      ],
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: Question = {
+      ...baseData,
+      translations: [],
+      products: [
+        {
+          id: 1,
+          products_id: {
+            id: 1,
+            translations: [],
+            product_type: {
+              id: 1,
+              translations: [],
+            },
+          },
+        },
+      ],
+    };
+
+    expect(toQuestionListView(rawData)).toEqual({
+      id: 1,
+      title: '',
+      content: '',
+      products: [
+        {
+          id: 1,
+          name: '',
+          type: {
+            id: 1,
+            name: '',
+          },
+        },
+      ],
+    });
+  });
+});

server/mappers/questionMapper.ts

@@ -0,0 +1,62 @@
+/**
+ * 将 Directus 返回的 Question 数据转换为 ProductQuestionView 视图模型
+ *
+ * @param raw: 原始的 Question 数据
+ * @returns 转换后的 ProductQuestionView 对象
+ *
+ * @example
+ * const view = toProductQuestionView(rawQuestion);
+ */
+export function toProductQuestionView(raw: Question): ProductQuestionView {
+  const trans = raw.translations?.[0];
+
+  return {
+    id: raw.id,
+    title: trans?.title ?? '',
+    content: trans?.content ?? '',
+  };
+}
+
+/**
+ * 将 Directus 返回的 Question 数据转换为 QuestionListView 视图模型
+ *
+ * @param raw: 原始的 Question 数据
+ * @returns 转换后的 QuestionListView 对象
+ * ---
+ *  @example
+ *  const view = toQuestionListView(rawQuestion);
+ */
+export function toQuestionListView(raw: Question): QuestionListView {
+  const trans = raw.translations?.[0];
+
+  const related_products: QuestionListProduct[] = (raw.products ?? [])
+    .filter(isObject<ProductsQuestion>)
+    .map((item) => item.products_id)
+    .filter(isObject<Product>)
+    .map((item) => {
+      const translations = item.translations?.[0];
+
+      const product_type = isObject<ProductType>(item.product_type)
+        ? ({
+            id: item.product_type.id,
+            name: item.product_type.translations?.[0]?.name ?? '',
+          } satisfies QuestionListProductType)
+        : ({
+            id: -1,
+            name: '',
+          } satisfies QuestionListProductType);
+
+      return {
+        id: item.id,
+        name: translations?.name ?? '',
+        type: product_type,
+      };
+    });
+
+  return {
+    id: raw.id,
+    title: trans?.title ?? '',
+    content: trans?.content ?? '',
+    products: related_products,
+  };
+}

server/mappers/searchItemMapper.ts

@@ -0,0 +1,16 @@
+/**
+ * 搜索索引转换器
+ * @param hit 搜索条目
+ * @returns 转换后的搜索条目视图模型
+ *
+ * ---
+ *  @example
+ *  const view = toSearchItemView(item, 'products');
+ */
+export function toSearchItemView<T extends MeiliSearchItemType>(
+  item: MeiliIndexMap[T],
+  type: T
+): SearchItemView {
+  const converter = converters[type];
+  return converter(item);
+}

server/mappers/solutionMapper.test.ts

@@ -0,0 +1,100 @@
+import { describe, test, expect } from 'vitest';
+import { toSolutionListView, toSolutionView } from './solutionMapper';
+
+/**
+ * 单元测试: toSolutionListView
+ */
+describe('toSolutionListView', () => {
+  const baseData: Solution = {
+    id: 1,
+    translations: [
+      { id: 1, title: 'Solution Title', summary: 'Solution Summary' },
+    ],
+    type: {
+      id: 1,
+      translations: [{ id: 1, name: 'Type Name' }],
+      sort: 1,
+    },
+  };
+  test('convert raw data to SolutionListView correctly', () => {
+    const rawData: Solution = { ...baseData };
+
+    expect(toSolutionListView(rawData)).toEqual({
+      id: 1,
+      title: 'Solution Title',
+      summary: 'Solution Summary',
+      solution_type: {
+        id: 1,
+        name: 'Type Name',
+        sort: 1,
+      },
+      cover: '',
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: Solution = {
+      ...baseData,
+      translations: [],
+    };
+
+    expect(toSolutionListView(rawData)).toEqual({
+      id: 1,
+      title: '',
+      summary: '',
+      solution_type: {
+        id: 1,
+        name: 'Type Name',
+        sort: 1,
+      },
+      cover: '',
+    });
+  });
+});
+
+/**
+ * 单元测试: toSolutionView
+ */
+describe('toSolutionView', () => {
+  const baseData: Solution = {
+    id: 1,
+    translations: [
+      {
+        id: 1,
+        title: 'Solution Title',
+        summary: 'Solution Summary',
+        content: 'Solution Content',
+      },
+    ],
+    create_at: '2023-01-01T00:00:00Z',
+  };
+
+  test('convert raw data to SolutionView correctly', () => {
+    const rawData: Solution = {
+      ...baseData,
+    };
+
+    expect(toSolutionView(rawData)).toEqual({
+      id: 1,
+      title: 'Solution Title',
+      summary: 'Solution Summary',
+      content: 'Solution Content',
+      createAt: '2023-01-01T00:00:00Z',
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: Solution = {
+      ...baseData,
+      translations: [],
+    };
+
+    expect(toSolutionView(rawData)).toEqual({
+      id: 1,
+      title: '',
+      summary: '',
+      content: '',
+      createAt: '2023-01-01T00:00:00Z',
+    });
+  });
+});

server/mappers/solutionMapper.ts

@@ -0,0 +1,76 @@
+/**
+ * 将 Directus 返回的 SolutionType 数据转换为 SolutionTypeView 视图模型
+ *
+ * @param raw: 原始的 SolutionType 数据
+ * @returns 转换后的 SolutionTypeView 对象
+ *
+ * ---
+ *
+ *  @example
+ *  const view = toSolutionTypeView(rawSolutionType);
+ */
+export function toSolutionTypeView(raw: SolutionType): SolutionTypeView {
+  const trans = raw?.translations?.[0];
+
+  return {
+    id: raw.id,
+    name: trans?.name ?? '',
+    sort: raw?.sort ?? 999,
+  };
+}
+
+/**
+ * 将 Directus 返回的 Solution 数据转换为 SolutionListView 视图模型
+ *
+ * @param raw: 原始的 Solution 数据
+ * @returns 转换后的 SolutionListView 对象
+ *
+ * ---
+ *
+ * @example
+ * const view = toSolutionListView(rawSolution);
+ */
+export function toSolutionListView(raw: Solution): SolutionListView {
+  const trans = raw.translations?.[0];
+
+  const type = isObject<SolutionType>(raw.type)
+    ? toSolutionTypeView(raw.type)
+    : ({
+        id: -1,
+        name: 'uncategory',
+        sort: 999,
+      } satisfies SolutionTypeView);
+
+  const cover = isObject<DirectusFile>(raw.cover) ? (raw?.cover.id ?? '') : '';
+
+  return {
+    id: raw.id,
+    title: trans?.title ?? '',
+    summary: trans?.summary ?? '',
+    solution_type: type,
+    cover: cover,
+  };
+}
+
+/**
+ * 将 Directus 返回的 Solution 数据转换为 SolutionView 视图模型
+ *
+ * @param raw: 原始的 Solution 数据
+ * @returns 转换后的 SolutionView 对象
+ *
+ * ---
+ *
+ * @example
+ * const view = toSolutionView(rawSolution);
+ */
+export function toSolutionView(raw: Solution): SolutionView {
+  const trans = raw.translations?.[0];
+
+  return {
+    id: raw.id,
+    title: trans?.title ?? '',
+    summary: trans?.summary ?? '',
+    content: trans?.content ?? '',
+    createAt: raw?.create_at ?? '',
+  };
+}

server/services/cms/companyProfileService.ts

@@ -0,0 +1,25 @@
+import { toCompanyProfileView } from '~~/server/mappers/companyProfileMapper';
+
+export const companyProfileService = {
+  async getCompanyProfile(locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/companyProfile.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ company_profile: CompanyProfile }>(
+      query,
+      {
+        locale: locale,
+      }
+    );
+
+    return toCompanyProfileView(data?.company_profile);
+  },
+};

server/services/cms/contactInfoService.ts

@@ -0,0 +1,22 @@
+import { toContactInfoView } from '~~/server/mappers/contactInfoMapper';
+
+export const contactInfoService = {
+  async getContactInfo(locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/contactInfo.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ contact_info: ContactInfo }>(query, {
+      locale: locale,
+    });
+
+    return toContactInfoView(data?.contact_info);
+  },
+};

server/services/cms/documentService.ts

@@ -0,0 +1,27 @@
+import { toDocumentListView } from '~~/server/mappers/documentMapper';
+
+export const documentService = {
+  async getDocumentList(locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/documentList.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ product_documents: ProductDocument[] }>(
+      query,
+      {
+        locale: locale,
+      }
+    );
+
+    const documents = data?.product_documents || [];
+
+    return documents.map((document) => toDocumentListView(document));
+  },
+};

server/services/cms/homepageService.ts

@@ -0,0 +1,22 @@
+import { toHomepageView } from '~~/server/mappers/homepageMapper';
+
+export const homepageService = {
+  async getHomepage(locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/homepage.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ homepage: Homepage }>(query, {
+      locale: locale,
+    });
+
+    return toHomepageView(data?.homepage);
+  },
+};

server/services/cms/productService.ts

@@ -0,0 +1,55 @@
+import {
+  toProductView,
+  toProductListView,
+} from '~~/server/mappers/productMapper';
+
+export const productService = {
+  async getProductList(locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/productList.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ products: Product[] }>(query, {
+      locale: locale,
+    });
+
+    const products = data?.products || [];
+
+    return products.map((product) => toProductListView(product));
+  },
+  async getProductById(id: string, locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/product.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ products_by_id: Product }>(query, {
+      id: id,
+      locale: locale,
+    });
+
+    const product = data?.products_by_id;
+
+    if (!product || product.status === 'archived') {
+      throw createError({
+        statusCode: 404,
+        statusMessage: 'Product not found',
+      });
+    }
+
+    return toProductView(product);
+  },
+};

server/services/cms/questionService.ts

@@ -0,0 +1,24 @@
+import { toQuestionListView } from '~~/server/mappers/questionMapper';
+
+export const questionService = {
+  async getQuestionList(locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/questionList.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ questions: Question[] }>(query, {
+      locale: locale,
+    });
+
+    const questions = data?.questions || [];
+
+    return questions.map((question) => toQuestionListView(question));
+  },
+};

server/services/cms/solutionService.ts

@@ -0,0 +1,55 @@
+import {
+  toSolutionView,
+  toSolutionListView,
+} from '~~/server/mappers/solutionMapper';
+
+export const solutionService = {
+  async getSolutionList(locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/solutionList.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ solutions: Solution[] }>(query, {
+      locale: locale,
+    });
+
+    const solutions = data?.solutions || [];
+
+    return solutions.map((solution) => toSolutionListView(solution));
+  },
+  async getSolutionById(id: string, locale: string) {
+    const query = await loadAssetAsString(
+      'assets/server',
+      'graphql/solution.graphql'
+    );
+    if (!query) {
+      throw createError({
+        statusCode: 500,
+        message: 'GraphQL query not found',
+      });
+    }
+
+    const data = await directus.query<{ solutions_by_id: Solution }>(query, {
+      id: id,
+      locale: locale,
+    });
+
+    const solution = data?.solutions_by_id;
+
+    if (!solution || solution.status === 'archived') {
+      throw createError({
+        statusCode: 404,
+        statusMessage: 'Solution not found',
+      });
+    }
+
+    return toSolutionView(solution);
+  },
+};

server/utils/object.test.ts

@@ -0,0 +1,66 @@
+import { expect, test, describe } from 'vitest';
+
+/**
+ * 单元测试: isObject
+ */
+describe('isObject', () => {
+  test('identify plain object', () => {
+    expect(isObject({})).toBe(true);
+    expect(isObject({ key: 'value' })).toBe(true);
+  });
+  test('identify null as non objevt', () => {
+    expect(isObject(null)).toBe(false);
+  });
+  test('identify non-object types', () => {
+    expect(isObject(undefined)).toBe(false);
+    expect(isObject(42)).toBe(false);
+    expect(isObject('string')).toBe(false);
+    expect(isObject(Symbol('sym'))).toBe(false);
+    expect(isObject(true)).toBe(false);
+    expect(isObject(() => {})).toBe(false);
+  });
+  test('identify arrays as objects', () => {
+    expect(isObject([])).toBe(true);
+  });
+  test('identify narrowed object type', () => {
+    const value: unknown = { id: 1 };
+    if (isObject<{ id: number }>(value)) {
+      expect(value.id).toBe(1);
+    } else {
+      throw new Error('Type narrowing failed');
+    }
+  });
+});
+
+/**
+ * 单元测试: isArrayOfObject
+ */
+describe('isArrayOfObject', () => {
+  test('identify array of plain objects', () => {
+    const arr = [{ id: 1 }, { name: 'Alice' }];
+    expect(isArrayOfObject<{ id?: number; name?: string }>(arr)).toBe(true);
+  });
+  test('identify array containing non-objects', () => {
+    expect(isArrayOfObject([1, 2, 3])).toBe(false);
+    expect(isArrayOfObject([{ id: 1 }, null])).toBe(false);
+    expect(isArrayOfObject([{ id: 1 }, 'string'])).toBe(false);
+  });
+  test('identify non-array types', () => {
+    expect(isArrayOfObject(null)).toBe(false);
+    expect(isArrayOfObject({})).toBe(false);
+    expect(isArrayOfObject(42)).toBe(false);
+  });
+  test('identify empty array as array of objects', () => {
+    expect(isArrayOfObject([])).toBe(true);
+  });
+  test('identify narrowed array of object type', () => {
+    const data: unknown = [{ id: 1 }, { id: 2 }];
+    if (isArrayOfObject<{ id: number }>(data)) {
+      // TS 能识别为 { id: number }[]
+      expect(data[0].id).toBe(1);
+      expect(data[1].id).toBe(2);
+    } else {
+      throw new Error('Type guard failed');
+    }
+  });
+});

server/utils/object.ts

@@ -0,0 +1,30 @@
+/**
+ * 判断某一值是否为非null对象
+ *
+ * @template T 泛型类型，用于推断目标对象的类型
+ * @param value: 需要判断的值
+ * @returns 如果值是非null对象则返回true，否则返回false
+ *
+ * @example
+ * if (isObject<Product>(value)) value.id
+ */
+export const isObject = <T extends object>(value: unknown): value is T =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * 判断某一值是否为非null对象组成的数组
+ *
+ * @template T 泛型类型，用于推断目标对象的类型
+ * @param value: 需要判断的值
+ * @returns 如果值是非null对象组成的数组则返回true，否则返回false
+ *
+ * @example
+ * const data: unknown = [{ id: 1 }, { id: 2 }];
+ * if (isArrayOfObject)<{ id: number }>(data) {
+ * // TypeScript 知道 data 是 { id: number }[] 类型
+ *   console.log(data[0].id);
+ * }
+ */
+export const isArrayOfObject = <T extends object>(arr: unknown): arr is T[] => {
+  return Array.isArray(arr) && arr.every(isObject<T>);
+};

server/utils/search-converter.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'vitest';
+
+/**
+ * 单元测试: converters
+ */
+describe('converters', () => {
+  test('convert product item', () => {
+    const item = {
+      id: 1,
+      name: 'Hydraulic Pump',
+      summary: 'High efficiency',
+      description: 'Detailed description',
+      type: 'pump',
+    };
+    const result = converters.products(item);
+    expect(result).toEqual({
+      id: 1,
+      type: 'product',
+      title: 'Hydraulic Pump',
+      summary: 'High efficiency',
+    });
+  });
+
+  test('convert solution item', () => {
+    const item = {
+      id: 1,
+      title: 'Solution A',
+      summary: 'Effective solution',
+      content: 'Detailed content',
+      type: 'Type A',
+    };
+    const result = converters.solutions(item);
+    expect(result).toEqual({
+      id: 1,
+      type: 'solution',
+      title: 'Solution A',
+      summary: 'Effective solution',
+    });
+  });
+
+  test('convert question item', () => {
+    const item = {
+      id: 1,
+      title: 'How to use product?',
+      content:
+        'This is a detailed explanation of how to use the product effectively.',
+      products: ['Product A'],
+      product_types: ['Type A'],
+    };
+    const result = converters.questions(item);
+    expect(result).toEqual({
+      id: 1,
+      title: 'How to use product?',
+      summary:
+        'This is a detailed explanation of how to use the product effectively....',
+      type: 'question',
+    });
+  });
+
+  test('convert product document item', () => {
+    const item = {
+      id: 1,
+      title: 'User Manual',
+      products: ['Product A'],
+      product_types: ['Type A'],
+      fileUUID: 'TEST-UUID',
+    };
+    const result = converters.product_documents(item);
+    expect(result).toEqual({
+      id: 'TEST-UUID',
+      title: 'User Manual',
+      summary: undefined,
+      type: 'document',
+    });
+  });
+});

server/utils/search-converters.ts

@@ -0,0 +1,36 @@
+/**
+ * 各索引对应的转换函数表
+ */
+export const converters: {
+  [K in keyof MeiliIndexMap]: (item: MeiliIndexMap[K]) => SearchItemView;
+} = {
+  products: (item: MeiliIndexMap['products']): SearchItemView => ({
+    id: item.id,
+    type: 'product',
+    title: item.name,
+    summary: item.summary,
+  }),
+
+  solutions: (item: MeiliIndexMap['solutions']): SearchItemView => ({
+    id: item.id,
+    type: 'solution',
+    title: item.title,
+    summary: item.summary,
+  }),
+
+  questions: (item: MeiliIndexMap['questions']): SearchItemView => ({
+    id: item.id,
+    type: 'question',
+    title: item.title,
+    summary: item.content.slice(0, 100) + '...',
+  }),
+
+  product_documents: (
+    item: MeiliIndexMap['product_documents']
+  ): SearchItemView => ({
+    id: item.fileUUID || item.id,
+    type: 'document',
+    title: item.title,
+    summary: '',
+  }),
+};