📦 製品サービス

製品サービスは、製品エンティティを包括的なCRUD操作と強力なバッチ処理機能で管理するための完全な REST API を提供します。NodeBlocks の関数型合成アプローチで構築され、MongoDB とシームレスに統合します。

---

🚀 クイックスタート

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

const {nodeBlocksErrorMiddleware} = middlewares;
const {productService} = services;
const {withMongo, createFileStorageDriver} = drivers;

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

// 画像アップロードURLエンドポイントで必須:
// GOOGLE_APPLICATION_CREDENTIALS が GCP サービスアカウント JSON に設定されていることを確認してください。
const fileStorageDriver = createFileStorageDriver('your-gcp-project-id', 'your-bucket-name');

express()
  .use(
    productService(
      {
        ...(await connectToDatabase('products')),
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('profiles')), // いいねしたユーザーの機能に必要
        ...(await connectToDatabase('productVariants')), // 製品バリアントでは任意
        ...(await connectToDatabase('organizations')), // 組織別製品一覧に必要
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        authMode: 'bearer', // または 'cookie'
        identity: {
          typeIds: {
            admin: '100',
            guest: '000',
            regular: '001',
          },
        },
        organization: {
          roles: {
            admin: 'admin',
            member: 'member',
            owner: 'owner',
          },
        },
      },
      { fileStorageDriver }
    )
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

---

📋 エンドポイント概要

個別製品操作

メソッド	パス	説明	認可
POST	/products	新しい製品を作成	ベアラートークン必須（管理者のみ）
GET	/products/:productId	IDで製品を取得	不要
GET	/products	製品を一覧/フィルタ	不要
GET	/products/organizations/:organizationId	組織別の製品を一覧	ベアラートークン必須（組織メンバー以上）
GET	/products/:productId/likers	製品に「いいね」したユーザーを一覧	ベアラートークン必須（管理者のみ）
PATCH	/products/:productId	製品を更新	ベアラートークン必須（管理者のみ）
DELETE	/products/:productId	製品を削除	ベアラートークン必須（管理者のみ）
POST	/products/:productId/copy	既存の製品をコピー	ベアラートークン必須（管理者のみ）

ファイルアップロード操作

メソッド	パス	説明	認可
GET	/products/:productId/image-upload-url	製品画像アップロード用の署名付きURLを取得	ベアラートークン必須（管理者のみ）
POST	/products/:productId/images	製品画像エントリを作成	ベアラートークン必須（管理者のみ）
DELETE	/products/:productId/images/:imageId	製品画像を削除	ベアラートークン必須（管理者のみ）

バッチ製品操作

メソッド	パス	説明	認可
POST	/products/batch	複数の製品を作成	ベアラートークン必須（管理者のみ）
PATCH	/products/batch	複数の製品を更新	ベアラートークン必須（管理者のみ）
DELETE	/products/batch	複数の製品を削除	ベアラートークン必須（管理者のみ）
POST	/products/batch/copy	複数の製品をコピー	ベアラートークン必須（管理者のみ）

製品バリアント操作

メソッド	パス	説明	認可
POST	/products/:productId/variants	製品バリアントを作成	ベアラートークン必須（管理者のみ）
GET	/products/:productId/variants	製品のバリアントを一覧	不要
GET	/products/:productId/variants/:productVariantId	特定のバリアントを取得	ベアラートークン必須
PATCH	/products/:productId/variants/:productVariantId	製品バリアントを更新	ベアラートークン必須（管理者のみ）
DELETE	/products/:productId/variants/:productVariantId	製品バリアントを削除	ベアラートークン必須（管理者のみ）
POST	/product/:productId/variants/bulk	バリアントを一括作成	ベアラートークン必須（管理者のみ）
PATCH	/product/:productId/variants/bulk	バリアントを一括更新	ベアラートークン必須（管理者のみ）
POST	/product/:productId/variants/bulk-delete	バリアントを一括削除	ベアラートークン必須（管理者のみ）

注意: バリアントの一括操作は、意図的に複数形ではない /product/... を使用します。

---

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

製品エンティティは、自動生成されるベースフィールドと製品固有のデータで構成されます：

{
  "name": "string",
  "description": "string",
  "images": [
    {"objectId": "string (uuid)", "type": "string", "id": "string (uuid)"}
  ],
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細

フィールド	型	自動生成	必須	説明
name	string	❌	✅	製品名
description	string	❌	✅	製品説明
images	array	一部	✅	製品画像の配列
images[].objectId	string (uuid)	❌	✅	ストレージ内の画像ファイル識別子
images[].type	string	❌	✅	画像の MIME タイプ（例：image/png）
createdAt	datetime	✅	✅	作成日時
id	string	✅	✅	一意識別子（UUID）
updatedAt	datetime	✅	✅	最終更新日時

📝 注意: 自動生成フィールドはサービス側で設定され、作成/更新リクエストに含めないでください。各画像にも id、createdAt、updatedAt が設定されます。レスポンスでは画像を { type, url } に正規化し、objectId と画像のベースフィールドは返しません。フィールド順序は実際の API 出力と一致します。

---

🔐 認証ヘッダー

保護されたエンドポイントでは、次のヘッダーを含めてください：

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

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

🍪 Cookie 認証: authMode: 'cookie' の場合、アクセストークンは Authorization ヘッダーではなく accessToken Cookie から読み取られます。ホストアプリケーションで cookie-parser を登録してください。

---

🔧 APIエンドポイント

1. 製品作成

提供された情報で新しい製品を作成します。

リクエスト:

• メソッド: POST
• パス: /products
• ヘッダー: Content-Type: application/json, Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

リクエストボディ:

フィールド	型	必須	説明
name	string	✅	製品名
description	string	✅	製品説明

レスポンスボディ:

フィールド	型	説明
id	string	一意の製品識別子
name	string	製品名
description	string	製品説明
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: 自動強制（name、description必須）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X POST {{host}}/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "name": "Premium Widget",
    "description": "High-quality widget for enterprise use"
  }'

