バージョン: 0.14.0 (最新)

📂 カテゴリサービス

Category サービスは、ステータス制御付きの階層カテゴリを管理する完全な REST API を提供します。Nodeblocks の関数合成アプローチと MongoDB 統合を使用し、Product カテゴリ、コンテンツ分類、組織構造を扱うよう設計されています。

🚀 クイックスタート

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

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

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

express()
  .use(
    categoryService(
      {
        ...(await connectToDatabase('categories')),
        ...(await connectToDatabase('identities')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        authMode: 'bearer', // or 'cookie',
        identity: {
          typeIds: {
            admin: '100',
            guest: '000',
            regular: '001',
          },
        },
      },
    ),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 エンドポイント概要

カテゴリ操作

メソッド	Path	説明	認証が必要
`POST`	`/categories`	新しいカテゴリを作成	✅ Admin
`GET`	`/categories/:categoryId`	ID でカテゴリを取得	❌
`GET`	`/categories`	すべてのカテゴリを一覧表示	❌
`PATCH`	`/categories/:categoryId`	カテゴリを更新	✅ Admin
`DELETE`	`/categories/:categoryId`	カテゴリを削除	✅ Admin

ステータス管理操作

メソッド	Path	説明	認証が必要
`POST`	`/categories/:categoryId/enable`	カテゴリを有効化（ステータスを 'active' に設定）	✅ Admin
`POST`	`/categories/:categoryId/disable`	カテゴリを無効化（ステータスを 'inactive' に設定）	✅ Admin

🗄️ エンティティスキーマ

カテゴリエンティティは、ベースフィールド（自動生成）とカテゴリ固有データを組み合わせます:

{
  "name": "string",
  "description": "string",
  "status": "string",
  "parent": "string",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細

フィールド	型	自動生成	必須	説明
`name`	string	❌	✅	カテゴリ名
`description`	string	❌	✅	カテゴリ説明
`status`	string	❌	✅	カテゴリステータス ('active', 'inactive', etc.)
`parent`	string	❌	❌	階層構造用の親カテゴリ ID
`createdAt`	datetime	✅	✅	作成タイムスタンプ
`id`	string	✅	✅	一意の識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新タイムスタンプ

📝 注: 自動生成フィールドはサービスが設定するため、作成／更新リクエストに含めないでください。parent フィールドにより階層カテゴリ構造を使用できます。

🔐 認証ヘッダー

保護されたエンドポイントでは、次のヘッダーを含めます:

Authorization: Bearer <admin_access_token>
x-nb-fingerprint: <device_fingerprint>

⚠️ 重要: 認可時にフィンガープリントが指定された場合、すべての認証済みリクエストで x-nb-fingerprint ヘッダーが必須です。ない場合、リクエストは 401 Unauthorized を返します。

🔧 API エンドポイント

1. カテゴリ作成

指定した情報で新しいカテゴリを作成します。

リクエスト:

Method: POST
Path: /categories
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: Bearer トークンが必要（管理者）

リクエスト本文:

フィールド	型	必須	説明
`name`	string	✅	カテゴリ名
`description`	string	✅	カテゴリ説明
`status`	string	✅	カテゴリステータス
`parent`	string	❌	親カテゴリ ID（階層構造用）

レスポンス本文:

フィールド	型	説明
`name`	string	カテゴリ名
`description`	string	カテゴリ説明
`status`	string	カテゴリステータス
`parent`	string	親カテゴリ ID（該当する場合）
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のカテゴリ識別子
`updatedAt`	string	最終更新タイムスタンプ

検証:

スキーマ検証: 自動適用（name、description、status が必須）
ルートバリデーター:
- 認証済みリクエスト（ベアラートークン）が必要
- 管理者ロールが必要

リクエスト例:

curl -X POST http://localhost:8089/categories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin_token>" \
  -H "x-nb-fingerprint: <device-fingerprint>" \
  -d '{
    "name": "Electronics",
    "description": "Electronic devices and accessories",
    "status": "active"
  }'

リクエスト例（親あり）:

curl -X POST http://localhost:8089/categories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin_token>" \
  -H "x-nb-fingerprint: <device-fingerprint>" \
  -d '{
    "name": "Smartphones",
    "description": "Mobile phones and accessories",
    "status": "active",
    "parent": "682f4a3e-e37e-4480-bc36-dda085e7ce26"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Electronics",
  "description": "Electronic devices and accessories",
  "status": "active",
  "createdAt": "2025-07-07T07:45:59.013Z",
  "id": "682f4a3e-e37e-4480-bc36-dda085e7ce26",
  "updatedAt": "2025-07-07T07:45:59.013Z"
}

エラーレスポンス:

リクエストボディがまったくない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Request body is required"
  }
}

