採番モジュール

1. 目的

SequencesModule は、DynamoDB を主要なデータベースとして使用してシステム内で動的なシーケンスを管理するためのサービスです。

このサービスは次の目的で設計されています:

• シーケンスタイプ、テナント、日付などのパラメータに基づいて一意なシーケンス番号を生成します。
• 次のようなサイクルに基づいてシーケンスを自動的にリセットします:
  • 毎日。
  • 毎月。
  • 毎年。
  • 会計年度単位。

システムの特定の要件に従ってシーケンス番号をフォーマットします（例: TODO-PERSONAL-72-001）。 マルチテナントシステムでのデータの整合性と完全性を確保します。

動作の仕組み

2. 使用方法

SequencesModule の動作をカスタマイズするには、静的な register() メソッドでオプションの object を渡します。オプションオブジェクトには、1 つのプロパティのみが含まれています。

• enableController: デフォルトのシーケンスコントローラーを有効または無効にします。

シーケンスモジュールの使用方法とシーケンスコントローラーの認証をカスタマイズする方法を示す簡単な例を作成します。

// seq.controller.ts
import { SequencesController } from "@mbc-cqrs-serverless/sequence";
import { Controller } from "@nestjs/common";
import { ApiTags } from "@nestjs/swagger";
import { Auth } from "src/auth/auth.decorator";
import { ROLE } from "src/auth/role.enum";

@Controller("api/sequence")
@ApiTags("sequence")
@Auth(ROLE.ADMIN)
export class SeqController extends SequencesController {}

// seq.module.ts
import { SequencesModule } from "@mbc-cqrs-serverless/sequence";
import { Module } from "@nestjs/common";

import { SeqController } from "./seq.controller";

@Module({
  imports: [SequencesModule.register({ enableController: false })],
  controllers: [SeqController],
  exports: [SequencesModule],
})
export class SeqModule {}

コントローラーのほかに、SequencesService を直接注入して使用することでシーケンスを生成できます。

SequencesServiceには4つのパブリックメソッドがあります（現行2つ、非推奨1つ、v1.1.0で削除1つ）：

async generateSequenceItem(dto: GenerateFormattedSequenceDto, options?: {invokeContext: IInvoke}): Promise<SequenceEntity>

GenerateFormattedSequenceDto オブジェクトで提供されたパラメータに基づいて新しいシーケンスを生成します。

パラメータ

dto: GenerateFormattedSequenceDto（生成設定DTO） シーケンス生成の動作をカスタマイズするデータ転送オブジェクトです。そのプロパティには以下が含まれます:

• date?: Date（基準日、省略時は現在日時）

  • デフォルト: 現在の日付。
  • 説明: シーケンスが生成される日付を指定します。

• rotateBy?: RotateByEnum

  • デフォルト: NONE。

  • オプション

    • FISCAL_YEARLY（会計年度） ('fiscal_yearly')
    • YEARLY（年次） ('yearly')
    • MONTHLY（月次） ('monthly')
    • DAILY（日次） ('daily')
    • NONE（採番なし） ('none')

  • 説明: シーケンスカウンターが1にリセットされるタイミングを決定します。

  • ローテーション戦略の一覧:

    戦略	カウンターがリセットされる条件	例
    NONE	なし — カウンターは無限にインクリメント	1, 2, 3, … 9999
    DAILY	日付が変わったとき	毎日深夜にリセット
    MONTHLY	月が変わったとき	毎月1日にリセット
    YEARLY	年が変わったとき	毎年1月1日にリセット
    FISCAL_YEARLY	会計年度が変わったとき（開始月は startMonth で制御）	会計年度開始時にリセット；デフォルトは4月（日本の慣例）

• tenantCode: string

  • 必須: はい。
  • 説明: テナントと用途のタイプコードを識別します。

• typeCode: string（シーケンス種別コード）

  • 必須: はい。
  • 説明: シーケンスのタイプコードを識別します。

• params?: SequenceParamsDto（追加パラメーター）

  • 必須: いいえ
  • 説明: シーケンスを識別するためのパラメータを定義します。

    import { IsString, IsOptional } from 'class-validator';
    
    export class SequenceParamsDto {
      @IsString()
      code1: string
    
      @IsString()
      @IsOptional()
      code2?: string
    
      @IsOptional()
      @IsString()
      code3?: string
    
      @IsOptional()
      @IsString()
      code4?: string
    
      @IsOptional()
      @IsString()
      code5?: string
    
      constructor(partial: Partial<SequenceParamsDto>) {
        Object.assign(this, partial)
      }
    }