成功レスポンス:

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

{
  "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "name": "Premium Widget",
  "description": "High-quality widget for enterprise use",
  "createdAt": "2024-05-28T09:41:22.552Z",
  "updatedAt": "2024-05-28T09:41:22.552Z"
}

エラーレスポンス:

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

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

データベース挿入操作が失敗した場合:

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

{
  "error": {
    "message": "Failed to create product"
  }
}

---

2. IDで製品取得

一意のIDで特定の製品を取得します。

リクエスト:

• メソッド: GET
• パス: /products/:productId
• 認可: 不要

URL パラメータ:

パラメータ	型	必須	説明
productId	string	✅	一意の製品識別子

レスポンスボディ:

フィールド	型	説明
id	string	一意の製品識別子
name	string	製品名
description	string	製品説明
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: パスパラメータ検証（productId必須）
• ルートバリデーション: なし

リクエスト例:

curl {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2

成功レスポンス:

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

{
  "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "name": "Premium Widget",
  "description": "High-quality widget for enterprise use",
  "createdAt": "2024-05-28T09:41:22.552Z",
  "updatedAt": "2024-05-28T09:41:22.552Z"
}

エラーレスポンス:

指定IDの製品が存在しない場合:

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

{
  "error": {
    "message": "Product not found"
  }
}

---

3. 製品一覧

フィルタやページングを指定して製品の一覧を取得します。

リクエスト:

• メソッド: GET
• パス: /products
• 認可: 不要

クエリパラメータ:

パラメータ	型	必須	説明
name	string	❌	製品名でフィルタ
description	string	❌	製品説明でフィルタ
page	number	❌	ページングのページ番号
limit	number	❌	1ページあたりの件数

レスポンスボディ:

フィールド	型	説明
id	string	一意の製品識別子
name	string	製品名
description	string	製品説明
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: クエリパラメータ検証（オプションのname、description、page、limit）
• ルートバリデーション: なし

リクエスト例:

全件取得:

curl {{host}}/products

製品名でフィルタ:

curl "{{host}}/products?name=Premium%20Widget"

ページング指定:

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

成功レスポンス:

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

[
  {
    "name": "Premium Widget",
    "description": "Updated high-quality widget for enterprise use",
    "createdAt": "2025-06-24T06:39:17.101Z",
    "id": "3d0e4b74-398c-43e2-a7b4-c9a180477322",
    "updatedAt": "2025-06-24T06:39:17.101Z"
  },
  {
    "name": "Product A",
    "description": "Updated batch description",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "0e0dd6c7-c3d5-49e5-a1d8-20daa34d380a",
    "updatedAt": "2025-06-24T06:39:55.720Z"
  },
  {
    "name": "Product B",
    "description": "Updated batch description",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "d5a60fdf-2a22-4fcc-8e40-a68cb89cce72",
    "updatedAt": "2025-06-24T06:39:55.720Z"
  }
]

---

4. 組織 ID による製品一覧

GET /products/organizations/:organizationId は、組織に属する製品をページネーション付きで返します。組織メンバー以上の認証が必要です。

organizationId、page（1～1000）、limit（1～50）を使用できます。組織メンバー、管理者、または所有者であることを検証します。

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/organizations/org-123"

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/organizations/org-123?page=1&limit=5"

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

{"data":[{"id":"prod-123","organizationId":"org-456","name":"Premium Widget","description":"High-quality widget for professionals","images":[{"type":"image/jpeg","url":"https://storage.googleapis.com/bucket/abc123..."}],"createdAt":"2024-01-15T10:30:00Z","updatedAt":"2024-01-15T10:30:00Z"}],"metadata":{"pagination":{"page":1,"limit":5,"total":25,"totalPages":5,"hasNext":true,"hasPrev":false}}}

認証失敗は 401、組織へのアクセス権がない場合は 403、データベースまたはファイルストレージの失敗は 500 を返します。

5. 製品に「いいね」したユーザーの一覧

GET /products/:productId/likers は、製品に「いいね」したユーザーをページネーション付きで返します。管理者の認証が必要です。

productId、page（1～1000）、limit（1～50）を使用できます。レスポンスにはアバターがある場合、署名付き URL を含む avatar を返します。

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/prod-123/likers"

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/prod-123/likers?page=1&limit=5"

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

{"data":[{"id":"user-123","name":"John Doe","avatar":{"type":"image/jpeg","url":"https://storage.googleapis.com/bucket/abc123..."}}],"metadata":{"pagination":{"page":1,"limit":5,"total":25,"totalPages":5,"hasNext":true,"hasPrev":false}}}

認証失敗は 401、権限不足は 403、製品がない場合は 404、データベースまたはファイルストレージの失敗は 500 を返します。

6. 製品更新

部分更新で既存の製品を更新します。

リクエスト:

• メソッド: PATCH
• パス: /products/:productId
• ヘッダー: Content-Type: application/json, Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

URL パラメータ:

パラメータ	型	必須	説明
productId	string	✅	一意の製品識別子

リクエストボディ（全フィールド任意）:

フィールド	型	必須	説明
name	string	❌	製品名
description	string	❌	製品説明

レスポンスボディ:

フィールド	型	説明
id	string	一意の製品識別子
name	string	更新後の製品名
description	string	更新後の製品説明
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: 自動強制（部分更新、全フィールド任意、追加プロパティ不許可）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X PATCH {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"description": "Updated high-quality widget for enterprise use"}'

成功レスポンス:

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

{
  "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "name": "Premium Widget",
  "description": "Updated high-quality widget for enterprise use",
  "createdAt": "2024-05-28T09:41:22.552Z",
  "updatedAt": "2024-05-28T14:22:15.789Z"
}

エラーレスポンス:

指定IDの製品が存在しない場合:

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

{
  "error": {
    "message": "Product not found"
  }
}

---

7. 製品削除

システムから製品を完全に削除します。

リクエスト:

• メソッド: DELETE
• パス: /products/:productId
• ヘッダー: Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

URL パラメータ:

パラメータ	型	必須	説明
productId	string	✅	一意の製品識別子

レスポンスボディ:

フィールド	型	説明
なし	-	成功時はレスポンスボディなし

バリデーション:

• スキーマ検証: パスパラメータ検証（productId必須）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X DELETE {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2 \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

指定IDの製品が存在しない場合:

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

{
  "error": {
    "message": "Product not found"
  }
}

---

8. 製品コピー

既存の製品のコピーを新しいIDで作成します。

リクエスト:

• メソッド: POST
• パス: /products/:productId/copy
• ヘッダー: Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

URL パラメータ:

パラメータ	型	必須	説明
productId	string	✅	コピーする製品のID

レスポンスボディ:

フィールド	型	説明
id	string	コピーされた製品の一意識別子
name	string	製品名（オリジナルからコピー）
description	string	製品説明（オリジナルからコピー）
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: パスパラメータ検証（productId必須）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X POST {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/copy \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

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

{
  "id": "9abc123f-1cd8-4def-b123-456789abcdef",
  "name": "Premium Widget",
  "description": "High-quality widget for enterprise use",
  "createdAt": "2024-05-28T15:30:45.123Z",
  "updatedAt": "2024-05-28T15:30:45.123Z"
}

エラーレスポンス:

指定IDの製品が存在しない場合:

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

{
  "error": {
    "message": "Product not found"
  }
}

---

🔄 バッチ製品操作

製品サービスは、複数の製品を効率的に管理するための強力なバッチ操作を提供します。

9. 複数製品作成

単一のリクエストで複数の製品を作成します。

リクエスト:

• メソッド: POST
• パス: /products/batch
• ヘッダー: Content-Type: application/json, Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

リクエストボディ: 各々が name と description を必要とする製品オブジェクトの配列。

レスポンスボディ:

フィールド	型	説明
id	string	一意の製品識別子
name	string	製品名
description	string	製品説明
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: 自動強制（必須のnameおよびdescriptionを含む製品オブジェクトの配列）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X POST {{host}}/products/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[
    {
      "name": "Product A",
      "description": "Description for Product A"
    },
    {
      "name": "Product B",
      "description": "Description for Product B"
    }
  ]'

成功レスポンス:

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

[
  {
    "name": "Product A",
    "description": "Description for Product A",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "0e0dd6c7-c3d5-49e5-a1d8-20daa34d380a",
    "updatedAt": "2025-06-24T06:39:45.378Z"
  },
  {
    "name": "Product B",
    "description": "Description for Product B",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "d5a60fdf-2a22-4fcc-8e40-a68cb89cce72",
    "updatedAt": "2025-06-24T06:39:45.378Z"
  }
]

---

10. 複数製品更新

単一のリクエストで複数の製品を同じデータで更新します。

リクエスト:

• メソッド: PATCH
• パス: /products/batch
• ヘッダー: Content-Type: application/json, Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

リクエストボディ:

フィールド	型	必須	説明
ids	array of strings	✅	更新する製品IDの配列
data	object	✅	全製品に適用する更新データ
data.name	string	❌	新しい製品名
data.description	string	❌	新しい製品説明

レスポンスボディ:

フィールド	型	説明
id	string	一意の製品識別子
name	string	更新後の製品名
description	string	更新後の製品説明
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: 自動強制（ids配列とdataオブジェクト必須）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X PATCH {{host}}/products/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "ids": [
      "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
      "8fec096b-1bc7-5bfe-c827-3600e8fe2790"
    ],
    "data": {
      "description": "Updated batch description"
    }
  }'

成功レスポンス:

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

[
  {
    "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
    "name": "Product A",
    "description": "Updated batch description",
    "createdAt": "2024-05-28T09:41:22.552Z",
    "updatedAt": "2024-05-28T15:45:12.789Z"
  },
  {
    "id": "8fec096b-1bc7-5bfe-c827-3600e8fe2790",
    "name": "Product B",
    "description": "Updated batch description",
    "createdAt": "2024-05-28T09:41:23.123Z",
    "updatedAt": "2024-05-28T15:45:12.789Z"
  }
]

---

11. 複数製品削除

単一のリクエストで複数の製品を削除します。

リクエスト:

• メソッド: DELETE
• パス: /products/batch
• ヘッダー: Content-Type: application/json, Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

リクエストボディ: 削除する製品IDの配列。

レスポンスボディ:

フィールド	型	説明
なし	-	成功時はレスポンスボディなし

バリデーション:

• スキーマ検証: 自動強制（文字列の配列）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X DELETE {{host}}/products/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[
    "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
    "8fec096b-1bc7-5bfe-c827-3600e8fe2790"
  ]'

成功レスポンス:

HTTP/1.1 204 No Content

---

12. 複数製品コピー

単一のリクエストで複数の製品のコピーを作成します。

リクエスト:

• メソッド: POST
• パス: /products/batch/copy
• ヘッダー: Content-Type: application/json, Authorization: Bearer <access-token>
• 認可: ベアラートークン必須（管理者のみ）

リクエストボディ: コピーする製品IDの配列。

レスポンスボディ:

フィールド	型	説明
id	string	コピーされた製品の一意識別子
name	string	製品名（オリジナルからコピー）
description	string	製品説明（オリジナルからコピー）
createdAt	string	作成日時
updatedAt	string	最終更新日時

バリデーション:

• スキーマ検証: 自動強制（文字列の配列）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl -X POST {{host}}/products/batch/copy \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[
    "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
    "8fec096b-1bc7-5bfe-c827-3600e8fe2790"
  ]'

成功レスポンス:

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

[
  {
    "id": "9abc123f-1cd8-4def-b123-456789abcdef",
    "name": "Product A",
    "description": "Description for Product A",
    "createdAt": "2024-05-28T16:00:00.000Z",
    "updatedAt": "2024-05-28T16:00:00.000Z"
  },
  {
    "id": "def456a1-2e3f-4567-8901-23456789bcde",
    "name": "Product B",
    "description": "Description for Product B",
    "createdAt": "2024-05-28T16:00:00.100Z",
    "updatedAt": "2024-05-28T16:00:00.100Z"
  }
]

---

13. 製品画像アップロード URL の取得

製品画像を安全にアップロードするための署名付きURLを生成します。オブジェクトIDと一時的な署名付きURLを返します。

リクエスト:

• メソッド: GET
• パス: /products/:productId/image-upload-url
• ヘッダー: Authorization: Bearer <token>
• 認可: ベアラートークン必須（管理者のみ）

URL パラメータ:

パラメータ	型	必須	説明
productId	string	✅	対象製品ID

クエリパラメータ:

パラメータ	型	必須	説明
contentType	string	✅	画像MIMEタイプ（例: image/png）
contentLength	number	✅	ファイルサイズ（バイト単位、最大10MB）

レスポンスボディ:

フィールド	型	説明
objectId	string	製品画像用の生成されたストレージオブジェクトID
url	string	ファイルをアップロードするための署名付きURL

バリデーション:

• スキーマ検証: 画像アップロードスキーマを使用（コンテンツタイプとサイズ制約）
• ルートバリデーション:
  • 認証済みリクエスト（ベアラー）必須
  • 管理者ロール必須

リクエスト例:

curl "{{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/image-upload-url?contentType=image/webp&contentLength=2097152" \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

{
  "objectId": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "url": "https://storage.googleapis.com/bucket/products/...&X-Goog-Expires=900&X-Goog-Signature=..."
}

---

14. 製品画像の作成

POST /products/:productId/images は、アップロード済みオブジェクトの objectId と MIME type から画像エントリを作成します。管理者の認証が必要です。

URL パラメータ	型	必須	説明
productId	string	✅	対象製品 ID

リクエストフィールド	型	必須	説明
objectId	string	✅	アップロード URL から取得したストレージオブジェクト ID
type	string	✅	画像のタイプまたはカテゴリ

レスポンスフィールド	型	説明
type	string	画像の MIME タイプ
url	string	アップロード画像の署名付き URL

curl -X POST "{{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/images" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"objectId":"image-uuid-123","type":"product-image"}'

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

{"type":"image/webp","url":"https://storage.googleapis.com/bucket/products/...&X-Goog-Expires=900&X-Goog-Signature=..."}

15. 製品画像の削除

DELETE /products/:productId/images/:imageId は画像エントリを削除します。管理者の認証が必要です。

URL パラメータ	型	必須	説明
productId	string	✅	対象製品 ID
imageId	string	✅	削除する画像 ID

curl -X DELETE "{{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/images/image-uuid-123" \
  -H "Authorization: Bearer <access-token>"

16. 製品バリアントの作成

POST /products/:productId/variants は製品バリアントを作成します。管理者の認証が必要です。

リクエストフィールド	型	必須	説明
title	string	✅	バリアントのタイトル
description	string	❌	バリアントの説明
sku	string	❌	在庫管理単位の識別子
imageIds	string 配列	❌	バリアントに関連付ける画像 ID
price	object	❌	価格情報

price には amount、currency、taxIncluded、taxable を指定できます。リクエストボディでは title が必須です。

価格フィールド	型	必須	説明
amount	number	❌	価格
currency	string	❌	ISO 通貨コード
taxIncluded	boolean	❌	価格に税が含まれるか
taxable	boolean	❌	バリアントが課税対象か

レスポンスフィールド	型	説明
id	string	一意のバリアント識別子
productId	string	親製品 ID
title	string	バリアントのタイトル
description	string	バリアントの説明
sku	string	在庫管理単位
imageIds	array	画像 ID の配列
price	object	価格情報
createdAt	string	作成日時
updatedAt	string	最終更新日時

curl -X POST "{{host}}/products/product-123/variants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"title":"Large Size","description":"Large variant of the product","sku":"PROD-LG-001","price":{"amount":29.99,"currency":"USD","taxIncluded":false,"taxable":true}}'

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

{"id":"variant-456","productId":"product-123","title":"Large Size","description":"Large variant of the product","sku":"PROD-LG-001","price":{"amount":29.99,"currency":"USD","taxIncluded":false,"taxable":true},"createdAt":"2025-01-15T10:30:00.000Z","updatedAt":"2025-01-15T10:30:00.000Z"}

17. 製品バリアントの一覧

GET /products/:productId/variants は製品のバリアントを一覧で返します。認証は不要です。

page（1～1000）と limit（1～50）でページネーションを指定できます。レスポンスはバリアント配列 data とページネーション情報 metadata を返します。

{"data":[{"id":"string","productId":"string","title":"string","description":"string","sku":"string","imageIds":["string"],"price":{"amount":number,"currency":"string","taxIncluded":boolean,"taxable":boolean},"createdAt":"string","updatedAt":"string"}],"metadata":{"pagination":{"page":number,"limit":number,"total":number,"totalPages":number,"hasNext":boolean,"hasPrev":boolean}}}

curl "{{host}}/products/product-123/variants?page=1&limit=20"

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

{"data":[{"id":"variant-456","productId":"product-123","title":"Large Size","description":"Large variant","sku":"PROD-LG-001","imageIds":[],"price":{"amount":29.99,"currency":"USD","taxIncluded":false,"taxable":true},"createdAt":"2025-01-15T10:30:00.000Z","updatedAt":"2025-01-15T10:30:00.000Z"}],"metadata":{"pagination":{"page":1,"limit":20,"total":5,"totalPages":1,"hasNext":false,"hasPrev":false}}}

18. 製品バリアントの取得

GET /products/:productId/variants/:productVariantId は指定されたバリアントを返します。認証が必要です。

productId と productVariantId の両方を URL パラメータに指定します。リクエストには認証済みの bearer トークンが必要です。

URL パラメータ	型	必須	説明
productId	string	✅	親製品 ID
productVariantId	string	✅	バリアント ID

レスポンスフィールド	型	説明
id	string	一意のバリアント識別子
productId	string	親製品 ID
title	string	バリアントのタイトル
description	string	バリアントの説明
sku	string	在庫管理単位
imageIds	array	画像 ID の配列
price	object	価格情報
createdAt	string	作成日時
updatedAt	string	最終更新日時

curl "{{host}}/products/product-123/variants/variant-456" \
  -H "Authorization: Bearer <access-token>"

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

{"id":"variant-456","productId":"product-123","title":"Large Size","description":"Large variant of the product","sku":"PROD-LG-001","imageIds":[],"price":{"amount":29.99,"currency":"USD","taxIncluded":false,"taxable":true},"createdAt":"2025-01-15T10:30:00.000Z","updatedAt":"2025-01-15T10:30:00.000Z"}

認証に失敗した場合は 401、バリアントがない場合は 404、データベース操作に失敗した場合は 500 を返します。

19. 製品バリアントの更新

PATCH /products/:productId/variants/:productVariantId はバリアントを更新します。管理者の認証が必要です。

title、description、sku、imageIds、price はすべて任意です。price の amount、currency、taxIncluded、taxable も任意です。追加プロパティは使用できません。

更新フィールド	型	必須	説明
title	string	❌	バリアントのタイトル
description	string	❌	バリアントの説明
sku	string	❌	在庫管理単位の識別子
imageIds	string 配列	❌	関連付ける画像 ID
price	object	❌	価格情報

価格フィールド	型	必須	説明
amount	number	❌	価格
currency	string	❌	ISO 通貨コード
taxIncluded	boolean	❌	価格に税が含まれるか
taxable	boolean	❌	バリアントが課税対象か

更新レスポンスフィールド	型	説明
id	string	一意のバリアント識別子
productId	string	親製品 ID
title	string	更新後のバリアントタイトル
description	string	更新後のバリアント説明
sku	string	更新後の在庫管理単位
imageIds	array	更新後の画像 ID 配列
price	object	更新後の価格情報
createdAt	string	作成日時
updatedAt	string	最終更新日時

curl -X PATCH "{{host}}/products/product-123/variants/variant-456" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"price":{"amount":34.99,"currency":"USD"}}'

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

