feat: directus视图与转换函数

- views: 用于前端渲染的视图模型
- mapper: 用于视图模型转换的转换函数
- utils: 相关工具函数

app/models/mappers/documentMapper.ts

@@ -0,0 +1,29 @@
+/**
+ * 将 Directus 返回的 Document 数据转换为 DocumentView 视图模型
+ *
+ * @param raw: 原始的 Document 数据
+ * @returns 转换后的 DocumentView 对象
+ *
+ * @example
+ * const view = toDocumentView(rawDocument);
+ */
+export function toDocumentView(raw: ProductDocument): ProductDocumentView {
+  const trans = raw.translations?.[0] ?? {
+    title: '',
+  };
+
+  const fileId = typeof raw.file === 'string' ? raw.file : raw.file?.id;
+  const file = raw.file as DirectusFile;
+
+  const { getFileUrl } = useDirectusFiles();
+
+  const url = getFileUrl(fileId);
+
+  return {
+    id: raw.id,
+    filename: file.filename_download,
+    title: trans.title,
+    url: url,
+    size: file.filesize,
+  };
+}

app/models/mappers/productMapper.ts

@@ -0,0 +1,134 @@
+/**
+ * 将 Directus返回的 Product 数据转换为 ProductListView 视图模型
+ *
+ * @param raw: 原始的 Product 数据
+ * @returns 转换后的 ProductListView 对象
+ *
+ * @example
+ * const view = toProductListView(rawProduct);
+ */
+export function toProductListView(raw: Product): ProductListView {
+  const trans = raw.translations?.[0] ?? { name: '', summary: '' };
+
+  return {
+    id: raw.id,
+    product_type:
+      typeof raw.product_type === 'string'
+        ? raw.product_type
+        : typeof raw.product_type === 'object' && raw.product_type
+          ? raw.product_type.translations[0].name || ''
+          : '',
+    name: trans.name,
+    summary: trans.summary,
+    cover: raw.cover.toString(),
+  };
+}
+
+/**
+ * 将 Directus 返回的 ProductSpecGroup 数据转换为 ProductSpecGroupView 视图模型
+ *
+ * @param raw: 原始的 ProductSpecGroup 数据
+ * @returns 转换后的 ProductSpecGroupView 对象
+ *
+ * @example
+ * const view = toProductSpecGroupView(rawSpecGroup);
+ */
+export function toProductSpecGroupView(
+  raw: ProductSpecGroup
+): ProductSpecGroupView {
+  const trans = raw.translations?.[0] ?? {
+    name: '',
+  };
+
+  return {
+    id: raw.id,
+    name: trans.name,
+    specs: raw.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] ?? {
+    key: '',
+  };
+
+  return {
+    id: raw.id,
+    key: trans.key,
+    value: raw.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] ?? {
+    name: '',
+    summary: '',
+    description: '',
+  };
+
+  const images = (raw.images ?? [])
+    .filter(isObject<ProductsProductImage>)
+    .map((item) => item.product_images_id)
+    .filter(isObject<ProductImage>)
+    .map((item) => {
+      return {
+        id: item.id,
+        image: item.image.toString(),
+        caption: item.translations?.[0]?.caption || '',
+      };
+    });
+
+  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) => toQuestionView(item));
+
+  const documents = (raw.documents ?? [])
+    .filter(isObject<ProductsProductDocument>)
+    .map((item) => item.product_documents_id)
+    .filter(isObject<ProductDocument>)
+    .map((item) => toDocumentView(item));
+
+  return {
+    id: raw.id,
+
+    product_type:
+      typeof raw.product_type === 'string'
+        ? raw.product_type
+        : typeof raw.product_type === 'object' && raw.product_type
+          ? raw.product_type.translations[0].name || ''
+          : '',
+    name: trans.name,
+    summary: trans.summary,
+    images: images,
+    description: trans.description,
+    specs: specs,
+    faqs: faqs,
+    documents: documents,
+  };
+}

app/models/mappers/questionMapper.ts

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

app/models/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>);
+};

app/models/views/ProductDocumentView.ts

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

app/models/views/ProductListView.ts

@@ -0,0 +1,20 @@
+/**
+ * 产品列表视图模型
+ * 用于产品列表(/products)渲染的数据结构
+ */
+export interface ProductListView {
+  /** 唯一标识符 **/
+  id: number;
+
+  /** 产品名称 **/
+  name: string;
+
+  /** 产品简介 **/
+  summary: string;
+
+  /** 产品类型 **/
+  product_type: string;
+
+  /** 产品封面(图片的id) **/
+  cover: string;
+}

app/models/views/ProductSpecGroupView.ts

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

app/models/views/ProductView.ts

@@ -0,0 +1,38 @@
+interface ImageView {
+  id: number;
+  image: string;
+  caption: string;
+}
+
+/**
+ * 产品视图模型
+ * 用于产品详情页(/products/[slug])渲染的数据结构
+ */
+export interface ProductView {
+  /** 唯一标识符 **/
+  id: number;
+
+  /** 产品名称 **/
+  name: string;
+
+  /** 产品简介 **/
+  summary: string;
+
+  /** 产品类型 **/
+  product_type: string;
+
+  /** 产品图片 **/
+  images: ImageView[];
+
+  /** 产品详情 **/
+  description: string;
+
+  /** 产品规格 **/
+  specs: ProductSpecGroupView[];
+
+  /** 产品常见问题 **/
+  faqs: QuestionView[];
+
+  /** 产品文档 **/
+  documents: ProductDocumentView[];
+}

app/models/views/QuestionView.ts

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