リクエストボディに必須フィールドがない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'description'",
      "request body must have required property 'status'"
    ]
  }
}

認証に失敗した場合:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "Token fails security check"
  }
}

2. ID によるカテゴリ取得

一意の ID で指定したカテゴリを取得します。

リクエスト:

Method: GET
Path: /categories/:categoryId
Authorization: 不要

URL パラメーター:

パラメーター	型	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンス本文:

フィールド	型	説明
`name`	string	カテゴリ名
`description`	string	カテゴリ説明
`status`	string	カテゴリステータス
`parent`	string	Parent category ID (if applicable)
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のカテゴリ識別子
`updatedAt`	string	最終更新タイムスタンプ

検証:

スキーマ検証: categoryId パスパラメーターを検証
ルートバリデーター:
- カテゴリが存在することを検証

リクエスト例:

curl http://localhost:8089/categories/682f4a3e-e37e-4480-bc36-dda085e7ce26

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Electronics",
  "description": "Electronic devices and accessories",
  "status": "active",
  "createdAt": "2025-07-07T07:45:59.013Z",
  "id": "682f4a3e-e37e-4480-bc36-dda085e7ce26",
  "updatedAt": "2025-07-07T07:45:59.013Z"
}

エラーレスポンス:

リクエストボディがまったくない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Request body is required"
  }
}

指定した ID のカテゴリが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Category does not exist"
  }
}

3. カテゴリ一覧

すべてのカテゴリのリストを取得します。

リクエスト:

Method: GET
Path: /categories
Authorization: 不要

クエリパラメーター:

パラメーター	型	必須	説明
`name`	string	❌	カテゴリ名でフィルター
`description`	string	❌	説明でフィルター
`parent`	string	❌	親カテゴリ ID でフィルター
`status`	string	❌	ステータスでフィルター
`page`	number	❌	ページネーション用のページ番号（1～1000）
`limit`	number	❌	ページあたりの件数（1～50）

レスポンス本文: カテゴリ配列とメタデータを含むページネーション済みレスポンス。

レスポンス構造:

{
  "data": [
    {
      "name": "string",
      "description": "string",
      "status": "string",
      "parent": "string",
      "createdAt": "string",
      "id": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

検証:

スキーマ検証: name、description、parent、status、ページネーション（page、limit）のクエリパラメータを検証
ルートバリデーター: なし

リクエスト例:

すべてのカテゴリを一覧表示:

curl http://localhost:8089/categories

ステータスでフィルター:

curl "http://localhost:8089/categories?status=active"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "name": "Electronics",
      "description": "Electronic devices and accessories",
      "status": "active",
      "createdAt": "2025-07-07T07:45:59.013Z",
      "id": "682f4a3e-e37e-4480-bc36-dda085e7ce26",
      "updatedAt": "2025-07-07T07:45:59.013Z"
    },
    {
      "name": "Smartphones",
      "description": "Mobile phones and accessories",
      "status": "active",
      "parent": "682f4a3e-e37e-4480-bc36-dda085e7ce26",
      "createdAt": "2025-07-07T07:46:17.133Z",
      "id": "4260c15e-7791-4f09-a846-b6ffa3a73101",
      "updatedAt": "2025-07-07T07:46:17.133Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

ページネーション付きリクエスト例:

curl "http://localhost:8089/categories?page=1&limit=10"

4. カテゴリ更新

部分データで既存のカテゴリを更新します。

リクエスト:

Method: PATCH
Path: /categories/:categoryId
Headers: Content-Type: application/json
認可: 必須（管理者）

URL パラメーター:

パラメーター	型	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

リクエスト本文（すべて任意）:

フィールド	型	必須	説明
`name`	string	❌	カテゴリ名
`description`	string	❌	カテゴリ説明
`parent`	string	❌	親カテゴリ ID

⚠️ 重要: status フィールドは更新リクエストでは使用できません。ステータスの変更には専用の有効化／無効化エンドポイントを使用してください。

レスポンス本文:

フィールド	型	説明
`name`	string	更新後のカテゴリ名
`description`	string	更新後のカテゴリ説明
`status`	string	カテゴリステータス（変更されません）
`parent`	string	更新後の親カテゴリ ID（該当する場合）
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のカテゴリ識別子
`updatedAt`	string	最終更新タイムスタンプ

検証:

スキーマ検証: 自動適用（部分更新。指定できるフィールドは限定されます）
ルートバリデーター:
- 認証済みリクエスト（ベアラートークン）が必要
- 管理者ロールが必要
- カテゴリが存在することを検証

リクエスト例:

curl -X PATCH http://localhost:8089/categories/682f4a3e-e37e-4480-bc36-dda085e7ce26 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin_token>" \
  -d '{"description": "Updated electronic devices and accessories"}'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Electronics",
  "description": "Updated electronic devices and accessories",
  "status": "active",
  "createdAt": "2025-07-07T07:45:59.013Z",
  "id": "682f4a3e-e37e-4480-bc36-dda085e7ce26",
  "updatedAt": "2025-07-07T07:46:50.017Z"
}

エラーレスポンス:

リクエストボディがまったくない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Request body is required"
  }
}