{"id":"variant-456","productId":"product-123","title":"Large Size","description":"Large variant of the product","sku":"PROD-LG-001","imageIds":[],"price":{"amount":34.99,"currency":"USD","taxIncluded":false,"taxable":true},"createdAt":"2025-01-15T10:30:00.000Z","updatedAt":"2025-01-15T14:22:15.789Z"}

認証失敗は 401、権限不足は 403、バリアントがない場合は 404、データベース操作の失敗は 500 を返します。

20. 製品バリアントの削除

DELETE /products/:productId/variants/:productVariantId はバリアントを削除します。管理者の認証が必要です。

curl -X DELETE "{{host}}/products/product-123/variants/variant-456" \
  -H "Authorization: Bearer <access-token>"

HTTP/1.1 204 No Content

認証失敗は 401、権限不足は 403、データベース操作の失敗は 500 を返します。

21. 製品バリアントの一括作成

POST /product/:productId/variants/bulk は複数のバリアントを作成します。管理者の認証が必要です。

1 回のリクエストで 1～100 件のバリアントを作成できます。各バリアントには title が必要です。

curl -X POST "{{host}}/product/product-123/variants/bulk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[{"title":"Small Size","sku":"PROD-SM-001"},{"title":"Large Size","sku":"PROD-LG-001"}]'

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

