📂 カテゴリサービス

カテゴリサービスは、階層構造サポートとバルク操作を含むカテゴリエンティティ管理のための完全なREST APIを提供します。Nodeblocks関数コンポジションアプローチを使用して構築され、MongoDBとシームレスに統合されます。

---

🚀 クイックスタート

import express from 'express';
import { MongoClient } from 'mongodb';

import { middlewares, services } from '@nodeblocks/backend-sdk';

const { nodeBlocksErrorMiddleware } = middlewares;
const { categoryService } = services;

const client = new MongoClient('mongodb://localhost:27017').db('dev');

express()
  .use(
    categoryService(
      {
        categories: client.collection('categories'),
        identity: client.collection('identity'),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        user: {
          typeIds: {
            admin: '100',
            guest: '000',
            user: '001',
          },
        },
      }
    )
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('カテゴリサービスが起動しました'));

---

📋 エンドポイント概要

メソッド	パス	説明	認証
POST	/categories	新規カテゴリを作成	Bearerトークン必須（管理者）
GET	/categories/:categoryId	IDでカテゴリを取得	公開アクセス
GET	/categories	カテゴリリストを取得	公開アクセス
PATCH	/categories/:categoryId	カテゴリを更新	Bearerトークン必須（管理者）
DELETE	/categories/:categoryId	カテゴリを削除	Bearerトークン必須（管理者）
GET	/categories/tree	カテゴリツリーを取得	公開アクセス
POST	/categories/batch	バッチ操作を実行	Bearerトークン必須（管理者）

---

📂 カテゴリ操作

1. カテゴリ作成

curl -X POST http://localhost:8089/categories \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "エレクトロニクス",
    "description": "電子機器とアクセサリー",
    "slug": "electronics",
    "parentId": null,
    "metadata": {
      "icon": "🔌",
      "displayOrder": 1
    }
  }'

2. 子カテゴリ作成

curl -X POST http://localhost:8089/categories \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ノートパソコン",
    "description": "ポータブルコンピューター",
    "slug": "laptops",
    "parentId": "electronics-category-uuid",
    "metadata": {
      "icon": "💻",
      "displayOrder": 1
    }
  }'

3. カテゴリツリー取得

curl -X GET http://localhost:8089/categories/tree

レスポンス例:

{
  "tree": [
    {
      "id": "electronics-uuid",
      "name": "エレクトロニクス",
      "slug": "electronics",
      "level": 0,
      "children": [
        {
          "id": "laptops-uuid",
          "name": "ノートパソコン",
          "slug": "laptops",
          "level": 1,
          "children": []
        },
        {
          "id": "phones-uuid",
          "name": "スマートフォン",
          "slug": "phones",
          "level": 1,
          "children": []
        }
      ]
    }
  ]
}

---

📊 データスキーマ

カテゴリエンティティ

interface Category {
  id: string;                    // 一意識別子
  name: string;                  // カテゴリ名（必須）
  description?: string;          // カテゴリ説明
  slug: string;                  // URL用スラッグ（一意）
  parentId?: string;             // 親カテゴリID
  level: number;                 // 階層レベル（自動計算）
  path: string;                  // 階層パス（自動生成）
  status?: 'active' | 'inactive'; // ステータス
  metadata?: {
    icon?: string;               // アイコン
    color?: string;              // 色
    displayOrder?: number;       // 表示順序
    seo?: {
      title?: string;
      description?: string;
      keywords?: string[];
    };
  };
  statistics?: {
    productCount?: number;       // 商品数
    childrenCount?: number;      // 子カテゴリ数
  };
  createdAt: string;             // 作成日時
  updatedAt: string;             // 更新日時
}

---

🌳 階層管理

パス自動生成

// 階層パスの例
{
  "id": "laptops-uuid",
  "name": "ノートパソコン",
  "parentId": "electronics-uuid",
  "level": 1,
  "path": "/electronics/laptops"
}

階層操作

# 特定レベルのカテゴリ取得
curl -X GET "http://localhost:8089/categories?level=1"

# 特定親カテゴリの子要素取得
curl -X GET "http://localhost:8089/categories?parentId=electronics-uuid"

# 最大深度指定でツリー取得
curl -X GET "http://localhost:8089/categories/tree?maxDepth=2"

---

🛠️ 高度な機能

バッチ操作

# 複数カテゴリの一括作成
curl -X POST http://localhost:8089/categories/batch \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "categories": [
      {
        "name": "ホーム&ガーデン",
        "slug": "home-garden",
        "parentId": null
      },
      {
        "name": "家具",
        "slug": "furniture",
        "parentId": "home-garden-uuid"
      }
    ]
  }'

# 表示順序の一括更新
curl -X POST http://localhost:8089/categories/batch \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "reorder",
    "updates": [
      { "id": "category-1-uuid", "displayOrder": 1 },
      { "id": "category-2-uuid", "displayOrder": 2 },
      { "id": "category-3-uuid", "displayOrder": 3 }
    ]
  }'

カテゴリ移動

# カテゴリを別の親に移動
curl -X PATCH http://localhost:8089/categories/laptops-uuid \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": "computers-uuid"
  }'

---

🔍 検索とフィルタリング

高度な検索

# 名前で検索
curl -X GET "http://localhost:8089/categories?search=コンピューター"

# ステータスフィルタ
curl -X GET "http://localhost:8089/categories?status=active"

# 階層レベルフィルタ
curl -X GET "http://localhost:8089/categories?level=0" # ルートカテゴリのみ

# 表示順でソート
curl -X GET "http://localhost:8089/categories?sort=displayOrder&order=asc"

---

🧪 テスト例

describe('カテゴリサービス', () => {
  test('階層カテゴリ作成が成功する', async () => {
    // 親カテゴリを作成
    const parentCategory = await createCategory({
      name: 'エレクトロニクス',
      slug: 'electronics'
    });

    // 子カテゴリを作成
    const childCategory = await createCategory({
      name: 'ノートパソコン',
      slug: 'laptops',
      parentId: parentCategory.id
    });

    expect(childCategory.level).toBe(1);
    expect(childCategory.path).toBe('/electronics/laptops');
  });
});

---

🔗 関連リソース

• 商品サービス - カテゴリ関連商品
• 属性サービス - カテゴリ属性管理
• カテゴリブロック - 低レベルカテゴリコンポーネント