CMS NestJS Modules (內容管理系統模組)

Overview

@rytass/cms-base-nestjs-module 系列提供完整的 NestJS CMS 解決方案，支援文章管理、分類系統、審核流程和多語言內容。

套件清單

套件	說明
`@rytass/cms-base-nestjs-module`	核心 CMS 模組（服務層、實體、DataLoader）
`@rytass/cms-base-nestjs-graphql-module`	GraphQL 整合層（Resolvers、Queries、Mutations）

Quick Start

安裝

# 核心模組
npm install @rytass/cms-base-nestjs-module

# GraphQL 整合（可選）
npm install @rytass/cms-base-nestjs-graphql-module

基本設定

import { CMSBaseModule } from '@rytass/cms-base-nestjs-module';

@Module({
  imports: [
    TypeOrmModule.forRoot({ /* 資料庫配置 */ }),
    CMSBaseModule.forRoot({
      multipleLanguageMode: true,
      enableDraftMode: true,
      signatureLevels: ['編輯', '主編'],
    }),
  ],
})
export class AppModule {}

GraphQL 整合

import { CMSBaseGraphQLModule } from '@rytass/cms-base-nestjs-graphql-module';

@Module({
  imports: [
    GraphQLModule.forRoot({ /* Apollo 配置 */ }),
    CMSBaseGraphQLModule.forRoot({
      multipleLanguageMode: true,
      enableDraftMode: true,
      signatureLevels: ['編輯', '主編'],
    }),
  ],
})
export class AppModule {}

Core Concepts

文章生命週期 (Article Stages)

DRAFT → REVIEWING → VERIFIED → SCHEDULED/RELEASED
                  ↓
               DELETED

階段	說明	觸發操作
`DRAFT`	草稿	建立/退回
`REVIEWING`	審核中	submit()
`VERIFIED`	已核准	approve()
`SCHEDULED`	預約發布	release(futureDate)
`RELEASED`	已發布	release()
`DELETED`	已刪除	archive()
`UNKNOWN`	未知狀態	例外狀態

Symbol-Based 注入

import {
  RESOLVED_ARTICLE_REPO,
  ArticleBaseService,
} from '@rytass/cms-base-nestjs-module';

@Injectable()
export class ArticleResolver {
  constructor(
    @Inject(RESOLVED_ARTICLE_REPO)
    private readonly articleRepo: Repository<BaseArticleEntity>,

    // ArticleBaseService 直接使用類別注入
    private readonly articleService: ArticleBaseService,
  ) {}
}

DataLoader 模式

防止 N+1 查詢問題：

import { ArticleDataLoader } from '@rytass/cms-base-nestjs-module';

@Injectable()
export class ArticleResolver {
  constructor(private readonly articleDataLoader: ArticleDataLoader) {}

  @ResolveField()
  async categories(@Parent() article: Article) {
    return this.articleDataLoader.categoriesLoader.load(article.id);
  }
}

可用的 DataLoaders：

DataLoader	提供的 Loaders
`ArticleDataLoader`	`stageLoader`, `categoriesLoader`
`ArticleVersionDataLoader`	`stageVersionsLoader`, `versionsLoader`
`ArticleSignatureDataLoader`	`versionSignaturesLoader`
`CategoryDataLoader`	`withParentsLoader`

Common Patterns

自訂實體擴展

import { BaseArticleEntity } from '@rytass/cms-base-nestjs-module';

@Entity('articles')
@ChildEntity()
export class CustomArticle extends BaseArticleEntity {
  @Column({ nullable: true })
  featuredImage?: string;

  @Column({ type: 'jsonb', nullable: true })
  seoMetadata?: Record<string, any>;
}

// 模組配置
CMSBaseModule.forRoot({
  articleEntity: CustomArticle,
  articleVersionEntity: CustomArticleVersion,       // 可選
  articleVersionContentEntity: CustomContent,       // 可選
  categoryEntity: CustomCategory,                   // 可選
})

文章版本管理

// 新增版本
await articleService.addVersion(articleId, {
  title: '更新標題',
  content: [...],
  categoryIds: ['cat-1'],
  userId: 'user-1',
  submitted: true,  // 直接提交審核
});

// 刪除特定版本
await articleService.deleteVersion(articleId, 2);

// 封存文章（軟刪除）
await articleService.archive(articleId);

多語言內容

// 建立多語言文章
await articleService.create({
  multiLanguageContents: {
    'zh-TW': { title: '標題', content: '內容' },
    'en-US': { title: 'Title', content: 'Content' },
  },
  categoryIds: ['cat-1'],
});

審核流程

// 1. 提交審核
await articleService.submit(articleId, { userId: 'user-1' });

// 2. 核准
await articleService.approveVersion(
  { id: articleId, version: 1 },
  { signatureLevel: '主編', signerId: 'user-1' },
);

// 3. 發布
await articleService.release(articleId, {
  releasedAt: new Date(),
  version: 1,  // 可選，指定版本
  userId: 'user-1',
});

// 4. 退回（重新編輯）
await articleService.putBack(articleId);

// 5. 拒絕審核
await articleService.rejectVersion(
  { id: articleId },
  { signatureLevel: '主編', signerId: 'user-1', reason: '內容不完整' },
);

// 6. 撤回已發布文章
await articleService.withdraw(articleId, 1);  // id, version

GraphQL 查詢範例