[{"id":"variant-1","productId":"product-123","title":"Small Size","sku":"PROD-SM-001"},{"id":"variant-2","productId":"product-123","title":"Large Size","sku":"PROD-LG-001"}]

22. 製品バリアントの一括更新

PATCH /product/:productId/variants/bulk は複数のバリアントを更新します。管理者の認証が必要です。

ids に更新対象のバリアント ID 配列を、data に共通の更新内容を指定します。

リクエストフィールド	型	必須	説明
ids	string 配列	✅	更新するバリアント ID の配列
data	object	✅	すべての対象に適用する更新データ

curl -X PATCH "{{host}}/product/product-123/variants/bulk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"ids":["variant-1","variant-2"],"data":{"price":{"amount":34.99,"currency":"USD"}}}'

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

[{"id":"variant-1","productId":"product-123"},{"id":"variant-2","productId":"product-123"}]

23. 製品バリアントの一括削除

POST /product/:productId/variants/bulk-delete は複数のバリアントを削除します。管理者の認証が必要です。

リクエストフィールド	型	必須	説明
ids	string 配列	✅	削除するバリアント ID の配列

curl -X POST "{{host}}/product/product-123/variants/bulk-delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"ids":["variant-1","variant-2"]}'

HTTP/1.1 204 No Content

