feat(category): enrich detail responses with summary/tags/pin/count and tagsSum

Expand findCategoryPost select fields and sort by pin first; rewrite
findArticleWithTag mapping to surface the same enriched fields with a
typed return shape. Add a new getCategoryTagsSum aggregation and attach
the result to GET /categories/:slug, fetched in parallel with children.

api-client types follow with CategoryChildPost / TagDetailPost and an
optional tagsSum field on CategoryWithChildrenModel; fixtures updated.

Backs design: Yohaku/docs/superpowers/specs/2026-04-30-category-tag-detail-design.md

Author: Innei

apps/core/src/modules/category/category.controller.ts

@@ -123,16 +123,20 @@ export class CategoryController {
       throw new CannotFindException()
     }
 
-    let children: any[] =
-      (await this.categoryService.findCategoryPost(res._id.toHexString(), {
+    const [postsResult, tagsSum] = await Promise.all([
+      this.categoryService.findCategoryPost(res._id.toHexString(), {
         $and: [tag ? { tags: tag } : {}],
-      })) || []
+      }),
+      this.categoryService.getCategoryTagsSum(res._id.toHexString()),
+    ])
+
+    let children: any[] = postsResult || []
 
     if (lang && children.length) {
       children = await this.translatePostTitles(children, lang)
     }
 
-    return { data: { ...res, children } }
+    return { data: { ...res, children, tagsSum } }
   }
 
   private translatePostTitles(posts: any[], lang: string) {

apps/core/src/modules/category/category.service.ts

@@ -3,6 +3,7 @@ import { ModuleRef } from '@nestjs/core'
 import type { DocumentType, ReturnModelType } from '@typegoose/typegoose'
 import { omit } from 'es-toolkit/compat'
 import type { QueryFilter } from 'mongoose'
+import { Types } from 'mongoose'
 
 import { BizException } from '~/common/exceptions/biz.exception'
 import { CannotFindException } from '~/common/exceptions/cant-find.exception'
@@ -21,6 +22,19 @@ import type { PostService } from '../post/post.service'
 import { SlugTrackerService } from '../slug-tracker/slug-tracker.service'
 import { CategoryModel, CategoryType } from './category.model'
 
+type TagDetailMapped = {
+  _id: Types.ObjectId
+  title: string
+  slug: string
+  category: Record<string, unknown>
+  created?: Date
+  modified?: Date | null
+  summary?: string | null
+  tags?: string[]
+  pin?: Date | null
+  count?: { read?: number; like?: number }
+}
+
 @Injectable()
 export class CategoryService implements OnApplicationBootstrap {
   private postService: PostService
@@ -91,10 +105,24 @@ export class CategoryService implements OnApplicationBootstrap {
     return data
   }
 
+  async getCategoryTagsSum(categoryId: string) {
+    const data = await this.postService.model.aggregate([
+      {
+        $match: { categoryId: Types.ObjectId.createFromHexString(categoryId) },
+      },
+      { $project: { tags: 1 } },
+      { $unwind: '$tags' },
+      { $group: { _id: '$tags', count: { $sum: 1 } } },
+      { $project: { _id: 0, name: '$_id', count: 1 } },
+      { $sort: { count: -1, name: 1 } },
+    ])
+    return data as Array<{ name: string; count: number }>
+  }
+
   async findArticleWithTag(
     tag: string,
     condition: QueryFilter<DocumentType<PostModel>> = {},
-  ): Promise<null | any[]> {
+  ): Promise<TagDetailMapped[]> {
     const posts = await this.postService.model
       .find(
         {
@@ -108,13 +136,31 @@ export class CategoryService implements OnApplicationBootstrap {
     if (posts.length === 0) {
       throw new CannotFindException()
     }
-    return posts.map(({ _id, title, slug, category, created }) => ({
-      _id,
-      title,
-      slug,
-      category: omit(category, ['count', '__v', 'created', 'modified']),
-      created,
-    }))
+    return posts.map(
+      ({
+        _id,
+        title,
+        slug,
+        category,
+        created,
+        modified,
+        summary,
+        tags,
+        pin,
+        count,
+      }) => ({
+        _id,
+        title,
+        slug,
+        category: omit(category, ['count', '__v', 'created', 'modified']),
+        created,
+        modified,
+        summary,
+        tags,
+        pin,
+        count: count ? { read: count.read, like: count.like } : undefined,
+      }),
+    )
   }
 
   async findCategoryPost(categoryId: string, condition: any = {}) {
@@ -123,8 +169,9 @@ export class CategoryService implements OnApplicationBootstrap {
         categoryId,
         ...condition,
       })
-      .select('title created slug _id')
-      .sort({ created: -1 })
+      .select('title slug created modified summary tags pin count images')
+      .sort({ pin: -1, created: -1 })
+      .lean()
   }
 
   async findPostsInCategory(id: string) {

packages/api-client/__tests__/controllers/category.test.ts

@@ -1,7 +1,8 @@
+import camelcaseKeys from 'camelcase-keys'
+
 import { mockRequestInstance } from '~/__tests__/helpers/instance'
 import { mockResponse } from '~/__tests__/helpers/response'
 import { CategoryController } from '~/controllers'
-import camelcaseKeys from 'camelcase-keys'
 
 describe('test Category client', () => {
   const client = mockRequestInstance(CategoryController)
@@ -41,14 +42,31 @@ describe('test Category client', () => {
               title: 'pageproxy，为 spa 提供初始数据注入',
               slug: 'pageproxy-spa-inject',
               created: '2021-08-14T04:37:29.880Z',
+              modified: '2021-08-14T04:37:29.880Z',
+              summary: 'A short summary',
+              tags: ['spa', 'inject'],
+              pin: null,
+              count: { read: 100, like: 5 },
+              images: [],
             },
             {
               id: '60cffff50ec52e0349cbb29f',
               title: '曲折的 Vue 3 重构后台之路',
               slug: 'mx-space-vue-3',
               created: '2021-06-21T02:56:53.126Z',
+              modified: '2021-06-21T02:56:53.126Z',
+              summary: 'Refactor journey',
+              tags: ['vue3'],
+              pin: 'pin-id',
+              count: { read: 200, like: 12 },
+              images: [],
             },
           ],
+          tagsSum: [
+            { name: 'spa', count: 1 },
+            { name: 'inject', count: 1 },
+            { name: 'vue3', count: 1 },
+          ],
         },
       })
 
@@ -72,14 +90,31 @@ describe('test Category client', () => {
               title: 'pageproxy，为 spa 提供初始数据注入',
               slug: 'pageproxy-spa-inject',
               created: '2021-08-14T04:37:29.880Z',
+              modified: '2021-08-14T04:37:29.880Z',
+              summary: 'A short summary',
+              tags: ['spa', 'inject'],
+              pin: null,
+              count: { read: 100, like: 5 },
+              images: [],
             },
             {
               id: '60cffff50ec52e0349cbb29f',
               title: '曲折的 Vue 3 重构后台之路',
               slug: 'mx-space-vue-3',
               created: '2021-06-21T02:56:53.126Z',
+              modified: '2021-06-21T02:56:53.126Z',
+              summary: 'Refactor journey',
+              tags: ['vue3'],
+              pin: 'pin-id',
+              count: { read: 200, like: 12 },
+              images: [],
             },
           ],
+          tagsSum: [
+            { name: 'spa', count: 1 },
+            { name: 'inject', count: 1 },
+            { name: 'vue3', count: 1 },
+          ],
         },
       })
 
@@ -106,6 +141,11 @@ describe('test Category client', () => {
             slug: 'programming',
           },
           created: '2021-04-18T09:33:33.271Z',
+          modified: '2021-04-18T09:33:33.271Z',
+          summary: 'A summary',
+          tags: ['react', 'scroll'],
+          pin: null,
+          count: { read: 80, like: 3 },
         },
       ],
     })

