顧客管理プラグイン (Customer Management Plugin)¶

概要¶

Ritsubiの複雑な顧客管理要件に対応するVendureカスタムプラグイン。15種類の顧客ステータス管理と33カテゴリの商品アクセス制御を実現します。

互換性レンジ¶

Vendure: 3.5.x（apps/vendure-server は ^3.5.1 を使用）
Node.js: >=22.11.0（apps/vendure-server/package.json の engines に準拠）

パッケージ情報¶

パッケージ名: @ritsubi/customer-management-plugin
パス: /packages/plugins/customer-management
エントリーポイント: src/index.ts

実装機能¶

1. 顧客ステータス管理（15種類）¶

Ritsubiの顧客は15種類のステータスに分類され、それぞれ異なる権限とアクセスレベルを持ちます。

顧客ステータス一覧¶

ステータスコード	説明	アクセスレベル
`STATUS_01`	プレミアム企業会員	最高レベル
`STATUS_02`	一般企業会員	高レベル
`STATUS_03`	個人サロン（上級）	中～高レベル
...	...	...

2. 商品カテゴリアクセス制御（33カテゴリ）¶

顧客ステータスに応じて、アクセスできる商品カテゴリを動的に制御します。

カテゴリ体系¶

エクスビアンス（Exuviance）
├── スキンケア基礎化粧品
├── スペシャルケア商品
└── プロフェッショナル用商品

メソセウティカル（Mesoceutical）
├── 美容クリニック向け施術商品
└── 医療機関専用商品

美容機器消耗品
├── フェイシャル機器消耗品
├── ボディ機器消耗品
└── ...（14種類の機器カテゴリ）

3. 階層的権限管理¶

顧客ステータスに基づく階層的な権限システムを実装。

カタログ表示制御: ステータスごとに表示可能な商品を制御
価格表示制御: ステータスに応じた価格の表示・非表示
購入制限: 特定商品の購入可否を制御
キャンペーン適用: ステータスに応じたキャンペーン適用

4. ステータス変更履歴¶

顧客ステータスの変更履歴を記録し、トレーサビリティを確保。

5. 一括ステータス更新¶

管理画面から複数顧客のステータスを一括更新可能。

技術仕様¶

プラグイン設定オプション¶

export interface CustomerManagementPluginOptions {
  /**
   * 階層的顧客ステータス管理を有効にする
   */
  enableStatusHierarchy?: boolean;

  /**
   * カテゴリアクセス制御を有効にする
   */
  enableCategoryAccess?: boolean;

  /**
   * 管理画面での一括ステータス更新を有効にする
   */
  enableBulkStatusUpdate?: boolean;

  /**
   * ステータス変更履歴を記録する
   */
  enableStatusHistory?: boolean;
}

プラグイン初期化¶

import { CustomerManagementPlugin } from '@ritsubi/customer-management-plugin';

// Vendure設定
export const config: VendureConfig = {
  plugins: [
    CustomerManagementPlugin.init({
      enableStatusHierarchy: true,
      enableCategoryAccess: true,
      enableBulkStatusUpdate: true,
      enableStatusHistory: true,
    }),
  ],
};

サービス¶

CustomerStatusService¶

顧客ステータスの管理と検証を行うコアサービス。

主要メソッド:

getCustomerStatus(customerId: ID): Promise<CustomerStatus>
顧客の現在のステータスを取得
updateCustomerStatus(customerId: ID, newStatus: string): Promise<void>
顧客ステータスを更新
canAccessCategory(customerId: ID, categoryId: ID): Promise<boolean>
顧客が特定カテゴリにアクセス可能か判定
getAccessibleCategories(customerId: ID): Promise<Category[]>
顧客がアクセス可能なカテゴリ一覧を取得

対応する要件¶

要件定義書との対応¶

3.1.1 顧客ステータス管理: 15種類の顧客ステータスと階層的権限管理
3.1.2 商品カテゴリ体系・アクセス制御: 33カテゴリのアクセス制御

使用例¶

フロントエンド（Next.js）での使用¶

// 顧客がアクセス可能なカテゴリを取得
const { data } = await apolloClient.query({
  query: GET_ACCESSIBLE_CATEGORIES,
  variables: { customerId: currentUser.id },
});

// カテゴリアクセス可否の確認
const canAccess = await apolloClient.query({
  query: CAN_ACCESS_CATEGORY,
  variables: {
    customerId: currentUser.id,
    categoryId: 'exuviance-professional',
  },
});

管理画面での使用¶

// 顧客ステータス一括更新
await customerStatusService.bulkUpdateStatus(
  ['customer1', 'customer2', 'customer3'],
  'STATUS_02',
);

// ステータス変更履歴確認
const history = await customerStatusService.getStatusHistory('customer1');

データモデル¶

カスタムフィールド¶

このプラグインは以下のVendureカスタムフィールドを利用します（他プラグインで定義される場合があります）：

Customer.customerStatus - 顧客ステータスコード
Customer.statusChangeHistory - ステータス変更履歴（JSON形式）
Customer.accessibleCategories - アクセス可能カテゴリID一覧

開発ガイド¶

ローカル開発¶

# プラグインディレクトリへ移動
cd packages/plugins/customer-management

# 依存関係インストール
pnpm install

# ビルド
pnpm build

# テスト実行
pnpm test

型定義¶

export interface CustomerStatus {
  code: string;
  name: string;
  accessLevel: number;
  accessibleCategories: string[];
  canViewPrices: boolean;
  canPurchase: boolean;
}

セキュリティ考慮事項¶

アクセス制御の徹底: すべてのカテゴリアクセスはバックエンドで検証
ステータス変更権限: ステータス変更は管理者権限が必要
履歴の改ざん防止: ステータス変更履歴は追記のみ可能
GraphQL認証: すべてのクエリ・ミューテーションで認証を必須化

パフォーマンス最適化¶

キャッシング: 顧客ステータスとカテゴリアクセス情報をRedisにキャッシュ
バッチ処理: 一括ステータス更新はトランザクションで処理
遅延ロード: カテゴリ一覧は必要に応じて動的にロード

トラブルシューティング¶

よくある問題¶

問題: 顧客がカテゴリにアクセスできない

原因: ステータスの権限レベルが不足
解決: 管理画面で適切なステータスに更新

問題: ステータス変更が反映されない

原因: キャッシュのTTLが長すぎる
解決: キャッシュをクリアまたはTTLを調整

今後の拡張予定¶

ステータス自動昇格機能（購入実績ベース）
カテゴリアクセス申請ワークフロー
ステータス期限管理（年間契約など）
詳細な権限カスタマイズUI