製品 API フィールドリファレンス:

| 区分 | フィールドまたは操作 | 説明 | |---|---| | 製品 | id | 一意の製品識別子 | | 製品 | name | 製品名 | | 製品 | description | 製品説明 | | 製品 | images | 製品画像の配列 | | 製品 | images[].objectId | ストレージ内の画像オブジェクト ID | | 製品 | images[].type | 画像の MIME タイプ | | 製品 | images[].createdAt | 画像の作成日時 | | 製品 | images[].updatedAt | 画像の最終更新日時 | | 製品 | createdAt | 製品の作成日時 | | 製品 | updatedAt | 製品の最終更新日時 | | 画像 | objectId | アップロード済みファイルのストレージ ID | | 画像 | type | 作成する画像のカテゴリ | | 画像 | url | ファイルアクセス用の署名付き URL | | 画像 | contentType | アップロード URL 用の画像 MIME タイプ | | 画像 | contentLength | アップロードするファイルサイズ | | 組織一覧 | organizationId | 組織スコープの製品取得に使う ID | | 組織一覧 | page | ページ番号（1～1000） | | 組織一覧 | limit | 1ページあたりの件数（1～50） | | 組織一覧 | data | 製品オブジェクトの配列 | | 組織一覧 | metadata.pagination.page | 現在のページ番号 | | 組織一覧 | metadata.pagination.limit | ページサイズ | | 組織一覧 | metadata.pagination.total | 製品の総数 | | 組織一覧 | metadata.pagination.totalPages | 総ページ数 | | 組織一覧 | metadata.pagination.hasNext | 次のページがあるか | | 組織一覧 | metadata.pagination.hasPrev | 前のページがあるか | | いいね一覧 | productId | いいねを取得する製品 ID | | いいね一覧 | data[].id | いいねしたユーザーの ID | | いいね一覧 | data[].name | いいねしたユーザーの表示名 | | いいね一覧 | data[].avatar | 署名付き URL を含むアバター | | いいね一覧 | data[].avatar.type | アバター画像の MIME タイプ | | いいね一覧 | data[].avatar.url | アバター取得用の署名付き URL | | バリアント | productId | 親製品 ID | | バリアント | id | 一意のバリアント識別子 | | バリアント | title | バリアントのタイトル | | バリアント | description | バリアントの説明 | | バリアント | sku | 在庫管理単位の識別子 | | バリアント | imageIds | 関連付けた画像 ID の配列 | | バリアント | price | バリアントの価格情報 | | バリアント | price.amount | 価格 | | バリアント | price.currency | ISO 通貨コード | | バリアント | price.taxIncluded | 価格に税が含まれるか | | バリアント | price.taxable | 課税対象か | | バリアント | createdAt | バリアントの作成日時 | | バリアント | updatedAt | バリアントの最終更新日時 | | 一括作成 | POST /products/batch | 複数の製品を作成 | | 一括更新 | PATCH /products/batch | 複数の製品を更新 | | 一括削除 | DELETE /products/batch | 複数の製品を削除 | | 一括コピー | POST /products/batch/copy | 複数の製品をコピー | | 一括バリアント作成 | POST /product/:productId/variants/bulk | 1～100 件のバリアントを作成 | | 一括バリアント更新 | PATCH /product/:productId/variants/bulk | 指定したバリアント群を更新 | | 一括バリアント削除 | POST /product/:productId/variants/bulk-delete | 指定したバリアント群を削除 | | 一括バリアント | ids | 操作対象のバリアント ID 配列 | | 一括バリアント | data | 一括更新で適用する共通の更新データ | | 作成 | POST /products | 新しい製品を作成 | | 取得 | GET /products/:productId | ID 指定で製品を取得 | | 一覧 | GET /products | 製品を一覧またはフィルタ取得 | | 更新 | PATCH /products/:productId | 製品を部分更新 | | 削除 | DELETE /products/:productId | 製品を削除 | | コピー | POST /products/:productId/copy | 製品のコピーを作成 | | 画像 URL | GET /products/:productId/image-upload-url | 画像アップロード用の署名付き URL を取得 | | 画像作成 | POST /products/:productId/images | 製品画像エントリを作成 | | 画像削除 | DELETE /products/:productId/images/:imageId | 製品画像を削除 | | バリアント作成 | POST /products/:productId/variants | 製品バリアントを作成 | | バリアント一覧 | GET /products/:productId/variants | 製品のバリアントを一覧取得 | | バリアント取得 | GET /products/:productId/variants/:productVariantId | 指定バリアントを取得 | | バリアント更新 | PATCH /products/:productId/variants/:productVariantId | 指定バリアントを更新 | | バリアント削除 | DELETE /products/:productId/variants/:productVariantId | 指定バリアントを削除 | | 認可 | 製品作成 | 管理者の bearer 認証が必要 | | 認可 | 製品更新 | 管理者の bearer 認証が必要 | | 認可 | 製品削除 | 管理者の bearer 認証が必要 | | 認可 | 製品コピー | 管理者の bearer 認証が必要 | | 認可 | 組織別一覧 | 組織メンバー、管理者、または所有者が必要 | | 認可 | いいね一覧 | 管理者の bearer 認証が必要 | | 認可 | バリアント作成 | 管理者の bearer 認証が必要 | | 認可 | バリアント一覧 | 認証は不要 | | 認可 | バリアント取得 | bearer 認証が必要 | | 認可 | バリアント更新 | 管理者の bearer 認証が必要 | | 認可 | バリアント削除 | 管理者の bearer 認証が必要 | | 検証 | name | 製品作成時に必須 | | 検証 | description | 製品作成時に必須 | | 検証 | title | バリアント作成時に必須 | | 検証 | productId | 製品およびバリアント操作のパスで必須 | | 検証 | productVariantId | 個別バリアント操作のパスで必須 | | 検証 | imageId | 製品画像削除のパスで必須 | | エラー | 401 Unauthorized | 認証トークンがない、または無効 | | エラー | 403 Forbidden | 必要な管理者または組織権限がない | | エラー | 404 Not Found | 製品またはバリアントが存在しない | | エラー | 500 Internal Server Error | データベースまたはファイルストレージ操作に失敗 |