packages/api-client/controllers/category.ts

@@ -7,16 +7,17 @@ import type {
 } from '~/interfaces/request'
 import { attachRawFromOneToAnthor, destructureData } from '~/utils'
 import { autoBind } from '~/utils/auto-bind'
+
 import type { HTTPClient } from '../core/client'
 import { RequestError } from '../core/error'
 import type {
   CategoryEntries,
   CategoryModel,
   CategoryWithChildrenModel,
+  TagDetailPost,
   TagModel,
 } from '../models/category'
 import { CategoryType } from '../models/category'
-import type { PostModel } from '../models/post'
 
 declare module '../core/client' {
   interface HTTPClient<
@@ -106,7 +107,7 @@ export class CategoryController<ResponseWrapper> implements IController {
   async getTagByName(name: string) {
     const res = await this.proxy(name).get<{
       tag: string
-      data: Pick<PostModel, 'id' | 'title' | 'slug' | 'category' | 'created'>[]
+      data: TagDetailPost[]
     }>({
       params: {
         tag: 1,

packages/api-client/models/category.ts

@@ -12,14 +12,46 @@ export interface CategoryModel extends BaseModel {
   slug: string
   name: string
 }
+
+export type CategoryChildPost = Pick<
+  PostModel,
+  | 'id'
+  | 'title'
+  | 'slug'
+  | 'modified'
+  | 'created'
+  | 'summary'
+  | 'tags'
+  | 'pin'
+  | 'count'
+  | 'images'
+>
+
 export type CategoryWithChildrenModel = CategoryModel & {
-  children: Pick<PostModel, 'id' | 'title' | 'slug' | 'modified' | 'created'>[]
+  children: CategoryChildPost[]
+  /** Aggregated tag-name → post-count for posts under this category. */
+  tagsSum?: Array<{ name: string; count: number }>
 }
 
 export type CategoryEntries = {
   entries: Record<string, CategoryWithChildrenModel>
 }
+
 export interface TagModel {
   count: number
   name: string
 }
+
+export type TagDetailPost = Pick<
+  PostModel,
+  | 'id'
+  | 'title'
+  | 'slug'
+  | 'category'
+  | 'created'
+  | 'modified'
+  | 'summary'
+  | 'tags'
+  | 'pin'
+  | 'count'
+>