# 公開文章列表
query Articles($page: Int, $limit: Int) {
  articles(page: $page, limit: $limit) {
    items {
      articleId
      title
      categories { id, name }
      releasedBy { username }
    }
    meta { totalCount, hasNextPage }
  }
}

# 後台文章（含所有階段）
query BackstageArticles($stage: ArticleStage) {
  backstageArticles(stage: $stage) {
    items {
      articleId
      stage
      signatures { approved, level }
    }
  }
}

權限控制整合

注意： BaseResource 和 BaseAction 枚舉定義在 @rytass/cms-base-nestjs-graphql-module 的 src/constants/enum/ 目錄下，但目前未從 index.ts 導出。如需使用，請直接引用字串或在專案中自行定義。

import { AllowActions } from '@rytass/member-base-nestjs-module';

@Mutation()
@AllowActions([['article', 'create']])  // 使用字串代替枚舉
async createArticle() { }

Module Options

選項	預設	說明
`multipleLanguageMode`	false	啟用多語言內容
`allowMultipleParentCategories`	false	分類允許多個父分類
`allowCircularCategories`	false	分類允許循環參照
`fullTextSearchMode`	false	啟用全文搜尋
`enableDraftMode`	false	啟用草稿模式
`signatureLevels`	[]	審核層級定義
`autoReleaseWhenLatestSignatureApproved`	false	最終核准後自動發布
`articleEntity`	BaseArticleEntity	自訂文章實體類別
`articleVersionEntity`	BaseArticleVersionEntity	自訂文章版本實體類別
`articleVersionContentEntity`	BaseArticleVersionContentEntity	自訂文章內容實體類別
`categoryEntity`	BaseCategoryEntity	自訂分類實體類別
`categoryMultiLanguageNameEntity`	BaseCategoryMultiLanguageNameEntity	自訂多語言分類名稱實體類別
`signatureLevelEntity`	BaseSignatureLevelEntity	自訂審核層級實體類別

Additional Types

Enums

// 文章階段
enum ArticleStage {
  DRAFT = 'DRAFT',
  REVIEWING = 'REVIEWING',
  VERIFIED = 'VERIFIED',
  SCHEDULED = 'SCHEDULED',
  RELEASED = 'RELEASED',
  DELETED = 'DELETED',
  UNKNOWN = 'UNKNOWN',
}

// 文章排序
enum ArticleSorter {
  CREATED_AT_DESC = 'CREATED_AT_DESC',
  CREATED_AT_ASC = 'CREATED_AT_ASC',
  UPDATED_AT_DESC = 'UPDATED_AT_DESC',
  UPDATED_AT_ASC = 'UPDATED_AT_ASC',
  SUBMITTED_AT_DESC = 'SUBMITTED_AT_DESC',
  SUBMITTED_AT_ASC = 'SUBMITTED_AT_ASC',
  RELEASED_AT_DESC = 'RELEASED_AT_DESC',
  RELEASED_AT_ASC = 'RELEASED_AT_ASC',
}

// 文章搜尋模式
enum ArticleSearchMode {
  FULL_TEXT = 'full_text',
  TITLE = 'title',
  TITLE_AND_TAG = 'title-and-tag',
}

// 審核結果
enum ArticleSignatureResult {
  APPROVED = 'APPROVED',
  REJECTED = 'REJECTED',
}

Error Classes

// 基礎錯誤
class MultipleLanguageModeIsDisabledError extends Error {}

// 文章相關錯誤
class ArticleNotFoundError extends Error {}
class ArticleVersionNotFoundError extends Error {}

// 分類相關錯誤
class CategoryNotFoundError extends Error {}
class CircularCategoryNotAllowedError extends Error {}
class MultipleParentCategoryNotAllowedError extends Error {}
class ParentCategoryNotFoundError extends Error {}

Symbol Tokens

Repository Tokens（可用於依賴注入）：

RESOLVED_ARTICLE_REPO
RESOLVED_ARTICLE_VERSION_REPO
RESOLVED_ARTICLE_VERSION_CONTENT_REPO
RESOLVED_CATEGORY_REPO
RESOLVED_CATEGORY_MULTI_LANGUAGE_NAME_REPO
RESOLVED_SIGNATURE_LEVEL_REPO

Mode Tokens（模組配置狀態）：

MULTIPLE_LANGUAGE_MODE
DRAFT_MODE
MULTIPLE_CATEGORY_PARENT_MODE
CIRCULAR_CATEGORY_MODE
FULL_TEXT_SEARCH_MODE
SIGNATURE_LEVELS
AUTO_RELEASE_AFTER_APPROVED

API Reference

詳細 API 文件請參閱 reference.md。

Troubleshooting

循環依賴錯誤

使用 Symbol Token 注入而非直接類別注入：

// 正確
@Inject(RESOLVED_ARTICLE_REPO) repo: Repository<Article>

// 避免
constructor(private readonly repo: ArticleRepository)

DataLoader 快取問題

ArticleDataLoader 提供的 loaders：

stageLoader - 帶 LRU 快取
categoriesLoader - 帶 LRU 快取

如需無快取版本，請在自訂 DataLoader 時設定：

// DataLoader 本身支援 cache: false 選項
const uncachedLoader = new DataLoader(
  (keys) => this.batchLoad(keys),
  { cache: false }
);

多語言模式未啟用

確認模組配置 multipleLanguageMode: true，否則只能存取第一個語言內容。

cms-modules