操作上の注意:

• 画像のストレージ参照は API レスポンスでアクセス可能な URL に正規化されます。
• 画像アップロード URL を取得した後で、返された URL へファイルをアップロードしてください。
• 画像エントリの作成では、アップロード済みの objectId を使用します。
• 製品画像を削除すると、関連するクラウドストレージファイルも削除されます。
• 製品作成では name と description の両方が必要です。
• 製品更新では指定したフィールドだけが変更されます。
• 製品の自動生成フィールドは作成または更新リクエストに指定しません。
• 製品コピーでは元の製品とは異なる新しい ID が生成されます。
• バッチ作成では各製品が個別に検証されます。
• バッチ更新では ids のすべての製品に同じ data を適用します。
• バッチ削除では削除対象の製品 ID 配列をリクエストボディに渡します。
• バッチコピーでは各コピーに新しい製品 ID が生成されます。
• 組織別一覧はマルチテナントの製品カタログに適しています。
• 組織別一覧では組織ロールの設定が必要です。
• 組織メンバーでないユーザーは組織別製品を取得できません。
• 製品に「いいね」したユーザーの一覧は管理者向けの分析に利用できます。
• いいね一覧のアバター URL はストレージ参照から正規化されます。
• バリアントを使用する場合は productVariants データストアを提供してください。
• バリアントのタイトルは作成時に必須です。
• バリアントの説明は任意です。
• バリアントの SKU は任意です。
• バリアントには複数の製品画像を関連付けられます。
• バリアント価格には通貨を指定できます。
• taxIncluded は価格に税を含めるかを表します。
• taxable はバリアントが課税対象かを表します。
• バリアント一覧は公開の読み取り操作です。
• 個別バリアントの取得には認証が必要です。
• バリアントの変更と削除は管理者に限定されます。
• 一括バリアント作成は 1 回につき 1～100 件を受け付けます。
• 一括バリアント更新は複数 ID と共通データを受け取ります。
• 一括バリアント削除は ID 配列を受け取ります。
• 一括バリアントルートは意図的に単数形の /product を使用します。
• 通常の製品ルートは複数形の /products を使用します。
• ページ番号は 1 から始まります。
• limit は 1 ページに返す最大件数を指定します。
• total はフィルター結果全体の件数を表します。
• totalPages は結果全体のページ数を表します。
• hasNext は次ページの有無を表します。
• hasPrev は前ページの有無を表します。
• 製品が見つからない場合は 404 を返します。
• バリアントが見つからない場合は 404 を返します。
• 認証情報がない場合は 401 を返します。
• 管理者権限がない場合は 403 を返します。
• 無効なリクエストボディは 400 を返します。
• データストア処理の失敗は 500 を返します。
• ファイルストレージ処理の失敗は 500 を返します。
• 署名付き URL には有効期限があるため、すぐに使用してください。
• 画像 MIME タイプとファイルサイズはアップロードスキーマで検証されます。
• 画像を含む製品のレスポンスでは画像ごとに type と url を返します。
• 製品データのフィールド順序は実際の API 出力に従います。
• 管理用クライアントでは、失敗したバッチ操作のエラーを表示してください。
• 公開クライアントでは、バリアント一覧のページネーションを処理してください。
• 製品カタログでは、組織スコープと公開スコープを区別してください。
• 画像を参照する前に、署名付き URL の有効期限を考慮してください。
• 管理者操作には安全な bearer トークンまたは cookie 認証を使用してください。
• authMode: 'cookie' を使う場合、アクセストークンは Cookie から読み取られます。
• bearer モードでは Authorization ヘッダーにアクセストークンを指定します。
• フィンガープリントが認可時に指定されている場合は x-nb-fingerprint も送信します。
• 製品とバリアントの ID は API が返した値を使用してください。
• SKU は在庫システムと統合する場合のアプリケーション側識別子として使用できます。
• 製品作成の成功レスポンスには作成日時と更新日時が含まれます。
• 製品更新の成功レスポンスには更新後の値が含まれます。
• 製品削除が成功した場合のステータスは 204 No Content です。
• 製品画像の作成が成功した場合のステータスは 201 Created です。
• バリアント作成が成功した場合のステータスは 201 Created です。
• バリアント更新が成功した場合のステータスは 200 OK です。
• バリアント削除が成功した場合のステータスは 204 No Content です。
• 一括バリアント削除が成功した場合のステータスは 204 No Content です。
• アップロード URL の取得には対象製品の ID が必要です。
• 画像エントリの作成には対象製品の ID が必要です。
• 画像エントリの削除には対象製品 ID と画像 ID が必要です。
• バリアント作成には親製品の ID が必要です。
• バリアント取得には親製品 ID とバリアント ID が必要です。
• バリアント更新には親製品 ID とバリアント ID が必要です。
• バリアント削除には親製品 ID とバリアント ID が必要です。
• バッチ製品操作には管理者認可が必要です。
• 個別製品の作成には管理者認可が必要です。
• 個別製品の更新には管理者認可が必要です。
• 個別製品の削除には管理者認可が必要です。
• 個別製品のコピーには管理者認可が必要です。
• 画像アップロード URL の取得には管理者認可が必要です。
• 製品画像の作成には管理者認可が必要です。
• 製品画像の削除には管理者認可が必要です。
• API レスポンスの URL は直接ストレージオブジェクト ID を公開しません。
• 画像 URL をクライアントに保存する場合は有効期限切れを処理してください。
• 組織別製品一覧は画像 URL の正規化を行います。
• いいね一覧はアバター URL の正規化を行います。
• バリアント一覧の各要素には親製品 ID が含まれます。
• バリアント一覧の各要素には価格情報を含められます。
• 一括作成のバリアントは同じ親製品に関連付けられます。
• 一括更新のバリアントは同じ親製品に属している必要があります。
• 一括削除のバリアントは同じ親製品に属している必要があります。
• 通貨コードは価格を扱うクライアントで適切に表示してください。
• 税の扱いは taxIncluded と taxable の組み合わせに従います。
• 管理ダッシュボードでは、製品とバリアントの更新日時を表示できます。
• 製品コピー後は、必要に応じて名前や説明を更新してください。
• 画像を追加する前に、対象製品が存在することを確認してください。
• バリアントを作成する前に、対象製品が存在することを確認してください。
• API エラーのサーバー返却メッセージは技術リテラルとして扱ってください。
• すべてのページネーションレスポンスでは data と metadata を確認してください。
• ページサイズはクライアントの表示要件に合わせて選択してください。
• 大きな製品カタログでは次ページの有無を使用して追加読み込みを実装できます。
• 価格を更新する場合は通貨コードも確認してください。
• 画像を更新する場合は新しいアップロード URL を取得してください。
• 削除済みの画像 ID を再利用しないでください。
• 製品の公開表示では正規化済みの画像 URL を使用してください。
• バリアントの公開表示ではタイトルと価格を一貫して表示してください。