• prefix?: string

  • 必須: いいえ
  • 説明: フォーマットされたシーケンスの先頭に追加するオプションのプレフィックス。プレフィックスはフォーマットされたパターンの前に追加されます。
  • 例: prefixが'INV-'でフォーマットが'2024-001'を生成する場合、結果は'INV-2024-001'になります。

• postfix?: string

  • 必須: いいえ
  • 説明: フォーマットされたシーケンスの末尾に追加するオプションのポストフィックス。ポストフィックスはフォーマットされたパターンの後に追加されます。
  • 例: postfixが'-DRAFT'でフォーマットが'2024-001'を生成する場合、結果は'2024-001-DRAFT'になります。

レスポンス

この関数の戻り値は次のような SequenceEntity 型になります。

export class SequenceEntity {
  id: string
  no: number
  formattedNo: string
  issuedAt: Date

  constructor(partial: Partial<SequenceEntity>) {
    Object.assign(this, partial)
  }
}

カスタマイズ方法

デフォルトでは、返されるデータには、「%%no%%」形式の formattedNo フィールドが含まれます。「no」はシーケンス番号を表します。独自のカスタム形式を定義したい場合は、次のパラメータを使用して DynamoDB のマスター データを更新できます。

• PK: MASTER${KEY_SEPARATOR}${tenantCode}
• SK: MASTER_DATA${KEY_SEPARATOR}${typeCode}

データ構造は以下のとおりです：

  {
    "format": "string",
    "startMonth": "number",
    "registerDate": "string"
  }

例

たとえば、「code1」から「code5」、「year」、「month」、「day」、「date」、「no」、および「fiscal_year」をフォーマットに追加する場合、フォーマットは次のようになります。

{
  "format": "%%code2#:0>7%%-%%fiscal_year#:0>2%%-%%code3%%%%no#:0>3%%"
} 

このフォーマットでは:

• 変数は %% <param> %% 内に記述されます。
• #:0>N サフィックスは値を N 文字幅に左ゼロ埋めします（例: #:0>3 は 5 を 005 にします）。サフィックスを省略すると値はそのまま使用されます。

フォーマット指定子の一覧:

サフィックス	意味	入力 5 の場合	結果
（なし）	パディングなし — そのままの値	5	5
#:0>3	左ゼロ埋めで3文字幅にする	5	005
#:0>7	左ゼロ埋めで7文字幅にする	5	0000005

例えば:

• %%code2#:0>7%% は、code2 が 7 文字の長さにフォーマットされ、必要に応じて先頭にゼロが埋め込まれます。
• %%fiscal_year#:0>2%% は、fiscal_year を 2 文字の長さにフォーマットします。
• %%code3%% は code3 の値をそのまま表します。
• %%no#:0>3%% は、シーケンス番号 (no) が 3 桁の長さにフォーマットされ、必要に応じて先頭にゼロが埋め込まれることを保証します。

特定の月から始まる会計年度を計算したい場合は、「startMonth」フィールドを追加できます。たとえば、会計年度を 3 月から開始する場合、形式は次のようになります。

{
  "format": "%%code2#:0>7%%-%%fiscal_year#:0>2%%-%%code3%%%%no#:0>3%%",
  "startMonth": 3
}

この場合:

• startMonth: 会計年度を開始する月を定義します (例: 3 月の場合は 3)。デフォルトは 4 (4月)で、日本の会計年度慣習（4月〜3月）に従います。

特定の日付 (例: 2005-01-01) から始まる会計年度を計算したい場合は、次のように registerDate フィールドを追加できます。

{
  "format": "%%code2#:0>7%%-%%fiscal_year#:0>2%%-%%code3%%%%no#:0>3%%",
  "registerDate": "2005-01-01"
}

この場合:

• registerDate: 会計年度の正確な開始日を定義します (例: "2005-01-01")。

これにより、特定のビジネス ニーズに応じて会計年度の計算をカスタマイズできます。

async generateSequenceItemWithProvideSetting(dto: GenerateFormattedSequenceWithProvidedSettingDto, options?: {invokeContext: IInvoke}): Promise<SequenceEntity>

