feat(content): introduce content preference handling for notes and pages

Innei · Innei · commit 14ed55b9a4c6 · 2026-02-23T22:56:53.000+08:00
- Added `zPrefer` schema to support content preference in note and page queries.
- Implemented `applyContentPreference` utility function to conditionally format content based on user preference.
- Updated note and page controllers to utilize the new preference handling in response data.
- Enhanced API client controllers to accept and forward content preference options.

Signed-off-by: Innei &lt;tukon479@gmail.com&gt;
diff --git a/apps/core/src/common/zod/custom.ts b/apps/core/src/common/zod/custom.ts
@@ -53,6 +53,8 @@ export const zRefTypeTransform = z.preprocess((val) => {
   return mapping[val.toLowerCase()] || val
 }, z.string().optional())
 
+export const zPrefer = z.enum(['lexical']).optional()
+
 export const zLang = z
   .preprocess(
     (val) =>
diff --git a/apps/core/src/common/zod/index.ts b/apps/core/src/common/zod/index.ts
@@ -1,6 +1,16 @@
-export { z } from 'zod'
-export { createZodDto } from 'nestjs-zod'
-
+export {
+  zBooleanOrString,
+  zEmail,
+  zLang,
+  zMaxLengthString,
+  zPinDate,
+  zPrefer,
+  zRefTypeTransform,
+  zSlug,
+  zTransformBoolean,
+  zTransformEmptyNull,
+  zUrl,
+} from './custom'
 export {
   zAllowedUrl,
   zArrayUnique,
@@ -23,21 +33,9 @@ export {
   zStrictUrl,
   zUniqueStringArray,
 } from './primitives'
-
-export {
-  zBooleanOrString,
-  zEmail,
-  zLang,
-  zMaxLengthString,
-  zPinDate,
-  zRefTypeTransform,
-  zSlug,
-  zTransformBoolean,
-  zTransformEmptyNull,
-  zUrl,
-} from './custom'
-
 export {
   ExtendedZodValidationPipe,
   extendedZodValidationPipeInstance,
 } from './validation.pipe'
+export { createZodDto } from 'nestjs-zod'
+export { z } from 'zod'
diff --git a/apps/core/src/modules/note/note.controller.ts b/apps/core/src/modules/note/note.controller.ts
@@ -11,8 +11,8 @@ import {
 import { ApiController } from '~/common/decorators/api-controller.decorator'
 import { Auth } from '~/common/decorators/auth.decorator'
 import { HTTPDecorators, Paginator } from '~/common/decorators/http.decorator'
-import { IpLocation } from '~/common/decorators/ip.decorator'
 import type { IpRecord } from '~/common/decorators/ip.decorator'
+import { IpLocation } from '~/common/decorators/ip.decorator'
 import { Lang } from '~/common/decorators/lang.decorator'
 import { IsAuthenticated } from '~/common/decorators/role.decorator'
 import { BizException } from '~/common/exceptions/biz.exception'
@@ -22,6 +22,7 @@ import { CountingService } from '~/processors/helper/helper.counting.service'
 import { TranslationService } from '~/processors/helper/helper.translation.service'
 import { MongoIdDto } from '~/shared/dto/id.dto'
 import { addYearCondition } from '~/transformers/db-query.transformer'
+import { applyContentPreference } from '~/utils/content.util'
 import type { QueryFilter } from 'mongoose'
 import { NoteModel } from './note.model'
 import {
@@ -76,7 +77,7 @@ export class NoteController {
       page,
       select: isAuthenticated
         ? select
-        : select?.replace(/[+-]?(coordinates|location|password)/g, ''),
+        : select?.replaceAll(/[+-]?(coordinates|location|password)/g, ''),
       sort: sortBy ? { [sortBy]: sortOrder || -1 } : { created: -1 },
     })
   }
@@ -242,7 +243,7 @@ export class NoteController {
     @Lang() lang?: string,
   ) {
     const { nid } = params
-    const { password, single: isSingle } = query
+    const { password, single: isSingle, prefer } = query
     const condition = isAuthenticated ? {} : { isPublished: true }
     const current: NoteModel | null = await this.noteService.model
       .findOne({
@@ -292,7 +293,7 @@ export class NoteController {
     }
 
     if (isSingle) {
-      return currentData
+      return applyContentPreference(currentData, prefer)
     }
 
     const select = '_id title nid id created modified'
@@ -320,7 +321,7 @@ export class NoteController {
     if (currentData.password) {
       currentData.password = '*'
     }
-    return { data: currentData, next, prev }
+    return { data: applyContentPreference(currentData, prefer), next, prev }
   }
 
   @Get('/topics/:id')
diff --git a/apps/core/src/modules/note/note.schema.ts b/apps/core/src/modules/note/note.schema.ts
@@ -4,6 +4,7 @@ import {
   zLang,
   zMongoId,
   zNonEmptyString,
+  zPrefer,
   zTransformEmptyNull,
 } from '~/common/zod'
 import { PagerSchema } from '~/shared/dto/pager.dto'
@@ -78,6 +79,7 @@ export const NotePasswordQuerySchema = z.object({
   password: zNonEmptyString.optional(),
   single: zCoerceBoolean.optional(),
   lang: zLang,
+  prefer: zPrefer,
 })
 
 export class NotePasswordQueryDto extends createZodDto(
diff --git a/apps/core/src/modules/page/page.controller.ts b/apps/core/src/modules/page/page.controller.ts
@@ -21,8 +21,14 @@ import {
 } from '~/processors/helper/helper.translation.service'
 import { MongoIdDto } from '~/shared/dto/id.dto'
 import { PagerDto } from '~/shared/dto/pager.dto'
+import { applyContentPreference } from '~/utils/content.util'
 import { PageModel } from './page.model'
-import { PageDto, PageReorderDto, PartialPageDto } from './page.schema'
+import {
+  PageDetailQueryDto,
+  PageDto,
+  PageReorderDto,
+  PartialPageDto,
+} from './page.schema'
 import { PageService } from './page.service'
 
 @ApiController('pages')
@@ -110,7 +116,11 @@ export class PageController {
   }
 
   @Get('/slug/:slug')
-  async getPageBySlug(@Param('slug') slug: string, @Lang() lang?: string) {
+  async getPageBySlug(
+    @Param('slug') slug: string,
+    @Query() query: PageDetailQueryDto,
+    @Lang() lang?: string,
+  ) {
     if (typeof slug !== 'string') {
       throw new BizException(ErrorCodeEnum.InvalidSlug)
     }
@@ -133,14 +143,17 @@ export class PageController {
       },
     })
 
-    return {
-      ...page,
-      title: translationResult.title,
-      text: translationResult.text,
-      isTranslated: translationResult.isTranslated,
-      translationMeta: translationResult.translationMeta,
-      availableTranslations: translationResult.availableTranslations,
-    }
+    return applyContentPreference(
+      {
+        ...page,
+        title: translationResult.title,
+        text: translationResult.text,
+        isTranslated: translationResult.isTranslated,
+        translationMeta: translationResult.translationMeta,
+        availableTranslations: translationResult.availableTranslations,
+      },
+      query.prefer,
+    )
   }
 
   @Post('/')
diff --git a/apps/core/src/modules/page/page.schema.ts b/apps/core/src/modules/page/page.schema.ts
@@ -1,4 +1,4 @@
-import { zCoerceInt, zMongoId, zNonEmptyString } from '~/common/zod'
+import { zCoerceInt, zMongoId, zNonEmptyString, zPrefer } from '~/common/zod'
 import { WriteBaseSchema } from '~/shared/schema'
 import { ImageSchema } from '~/shared/schema/image.schema'
 import { createZodDto } from 'nestjs-zod'
@@ -46,6 +46,15 @@ export const PageReorderSchema = z.object({
 
 export class PageReorderDto extends createZodDto(PageReorderSchema) {}
 
+/**
+ * Page detail query schema
+ */
+export const PageDetailQuerySchema = z.object({
+  prefer: zPrefer,
+})
+
+export class PageDetailQueryDto extends createZodDto(PageDetailQuerySchema) {}
+
 // Type exports
 export type PageInput = z.infer<typeof PageSchema>
 export type PartialPageInput = z.infer<typeof PartialPageSchema>
diff --git a/apps/core/src/modules/post/post.controller.ts b/apps/core/src/modules/post/post.controller.ts
@@ -11,8 +11,8 @@ import {
 import { ApiController } from '~/common/decorators/api-controller.decorator'
 import { Auth } from '~/common/decorators/auth.decorator'
 import { HTTPDecorators, Paginator } from '~/common/decorators/http.decorator'
-import { IpLocation } from '~/common/decorators/ip.decorator'
 import type { IpRecord } from '~/common/decorators/ip.decorator'
+import { IpLocation } from '~/common/decorators/ip.decorator'
 import { Lang } from '~/common/decorators/lang.decorator'
 import { IsAuthenticated } from '~/common/decorators/role.decorator'
 import { CannotFindException } from '~/common/exceptions/cant-find.exception'
@@ -23,6 +23,7 @@ import {
 } from '~/processors/helper/helper.translation.service'
 import { MongoIdDto } from '~/shared/dto/id.dto'
 import { addYearCondition } from '~/transformers/db-query.transformer'
+import { applyContentPreference } from '~/utils/content.util'
 import type { PipelineStage } from 'mongoose'
 import type { CategoryModel } from '../category/category.model'
 import { PostModel } from './post.model'
@@ -276,7 +277,7 @@ export class PostController {
   @Get('/:category/:slug')
   async getByCateAndSlug(
     @Param() params: CategoryAndSlugDto,
-    @Query() _: PostDetailQueryDto,
+    @Query() query: PostDetailQueryDto,
     @IpLocation() { ip }: IpRecord,
     @IsAuthenticated() isAuthenticated?: boolean,
     @Lang() lang?: string,
@@ -314,17 +315,20 @@ export class PostController {
       },
     })
 
-    return {
-      ...baseData,
-      title: translationResult.title,
-      text: translationResult.text,
-      summary: translationResult.summary,
-      tags: translationResult.tags,
-      isTranslated: translationResult.isTranslated,
-      translationMeta: translationResult.translationMeta,
-      availableTranslations: translationResult.availableTranslations,
-      liked,
-    }
+    return applyContentPreference(
+      {
+        ...baseData,
+        title: translationResult.title,
+        text: translationResult.text,
+        summary: translationResult.summary,
+        tags: translationResult.tags,
+        isTranslated: translationResult.isTranslated,
+        translationMeta: translationResult.translationMeta,
+        availableTranslations: translationResult.availableTranslations,
+        liked,
+      },
+      query.prefer,
+    )
   }
 
   @Post('/')
diff --git a/apps/core/src/modules/post/post.schema.ts b/apps/core/src/modules/post/post.schema.ts
@@ -5,6 +5,7 @@ import {
   zMongoId,
   zNonEmptyString,
   zPinDate,
+  zPrefer,
 } from '~/common/zod'
 import { PagerSchema } from '~/shared/dto/pager.dto'
 import { WriteBaseSchema } from '~/shared/schema'
@@ -64,6 +65,7 @@ export class CategoryAndSlugDto extends createZodDto(CategoryAndSlugSchema) {}
  */
 export const PostDetailQuerySchema = z.object({
   lang: zLang,
+  prefer: zPrefer,
 })
 
 export class PostDetailQueryDto extends createZodDto(PostDetailQuerySchema) {}
diff --git a/apps/core/src/utils/content.util.ts b/apps/core/src/utils/content.util.ts
@@ -64,6 +64,20 @@ export function computeContentHash(
   )
 }
 
+export function applyContentPreference<
+  T extends { text?: string; contentFormat?: string; content?: string },
+>(doc: T, prefer?: string): T {
+  if (
+    prefer === 'lexical' &&
+    doc.contentFormat === ContentFormat.Lexical &&
+    doc.content
+  ) {
+    const { text, ...rest } = doc
+    return rest as T
+  }
+  return doc
+}
+
 function traverseLexicalNodes(node: any, visitor: (node: any) => void): void {
   if (!node) return
   visitor(node)
diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -58,7 +58,7 @@ export default defineConfig(
       '@typescript-eslint/no-unsafe-function-type': 0,
       'unicorn/no-array-callback-reference': 0,
 
-     
+     "unicorn/no-thenable": 0,
       'no-duplicate-imports': 'off',
       'unicorn/explicit-length-check': 0,
       'unicorn/prefer-top-level-await': 0,
diff --git a/packages/api-client/controllers/note.ts b/packages/api-client/controllers/note.ts
@@ -33,6 +33,7 @@ export type NoteByNidOptions = {
   password?: string
   single?: boolean
   lang?: string
+  prefer?: 'lexical'
 }
 
 export type NoteMiddleListOptions = {
@@ -119,12 +120,13 @@ export class NoteController<ResponseWrapper> implements IController {
     NoteWrappedWithLikedAndTranslationPayload,
     ResponseWrapper
   > {
-    const { password, single, lang } = options || {}
+    const { password, single, lang, prefer } = options || {}
     return this.proxy.nid(nid.toString()).get({
       params: {
         password,
         single: single ? '1' : undefined,
         lang,
+        prefer,
       },
     })
   }
diff --git a/packages/api-client/controllers/page.ts b/packages/api-client/controllers/page.ts
@@ -58,7 +58,9 @@ export class PageController<ResponseWrapper> implements IController {
    * @param slug 路径
    * @returns
    */
-  getBySlug(slug: string) {
-    return this.proxy.slug(slug).get<PageModel>({})
+  getBySlug(slug: string, options?: { prefer?: 'lexical' }) {
+    return this.proxy.slug(slug).get<PageModel>({
+      params: options?.prefer ? { prefer: options.prefer } : undefined,
+    })
   }
 }
diff --git a/packages/api-client/controllers/post.ts b/packages/api-client/controllers/post.ts
@@ -82,7 +82,7 @@ export class PostController<ResponseWrapper> implements IController {
   getPost(
     categoryName: string,
     slug: string,
-    options?: { lang?: string },
+    options?: { lang?: string; prefer?: 'lexical' },
   ): RequestProxyResult<
     ModelWithLiked<ModelWithTranslation<PostModel>>,
     ResponseWrapper
@@ -95,13 +95,16 @@ export class PostController<ResponseWrapper> implements IController {
   getPost(
     idOrCategoryName: string,
     slug?: string,
-    options?: { lang?: string },
+    options?: { lang?: string; prefer?: 'lexical' },
   ): any {
     if (arguments.length == 1) {
       return this.proxy(idOrCategoryName).get<PostModel>()
     } else {
+      const params: Record<string, string | undefined> = {}
+      if (options?.lang) params.lang = options.lang
+      if (options?.prefer) params.prefer = options.prefer
       return this.proxy(idOrCategoryName)(slug).get<PostModel>({
-        params: options?.lang ? { lang: options.lang } : undefined,
+        params: Object.keys(params).length ? params : undefined,
       })
     }
   }
diff --git a/packages/api-client/models/base.ts b/packages/api-client/models/base.ts
@@ -36,15 +36,26 @@ export interface BaseCommentIndexModel extends BaseModel {
 
   allowComment: boolean
 }
-export interface TextBaseModel extends BaseCommentIndexModel {
+interface TextBaseModelMarkdown extends BaseCommentIndexModel {
   title: string
   text: string
+  contentFormat?: 'markdown'
+  content?: undefined
   images?: Image[]
   modified: string | null
-  contentFormat?: 'markdown' | 'lexical'
-  content?: string
 }
 
+interface TextBaseModelLexical extends BaseCommentIndexModel {
+  title: string
+  text?: string
+  contentFormat: 'lexical'
+  content: string
+  images?: Image[]
+  modified: string | null
+}
+
+export type TextBaseModel = TextBaseModelMarkdown | TextBaseModelLexical
+
 export type ModelWithLiked<T> = T & {
   liked: boolean
 }
diff --git a/packages/api-client/models/note.ts b/packages/api-client/models/note.ts
diff --git a/packages/api-client/models/page.ts b/packages/api-client/models/page.ts
diff --git a/packages/api-client/models/post.ts b/packages/api-client/models/post.ts