バリアント機能では productVariants データストアが必要です。一括バリアントルートは、意図的に複数形ではない /product/:productId/variants/bulk および /bulk-delete を使用します。つまり、これらのルートでは /products/... プレフィックスを使用しません。

---

⚙️ 設定オプション

データストア

コレクション	必須	説明
products	✅	製品ドキュメント
identities	✅	アイデンティティの検索および認証コンテキスト
profiles	✅	製品に「いいね」したユーザーのプロフィール
productVariants	❌	製品バリアントのエンドポイントでのみ必要
organizations	❌	/products/organizations/:organizationId で必要

組織スコープのエンドポイントには configuration.organization.roles も必要です。このキーには owner、admin、member を含めてください。

サービス設定

interface ProductServiceConfiguration {
  authSecrets: {
    authEncSecret: string;    // JWT 暗号化シークレット
    authSignSecret: string;   // JWT 署名シークレット
  };
  authMode?: 'bearer' | 'cookie'; // 未指定時は bearer
  identity?: {
    typeIds?: {
      admin: string;          // 管理者ユーザー種別識別子
      guest: string;          // ゲストユーザー種別識別子
      regular: string;        // 一般ユーザー種別識別子
    };
  };
}

設定詳細

製品サービスの設定は、セキュリティおよびユーザー種別管理の論理グループに整理されています。