指定した ID のカテゴリが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Category does not exist"
  }
}

リクエストボディに許可されないフィールドが含まれる場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties"
    ]
  }
}

5. カテゴリ削除

システムからカテゴリを完全に削除します。

リクエスト:

Method: DELETE
Path: /categories/:categoryId
認可: 必須（管理者）

URL パラメーター:

パラメーター	型	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンス本文:

フィールド	型	説明
レスポンスボディなし	-	削除エンドポイントは成功時にレスポンスボディを返しません

検証:

スキーマ検証: categoryId パスパラメーターを検証
ルートバリデーター:
- 認証済みリクエスト（ベアラートークン）が必要
- 管理者ロールが必要
- カテゴリが存在することを検証

リクエスト例:

curl -X DELETE http://localhost:8089/categories/682f4a3e-e37e-4480-bc36-dda085e7ce26 \
  -H "Authorization: Bearer <admin_token>"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

指定した ID のカテゴリが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Category does not exist"
  }
}

🔄 ステータス管理操作

カテゴリサービスは、カテゴリステータス管理用の専用エンドポイントを提供します。

6. カテゴリ有効化

カテゴリのステータスを 'active' に設定します。

リクエスト:

Method: POST
Path: /categories/:categoryId/enable
認可: 必須（管理者）

URL パラメーター:

パラメーター	型	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンス本文:

フィールド	型	説明
レスポンスボディなし	-	有効化エンドポイントは成功時にレスポンスボディを返しません

検証:

スキーマ検証: categoryId パスパラメーターを検証
ルートバリデーター:
- 認証済みリクエスト（ベアラートークン）が必要
- 管理者ロールが必要
- カテゴリが存在することを検証

リクエスト例:

curl -X POST http://localhost:8089/categories/682f4a3e-e37e-4480-bc36-dda085e7ce26/enable \
  -H "Authorization: Bearer <admin_token>"

成功レスポンス:

HTTP/1.1 204 No Content

7. カテゴリ無効化

カテゴリのステータスを 'inactive' に設定します。

リクエスト:

Method: POST
Path: /categories/:categoryId/disable
認可: 必須（管理者）

URL パラメーター:

パラメーター	型	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンス本文:

フィールド	型	説明
レスポンスボディなし	-	無効化エンドポイントは成功時にレスポンスボディを返しません

検証:

スキーマ検証: categoryId パスパラメーターを検証
ルートバリデーター:
- 認証済みリクエスト（ベアラートークン）が必要
- 管理者ロールが必要
- カテゴリが存在することを検証

リクエスト例:

curl -X POST http://localhost:8089/categories/682f4a3e-e37e-4480-bc36-dda085e7ce26/disable \
  -H "Authorization: Bearer <admin_token>"

成功レスポンス:

HTTP/1.1 204 No Content

🚨 エラー処理

すべての Category サービスエラーは、適切な HTTP ステータスコード付きの JSON 形式で返されます:

共通エラーコード

ステータス	エラーメッセージ	説明
400	Validation Error	リクエスト本文の形式が不正、または必須フィールドが不足
400	Request body is required	リクエスト本文がまったくない
400	request body must have required property 'name'	リクエスト本文に `name` フィールドがない
400	request body must have required property 'description'	リクエスト本文に `description` フィールドがない
400	request body must have required property 'status'	リクエスト本文に `status` フィールドがない
400	request body must NOT have additional properties	リクエストに未対応のフィールドが含まれる
400	Failed to create category	データベース挿入操作から挿入済み ID が返されなかった
400	Failed to update category	更新操作によるデータ変更がなかった
401	Invalid token	認証ペイロードが有効なユーザーアクセストークンではない
401	token could not be verified	認可トークンがない、または無効
401	Token fails security check	トークンのセキュリティ検証に失敗
403	Identity is not authorized to access this resource	必要な種別権限（管理者アクセス）がない
404	Category does not exist	保護されたルートで `doesCategoryExist` バリデーターが返す（取得、更新、削除、有効化、無効化）
404	Category not found	バリデーターを経由せずカテゴリハンドラーに到達した場合に返す
500	Failed to create category	作成中のデータベース接続問題、または予期しない失敗
500	Failed to get category	取得中のデータベース接続問題、または予期しない失敗
500	Failed to find categories	一覧取得中のデータベース接続問題、無効なフィルター構文、または予期しない失敗
500	Failed to update category	更新中のデータベース接続問題、または予期しない失敗
500	Failed to delete category	削除中のデータベース接続問題、または予期しない失敗

エラーレスポンス形式

{
  "error": {
    "message": "エラーメッセージの説明",
    "data": ["追加のエラー詳細"]
  }
}

検証エラーには追加の詳細が含まれます:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'description'",
      "request body must have required property 'status'"
    ]
  }
}

⚙️ 構成オプション

サービス構成

interface CategoryServiceConfiguration {
  authSecrets: {
    authEncSecret: string; // JWT 暗号化シークレット
    authSignSecret: string; // JWT 署名シークレット
  };
  authMode?: 'bearer' | 'cookie'; // 未指定時はベアラー認証
  identity?: {
    typeIds?: {
      admin: string;
      guest: string;
      regular: string;
    };
  };
}

🍪 Cookie 認証: authMode: 'cookie' の場合、保護されたルートは Cookie からアクセストークンを読み取ります。ホストアプリは cookie-parser を登録する必要があります。

データストア

コレクション	必須	説明
`categories`	✅	カテゴリドキュメント
`identities`	✅	アイデンティティ検索／認証コンテキスト

🔗 関連ドキュメント

製品サービス - 製品管理操作
属性サービス - 属性管理操作
プロフィールサービス - プロフィール管理操作
組織サービス - 組織管理操作
認証サービス - 認証と認可
エラー処理 - エラーパターンの理解
スキーマコンポーネント - データ検証の概念
カスタムサービスチュートリアル - 独自サービスの構築

🚀 クイックスタート​

📋 エンドポイント概要​

カテゴリ操作​

ステータス管理操作​

🗄️ エンティティスキーマ​

フィールド詳細​

🔐 認証ヘッダー​

🔧 API エンドポイント​

1. カテゴリ作成​

2. ID によるカテゴリ取得​

3. カテゴリ一覧​

4. カテゴリ更新​

5. カテゴリ削除​

🔄 ステータス管理操作​

6. カテゴリ有効化​

7. カテゴリ無効化​

🚨 エラー処理​

共通エラーコード​

エラーレスポンス形式​

⚙️ 構成オプション​

サービス構成​

データストア​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント概要

カテゴリ操作

ステータス管理操作

🗄️ エンティティスキーマ

フィールド詳細

🔐 認証ヘッダー

🔧 API エンドポイント

1. カテゴリ作成

2. ID によるカテゴリ取得

3. カテゴリ一覧

4. カテゴリ更新

5. カテゴリ削除

🔄 ステータス管理操作

6. カテゴリ有効化

7. カテゴリ無効化

🚨 エラー処理

共通エラーコード

エラーレスポンス形式

⚙️ 構成オプション

サービス構成

データストア

🔗 関連ドキュメント