バージョン: 0.13.0 (Previous)

🏷️ 属性サービス

属性サービス (attributesService) は、キーバリューペアによる属性グループの管理ための完全な REST API を提供します。Nodeblocks の関数型コンポジションアプローチと MongoDB 統合を使用して、商品属性、カテゴリプロパティ、およびその他の構造化メタデータを処理するように設計されています。

🚀 クイックスタート

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

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

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

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

📋 エンドポイント一覧

属性グループ操作

メソッド	パス	説明	認証必要
`POST`	`/attributes`	新しい属性グループを作成	✅ 管理者
`GET`	`/attributes/:attributeId`	ID で属性グループを取得	❌ なし
`GET`	`/attributes`	属性グループの一覧/フィルタ	❌ なし
`PATCH`	`/attributes/:attributeId`	属性グループを更新	✅ 管理者
`DELETE`	`/attributes/:attributeId`	属性グループを削除	✅ 管理者

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

属性グループエンティティは、基本フィールド（自動生成）��属性固有のデータを組み合わせます:

{
  "name": "string",
  "items": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細

フィールド	タイプ	自動生成	必須	説明
`name`	string	❌	✅	属性グループ名
`items`	array	❌	✅	キーバリューペアの配列（最小1項目）
`items[].key`	string	❌	✅	属性キー/名前
`items[].value`	string	❌	✅	属性値
`createdAt`	datetime	✅	✅	作成タイムスタンプ
`id`	string	✅	✅	ユニーク識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新タイムスタンプ

📝 注: 自動生成フィールドはサービスによって設定され、作成/更新リクエストに含まれていてはなりません。items 配列には少なくとも1つのキーバリューペアを含める必要があります。

🔐 認証ヘッダー

ベアラー認証のリクエストには、以下のヘッダーを含めてください:

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

⚠️ 重要: x-nb-fingerprint ヘッダーは、認証時にフィンガープリントが指定された場合、ベアラー認証リクエストに必須です。クッキーモードでは、アクセストークンは Authorization ヘッダーではなく accessToken クッキーから読み取られます。

🔧 API エンドポイント

1. 属性グループの作成

提供された名前とキーバリューペアで新しい属性グループを作成します。

リクエスト:

メソッド: POST
パス: /attributes
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認証: 管理者ロールが必要

リクエストボディ:

フィールド	タイプ	必須	説明
`name`	string	✅	属性グループ名
`items`	array	✅	キーバリューペアの配列
`items[].key`	string	✅	属性キー/名前
`items[].value`	string	✅	属性値

レスポンスボディ:

フィールド	タイプ	説明
`name`	string	属性グループ名
`items`	array	キーバリューペアの配列
`items[].key`	string	属性キー/名前
`items[].value`	string	属性値
`createdAt`	string	作成タイムスタンプ
`id`	string	ユニークな属性グループID
`updatedAt`	string	最終更新タイムスタンプ

バリデーション:

スキーマバリデーション: 自動的に適用（name, items 必須、追加プロパティ不可）
ルートバリデータ:
- 認証済みリクエストを要求（ベアラートークン）
- 管理者ロールを要求

アイテムバリデーション: 少なくとも1つのアイテムを含み、それぞれに必須の key と value が必要です。

例リクエスト:

curl -X POST {{host}}/attributes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin_token>" \
  -H "x-nb-fingerprint: test-device-fingerprint" \
  -d '{
    "name": "商品仕様",
    "items": [
      {
        "key": "色",
        "value": "青"
      },
      {
        "key": "サイズ",
        "value": "大"
      },
      {
        "key": "素材",
        "value": "綿"
      }
    ]
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "name": "商品仕様",
  "items": [
    {
      "key": "色",
      "value": "青"
    },
    {
      "key": "サイズ",
      "value": "大"
    },
    {
      "key": "素材",
      "value": "綿"
    }
  ],
  "createdAt": "2025-07-07T08:52:49.796Z",
  "id": "69b013c9-cb20-4a7e-9c1f-59a55db1d949",
  "updatedAt": "2025-07-07T08:52:49.796Z"
}

エラーレスポンス:

必須フィールドが欠落している場合:

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

{
  "error": {
    "message": "バリデーションエラー",
    "data": [
      "リクエストボディに必須プロパティ 'items' がありません"
    ]
  }
}

アイテム配列が空の場合:

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

{
  "error": {
    "message": "バリデーションエラー",
    "data": [
      "リクエストボディは1個以上のアイテムを持つ必要があります"
    ]
  }
}