このメソッドを使用すると、DynamoDBでのマスターデータ設定なしで、DTOで直接提供されたカスタム設定でシーケンスを生成できます。

パラメータ

dto: GenerateFormattedSequenceWithProvidedSettingDto シーケンスパラメータとフォーマット設定の両方を含むデータ転送オブジェクト。プロパティには以下が含まれます：

• date?: Date（基準日、省略時は現在日時）

  • デフォルト: 現在の日付。
  • 説明: シーケンスが生成される日付を指定します。

• rotateBy?: RotateByEnum

  • デフォルト: NONE。
  • オプション: FISCAL_YEARLY, YEARLY, MONTHLY, DAILY, NONE
  • 説明: シーケンスカウンターがリセットされるタイミングを決定します。詳細は上の generateSequenceItem のローテーション戦略表を参照してください。

• tenantCode: string

  • 必須: はい。
  • 説明: シーケンスのテナントを識別します。

• typeCode: string（シーケンス種別コード）

  • 必須: はい。
  • 説明: シーケンスのタイプコードを識別します。

• params?: SequenceParamsDto（追加パラメーター）

  • 必須: いいえ
  • 説明: シーケンスを識別するためのパラメータを定義します（code1からcode5）。

• prefix?: string

  • 必須: いいえ
  • 説明: フォーマットされたシーケンスの先頭に追加するオプションのプレフィックス。

• postfix?: string

  • 必須: いいえ
  • 説明: フォーマットされたシーケンスの末尾に追加するオプションのポストフィックス。

• format: string

  • 必須: はい。
  • 説明: 生成されるシーケンスの構造を定義するフォーマット文字列。例: %%code1%%-%%no#:0>5%%。

• registerDate?: string

  • 必須: いいえ
  • 説明: 会計年度計算に影響を与えるオプションの登録日（ISO 8601形式）。

• startMonth?: number

  • 必須: いいえ
  • 説明: 会計年度の開始月（1-12）。指定しない場合のデフォルトは4（4月）。

例

import { RotateByEnum } from "@mbc-cqrs-serverless/sequence";

const result = await this.sequencesService.generateSequenceItemWithProvideSetting(
  {
    tenantCode: 'tenant001',
    typeCode: 'INVOICE',
    format: '%%code1%%-%%no#:0>5%%',
    rotateBy: RotateByEnum.YEARLY,
    params: { code1: 'INV' },
  },
  { invokeContext },
);
// Returns: { formattedNo: 'INV-00001', no: 1, ... }

固定のマスターデータ設定ではなく、リクエストごとに異なる動的なシーケンス設定が必要な場合にこのメソッドを使用します。

prefixとpostfixを使用した例：

import { RotateByEnum } from "@mbc-cqrs-serverless/sequence";

const result = await this.sequencesService.generateSequenceItemWithProvideSetting(
  {
    tenantCode: 'tenant001',
    typeCode: 'ORDER',
    format: '%%fiscal_year%%-%%no#:0>4%%',
    rotateBy: RotateByEnum.FISCAL_YEARLY,
    startMonth: 4,
    params: { code1: 'ORD' },
    prefix: 'ORD-',    // Prepended to formatted sequence (フォーマットされたシーケンスの先頭に追加)
    postfix: '-DRAFT', // Appended to formatted sequence (フォーマットされたシーケンスの末尾に追加)
  },
  { invokeContext },
);
// Returns: { formattedNo: 'ORD-2024-0001-DRAFT', no: 1, ... }

async getCurrentSequence(key: DetailKey): Promise<DataEntity> 非推奨

備考

非推奨、削除予定: この API 要素は将来のバージョンで削除される可能性があります

async genNewSequence( dto: GenerateSequenceDto, options: {invokeContext: IInvoke}): Promise<DataEntity> 削除済み

v1.1.0で削除

このメソッドはv1.1.0で削除されました。代わりにgenerateSequenceItemまたはgenerateSequenceItemWithProvideSettingを使用してください。

関連ドキュメント

• 設定 - SequencesModuleの設定オプション
• マスター - シーケンスフォーマット用のマスターデータ設定
• キーパターン - シーケンスをソートキーとして使用するPK/SK設計
• Todoアプリを作る - シーケンスを使った実践的な例
• インターフェース - SequencesModuleOptionsインターフェース