🔐 セキュリティ設定

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

• 型: { authEncSecret: string; authSignSecret: string }
• 説明: JWT の暗号化および署名に使用する秘密鍵（トークン検証に使用）
• 必須: 本番環境では必須
• 子プロパティ:
  • authEncSecret: JWT ペイロード暗号化の秘密鍵
  • authSignSecret: JWT 署名検証の秘密鍵

👥 ユーザー種別設定

user.typeIds - ユーザー種別識別子の設定

• 型: { admin?: string; guest?: string; user?: string }
• 説明: ロールベースアクセス制御のためのカスタムユーザー種別識別子
• デフォルト: undefined（デフォルトの種別検証を使用）
• 子プロパティ:
  • admin: 管理者ユーザー種別の識別子
    • 型: string
    • 説明: 管理者ユーザーのカスタム識別子
    • 利用例: 管理操作のロールベースアクセス制御
    • 例: "admin", "administrator", "superuser"
  • guest: ゲストユーザー種別の識別子
    • 型: string
    • 説明: ゲストユーザーのカスタム識別子
    • 利用例: 未認証/一時ユーザーの限定的アクセス
    • 例: "guest", "visitor", "anonymous"
  • user: 一般ユーザー種別の識別子
    • 型: string
    • 説明: 一般ユーザーのカスタム識別子
    • 利用例: 標準的なユーザー権限
    • 例: "user", "member", "customer"

設定例

const productConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret'
  },
  user: {
    typeIds: {
      admin: '100',
      guest: '000',
      user: '001'
    }
  }
};

---

🚨 エラーハンドリング

製品サービスのエラーは、適切なHTTPステータスコードとJSON形式で返されます：

代表的なエラーコード

ステータス	エラーメッセージ	説明
400	Validation Error	リクエストボディ形式が無効または必須フィールドがない
400	Failed to create product	データベース挿入操作が挿入されたIDを返せなかった
400	Failed to update product	更新操作でデータが変更されない（変更なし）
400	Failed to create products	バッチ作成操作が失敗した
400	Failed to update products	バッチ更新操作が失敗した
400	Failed to delete products	バッチ削除操作が失敗した
400	Failed to copy product	製品コピー操作が失敗した
400	Failed to copy products	バッチコピー操作が失敗した
401	token could not be verified	認可トークンがない/無効
403	User is not authorized to access this resource	必要な権限がない（管理者アクセス）
404	Product not found	要求された操作の対象製品が存在しない
500	Failed to create product	作成中のDB接続問題/予期せぬ失敗
500	Failed to get product	取得中のDB接続問題/予期せぬ失敗
500	Failed to find products	一覧取得中のDB接続問題/フィルタ構文不正/予期せぬ失敗
500	Failed to update product	更新中のDB接続問題/予期せぬ失敗
500	Failed to delete product	削除中のDB接続問題/予期せぬ失敗
500	Failed to copy product	コピー中のDB接続問題/予期せぬ失敗

エラーレスポンス形式

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

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

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

---

🔗 関連ドキュメント

• ユーザーサービス - ユーザー管理操作
• 組織サービス - 組織管理操作
• 認証サービス - 認証および認可
• エラーハンドリング - エラーパターンの理解
• スキーマコンポーネント - データ検証の概念
• カスタムサービステュートリアル - 独自サービスの構築