認証が失敗した場合:

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

{
  "error": {
    "message": "トークンを検証できませんでした"
  }
}

2. ID で属性グループを取得

一意の ID によって特定の属性グループを取得します。

リクエスト:

メソッド: GET
パス: /attributes/:attributeId
ヘッダー: なし
認証: 不要

URL パラメータ:

パラメータ	タイプ	必須	説明
`attributeId`	string	✅	ユニークな属性グループID

レスポンスボディ:

フィールド	タイプ	説明
`name`	string	属性グループ名
`items`	array	キーバリューペアの配列
`items[].key`	string	属性キー/名前
`items[].value`	string	属性値
`createdAt`	string	作成タイムスタンプ
`id`	string	ユニークな属性グループID
`updatedAt`	string	最終更新タイムスタンプ

バリデーション:

スキーマバリデーション: パスパラメータの attributeId でバリデーション
ルートバリデータ: なし

例リクエスト:

curl {{host}}/attributes/69b013c9-cb20-4a7e-9c1f-59a55db1d949

成功レスポンス:

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

{
  "name": "商品仕様",
  "items": [
    {
      "key": "色",
      "value": "青"
    },
    {
      "key": "サイズ",
      "value": "大"
    },
    {
      "key": "素材",
      "value": "綿"
    }
  ],
  "createdAt": "2025-07-07T08:52:49.796Z",
  "id": "69b013c9-cb20-4a7e-9c1f-59a55db1d949",
  "updatedAt": "2025-07-07T08:52:49.796Z"
}

エラーレスポンス:

指定された ID の属性グループが存在しない場合:

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

{
  "error": {
    "message": "属性グループが見つかりません"
  }
}

3. 属性グループの一覧

オプションのフィルタとページネーションで属性グループの一覧を取得します。

リクエスト:

メソッド: GET
パス: /attributes
ヘッダー: なし
認証: 不要

クエリパラメータ:

パラメータ	タイプ	必須	説明
`name`	string	❌	属性グループ名でフィルタ
`page`	number	❌	ページネーションのページ番号（1-1000）
`limit`	number	❌	ページあたりのアイテム数（1-50）

レスポンスボディ: 属性グループ配列とメタデータを含むページネーションレスポンス。

レスポンス構造:

{
  "data": [
    {
      "name": "string",
      "items": [
        {
          "key": "string",
          "value": "string"
        }
      ],
      "createdAt": "string",
      "id": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

バリデーション:

スキーマバリデーション: クエリパラメータの name とページネーション（page, limit）でバリデーション
ルートバリデータ: なし

例リクエスト:

すべての属性グループを一覧:

curl {{host}}/attributes

名前でフィルタ:

curl "{{host}}/attributes?name=商品"

成功レスポンス:

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

{
  "data": [
    {
      "name": "商品仕様",
      "items": [
        {
          "key": "色",
          "value": "青"
        },
        {
          "key": "サイズ",
          "value": "大"
        }
      ],
      "createdAt": "2025-07-07T08:52:49.796Z",
      "id": "69b013c9-cb20-4a7e-9c1f-59a55db1d949",
      "updatedAt": "2025-07-07T08:52:49.796Z"
    },
    {
      "name": "技術詳細",
      "items": [
        {
          "key": "重量",
          "value": "2.5kg"
        },
        {
          "key": "寸法",
          "value": "30x20x15cm"
        }
      ],
      "createdAt": "2025-07-07T08:20:45.456Z",
      "id": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
      "updatedAt": "2025-07-07T08:20:45.456Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

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

curl "{{host}}/attributes?page=1&limit=10"

4. 属性グループの更新

既存の属性グループを更新します。注: スキーマによると、name フィールドのみが更新可能です — items 配列は更新エンドポイントを通じて変更できません。

リクエスト:

メソッド: PATCH
パス: /attributes/:attributeId
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認証: 管理者ロールが必要

URL パラメータ:

パラメータ	タイプ	必須	説明
`attributeId`	string	✅	ユニークな属性グループID

リクエストボディ:

フィールド	タイプ	必須	説明
`name`	string	❌	新しい属性グループ名

JSON ボディは存在し空であってはなりません。名前がスキーマでオプションでも、空のボディ {} または欠落したボディは "リクエストボディが必要です" で 400 を返します。

レスポンスボディ:

フィールド	タイプ	説明
`name`	string	更新された属性グループ名
`items`	array	キーバリューペアの配列（変更なし）
`items[].key`	string	属性キー/名前
`items[].value`	string	属性値
`createdAt`	string	作成タイムスタンプ
`id`	string	ユニークな属性グループID
`updatedAt`	string	最終更新タイムスタンプ

バリデーション:

スキーマバリデーション: 自動的に適用（name フィールドのみ許可、追加プロパティ不可）
ルートバリデータ:
- 認証済みリクエストを要求（ベアラートークン）
- 管理者ロールを要求

⚠️ 重要: 更新スキーマは name フィールドの更新のみを許可します。items 配列を変更するには、属性グループを削除して再生成する必要があります。

例リクエスト:

curl -X PATCH {{host}}/attributes/69b013c9-cb20-4a7e-9c1f-59a55db1d949 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin_token>" \
  -H "x-nb-fingerprint: test-device-fingerprint" \
  -d '{"name": "更新された商品仕様"}'

成功レスポンス:

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

{
  "name": "更新された商品仕様",
  "items": [
    {
      "key": "色",
      "value": "青"
    },
    {
      "key": "サイズ",
      "value": "大"
    },
    {
      "key": "素材",
      "value": "綿"
    }
  ],
  "createdAt": "2025-07-07T08:52:49.796Z",
  "id": "69b013c9-cb20-4a7e-9c1f-59a55db1d949",
  "updatedAt": "2025-07-07T08:54:07.406Z"
}

エラーレスポンス:

指定された ID の属性グループが存在しない場合:

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

{
  "error": {
    "message": "属性グループが見つかりません"
  }
}

認証が失敗した場合:

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

{
  "error": {
    "message": "トークンを検証できませんでした"
  }
}

5. 属性グループの削除

属性グループをシステムから完全に削除します。

リクエスト:

メソッド: DELETE
パス: /attributes/:attributeId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認証: 管理者ロールが必要

URL パラメータ:

パラメータ	タイプ	必須	説明
`attributeId`	string	✅	ユニークな属性グループID

レスポンスボディ:

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

バリデーション:

スキーマバリデーション: パスパラメータの attributeId でバリデーション
ルートバリデータ:
- 認証済みリクエストを要求（ベアラートークン）
- 管理者ロールを要求

例リクエスト:

curl -X DELETE {{host}}/attributes/69b013c9-cb20-4a7e-9c1f-59a55db1d949 \
  -H "Authorization: Bearer <admin_token>" \
  -H "x-nb-fingerprint: test-device-fingerprint"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

指定された ID の属性グループが存在しない場合:

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

{
  "error": {
    "message": "属性が見つかりません"
  }
}

認証が失敗した場合:

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

{
  "error": {
    "message": "トークンを検証できませんでした"
  }
}

⚙️ 設定オプション

サービスデータストア

interface AttributesServiceDataStore {
  attributes: Collection; // 必須 - 属性グループコレクション
  identities: Collection; // 必須 - 認証コンテキスト用アイデンティティ
}

サービス設定

interface AttributesServiceConfiguration {
  authSecrets: {
    authEncSecret: string; // JWT 暗号化シークレット
    authSignSecret: string; // JWT 署名シークレット
  };
  authMode?: 'bearer' | 'cookie'; // デフォルト: 未設定の場合ベアラー動作
  identity?: {
    typeIds?: {
      admin: string; // 管理者ユーザータイプ識別子
      guest: string; // ゲストユーザータイプ識別子
      regular: string; // 一般ユーザータイプ識別子
    };
  };
}

設定詳細

属性サービス設定は、セキュリティとユーザータイプ管理の論理グループに整理されています。

🔐 セキュリティ設定

authSecrets — JWT トークンセキュリティシークレット

タイプ: { authEncSecret: string; authSignSecret: string }
説明: JWT 暗号化と署名用のシークレットキー（トークン検証に使用）
必須: はい（本番用）
子プロパティ:
- authEncSecret: JWT ペイロード暗号化用のシークレットキー
- authSignSecret: JWT 署名検証用のシークレットキー

👥 ユーザータイプ設定

identity.typeIds — ユーザータイプ識別子設定

タイプ: { admin: string; guest: string; regular: string }
説明: ロールベースアクセス制御用のカスタムユーザータイプ識別子
デフォルト: undefined（オブジェクトはオプションですが、存在する場合 checkIdentityType は3つのキーすべてを要求します）
子プロパティ:
- admin: 管理者ユーザータイプ識別子
  - タイプ: string
  - 説明: 管理者ユーザー用のカスタム識別子
  - ユースケース: 管理操作のロールベースアクセス制御
  - 例: "admin", "administrator", "superuser"
- guest: ゲストユーザータイプ識別子
  - タイプ: string
  - 説明: ゲストユーザー用のカスタム識別子
  - ユースケース: 認証済みまたは一時的なユーザーの制限付きアクセス
  - 例: "guest", "visitor", "anonymous"
- regular: 一般ユーザータイプ識別子
  - タイプ: string
  - 説明: 一般ユーザー用のカスタム識別子
  - ユースケース: 標準ユーザーアクセス権限
  - 例: "user", "member", "customer"

例設定

const attributesConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret',
  },
  identity: {
    typeIds: {
      admin: 'administrator',
      guest: 'visitor',
      regular: 'member',
    },
  },
};

🚨 エラーハンドリング

すべての属性サービスエラーは適切な HTTP ステータスコードで JSON フォーマットで返されます:

一般的なエラーコード

ステータス	エラーメッセージ	説明
400	バリデーションエラー	リクエストボディのフォーマットが無効または必須フィールドが欠落
400	リクエストボディに必須プロパティ 'name' がありません	リクエストボディに name フィールドが欠落
400	リクエストボディに必須プロパティ 'items' がありません	リクエストボディに items 配列が欠落
400	リクエストボディは1個以上のアイテムを持つ必要があります	アイテム配列が空（最小1項目必要）
400	リクエストボディは追加プロパティを持ってはいけません	リクエストにサポートされていないフィールドが含まれています
400	属性グループの作成に失敗しました	データベース挿入操作が挿入IDを返さない
400	属性グループの更新に失敗しました	更新操作がデータを変更しない（変更なし検出）
401	トークンを検証できませんでした	欠落または無効な認証トークン
401	無効なトークン	`checkIdentityType` でのユーザーアクセストークン検証でトークンが失敗
403	アイデンティティはこのリソースにアクセスする権限がありません	アイデンティティに必要なタイプの権限がありません（管理者アクセス）
404	属性が見つかりません	要求された操作に対して属性グループが存在しない
500	属性グループの作成中に不明なエラー	データベース接続問題または作成中の予期せぬ失敗
500	属性グループの取得に失敗しました	データベース接続問題または取得中の予期せぬ失敗
500	属性の検索に失敗しました	データベース接続問題、無効なフィルター構文、または一覧中の予期せぬ失敗
500	属性グループの更新に失敗しました	データベース接続問題または更新中の予期せぬ失敗
500	属性の削除に失敗しました	データベース接続問題または削除中の予期せぬ失敗

エラーレスポンスフォーマット

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

バリデーションエラー は追加詳細を含みます:

{
  "error": {
    "message": "バリデーションエラー",
    "data": [
      "リクエストボディに必須プロパティ 'name' がありません",
      "リクエストボディに必須プロパティ 'items' がありません",
      "リクエストボディは1個以上のアイテムを持つ必要があります"
    ]
  }
}

🔗 関連ドキュメント

商品サービス - 商品管理操作
プロフィールサービス - プロフィール管理操作
組織サービス - 組織管理操作
認証サービス - 認証と認可
エラーハンドリング - エラーパターンの理解
スキーマコンポーネント - データバリデーションの概念
カスタムサービスチュートリアル - 独自のサービスを構築

🚀 クイックスタート​

📋 エンドポイント一覧​

属性グループ操作​

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

フィールド詳細​

🔐 認証ヘッダー​

🔧 API エンドポイント​

1. 属性グループの作成​

2. ID で属性グループを取得​

3. 属性グループの一覧​

4. 属性グループの更新​

5. 属性グループの削除​

⚙️ 設定オプション​

サービスデータストア​

サービス設定​

設定詳細​

🔐 セキュリティ設定​

👥 ユーザータイプ設定​

例設定​

🚨 エラーハンドリング​

一般的なエラーコード​

エラーレスポンスフォーマット​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント一覧

属性グループ操作

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

フィールド詳細

🔐 認証ヘッダー

🔧 API エンドポイント

1. 属性グループの作成

2. ID で属性グループを取得

3. 属性グループの一覧

4. 属性グループの更新

5. 属性グループの削除

⚙️ 設定オプション

サービスデータストア

サービス設定

設定詳細

🔐 セキュリティ設定

👥 ユーザータイプ設定

例設定

🚨 エラーハンドリング

一般的なエラーコード

エラーレスポンスフォーマット

🔗 関連ドキュメント