バージョン: 0.9.0 (最新)

📂 カテゴリサービス

Category Serviceは、ステータス制御を備えた階層カテゴリを管理するための完全なREST APIを提供します。Nodeblocksの関数型コンポジションアプローチとMongoDB統合を使用して、商品カテゴリ、コンテンツ分類、組織構造を処理するように設計されています。

🚀 クイックスタート

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', 'dev', 'user', 'password');

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

📋 エンドポイント概要

カテゴリ操作

Method	Path	説明	認証が必要
`POST`	`/categories`	新しいカテゴリを作成	✅ 管理者
`GET`	`/categories/:categoryId`	IDでカテゴリを取得	❌
`GET`	`/categories`	すべてのカテゴリをリスト	❌
`PATCH`	`/categories/:categoryId`	カテゴリを更新	✅ 管理者
`DELETE`	`/categories/:categoryId`	カテゴリを削除	✅ 管理者

ステータス管理操作

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

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

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

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

フィールド詳細

Field	Type	自動生成	必須	説明
`name`	string	❌	✅	カテゴリ名
`description`	string	❌	✅	カテゴリの説明
`status`	string	❌	✅	カテゴリのステータス（'active'、'inactive'など）
`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>
Authorization: Bearerトークンが必要（管理者）

リクエストボディ:

Field	Type	必須	説明
`name`	string	✅	カテゴリ名
`description`	string	✅	カテゴリの説明
`status`	string	✅	カテゴリのステータス
`parent`	string	❌	親カテゴリID（階層構造用）

レスポンスボディ:

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

バリデーション:

スキーマバリデーション: 自動的に強制されます（name、description、status必須）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要

リクエスト例:

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": "Validation Error",
    "data": [
      "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パラメータ:

Parameter	Type	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンスボディ:

Field	Type	説明
`name`	string	カテゴリ名
`description`	string	カテゴリの説明
`status`	string	カテゴリのステータス
`parent`	string	親カテゴリID（該当する場合）
`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"
}

エラーレスポンス:

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

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

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

3. カテゴリのリスト取得

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

リクエスト:

Method: GET
Path: /categories
Authorization: 不要

クエリパラメータ:

Parameter	Type	必須	説明
`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
Authorization: 必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

リクエストボディ（すべてのフィールドはオプション）:

Field	Type	必須	説明
`name`	string	❌	カテゴリ名
`description`	string	❌	カテゴリの説明
`parent`	string	❌	親カテゴリID

⚠️ 重要: statusフィールドは更新リクエストでは許可されません。ステータスの変更には専用のenable/disableエンドポイントを使用してください。

レスポンスボディ:

Field	Type	説明
`name`	string	更新されたカテゴリ名
`description`	string	更新されたカテゴリの説明
`status`	string	カテゴリのステータス（変更なし）
`parent`	string	更新された親カテゴリID（該当する場合）
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のカテゴリ識別子
`updatedAt`	string	最終更新タイムスタンプ

バリデーション:

スキーマバリデーション: 自動的に強制されます（部分更新、限られたフィールドのみ許可）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要
- カテゴリが存在することを検証

リクエスト例:

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"
}

エラーレスポンス:

指定された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
Authorization: 必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンスボディ:

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

バリデーション:

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

リクエスト例:

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"
  }
}

🔄 ステータス管理操作

Category Serviceは、カテゴリのステータスを管理するための専用エンドポイントを提供します。

6. カテゴリの有効化

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

リクエスト:

Method: POST
Path: /categories/:categoryId/enable
Authorization: 必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンスボディ:

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

バリデーション:

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

リクエスト例:

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
Authorization: 必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`categoryId`	string	✅	一意のカテゴリ識別子

レスポンスボディ:

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

バリデーション:

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

リクエスト例:

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

成功レスポンス:

HTTP/1.1 204 No Content

🚨 エラーハンドリング

すべてのカテゴリサービスエラーは、適切なHTTPステータスコードと共にJSON形式で返されます：

一般的なエラーコード

Status	Error Message	説明
400	Validation Error	無効なリクエストボディ形式または必須フィールドの欠落
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	更新操作がデータを変更しなかった（変更が検出されなかった）
400	Failed to delete category	データベース削除操作が失敗した
401	Authentication failed	認証トークンが欠落しているか無効
401	token could not be verified	認証トークンが欠落しているか無効
401	Token fails security check	トークンのセキュリティ検証が失敗しました
403	User is not authorized to access this resource	ユーザーに必要な権限がありません（管理者アクセス）
404	Category does not exist	リクエストされた操作に対してカテゴリが存在しません
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 'description'",
      "request body must have required property 'status'"
    ]
  }
}

🔗 関連ドキュメント

Product Service - 商品管理操作
Attribute Service - 属性管理操作
User Service - ユーザー管理操作
Organization Service - 組織管理操作
Authentication Service - 認証と認可
Error Handling - エラーパターンの理解
Schema Component - データバリデーションの概念
Custom Service Tutorial - 独自のサービスを構築

🚀 クイックスタート​

📋 エンドポイント概要​

カテゴリ操作​

ステータス管理操作​

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

フィールド詳細​

🔐 認証ヘッダー​

🔧 APIエンドポイント​

1. カテゴリの作成​

2. IDでカテゴリを取得​

3. カテゴリのリスト取得​

4. カテゴリの更新​

5. カテゴリの削除​

🔄 ステータス管理操作​

6. カテゴリの有効化​

7. カテゴリの無効化​

🚨 エラーハンドリング​

一般的なエラーコード​

エラーレスポンス形式​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント概要

カテゴリ操作

ステータス管理操作

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

フィールド詳細

🔐 認証ヘッダー

🔧 APIエンドポイント

1. カテゴリの作成

2. IDでカテゴリを取得

3. カテゴリのリスト取得

4. カテゴリの更新

5. カテゴリの削除

🔄 ステータス管理操作

6. カテゴリの有効化

7. カテゴリの無効化

🚨 エラーハンドリング

一般的なエラーコード

エラーレスポンス形式

🔗 関連ドキュメント