バージョン: 0.5.0 (最新)

📂 カテゴリサービス

カテゴリサービスは、ステータス管理を備えた階層カテゴリを管理するための完全な REST API を提供します。Nodeblocks の関数型合成アプローチと MongoDB 連携により、製品カテゴリ、コンテンツ分類、組織構造を扱えるよう設計されています。

🚀 クイックスタート

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

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

const client = getMongoClient('mongodb://localhost:27017', 'dev');

express()
  .use(
    categoryService(
      {
        categories: client.collection('categories'),
        identities: client.collection('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'));

📋 エンドポイント概要

カテゴリ操作

メソッド	パス	説明	認証
`POST`	`/categories`	カテゴリを新規作成	✅ 管理者
`GET`	`/categories/:categoryId`	IDでカテゴリを取得	❌
`GET`	`/categories`	カテゴリ一覧を取得	❌
`PATCH`	`/categories/:categoryId`	カテゴリを更新	✅ 管理者
`DELETE`	`/categories/:categoryId`	カテゴリを削除	✅ 管理者

ステータス管理操作

メソッド	パス	説明	認証
`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)"
}

フィールド詳細

フィールド	型	自動生成	必須	説明
`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
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須（管理者）

リクエストボディ:

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

レスポンスボディ:

フィールド	型	説明
`name`	string	カテゴリ名
`description`	string	カテゴリの説明
`status`	string	カテゴリのステータス
`parent`	string	親カテゴリID（該当する場合）
`createdAt`	string	作成日時
`id`	string	カテゴリ一意ID
`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": "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
認可: 不要

URL パラメータ:

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

レスポンスボディ:

フィールド	型	説明
`name`	string	カテゴリ名
`description`	string	カテゴリの説明
`status`	string	カテゴリのステータス
`parent`	string	親カテゴリID（該当する場合）
`createdAt`	string	作成日時
`id`	string	カテゴリ一意ID
`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
認可: 不要

クエリパラメータ:

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

レスポンスボディ:

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

バリデーション:

スキーマ検証: 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

[
  {
    "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"
  }
]

4. カテゴリの更新

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

リクエスト:

Method: PATCH
Path: /categories/:categoryId
ヘッダー: 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	カテゴリ一意ID
`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"
}

エラーレスポンス:

指定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

🚨 エラーハンドリング

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

代表的なエラーコード

ステータス	エラーメッセージ	説明
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	作成中のDB接続問題/予期せぬ失敗
500	Failed to get category	取得中のDB接続問題/予期せぬ失敗
500	Failed to find categories	一覧取得中のDB接続問題/フィルタ不正/予期せぬ失敗
500	Failed to update category	更新中のDB接続問題/予期せぬ失敗
500	Failed to delete category	削除中のDB接続問題/予期せぬ失敗

エラーレスポンス形式

{
  "error": {
    "message": "Error message description",
    "data": ["Additional error details"]
  }
}

Validation Errors には追加情報が含まれます：

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

🔗 関連ドキュメント

プロダクトサービス - プロダクト管理
属性サービス - 属性管理
ユーザーサービス - ユーザー管理
組織サービス - 組織管理
認証サービス - 認証と認可
エラーハンドリング - エラーパターンの理解
スキーマコンポーネント - データ検証の概念
カスタムサービスチュートリアル - 独自サービスの構築

🚀 クイックスタート​

📋 エンドポイント概要​

カテゴリ操作​

ステータス管理操作​

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

フィールド詳細​

🔐 認証ヘッダー​

🔧 APIエンドポイント​

1. カテゴリの作成​

2. カテゴリの取得（ID指定）​

3. カテゴリ一覧​

4. カテゴリの更新​

5. カテゴリの削除​

🔄 ステータス管理操作​

6. カテゴリの有効化​

7. カテゴリの無効化​

🚨 エラーハンドリング​

代表的なエラーコード​

エラーレスポンス形式​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント概要

カテゴリ操作

ステータス管理操作

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

フィールド詳細

🔐 認証ヘッダー

🔧 APIエンドポイント

1. カテゴリの作成

2. カテゴリの取得（ID指定）

3. カテゴリ一覧

4. カテゴリの更新

5. カテゴリの削除

🔄 ステータス管理操作

6. カテゴリの有効化

7. カテゴリの無効化

🚨 エラーハンドリング

代表的なエラーコード

エラーレスポンス形式

🔗 関連ドキュメント