refactor(mapper): 为Server端的Mapper添加空值处理与类型控制逻辑

- 空值处理与类型控制：为相关关系型字段的数据处理添加空值处理与类型控制
- 目录结构调整：分离Product/ProductList与Solution/SolutionList
- 修复bug：修复产品页与解决方案页无法正常触发404逻辑的问题

app/pages/products/[slug].vue

@@ -53,8 +53,8 @@
 
   // SEO
   usePageSeo({
-    title: product.value.name || $t('page-title.products'),
-    description: product.value.summary || '',
+    title: product.value?.name || $t('page-title.products'),
+    description: product.value?.summary || '',
   });
 </script>
 

app/pages/solutions/[slug].vue

@@ -44,8 +44,8 @@
   });
 
   usePageSeo({
-    title: solution.value.title || $t('page-title.solutions'),
-    description: solution.value.summary || '',
+    title: solution.value?.title || $t('page-title.solutions'),
+    description: solution.value?.summary || '',
   });
 </script>
 

server/mappers/documentMapper.test.ts

@@ -1,9 +1,5 @@
 import { describe, test, expect } from 'vitest';
-import {
-  toProductDocumentView,
-  toDocumentListView,
-  toDocumentTypeView,
-} from './documentMapper';
+import { toDocumentListView, toDocumentTypeView } from './documentMapper';
 
 /**
  * 单元测试: toDocumentTypeView
@@ -46,63 +42,6 @@ describe('toDocumentTypeView', () => {
     });
   });
 });
-/**
- * 单元测试: 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

server/mappers/documentMapper.ts

@@ -26,34 +26,6 @@ export function toDocumentTypeView(
   };
 }
 
-/**
- * 将 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.toString(),
-    fileId: fileId,
-    filename: file?.filename_download ?? '',
-    title: trans?.title ?? '',
-    url: url,
-    size: file?.filesize ?? 0,
-  };
-}
-
 /**
  * 将 Directus 返回的 Document 数据转换为 DocumentListView 视图模型
  *

server/mappers/productListMapper.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from 'vitest';
+import { toProductTypeView, toProductListView } from './productListMapper';
+
+/**
+ * 单元测试: toProductTypeView
+ */
+describe('toProductTypeView', () => {
+  const baseData: ProductType = {
+    id: 1,
+    translations: [
+      {
+        id: 1,
+        name: 'Type Name',
+      },
+    ],
+    sort: 5,
+  };
+
+  test('convert raw data to ProductTypeView correctly', () => {
+    const rawData: ProductType = { ...baseData };
+
+    expect(toProductTypeView(rawData)).toEqual({
+      id: '1',
+      name: 'Type Name',
+      sort: 5,
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: ProductType = {
+      ...baseData,
+      translations: [],
+    };
+
+    expect(toProductTypeView(rawData)).toEqual({
+      id: '1',
+      name: '',
+      sort: 5,
+    });
+  });
+
+  test('convert raw data with missing sort', () => {
+    const rawData: ProductType = {
+      ...baseData,
+      sort: undefined,
+    };
+
+    expect(toProductTypeView(rawData)).toEqual({
+      id: '1',
+      name: 'Type Name',
+      sort: 999,
+    });
+  });
+
+  test('convert null input to default value', () => {
+    const rawData: ProductType | string | null = null;
+
+    expect(toProductTypeView(rawData)).toEqual({
+      id: '-1',
+      name: '',
+      sort: 999,
+    });
+  });
+});
+
+/**
+ * 单元测试: 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,
+      },
+    });
+  });
+});

server/mappers/productListMapper.ts

@@ -0,0 +1,54 @@
+import { isObject } from '../../server/utils/object';
+
+/**
+ * 将Directus返回的ProductType数据转换为ProductTypeView视图模型
+ *
+ * @param raw: 原始的ProductType数据
+ * @returns 转换后的ProductTypeView对象
+ *
+ * @example
+ * const view = toProductTypeView(rawProductType);
+ */
+export function toProductTypeView(
+  raw: ProductType | string | null
+): ProductTypeView {
+  if (typeof raw === 'string' || raw === null) {
+    return {
+      id: '-1',
+      name: '',
+      sort: 999,
+    } satisfies ProductTypeView;
+  }
+  const trans = raw.translations?.[0] ?? { name: '' };
+
+  return {
+    id: raw.id.toString(),
+    name: trans.name,
+    sort: raw?.sort ?? 999,
+  } satisfies ProductTypeView;
+}
+
+/**
+ * 将 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 = toProductTypeView(raw.product_type ?? null);
+
+  const cover = isObject<DirectusFile>(raw.cover) ? raw.cover.id : '';
+
+  return {
+    id: raw.id.toString(),
+    product_type: type,
+    name: trans?.name ?? '',
+    summary: trans?.summary ?? '',
+    cover: cover,
+  } satisfies ProductListView;
+}

server/mappers/productMapper.test.ts

@@ -1,69 +1,111 @@
 import { describe, test, expect } from 'vitest';
 import {
-  toProductListView,
+  toProductImageView,
   toProductSpecView,
   toProductSpecGroupView,
+  toProductQuestionView,
+  toProductDocumentView,
   toProductView,
 } from './productMapper';
 
 /**
- * 单元测试: toProductListView
+ * 单元测试: toProductImageView
  */
-describe('toProductListView', () => {
-  test('convert raw data to ProductListView correctly', () => {
-    const rawData: Product = {
+describe('toProductImageView', () => {
+  const baseData: Array<ProductsProductImage> = [
+    {
       id: 1,
+      product_images_id: {
+        id: 1,
+        image: {
+          id: 'rand-om__-uuid-1234',
+        },
         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,
+            caption: 'Image Caption',
           },
-    };
+        ],
+      },
+    },
+    {
+      id: 2,
+      product_images_id: {
+        id: 2,
+        image: {
+          id: 'rand-om__-uuid-5678',
+        },
+        translations: [
+          {
+            id: 2,
+            caption: 'Image Caption 2',
+          },
+        ],
+      },
+    },
+  ];
 
-    expect(toProductListView(rawData)).toEqual({
+  test('convert raw data to ProductImageView correctly', () => {
+    const rawData: Array<ProductsProductImage> = [...baseData];
+
+    expect(toProductImageView(rawData)).toEqual([
+      {
         id: '1',
-      name: 'Product Name',
-      summary: 'Product Summary',
-      cover: 'cover-file-uuid-1234',
-      product_type: {
-        id: '1',
-        name: 'Type Name',
-        sort: 1,
+        image: 'rand-om__-uuid-1234',
+        caption: 'Image Caption',
       },
-    });
+      {
+        id: '2',
+        image: 'rand-om__-uuid-5678',
+        caption: 'Image Caption 2',
+      },
+    ]);
   });
 
   test('convert raw data with missing translations', () => {
-    const rawData: Product = {
+    const rawData: Array<ProductsProductImage> = [
+      {
         id: 1,
-      translations: [],
-      cover: {
-        id: 'cover-file-uuid-1234',
+        product_images_id: {
+          id: 1,
+          image: {
+            id: 'rand-om__-uuid-1234',
           },
-      product_type: {
-        id: 20,
           translations: [],
-        sort: 1,
         },
-    };
+      },
+    ];
 
-    expect(toProductListView(rawData)).toEqual({
+    expect(toProductImageView(rawData)).toEqual([
+      {
         id: '1',
-      name: '',
-      summary: '',
-      cover: 'cover-file-uuid-1234',
-      product_type: {
-        id: '20',
-        name: '',
-        sort: 1,
+        image: 'rand-om__-uuid-1234',
+        caption: '',
       },
+    ]);
   });
+
+  test('convert empty array to empty ProductImageView array', () => {
+    const rawData: Array<ProductsProductImage> = [];
+
+    expect(toProductImageView(rawData)).toEqual([]);
+  });
+
+  test('convert input with wrong type to default value', () => {
+    const rawData: string[] = ['1', '2'];
+
+    expect(toProductImageView(rawData)).toEqual([
+      {
+        id: '1',
+        image: '',
+        caption: '',
+      },
+      {
+        id: '2',
+        image: '',
+        caption: '',
+      },
+    ]);
   });
 });
 
@@ -71,30 +113,78 @@ describe('toProductListView', () => {
  * 单元测试: toProductSpecView
  */
 describe('toProductSpecView', () => {
-  test('convert raw data to ProductSpecView correctly', () => {
-    const rawData: ProductSpec = {
+  const baseData: ProductSpec[] = [
+    {
       id: 1,
-      translations: [{ id: 1, key: 'Key', value: 'Value' }],
-    };
+      translations: [
+        {
+          id: 1,
+          key: 'key 1',
+          value: 'value 1',
+        },
+      ],
+    },
+    {
+      id: 2,
+      translations: [
+        {
+          id: 2,
+          key: 'key 2',
+          value: 'value 2',
+        },
+      ],
+    },
+  ];
+  test('convert raw data to ProductSpecView correctly', () => {
+    const rawData: ProductSpec[] = [...baseData];
 
-    expect(toProductSpecView(rawData)).toEqual({
+    expect(toProductSpecView(rawData)).toEqual([
+      {
         id: '1',
-      key: 'Key',
-      value: 'Value',
-    });
+        key: 'key 1',
+        value: 'value 1',
+      },
+      {
+        id: '2',
+        key: 'key 2',
+        value: 'value 2',
+      },
+    ]);
   });
 
   test('convert raw data with missing translations', () => {
-    const rawData: ProductSpec = {
-      id: 1,
-      translations: [],
-    };
+    const rawData: ProductSpec[] = [{ id: 1, translations: [] }];
 
-    expect(toProductSpecView(rawData)).toEqual({
+    expect(toProductSpecView(rawData)).toEqual([
+      {
         id: '1',
         key: '',
         value: '',
+      },
+    ]);
   });
+
+  test('convert empty input to empty array', () => {
+    const rawData: ProductSpec[] = [];
+
+    expect(toProductSpecView(rawData)).toEqual([]);
+  });
+
+  test('convert input with wrong type to default value', () => {
+    const rawData: string[] = ['1', '2'];
+
+    expect(toProductSpecView(rawData)).toEqual([
+      {
+        id: '1',
+        key: '',
+        value: '',
+      },
+      {
+        id: '2',
+        key: '',
+        value: '',
+      },
+    ]);
   });
 });
 
@@ -103,37 +193,237 @@ describe('toProductSpecView', () => {
  */
 describe('toProductSpecGroupView', () => {
   test('convert raw data to ProductSpecGroupView correctly', () => {
-    const rawData: ProductSpecGroup = {
+    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({
+    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 = {
+    const rawData: ProductSpecGroup[] = [
+      {
         id: 1,
         translations: [],
         specs: [],
-    };
+      },
+    ];
 
-    expect(toProductSpecGroupView(rawData)).toEqual({
+    expect(toProductSpecGroupView(rawData)).toEqual([
+      {
         id: '1',
         name: '',
         specs: [],
+      },
+    ]);
   });
+
+  test('convert input with wrong type to default value', () => {
+    const rawData: string[] = ['1', '2'];
+
+    expect(toProductSpecGroupView(rawData)).toEqual([
+      {
+        id: '1',
+        name: '',
+        specs: [],
+      },
+      {
+        id: '2',
+        name: '',
+        specs: [],
+      },
+    ]);
+  });
+
+  test('convert empty ar ray to empty ProductSpecGroupView array', () => {
+    const rawData: ProductSpec[] = [];
+
+    expect(toProductSpecGroupView(rawData)).toEqual([]);
+  });
+});
+
+/**
+ * 单元测试: toProductQuestionView
+ */
+describe('toProductQuestionView', () => {
+  test('convert raw data to ProductQuestionView correctly', () => {
+    const rawData: ProductsQuestion[] = [
+      {
+        id: 1,
+        questions_id: {
+          id: 1,
+          translations: [
+            {
+              id: 1,
+              title: 'Question Title',
+              content: 'Question Content',
+            },
+          ],
+        },
+      },
+    ];
+
+    expect(toProductQuestionView(rawData)).toEqual([
+      {
+        id: '1',
+        title: 'Question Title',
+        content: 'Question Content',
+      },
+    ]);
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: ProductsQuestion[] = [
+      {
+        id: 1,
+        questions_id: {
+          id: 1,
+          translations: [],
+        },
+      },
+    ];
+
+    expect(toProductQuestionView(rawData)).toEqual([
+      {
+        id: '1',
+        title: '',
+        content: '',
+      },
+    ]);
+  });
+
+  test('convert empty array to empty ProductQuestionView array', () => {
+    const rawData: ProductsQuestion[] = [];
+
+    expect(toProductQuestionView(rawData)).toEqual([]);
+  });
+
+  test('convert input with wrong type to default value', () => {
+    const rawData: string[] = ['1', '2'];
+
+    expect(toProductQuestionView(rawData)).toEqual([
+      {
+        id: '1',
+        title: '',
+        content: '',
+      },
+      {
+        id: '2',
+        title: '',
+        content: '',
+      },
+    ]);
+  });
+});
+
+/**
+ * 单元测试: toProductDocumentView
+ */
+describe('toProductDocumentView', () => {
+  test('convert raw data to ProductDocumentView correctly', () => {
+    const rawData: ProductsProductDocument[] = [
+      {
+        id: 1,
+        product_documents_id: {
+          id: 1,
+          file: {
+            id: 'rand-om__-uuid-1234',
+            filesize: 1000,
+            filename_download: 'doc1.pdf',
+          },
+          translations: [
+            {
+              id: 1,
+              title: 'Document Title 1',
+            },
+          ],
+        },
+      },
+    ];
+
+    expect(toProductDocumentView(rawData)).toEqual([
+      {
+        id: '1',
+        fileId: 'rand-om__-uuid-1234',
+        filename: 'doc1.pdf',
+        title: 'Document Title 1',
+        size: 1000,
+        url: '/api/assets/rand-om__-uuid-1234',
+      },
+    ]);
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: ProductsProductDocument[] = [
+      {
+        id: 1,
+        product_documents_id: {
+          id: 1,
+          file: {
+            id: 'rand-om__-uuid-1234',
+            filesize: 1000,
+            filename_download: 'doc1.pdf',
+          },
+          translations: [],
+        },
+      },
+    ];
+
+    expect(toProductDocumentView(rawData)).toEqual([
+      {
+        id: '1',
+        fileId: 'rand-om__-uuid-1234',
+        filename: 'doc1.pdf',
+        title: '',
+        size: 1000,
+        url: '/api/assets/rand-om__-uuid-1234',
+      },
+    ]);
+  });
+
+  test('convert empty array to empty ProductDocumentView array', () => {
+    const rawData: ProductsProductDocument[] = [];
+
+    expect(toProductDocumentView(rawData)).toEqual([]);
+  });
+
+  test('convert input with wrong type to default value', () => {
+    const rawData: string[] = ['1', '2'];
+
+    expect(toProductDocumentView(rawData)).toEqual([
+      {
+        id: '1',
+        fileId: '',
+        filename: '',
+        title: '',
+        size: 0,
+        url: '',
+      },
+      {
+        id: '2',
+        fileId: '',
+        filename: '',
+        title: '',
+        size: 0,
+        url: '',
+      },
+    ]);
   });
 });
 
@@ -159,7 +449,6 @@ describe('toProductView', () => {
       name: 'Product Name',
       summary: 'Product Summary',
       description: 'Product Description',
-      product_type: '',
       images: [],
       documents: [],
       faqs: [],
@@ -178,7 +467,6 @@ describe('toProductView', () => {
       name: '',
       summary: '',
       description: '',
-      product_type: '',
       images: [],
       documents: [],
       faqs: [],

server/mappers/productMapper.ts

@@ -1,55 +1,41 @@
-import { toProductQuestionView } from './questionMapper';
-import { toProductDocumentView } from './documentMapper';
 import { isObject } from '../../server/utils/object';
 
 /**
- * 将Directus返回的ProductType数据转换为ProductTypeView视图模型
+ * 将 Directus 返回的 ProductImage 数据转换为 ProductImageView 视图模型
  *
- * @param raw: 原始的ProductType数据
- * @returns 转换后的ProductTypeView对象
+ * @param raw: 原始的 ProductsProductImage 数据
+ * @returns 转换后的 ProductImageView 对象
  *
  * @example
- * const view = toProductTypeView(rawProductType);
+ * const view = toProductImageView(rawProductImage);
  */
-export function toProductTypeView(raw: ProductType): ProductTypeView {
-  const trans = raw.translations?.[0] ?? { name: '' };
+export function toProductImageView(
+  raw: (ProductsProductImage | string)[]
+): ProductImageView[] {
+  return (raw ?? []).map((item) => {
+    if (!isObject<ProductsProductImage>(item))
+      return {
+        id: item,
+        image: '',
+        caption: '',
+      } satisfies ProductImageView;
+
+    const image = item.product_images_id;
+    if (!isObject<ProductImage>(image))
+      return {
+        id: item.id.toString(),
+        image: '',
+        caption: '',
+      } satisfies ProductImageView;
+
+    const trans = image.translations?.[0];
 
     return {
-    id: raw.id.toString(),
-    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: '',
-        name: '',
-        sort: 999,
-      } satisfies ProductTypeView);
-
-  const cover = isObject<DirectusFile>(raw.cover) ? raw.cover.id : '';
-
-  return {
-    id: raw.id.toString(),
-    product_type: type,
-    name: trans?.name ?? '',
-    summary: trans?.summary ?? '',
-    cover: cover,
-  };
+      id: item.id.toString(),
+      image: isObject<DirectusFile>(image.image) ? image.image.id : '',
+      caption: trans?.caption || '',
+    } satisfies ProductImageView;
+  });
 }
 
 /**
@@ -62,19 +48,26 @@ export function toProductListView(raw: Product): ProductListView {
  * const view = toProductSpecGroupView(rawSpecGroup);
  */
 export function toProductSpecGroupView(
-  raw: ProductSpecGroup
-): ProductSpecGroupView {
-  const trans = raw.translations?.[0];
+  raw: (ProductSpecGroup | string)[]
+): ProductSpecGroupView[] {
+  return (raw ?? []).map((item) => {
+    if (!isObject<ProductSpecGroup>(item)) {
+      return {
+        id: item,
+        name: '',
+        specs: [],
+      } satisfies ProductSpecGroupView;
+    }
+    const trans = item.translations?.[0];
 
-  const specs = raw.specs ?? [];
+    const specs = toProductSpecView(item?.specs ?? []);
 
     return {
-    id: raw.id.toString(),
+      id: item.id.toString(),
       name: trans?.name ?? '',
-    specs: specs
-      .filter(isObject<ProductSpec>)
-      .map((item) => toProductSpecView(item)),
-  };
+      specs: specs,
+    } satisfies ProductSpecGroupView;
+  });
 }
 
 /**
@@ -86,14 +79,120 @@ export function toProductSpecGroupView(
  * @example
  * const view = toProductSpecView(rawSpecGroup);
  */
-export function toProductSpecView(raw: ProductSpec): ProductSpecView {
-  const trans = raw.translations?.[0];
+export function toProductSpecView(
+  raw: (ProductSpec | string)[]
+): ProductSpecView[] {
+  return (raw ?? []).map((item) => {
+    if (!isObject<ProductSpec>(item)) {
+      return {
+        id: item,
+        key: '',
+        value: '',
+      } satisfies ProductSpecView;
+    }
+    const trans = item.translations?.[0];
 
     return {
-    id: raw.id.toString(),
+      id: item.id.toString(),
       key: trans?.key ?? '',
       value: trans?.value ?? '',
-  };
+    } satisfies ProductSpecView;
+  });
+}
+
+/**
+ * 将 Directus 返回的 ProductQuestion 数据转换为 ProductQuestionView 视图模型
+ *
+ * @param raw: 原始的ProductQuestion 数据
+ * @returns 转换后的 ProductQuestionView 对象
+ *
+ * @example
+ * const view = toProductQuestionView(rawQuestion);
+ */
+export function toProductQuestionView(
+  raw: (ProductsQuestion | string)[]
+): ProductQuestionView[] {
+  return (raw ?? []).map((item) => {
+    if (!isObject<ProductsQuestion>(item)) {
+      return {
+        id: item,
+        title: '',
+        content: '',
+      } satisfies ProductQuestionView;
+    }
+
+    const question = item.questions_id;
+    if (!isObject<Question>(question)) {
+      return {
+        id: item.id.toString(),
+        title: '',
+        content: '',
+      } satisfies ProductQuestionView;
+    }
+
+    const trans = question.translations?.[0];
+
+    return {
+      id: item.id.toString(),
+      title: trans?.title ?? '',
+      content: trans?.content ?? '',
+    } satisfies ProductQuestionView;
+  });
+}
+
+/**
+ * 将 Directus 返回的 ProductDocument 数据转换为 ProductDocumentView 视图模型
+ *
+ * @param raw: 原始的ProductDocument 数据
+ * @returns 转换后的 ProductDocumentView 对象
+ *
+ * @example
+ * const view = toProductDocumentView(rawDocument);
+ */
+export function toProductDocumentView(
+  raw: (ProductsProductDocument | string)[]
+): ProductDocumentView[] {
+  return (raw ?? []).map((item) => {
+    if (!isObject<ProductsProductDocument>(item)) {
+      return {
+        id: item,
+        fileId: '',
+        filename: '',
+        size: 0,
+        title: '',
+        url: '',
+      } satisfies ProductDocumentView;
+    }
+
+    const document = item.product_documents_id;
+    if (!isObject<ProductDocument>(document)) {
+      return {
+        id: item.id.toString(),
+        fileId: '',
+        filename: '',
+        size: 0,
+        title: '',
+        url: '',
+      } satisfies ProductDocumentView;
+    }
+
+    const file = isObject<DirectusFile>(document.file)
+      ? document.file
+      : undefined;
+
+    const url = file ? `/api/assets/${file.id}` : '';
+
+    const trans = document.translations?.[0];
+
+    return {
+      id: item.id.toString(),
+      fileId: file?.id ?? '',
+      filename: file?.filename_download ?? '',
+      size: file?.filesize ?? 0,
+      title: trans?.title ?? '',
+      url: url,
+    } satisfies ProductDocumentView;
+  });
 }
 
 /**
@@ -108,42 +207,16 @@ export function toProductSpecView(raw: ProductSpec): ProductSpecView {
 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.toString(),
-        image: image,
-        caption: item.translations?.[0]?.caption || '',
-      };
-    });
+  const images = toProductImageView(raw.images ?? []);
 
-  const type = isObject<ProductType>(raw.product_type)
-    ? (raw.product_type.translations?.[0]?.name ?? '')
-    : '';
+  const specs = toProductSpecGroupView(raw.specs ?? []);
 
-  const specs = (raw.specs ?? [])
-    .filter(isObject<ProductSpecGroup>)
-    .map((item) => toProductSpecGroupView(item));
+  const faqs = toProductQuestionView(raw.faqs ?? []);
 
-  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));
+  const documents = toProductDocumentView(raw.documents ?? []);
 
   return {
     id: raw.id.toString(),
-    product_type: type,
     name: trans?.name ?? '',
     summary: trans?.summary ?? '',
     images: images,
@@ -151,5 +224,5 @@ export function toProductView(raw: Product): ProductView {
     specs: specs,
     faqs: faqs,
     documents: documents,
-  };
+  } satisfies ProductView;
 }

server/mappers/questionMapper.test.ts

@@ -1,9 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import {
-  toProductQuestionView,
-  toQuestionListView,
-  toQuestionTypeView,
-} from './questionMapper';
+import { toQuestionListView, toQuestionTypeView } from './questionMapper';
 
 /**
  * 单元测试: toQuestionTypeView
@@ -47,42 +43,6 @@ describe('toQuestionTypeView', () => {
   });
 });
 
-/**
- * 单元测试: 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
  */

server/mappers/questionMapper.ts

@@ -26,25 +26,6 @@ export function toQuestionTypeView(
   };
 }
 
-/**
- * 将 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.toString(),
-    title: trans?.title ?? '',
-    content: trans?.content ?? '',
-  };
-}
-
 /**
  * 将 Directus 返回的 Question 数据转换为 QuestionListView 视图模型
  *

server/mappers/solutionListMapper.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect } from 'vitest';
+import { toSolutionListView, toSolutionTypeView } from './solutionListMapper';
+
+/**
+ * 单元测试: toSolutionTypeView
+ */
+describe('toSolutionTypeView', () => {
+  const baseData: SolutionType = {
+    id: 1,
+    translations: [
+      {
+        id: 1,
+        name: 'Type Name',
+      },
+    ],
+    sort: 5,
+  };
+
+  test('convert raw data to SolutionTypeView correctly', () => {
+    const rawData: SolutionType = { ...baseData };
+
+    expect(toSolutionTypeView(rawData)).toEqual({
+      id: '1',
+      name: 'Type Name',
+      sort: 5,
+    });
+  });
+
+  test('convert raw data with missing translations', () => {
+    const rawData: SolutionType = { ...baseData, translations: [] };
+
+    expect(toSolutionTypeView(rawData)).toEqual({
+      id: '1',
+      name: '',
+      sort: 5,
+    });
+  });
+
+  test('convert raw data with missing sort', () => {
+    const rawData: SolutionType = { ...baseData, sort: undefined };
+
+    expect(toSolutionTypeView(rawData)).toEqual({
+      id: '1',
+      name: 'Type Name',
+      sort: 999,
+    });
+  });
+
+  test('convert null input to default value', () => {
+    const rawData: SolutionType | string | null = null;
+
+    expect(toSolutionTypeView(rawData)).toEqual({
+      id: '-1',
+      name: 'uncategory',
+      sort: 999,
+    });
+  });
+});
+
+/**
+ * 单元测试: 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: '',
+    });
+  });
+});

server/mappers/solutionListMapper.ts

@@ -0,0 +1,58 @@
+import { isObject } from '../../server/utils/object';
+
+/**
+ * 将 Directus 返回的 SolutionType 数据转换为 SolutionTypeView 视图模型
+ *
+ * @param raw: 原始的 SolutionType 数据
+ * @returns 转换后的 SolutionTypeView 对象
+ *
+ * ---
+ *
+ *  @example
+ *  const view = toSolutionTypeView(rawSolutionType);
+ */
+export function toSolutionTypeView(
+  raw: SolutionType | string | null
+): SolutionTypeView {
+  if (typeof raw === 'string' || raw === null) {
+    return {
+      id: '-1',
+      name: 'uncategory',
+      sort: 999,
+    } satisfies SolutionTypeView;
+  }
+  const trans = raw?.translations?.[0];
+
+  return {
+    id: raw.id.toString(),
+    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 = toSolutionTypeView(raw.type ?? null);
+
+  const cover = isObject<DirectusFile>(raw.cover) ? (raw?.cover.id ?? '') : '';
+
+  return {
+    id: raw.id.toString(),
+    title: trans?.title ?? '',
+    summary: trans?.summary ?? '',
+    solution_type: type,
+    cover: cover,
+  };
+}

server/mappers/solutionMapper.test.ts

@@ -1,56 +1,5 @@
 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: '',
-    });
-  });
-});
+import { toSolutionView } from './solutionMapper';
 
 /**
  * 单元测试: toSolutionView

server/mappers/solutionMapper.ts

@@ -1,59 +1,3 @@
-import { isObject } from '../../server/utils/object';
-
-/**
- * 将 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.toString(),
-    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: '',
-        name: 'uncategory',
-        sort: 999,
-      } satisfies SolutionTypeView);
-
-  const cover = isObject<DirectusFile>(raw.cover) ? (raw?.cover.id ?? '') : '';
-
-  return {
-    id: raw.id.toString(),
-    title: trans?.title ?? '',
-    summary: trans?.summary ?? '',
-    solution_type: type,
-    cover: cover,
-  };
-}
-
 /**
  * 将 Directus 返回的 Solution 数据转换为 SolutionView 视图模型
  *

server/services/cms/productService.ts

@@ -1,7 +1,5 @@
-import {
-  toProductView,
-  toProductListView,
-} from '~~/server/mappers/productMapper';
+import { toProductView } from '~~/server/mappers/productMapper';
+import { toProductListView } from '~~/server/mappers/productListMapper';
 
 export const productService = {
   async getProductList(locale: string) {

server/services/cms/solutionService.ts

@@ -1,7 +1,5 @@
-import {
-  toSolutionView,
-  toSolutionListView,
-} from '~~/server/mappers/solutionMapper';
+import { toSolutionView } from '~~/server/mappers/solutionMapper';
+import { toSolutionListView } from '~~/server/mappers/solutionListMapper';
 
 export const solutionService = {
   async getSolutionList(locale: string) {

shared/types/views/index.ts

@@ -2,9 +2,6 @@ export * from './solution-view';
 export * from './solution-list-view';
 export * from './product-view';
 export * from './product-list-view';
-export * from './product-spec-group-view';
-export * from './product-document-view';
-export * from './product-question-view';
 export * from './document-list-view';
 export * from './question-list-view';
 export * from './company-profile-view';

shared/types/views/product-document-view.ts

@@ -1,23 +0,0 @@
-/**
- * 文档视图模型
- * 用于文档列表渲染的数据结构
- */
-export interface ProductDocumentView {
-  /** 唯一标识符 **/
-  id: string;
-
-  /** 文件UUID **/
-  fileId: string;
-
-  /** 文件名 **/
-  filename: string;
-
-  /** 文档标题 **/
-  title: string;
-
-  /** 文档大小 **/
-  size: number;
-
-  /** 文档链接 **/
-  url: string;
-}

shared/types/views/product-question-view.ts

@@ -1,14 +0,0 @@
-/**
- * 常见问题视图模型
- * 用于产品页常见问题渲染的数据结构
- */
-export interface ProductQuestionView {
-  /** 唯一标识符 **/
-  id: string;
-
-  /** 问题标题 **/
-  title: string;
-
-  /** 问题内容 **/
-  content: string;
-}

shared/types/views/product-spec-group-view.ts

@@ -1,29 +0,0 @@
-/**
- * 产品规格模型
- * 用于产品规格渲染的数据结构
- */
-export interface ProductSpecView {
-  /** 唯一标识符 **/
-  id: string;
-
-  /** 规格名称 **/
-  key: string;
-
-  /** 规格值 **/
-  value: string;
-}
-
-/**
- * 产品规格表模型
- * 用于产品规格表渲染的数据结构
- */
-export interface ProductSpecGroupView {
-  /** 唯一标识符 **/
-  id: string;
-
-  /** 规格组名称 **/
-  name: string;
-
-  /** 规格组 **/
-  specs: ProductSpecView[];
-}

shared/types/views/product-view.ts

@@ -1,13 +1,82 @@
-import type { ProductSpecGroupView } from './product-spec-group-view';
-import type { ProductQuestionView } from './product-question-view';
-import type { ProductDocumentView } from './product-document-view';
-
-interface ImageView {
+/**
+ * 产品图片视图模型
+ * 用于产品详情页(/products/[slug])中的产品图片数据结构
+ */
+export interface ProductImageView {
   id: string;
   image: string;
   caption: string;
 }
 
+/**
+ * 产品规格模型
+ * 用于产品规格渲染的数据结构
+ */
+export interface ProductSpecView {
+  /** 唯一标识符 **/
+  id: string;
+
+  /** 规格名称 **/
+  key: string;
+
+  /** 规格值 **/
+  value: string;
+}
+
+/**
+ * 产品规格表模型
+ * 用于产品规格表渲染的数据结构
+ */
+export interface ProductSpecGroupView {
+  /** 唯一标识符 **/
+  id: string;
+
+  /** 规格组名称 **/
+  name: string;
+
+  /** 规格组 **/
+  specs: ProductSpecView[];
+}
+
+/**
+ * 常见问题视图模型
+ * 用于产品页常见问题渲染的数据结构
+ */
+export interface ProductQuestionView {
+  /** 唯一标识符 **/
+  id: string;
+
+  /** 问题标题 **/
+  title: string;
+
+  /** 问题内容 **/
+  content: string;
+}
+
+/**
+ * 文档视图模型
+ * 用于文档列表渲染的数据结构
+ */
+export interface ProductDocumentView {
+  /** 唯一标识符 **/
+  id: string;
+
+  /** 文件UUID **/
+  fileId: string;
+
+  /** 文件名 **/
+  filename: string;
+
+  /** 文档标题 **/
+  title: string;
+
+  /** 文档大小 **/
+  size: number;
+
+  /** 文档链接 **/
+  url: string;
+}
+
 /**
  * 产品视图模型
  * 用于产品详情页(/products/[slug])渲染的数据结构
@@ -22,11 +91,8 @@ export interface ProductView {
   /** 产品简介 **/
   summary: string;
 
-  /** 产品类型 **/
-  product_type: string;
-
   /** 产品图片 **/
-  images: ImageView[];
+  images: ProductImageView[];
 
   /** 产品详情 **/
   description: string;