バージョン: 0.13.0 (Previous)

👤 プロフィールサービス

プロフィールサービスは、プロフィールエンティティを CRUD 操作で管理する完全な REST API です。Nodeblocks の関数型コンポジションアプローチで構築され、MongoDB とシームレスに統合されます。

🚀 クイックスタート

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

const {nodeBlocksErrorMiddleware} = middlewares;
const {profileService} = services;
const {withMongo} = drivers;
const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

express()
  .use(
    profileService(
      {
        ...(await connectToDatabase('profiles')),
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('organizations')),
        ...(await connectToDatabase('products')),
      },
      {
        authSecrets: {authEncSecret: 'your-encryption-secret', authSignSecret: 'your-signing-secret'},
        authMode: 'bearer', // または 'cookie'
        identity: {typeIds: {admin: '100', guest: '000', regular: '001'}},
      },
      // 任意の第3引数: { fileStorageDriver }。アバターアップロード URL と URL 正規化に必要
    ),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089);

📋 エンドポイント一覧

メソッド	パス	説明	認可
`POST`	`/profiles`	プロフィールを作成	ベアラートークン
`GET`	`/profiles/:profileId`	ID でプロフィールを取得	管理者または所有者
`GET`	`/profiles`	プロフィールを一覧／フィルタ	管理者のみ
`GET`	`/profiles/identities/:identityId`	identity ID で取得	本人のみ
`PATCH`	`/profiles/:profileId`	プロフィールを更新	管理者または所有者
`DELETE`	`/profiles/:profileId`	プロフィールを削除	管理者または所有者

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

メソッド	パス	説明
`GET`	`/profiles/:profileId/avatar-upload-url`	アバター用の署名付きアップロード URL を取得

プロフィールフォロー操作

メソッド	パス	説明
`PUT`	`/profiles/:profileId/profile-follows/:followProfileId`	プロフィールのフォローを作成
`DELETE`	`/profiles/:profileId/profile-follows/:followProfileId`	プロフィールのフォローを削除
`GET`	`/profiles/:profileId/followers`	ページネーション付きのフォロワーを取得

組織フォロー操作

メソッド	パス	説明
`PUT`	`/profiles/:profileId/organization-follows/:followOrganizationId`	組織フォローを作成
`DELETE`	`/profiles/:profileId/organization-follows/:followOrganizationId`	組織フォローを削除

商品いいね操作

メソッド	パス	説明
`PUT`	`/profiles/:profileId/product-likes/:likeProductId`	商品へのいいねを作成
`DELETE`	`/profiles/:profileId/product-likes/:likeProductId`	商品へのいいねを削除

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

{
  "id": "string",
  "createdAt": "string (datetime)",
  "updatedAt": "string (datetime)",
  "identityId": "string",
  "name": "string",
  "avatar": {"url": "string", "type": "string"},
  "profileFollows": [{"followProfileId": "string"}],
  "organizationFollows": [{"followOrganizationId": "string"}],
  "productLikes": [{"likeProductId": "string"}]
}

フィールド詳細

フィールド	型	自動生成	必須	説明
`id`	string	✅	✅	一意識別子（UUID）
`createdAt` / `updatedAt`	datetime	✅	✅	作成／最終更新日時
`identityId`	string	❌	✅	紐づくアイデンティティ ID
`name`	string	❌	✅	表示名
`avatar`	object または null	❌	❌	アバターのストレージメタデータ
`profileFollows`	array	✅	✅	プロフィールフォロー（空配列で初期化）
`organizationFollows`	array	✅	✅	組織フォロー（空配列で初期化）
`productLikes`	array	✅	✅	商品いいね（空配列で初期化）

注: 自動生成フィールドは作成／更新リクエストに含めません。avatar は null またはストレージメタデータを持つオブジェクトです。

🔐 認証ヘッダー

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

認可時にフィンガープリントを指定した場合、x-nb-fingerprint はすべての認証済みリクエストで必須です。authMode: 'cookie' では Bearer ヘッダーの代わりに Cookie からアクセストークンを読み取るため、ホストアプリで cookie-parser を登録してください。

🔧 API エンドポイント

1. プロフィールの作成

POST /profiles は identityId と name（必須）、および任意の avatar を受け取ります。対象 identity の管理者または本人である必要があります。成功時は作成済みプロフィールと空のフォロー／いいね配列を返します。

2. ID によるプロフィール取得

GET /profiles/:profileId は、管理者または対象プロフィールの所有者にプロフィールを返します。

3. プロフィール一覧

GET /profiles は管理者専用です。スキーマで定義されたフィルターおよびページネーション用クエリパラメータを指定できます。

4. プロフィールの更新

PATCH /profiles/:profileId は、管理者または所有者が表示名とアバター情報を部分更新するためのエンドポイントです。identity の関連付けや自動生成フィールドは変更できません。

5. プロフィールの削除

DELETE /profiles/:profileId は、管理者または所有者がプロフィールを削除します。成功時は 204 No Content を返します。

6. アバターアップロード URL の取得

GET /profiles/:profileId/avatar-upload-url は、所有者または管理者にアバターアップロード用の署名付き URL を返します。サービスの第3引数に fileStorageDriver を指定する必要があります。

7. identity ID によるプロフィール検索

GET /profiles/identities/:identityId は指定 identity に関連するプロフィールを返します。自己アクセスのみ許可されます。

8. プロフィールフォローの作成

PUT /profiles/:profileId/profile-follows/:followProfileId でフォローを作成します。

9. プロフィールフォローの削除

DELETE /profiles/:profileId/profile-follows/:followProfileId でフォローを解除します。

10. プロフィールフォロワーの取得

GET /profiles/:profileId/followers はフォロワーをページネーション付きで返します。

11. 組織フォローの作成

PUT /profiles/:profileId/organization-follows/:followOrganizationId で組織をフォローします。

12. 組織フォローの削除

DELETE /profiles/:profileId/organization-follows/:followOrganizationId で組織フォローを解除します。

13. 商品いいねの作成

PUT /profiles/:profileId/product-likes/:likeProductId で商品にいいねを付けます。

14. 商品いいねの削除

DELETE /profiles/:profileId/product-likes/:likeProductId で商品へのいいねを削除します。

プロフィール API リファレンス:

操作	パス	認可	成功時
プロフィール作成	`POST /profiles`	管理者または対象 identity の本人	`200 OK`
プロフィール取得	`GET /profiles/:profileId`	管理者またはプロフィール所有者	`200 OK`
プロフィール一覧	`GET /profiles`	管理者のみ	`200 OK`
プロフィール更新	`PATCH /profiles/:profileId`	管理者またはプロフィール所有者	`200 OK`
プロフィール削除	`DELETE /profiles/:profileId`	管理者またはプロフィール所有者	`204 No Content`
アバター URL	`GET /profiles/:profileId/avatar-upload-url`	管理者またはプロフィール所有者	`200 OK`
identity 別検索	`GET /profiles/identities/:identityId`	本人のみ	`200 OK`
プロフィールをフォロー	`PUT /profiles/:profileId/profile-follows/:followProfileId`	管理者またはプロフィール所有者	`204 No Content`
プロフィールのフォローを解除	`DELETE /profiles/:profileId/profile-follows/:followProfileId`	管理者またはプロフィール所有者	`204 No Content`
フォロワー取得	`GET /profiles/:profileId/followers`	管理者またはプロフィール所有者	`200 OK`
組織をフォロー	`PUT /profiles/:profileId/organization-follows/:followOrganizationId`	管理者またはプロフィール所有者	`204 No Content`
組織のフォローを解除	`DELETE /profiles/:profileId/organization-follows/:followOrganizationId`	管理者またはプロフィール所有者	`204 No Content`
商品にいいね	`PUT /profiles/:profileId/product-likes/:likeProductId`	管理者またはプロフィール所有者	`204 No Content`
商品のいいねを解除	`DELETE /profiles/:profileId/product-likes/:likeProductId`	管理者またはプロフィール所有者	`204 No Content`

プロフィールフィールド	型	必須	説明
`id`	string	自動生成	一意のプロフィール識別子
`identityId`	string	作成時に必須	関連付けるアイデンティティ ID
`name`	string	作成時に必須	表示名
`avatar`	object または null	❌	アバターのストレージメタデータ
`profileFollows`	array	自動生成	プロフィールフォローの配列
`organizationFollows`	array	自動生成	組織フォローの配列
`productLikes`	array	自動生成	商品いいねの配列
`createdAt`	string	自動生成	作成日時
`updatedAt`	string	自動生成	最終更新日時

作成リクエストでは identityId と name が必要です。avatar は任意で、{ objectId, type } を指定できます。追加プロパティは許可されません。更新では name と avatar のみ変更でき、リクエストボディ自体は空にできません。

curl -X POST {{host}}/profiles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"identityId":"811ff0a3-a26f-447b-b68a-dd83ea4000b9","name":"John Doe"}'

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

{"id":"7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2","identityId":"811ff0a3-a26f-447b-b68a-dd83ea4000b9","name":"John Doe","profileFollows":[],"organizationFollows":[],"productLikes":[],"createdAt":"2024-05-28T09:41:22.552Z","updatedAt":"2024-05-28T09:41:22.552Z"}

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

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

{"id":"7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2","identityId":"811ff0a3-a26f-447b-b68a-dd83ea4000b9","name":"John Doe Updated","avatar":null,"profileFollows":[],"organizationFollows":[],"productLikes":[],"createdAt":"2024-05-28T09:41:22.552Z","updatedAt":"2024-05-28T09:41:22.552Z"}

プロフィール一覧では identityId、name、page（1～1000）、limit（1～50）を使用してフィルターできます。レスポンスは data 配列と metadata.pagination を返します。

curl "{{host}}/profiles?name=John&page=1&limit=20" \
  -H "Authorization: Bearer <access-token>"

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

{"data":[{"id":"7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2","identityId":"811ff0a3-a26f-447b-b68a-dd83ea4000b9","name":"John Doe","avatar":null,"profileFollows":[],"organizationFollows":[],"productLikes":[]}],"metadata":{"pagination":{"page":1,"limit":20,"total":1,"totalPages":1,"hasNext":false,"hasPrev":false}}}

curl -X PATCH {{host}}/profiles/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"name":"John Doe Updated"}'

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

{"id":"7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2","name":"John Doe Updated","avatar":null}

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

HTTP/1.1 204 No Content

アバターアップロード URL では contentType と contentLength が必要です。許可される画像タイプは JPEG、PNG、WebP、GIF、SVG、AVIF、BMP、アイコン、TIFF、HEIF、HEIC で、サイズ上限は 10 MB です。

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

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

identity 別検索は本人のみが実行できます。page の既定値は 1、limit の既定値は 10 です。アバターがある場合は、ストレージ参照を署名付き URL に正規化します。

curl "{{host}}/profiles/identities/identity-123?page=1&limit=10" \
  -H "Authorization: Bearer <access-token>"

{"data":[{"id":"profile-123","identityId":"identity-123","name":"John Doe","avatar":{"url":"https://cdn.example.com/avatars/profile-123.jpg","type":"image/jpeg"},"profileFollows":[],"organizationFollows":[],"productLikes":[]}],"metadata":{"pagination":{"hasNext":false,"hasPrev":false,"limit":10,"page":1,"total":1,"totalPages":1}}}

フォローおよびいいね操作にはリクエストボディは不要です。関連するプロフィール、組織、または商品が存在することを検証します。重複するプロフィールフォロー、組織フォロー、商品いいねは 409 Conflict になります。

curl -X PUT "{{host}}/profiles/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/profile-follows/f8c9b2a1-3d4e-5f6g-7h8i-9j0k1l2m3n4o5p" \
  -H "Authorization: Bearer <access-token>"

HTTP/1.1 204 No Content

curl -X DELETE "{{host}}/profiles/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/profile-follows/f8c9b2a1-3d4e-5f6g-7h8i-9j0k1l2m3n4o5p" \
  -H "Authorization: Bearer <access-token>"

HTTP/1.1 204 No Content

フォロワー取得は GET /profiles/:profileId/followers を使用します。page と limit でページネーションを指定し、フォロワープロフィールの data と metadata.pagination を受け取ります。

curl "{{host}}/profiles/profile-123/followers?page=1&limit=20" \
  -H "Authorization: Bearer <access-token>"

{"data":[{"id":"follower-456","name":"Jane Smith","avatar":{"url":"https://storage.example.com/avatars/avatar.png","type":"image/png"}}],"metadata":{"pagination":{"page":1,"limit":20,"total":1,"totalPages":1,"hasNext":false,"hasPrev":false}}}

curl -X PUT "{{host}}/profiles/profile-123/organization-follows/org-456" \
  -H "Authorization: Bearer <access-token>"
curl -X DELETE "{{host}}/profiles/profile-123/organization-follows/org-456" \
  -H "Authorization: Bearer <access-token>"
curl -X PUT "{{host}}/profiles/profile-123/product-likes/product-456" \
  -H "Authorization: Bearer <access-token>"
curl -X DELETE "{{host}}/profiles/profile-123/product-likes/product-456" \
  -H "Authorization: Bearer <access-token>"

HTTP/1.1 204 No Content

エラー処理: 無効なリクエストは 400、認証トークンがないか無効な場合は 401、所有者または管理者権限がない場合は 403、プロフィールまたは関連エンティティが見つからない場合は 404、重複フォロー／いいねは 409、データベースまたはアバター処理の失敗は 500 を返します。

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

{"error":{"message":"token could not be verified"}}

{"error":{"message":"Identity is not authorized to access this resource"}}

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

{"error":{"message":"Failed to update profile"}}

詳細なリクエストおよびレスポンス契約:

エンドポイント	リクエスト項目	型	必須	契約
作成	`identityId`	string	✅	対象アイデンティティの識別子
作成	`name`	string	✅	プロフィールの表示名
作成	`avatar`	object/null	❌	`{ objectId, type }` または null
作成応答	`id`	string	✅	生成済みプロフィール ID
作成応答	`identityId`	string	✅	関連付けたアイデンティティ
作成応答	`profileFollows`	array	✅	空配列で初期化されるフォロー
作成応答	`organizationFollows`	array	✅	空配列で初期化される組織フォロー
作成応答	`productLikes`	array	✅	空配列で初期化される商品いいね
取得	`profileId`	string	✅	パスで指定するプロフィール ID
取得応答	`avatar`	object/null	❌	アバター情報または null
一覧	`identityId`	string	❌	アイデンティティ ID でのフィルター
一覧	`name`	string	❌	表示名でのフィルター
一覧	`page`	number	❌	1～1000 のページ番号
一覧	`limit`	number	❌	1～50 のページサイズ
一覧応答	`data`	array	✅	プロフィールオブジェクトの配列
一覧応答	`metadata`	object	✅	レスポンスメタデータ
一覧応答	`metadata.pagination`	object	✅	ページネーション情報
一覧応答	`metadata.pagination.page`	number	✅	現在のページ
一覧応答	`metadata.pagination.limit`	number	✅	ページサイズ
一覧応答	`metadata.pagination.total`	number	✅	結果の総数
一覧応答	`metadata.pagination.totalPages`	number	✅	総ページ数
一覧応答	`metadata.pagination.hasNext`	boolean	✅	次ページの有無
一覧応答	`metadata.pagination.hasPrev`	boolean	✅	前ページの有無
更新	`profileId`	string	✅	更新対象のプロフィール ID
更新	`name`	string	❌	新しい表示名
更新	`avatar`	object/null	❌	新しいアバター情報または null
更新応答	`updatedAt`	string	✅	更新日時
削除	`profileId`	string	✅	削除対象のプロフィール ID
アバター URL	`profileId`	string	✅	対象プロフィール ID
アバター URL	`contentType`	string	✅	画像 MIME タイプ
アバター URL	`contentLength`	number	✅	バイト単位のファイルサイズ
アバター URL 応答	`objectId`	string	✅	生成済みストレージオブジェクト ID
アバター URL 応答	`url`	string	✅	一時的な署名付き URL
identity 検索	`identityId`	string	✅	本人が検索するアイデンティティ ID
identity 検索	`page`	number	❌	既定値は 1
identity 検索	`limit`	number	❌	既定値は 10
フォロー作成	`profileId`	string	✅	フォロー元プロフィール ID
フォロー作成	`followProfileId`	string	✅	フォロー先プロフィール ID
フォロー削除	`profileId`	string	✅	フォロー元プロフィール ID
フォロー削除	`followProfileId`	string	✅	フォロー先プロフィール ID
フォロワー一覧	`profileId`	string	✅	フォロワーを取得するプロフィール ID
フォロワー一覧	`page`	number	❌	ページ番号
フォロワー一覧	`limit`	number	❌	ページサイズ
組織フォロー	`profileId`	string	✅	操作を行うプロフィール ID
組織フォロー	`followOrganizationId`	string	✅	フォロー先組織 ID
組織フォロー削除	`profileId`	string	✅	操作を行うプロフィール ID
組織フォロー削除	`followOrganizationId`	string	✅	フォロー解除する組織 ID
商品いいね	`profileId`	string	✅	操作を行うプロフィール ID
商品いいね	`likeProductId`	string	✅	いいねを付ける商品 ID
商品いいね削除	`profileId`	string	✅	操作を行うプロフィール ID
商品いいね削除	`likeProductId`	string	✅	いいねを解除する商品 ID
エラー	`400`	HTTP status	-	無効なリクエストまたは空の更新ボディ
エラー	`401`	HTTP status	-	トークンがない、または無効
エラー	`403`	HTTP status	-	所有者または管理者の権限がない
エラー	`404`	HTTP status	-	プロフィールまたは関連エンティティがない
エラー	`409`	HTTP status	-	重複したフォローまたはいいね
エラー	`500`	HTTP status	-	データストアまたはアバター処理の失敗

以下の例は、各保護操作で Authorization ヘッダーを使用する形を示します。cookie モードでは同じアクセストークンを accessToken Cookie に設定します。フィンガープリントを伴って認可したクライアントは、保護されたリクエストに x-nb-fingerprint を含めます。

curl {{host}}/profiles -H "Authorization: Bearer <access-token>"

curl "{{host}}/profiles?identityId=identity-123" -H "Authorization: Bearer <access-token>"

curl "{{host}}/profiles?name=John" -H "Authorization: Bearer <access-token>"

curl "{{host}}/profiles?page=1&limit=20" -H "Authorization: Bearer <access-token>"

curl -X PATCH {{host}}/profiles/profile-123 -H "Content-Type: application/json" -H "Authorization: Bearer <access-token>" -d '{"avatar":null}'

curl -X DELETE {{host}}/profiles/profile-123 -H "Authorization: Bearer <access-token>"

curl "{{host}}/profiles/profile-123/avatar-upload-url?contentType=image/png&contentLength=1048576" -H "Authorization: Bearer <access-token>"

curl "{{host}}/profiles/identities/identity-123" -H "Authorization: Bearer <access-token>"

curl -X PUT "{{host}}/profiles/profile-123/profile-follows/profile-456" -H "Authorization: Bearer <access-token>"

curl -X DELETE "{{host}}/profiles/profile-123/profile-follows/profile-456" -H "Authorization: Bearer <access-token>"

curl "{{host}}/profiles/profile-123/followers?page=1&limit=20" -H "Authorization: Bearer <access-token>"

curl -X PUT "{{host}}/profiles/profile-123/organization-follows/org-456" -H "Authorization: Bearer <access-token>"

curl -X DELETE "{{host}}/profiles/profile-123/organization-follows/org-456" -H "Authorization: Bearer <access-token>"

curl -X PUT "{{host}}/profiles/profile-123/product-likes/product-456" -H "Authorization: Bearer <access-token>"

curl -X DELETE "{{host}}/profiles/profile-123/product-likes/product-456" -H "Authorization: Bearer <access-token>"

HTTP/1.1 204 No Content

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

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

HTTP/1.1 403 Forbidden
Content-Type: application/json

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

HTTP/1.1 409 Conflict
Content-Type: application/json

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

プロフィール作成では、対象アイデンティティが存在することを確認してください。プロフィール取得では、返された identityId を認証済みユーザーのコンテキストと比較できます。プロフィール一覧は管理用の一覧画面に適しています。プロフィール一覧のフィルターは組み合わせて使用できます。プロフィール一覧の大きな結果セットでは hasNext を使用して追加読み込みを実装できます。プロフィール更新では identity の関連付けを変更できません。プロフィール更新では自動生成日時を変更できません。プロフィール削除後は関連画面で存在しないプロフィールを適切に処理してください。アバター URL は期限付きのため、取得後すぐにアップロードしてください。アバター URL のオブジェクト ID はプロフィール更新の avatar 参照に使用します。アバターの型はアップロード時に指定した画像 MIME タイプと一致させてください。 identity 別検索はモバイルアプリで認証済みユーザーのプロフィールを表示する用途に使えます。 identity 別検索は Web アプリケーションのプロフィール管理画面にも使えます。プロフィールフォローはソーシャルネットワーク機能の関係を作成します。プロフィールフォローは同じ対象への重複作成を防止します。フォロー解除は既存のフォロー関係を削除します。フォロワー一覧はフォロワーのプロフィール情報をページネーション付きで返します。組織フォローはプロフィールと組織の関係を作成します。商品いいねはプロフィールと商品の関係を作成します。組織または商品が見つからない場合、対応する操作は失敗します。所有者アクセスでは操作元プロフィールの identity を確認します。管理者アクセスでは identity の種別設定を使用します。保護されたルートは bearer モードまたは cookie モードで認証します。 cookie モードを使用するホストアプリケーションでは cookie-parser を登録します。アバター正規化には任意の fileStorageDriver が必要です。アバター URL を使用する機能では fileStorageDriver をサービスの第 3 引数で渡します。 profiles データストアはすべてのプロフィール操作に必要です。 identities データストアは認証と所有者検証に必要です。 organizations データストアは組織フォローの検証に必要です。 products データストアは商品いいねの検証に必要です。 authSecrets には JWT の暗号化および署名シークレットを設定します。 identity.typeIds は管理者、ゲスト、通常ユーザーの種別を定義できます。 organization.roles は組織操作に必要なロールを定義できます。 authMode を指定しない場合は bearer 動作になります。 authMode: 'cookie' ではアクセストークンを Cookie から読み取ります。無効なプロフィール ID はパスパラメータ検証で拒否されます。無効なページ番号またはページサイズはクエリ検証で拒否されます。作成リクエストの余分なプロパティはスキーマ検証で拒否されます。更新リクエストの余分なプロパティはスキーマ検証で拒否されます。空の更新リクエストは Request body is required エラーになります。重複フォローはクライアントで成功として扱わず、競合として表示してください。 API から返るエラーメッセージは技術リテラルとして変更しないでください。ページネーションの既定値は endpoint ごとに異なる場合があります。アバターを持たないプロフィールでは avatar が null または省略になります。フォローおよびいいねの成功レスポンスには本文がありません。アプリケーションでは 204 No Content を成功として処理してください。署名付きアバター URL を永続的な公開 URL として扱わないでください。プロフィール API の呼び出しでは HTTPS を使用してください。

フォロー、フォロワー、および商品いいねの応答例:

プロフィールフォローは、同じプロフィールを二重にフォローすることを防ぎます。

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":{"message":"Profile is already being followed"}}

フォロー解除の対象が存在しない場合は次のエラーを返します。

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

{"error":{"message":"Profile follow not found"}}

フォロワー一覧はアバターを持つ場合に URL とタイプを含めます。

{"data":[{"id":"user-456","name":"John Doe","avatar":{"url":"https://storage.example.com/avatars/avatar123.png","type":"image/png"}},{"id":"user-789","name":"Jane Smith","avatar":{"url":"https://storage.example.com/avatars/avatar456.jpg","type":"image/jpeg"}}],"metadata":{"pagination":{"page":1,"limit":20,"total":50,"totalPages":3,"hasNext":true,"hasPrev":false}}}

フォロワーを取得するプロフィールがない場合は次のエラーを返します。

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

組織フォローはプロフィールと対象組織の両方が存在することを確認します。

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":{"message":"Organization is already being followed"}}

プロフィールが見つからない組織フォローでは次のエラーになります。

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

組織が見つからない組織フォローでは次のエラーになります。

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

組織フォロー解除の対象がない場合は次のエラーになります。

{"error":{"message":"Organization follow not found"}}

商品いいねは対象商品が存在することを確認し、同じ商品の二重いいねを防ぎます。

{"error":{"message":"Product is already liked"}}

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

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

商品いいね解除の対象がない場合は次のエラーになります。

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

フォローおよびいいねの関係には、操作元プロフィールの所有者または管理者の認可が必要です。

{"error":{"message":"Identity is not authorized to access this resource"}}

プロフィールの取得、更新、削除では、リソースがない場合に同じ Profile not found エラーを返します。

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

作成処理でデータベース挿入が失敗した場合は次のエラーを返します。

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

取得処理でデータベース接続に失敗した場合は次のエラーを返します。

{"error":{"message":"Failed to get profile"}}

一覧処理でフィルターまたはデータベース操作に失敗した場合は次のエラーを返します。

{"error":{"message":"Failed to find profiles"}}

削除処理でデータベース操作に失敗した場合は次のエラーを返します。

{"error":{"message":"Failed to delete profile"}}

プロフィール、フォロー、およびいいねの機能は、ユーザー情報の表示、ソーシャル関係、組織の購読、商品エンゲージメントの分析に利用できます。管理画面ではプロフィールの一覧、フォロワー数、組織フォロー、商品いいねを組み合わせて表示できます。クライアントはページネーションメタデータを使用して大きな結果セットを段階的に読み込めます。アバターの正規化により、クライアントはストレージオブジェクト ID ではなくアクセス可能な URL を使用できます。プロフィール更新後は、返された updatedAt をキャッシュの無効化に使用できます。フォローまたはいいねの削除後は、UI 上の関係状態を 204 No Content に基づいて更新してください。

フォロー機能	フィールド	型	説明
プロフィールフォロー	`profileId`	string	フォロー操作を行うプロフィール ID
プロフィールフォロー	`followProfileId`	string	フォロー先プロフィール ID
プロフィールフォロー	リクエストボディ	なし	本文は不要
プロフィールフォロー	成功ステータス	HTTP	`204 No Content`
プロフィールフォロー	重複エラー	HTTP	`409 Conflict`
プロフィールフォロー	存在確認	boolean	両方のプロフィールが必要
フォロワー一覧	`profileId`	string	フォロワーを取得するプロフィール ID
フォロワー一覧	`data`	array	フォロワープロフィールの配列
フォロワー一覧	`data[].id`	string	フォロワー ID
フォロワー一覧	`data[].name`	string	フォロワー表示名
フォロワー一覧	`data[].avatar.url`	string	アバター URL
フォロワー一覧	`data[].avatar.type`	string	アバター MIME タイプ
組織フォロー	`profileId`	string	操作元プロフィール ID
組織フォロー	`followOrganizationId`	string	フォロー先組織 ID
組織フォロー	リクエストボディ	なし	本文は不要
組織フォロー	成功ステータス	HTTP	`204 No Content`
組織フォロー	重複エラー	HTTP	`409 Conflict`
組織フォロー	存在確認	boolean	プロフィールと組織が必要
商品いいね	`profileId`	string	操作元プロフィール ID
商品いいね	`likeProductId`	string	いいねを付ける商品 ID
商品いいね	リクエストボディ	なし	本文は不要
商品いいね	成功ステータス	HTTP	`204 No Content`
商品いいね	重複エラー	HTTP	`409 Conflict`
ページネーション	`page`	number	取得するページ番号
ページネーション	`limit`	number	1ページあたりの結果数
ページネーション	`hasNext`	boolean	次ページの有無
ページネーション	`hasPrev`	boolean	前ページの有無

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":{"message":"Profile is already being followed"}}

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":{"message":"Organization is already being followed"}}

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":{"message":"Product is already liked"}}

エンドポイントごとの動作と検証:

プロフィール作成は JSON リクエストボディを受け取ります。
プロフィール作成では Content-Type: application/json を指定します。
プロフィール作成では認証済みリクエストが必要です。
プロフィール作成は管理者または対象アイデンティティ本人に許可されます。
プロフィール作成の成功時にフォロー配列は空で初期化されます。
プロフィール作成の成功時にいいね配列は空で初期化されます。
プロフィール作成の失敗時に必須項目の検証詳細が data に入ります。
プロフィール作成では存在しない任意フィールドを送信できません。
プロフィール取得では profileId をパスで指定します。
プロフィール取得は管理者またはプロフィール所有者に限定されます。
プロフィール取得はアバターがない場合に null を返せます。
プロフィール取得は作成日時と更新日時を返します。
プロフィール取得の認可判定には関連するアイデンティティを使用します。
プロフィール一覧は管理者専用の読み取り操作です。
プロフィール一覧は表示名によるフィルターを受け取ります。
プロフィール一覧は identity ID によるフィルターを受け取ります。
プロフィール一覧はフィルターを省略すると管理可能なプロフィールを返します。
プロフィール一覧の page は整数です。
プロフィール一覧の limit は整数です。
プロフィール一覧ではページと件数の最小値および最大値を検証します。
プロフィール一覧の各要素はプロフィールの完全な関係配列を返します。
プロフィール一覧ではアバターを URL に正規化できます。
プロフィール一覧の不正なフィルターはエラーになります。
プロフィール更新は部分更新です。
プロフィール更新では表示名だけを変更できます。
プロフィール更新ではアバターだけを変更できます。
プロフィール更新では表示名とアバターを同時に変更できます。
プロフィール更新では identity ID を変更できません。
プロフィール更新ではフォロー配列を直接変更できません。
プロフィール更新では商品いいね配列を直接変更できません。
プロフィール更新では空のオブジェクトを送信しません。
プロフィール更新の無変更状態は成功として扱われません。
プロフィール削除は永続的にプロフィールを削除します。
プロフィール削除はレスポンスボディを返しません。
プロフィール削除では対象プロフィールの所有者確認を行います。
アバターアップロード URL はファイルを直接アップロードするために使用します。
アバターアップロード URL は一時的な URL です。
アバターアップロード URL の MIME タイプは画像に制限されます。
アバターアップロード URL のサイズ上限は 10,000,000 バイトです。
アバターアップロード URL を使う前に fileStorageDriver を設定します。
アバターのアップロード後に返されたオブジェクト ID をプロフィール更新に指定できます。
identity 別プロフィール検索は自己アクセスだけを許可します。
identity 別プロフィール検索では他人の identity ID を使用できません。
identity 別プロフィール検索はアバター URL を正規化します。
identity 別プロフィール検索はページネーションメタデータを返します。
プロフィールフォローではフォロー元とフォロー先の ID が必要です。
プロフィールフォローでは自分自身を扱うアプリケーション側のルールを考慮してください。
プロフィールフォローは既存関係を重複作成しません。
プロフィールフォローの作成はデータベースに関係を保存します。
プロフィールフォロー解除はデータベースから関係を削除します。
フォロー解除では存在しない関係を削除できません。
フォロワー一覧はフォロー先プロフィールのフォロワーを返します。
フォロワー一覧は大規模なフォロワー数に対応するページネーションを提供します。
フォロワー一覧は各フォロワーの表示名を返します。
フォロワー一覧は利用可能な場合にアバターを返します。
組織フォローでは組織 ID をパスで指定します。
組織フォローは対象組織の存在を検証します。
組織フォローは既存の組織フォローを重複作成しません。
組織フォロー解除はプロフィールと組織の関係を削除します。
組織フォロー解除は存在しない関係に対して失敗します。
商品いいねでは商品 ID をパスで指定します。
商品いいねは対象商品の存在を検証します。
商品いいねは既存のいいねを重複作成しません。
商品いいね解除はプロフィールと商品の関係を削除します。
商品いいね解除は存在しない関係に対して失敗します。
すべてのフォロー操作は空のリクエストボディを使用します。
すべての商品いいね操作は空のリクエストボディを使用します。
フォローといいねの成功時は 204 を確認します。
204 の応答本文を JSON として解析しないでください。
認証失敗では有効なアクセストークンを再取得してください。
権限不足では別のユーザーのプロフィールを変更しないでください。
404 ではクライアント表示を存在しない状態に更新してください。
409 では重複関係を成功として表示しないでください。
500 では一時的な障害として再試行方針を検討してください。
Cookie 認証ではクロスオリジン設定も確認してください。
Bearer 認証では Authorization ヘッダーを毎回送信します。
フィンガープリント認証では同じデバイスフィンガープリントを送信します。
メールアドレスなどのアイデンティティ詳細はプロフィール API のレスポンスに含まれません。
プロフィール API はアイデンティティ API の代わりではありません。
組織フォローの存在確認には組織サービスのデータを使います。
商品いいねの存在確認には商品サービスのデータを使います。
アバター URL の署名はストレージドライバーの実装に依存します。
アバターを削除する場合は更新リクエストで avatar: null を使用します。
アバターの object ID はクライアントで秘密情報として扱う必要はありません。
ただし署名付き URL は公開期限を意識して扱ってください。
プロフィール表示名の検索はアプリケーションのフィルター仕様に従います。
ページネーションを使用しない一覧でもメタデータが返ります。
クライアントは totalPages を使用してページナビゲーションを作成できます。
クライアントは hasPrev を使用して前へ移動する制御を表示できます。
クライアントは hasNext を使用して次へ移動する制御を表示できます。
フォロワー数はページネーションの total から取得できます。
プロフィール一覧の総数はページネーションの total から取得できます。
identity 別検索の総数はページネーションの total から取得できます。
プロフィールの関係状態を変更する前に認可を確認してください。
フロントエンドでは楽観的更新後も API エラーを処理してください。
API パス、JSON キー、サーバーエラー文字列は変更しないでください。

実装および利用ガイド:

プロフィールサービスは CRUD 操作を提供します。
プロフィールサービスは MongoDB と統合します。
プロフィールサービスは Nodeblocks の関数型合成を使用します。
プロフィールサービスは認証サービスと併用できます。
プロフィールサービスは組織サービスと併用できます。
プロフィールサービスは商品サービスと併用できます。
プロフィールサービスはソーシャル機能の基盤になります。
プロフィール作成前にアイデンティティを作成します。
プロフィール作成後に API から返る ID を保存します。
プロフィール ID はアイデンティティ ID と異なります。
identity ID はプロフィールの所有者を表します。
表示名はプロフィール画面に使用できます。
アバターはプロフィール画面に使用できます。
アバターがないユーザーには既定の UI を表示できます。
自動生成 ID はクライアントで指定しません。
自動生成日時はクライアントで指定しません。
フォロー配列はサービスが管理します。
組織フォロー配列はサービスが管理します。
商品いいね配列はサービスが管理します。
作成時にはこれらの関係配列を送信しません。
更新時にもこれらの関係配列を送信しません。
関係の作成には専用のエンドポイントを使います。
関係の削除には専用のエンドポイントを使います。
プロフィールの取得には正確なプロフィール ID を使います。
プロフィール取得の結果はプロフィール詳細画面に使えます。
プロフィール一覧の結果は管理者画面に使えます。
identity 別検索の結果は本人のプロフィール選択に使えます。
表示名フィルターは検索 UI に使えます。
identity ID フィルターは運用調査に使えます。
ページ番号は 1 から始まります。
ページサイズは利用者の画面サイズに合わせます。
ページサイズが大きすぎる場合は応答が増大します。
ページサイズが小さすぎる場合はリクエスト回数が増えます。
metadata.pagination は一覧応答に含まれます。
page は現在表示しているページを示します。
limit は要求したページサイズを示します。
total は検索結果の件数を示します。
totalPages は利用可能なページ数を示します。
hasNext は続きを読み込めるか示します。
hasPrev は前のページがあるか示します。
アバターが存在する場合は URL を使用して画像を表示します。
アバターの URL はストレージアクセス用です。
アバター URL の MIME タイプを画像要素の処理に使えます。
アバター URL を長期キャッシュしないでください。
アバター URL の有効期限切れ時は新しい URL を取得します。
アバター URL の取得はアップロード前の手順です。
アバター本体は署名付き URL へアップロードします。
アップロード成功後に object ID を保存します。
保存した object ID をアバター更新に使います。
アバターを外す場合は null を使います。
null のアバターはエラーではありません。
アバターの更新はプロフィール所有者が実行できます。
アバターの更新は管理者も実行できます。
プロフィール名の更新はプロフィール所有者が実行できます。
プロフィール名の更新は管理者も実行できます。
他人のプロフィールを通常ユーザーが更新できません。
他人のプロフィールを通常ユーザーが削除できません。
読み取りも所有者または管理者に制限されます。
管理者の判定には identity の種別を使います。
所有者の判定には identity ID を使います。
認可前に認証が必要です。
未認証の場合はリクエストを保護しません。
無効なトークンは認証失敗になります。
有効期限切れのトークンは更新または再ログインが必要です。
Cookie モードではブラウザーが Cookie を送信します。
Bearer モードではクライアントがヘッダーを送信します。
CORS を使う場合は Cookie 設定を確認します。
Cookie のセキュリティ属性を本番環境で確認します。
フィンガープリントを使う場合は同じデバイス情報を送信します。
フィンガープリントが不要な認可ではこのヘッダーを省略できます。
フィンガープリントの値は API の仕様に従って生成します。
プロフィールフォローは一方向の関係です。
フォロー先がフォロー元を自動的にフォローすることはありません。
フォロー関係はフォロワー一覧に反映されます。
フォロー関係はプロフィールのソーシャル表示に使用できます。
重複フォローはクライアント側でも防止できます。
サーバー側の競合応答も必ず処理します。
フォローを解除した後はフォロワー一覧を再読み込みできます。
フォロワー一覧はページネーションを使用します。
フォロワー一覧はアバターを持たないユーザーも返します。
フォロワー一覧でアバターがない場合は既定画像を表示できます。
組織フォローは組織の購読機能に使えます。
組織フォローは組織の更新通知機能に使えます。
組織フォローは組織のフォロワー分析に使えます。
組織フォローを作る前に組織 ID を確認します。
組織フォローを解除する前に関係の状態を確認できます。
商品いいねは商品への関心を表します。
商品いいねは商品人気の分析に使えます。
商品いいねはおすすめ機能に使えます。
商品いいねを作る前に商品 ID を確認します。
商品いいねを解除する前に関係の状態を確認できます。
同じ商品へのいいねは 1 つだけ存在します。
同じ組織へのフォローは 1 つだけ存在します。
同じプロフィールへのフォローは 1 つだけ存在します。
関係 API は空の本文で呼び出します。
空の本文は JSON の空オブジェクトとは異なります。
関係 API の成功時は HTTP ステータスだけを確認します。
成功後に関係配列の UI を更新します。
失敗後に楽観的更新をロールバックします。
400 はリクエスト形式の問題を示します。
401 は認証状態の問題を示します。
403 はアクセス権の問題を示します。
404 は対象リソースの問題を示します。
409 は関係の重複または競合を示します。
500 はサーバー側またはデータストア側の問題を示します。
Validation Error の data は修正すべき項目を示します。
エラーの message は表示用に翻訳せず技術値として扱います。
クライアント向け表示はアプリケーション側で適切に作成します。
サーバー返却の HTTP ステータスは変更しません。
リクエストの JSON キーは変更しません。
API パスの単数形と複数形を変更しません。
URL パラメータ名を変更しません。
設定値は環境変数で管理できます。
authSecrets はソースコードに直接公開しません。
本番環境では強い JWT シークレットを使用します。
MongoDB コレクションの名前はサービス設定と一致させます。
profiles コレクションはプロフィールを保存します。
identities コレクションはアイデンティティを保存します。
organizations コレクションは組織を保存します。
products コレクションは商品を保存します。
サービス起動時に必要なデータストアを渡します。
アバター機能を使う場合にファイルストレージドライバーを渡します。
ストレージドライバーの失敗はエラーとして処理します。
データベース接続の失敗はエラーとして処理します。
失敗した書き込みを無条件に再試行しません。
書き込みの再試行では重複関係に注意します。
読み取りの再試行では認証状態を確認します。
ユーザーが削除済みプロフィールを開いた場合は一覧へ戻します。
管理者はプロフィール一覧から詳細画面へ遷移できます。
所有者は自分のプロフィールを編集できます。
所有者は自分のプロフィールを削除できます。
プロフィール API はユーザーのパスワードを返しません。
プロフィール API は認証トークンを返しません。
認証トークンは認証サービスで取得します。
組織情報の詳細は組織サービスで取得します。
商品情報の詳細は商品サービスで取得します。
プロフィール応答の関係配列はアプリの状態表示に使えます。
大量のプロフィールでは一覧 API のページネーションを常に使います。
大量のフォロワーではフォロワー API のページネーションを常に使います。
アバターの画像形式はクライアント対応状況も考慮します。
HEIC や HEIF を使う場合はブラウザー対応を確認します。
SVG を表示する場合はアプリケーションのセキュリティ方針を確認します。
アップロードするファイルサイズをクライアント側でも確認できます。
API 側のサイズ検証をクライアント側検証の代わりにしません。
API 側の認可をクライアント側の表示制御の代わりにしません。
すべての保護操作はサーバー側の認可判定を通ります。
プロフィール API の正常系と異常系をクライアント実装でテストしてください。
作成、取得、一覧、更新、削除のすべてのフローを確認してください。
アバターのアップロード URL とプロフィール更新の連携を確認してください。
identity 別検索で本人以外のアクセスが拒否されることを確認してください。
フォロー、フォロー解除、フォロワー一覧の各フローを確認してください。
組織フォローと商品いいねの各フローを確認してください。
重複関係が競合として返されることを確認してください。
ページネーションの先頭、途中、最後のページを確認してください。
Cookie モードと bearer モードの両方を使用する場合はそれぞれを確認してください。
ファイルストレージを設定した環境でアバター URL の期限切れも確認してください。

🗄️ データストア

コレクション	必須	用途
`profiles`	✅	プロフィール文書
`identities`	✅	認証と所有者検証
`organizations`	✅	組織フォローの検証
`products`	✅	商品いいねの検証

⚙️ 設定オプション

サービス設定

authSecrets に JWT の暗号化・署名シークレットを指定します。authMode は 'bearer' または 'cookie'（未指定時はベアラー動作）です。identity.typeIds では管理者、ゲスト、通常ユーザーの種別 ID を、組織操作には organization.roles を設定できます。

設定詳細

🔐 セキュリティ設定

authSecrets には JWT の暗号化および署名用シークレットを指定します。

👥 ユーザー種別設定

identity.typeIds には管理者、ゲスト、通常ユーザーの種別 ID を指定します。

🏢 組織役割設定

組織フォローの操作では、必要に応じて organization.roles を設定します。

🔑 認証モード

authMode は 'bearer' または 'cookie' です。指定しない場合は bearer モードになります。

設定例

const profileConfig = {
  authSecrets: {authEncSecret: 'your-enc-secret', authSignSecret: 'your-sign-secret'},
  authMode: 'bearer',
  identity: {typeIds: {admin: '100', guest: '000', regular: '001'}},
};

🚨 エラーハンドリング

エラーは {error: {message, data?}} 形式で返されます。主な状態コードは、無効なリクエストの 400、認証失敗の 401、権限不足の 403、プロフィールまたは関連エンティティがない場合の 404、競合するフォロー／いいね操作などの 409、データストア障害の 500 です。

代表的なエラーコード

400 は無効なリクエスト、401 は認証失敗、403 は権限不足、404 は見つからないリソース、409 は競合、500 はデータストア障害を表します。

エラーレスポンス形式

エラーは {error: {message, data?}} の JSON 形式で返されます。

🚀 クイックスタート​

📋 エンドポイント一覧​

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

プロフィールフォロー操作​

組織フォロー操作​

商品いいね操作​

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

フィールド詳細​

🔐 認証ヘッダー​

🔧 API エンドポイント​

1. プロフィールの作成​

2. ID によるプロフィール取得​

3. プロフィール一覧​

4. プロフィールの更新​

5. プロフィールの削除​

6. アバターアップロード URL の取得​

7. identity ID によるプロフィール検索​

8. プロフィールフォローの作成​

9. プロフィールフォローの削除​

10. プロフィールフォロワーの取得​

11. 組織フォローの作成​

12. 組織フォローの削除​

13. 商品いいねの作成​

14. 商品いいねの削除​

🗄️ データストア​

⚙️ 設定オプション​

サービス設定​

設定詳細​

🔐 セキュリティ設定​

👥 ユーザー種別設定​

🏢 組織役割設定​

🔑 認証モード​

設定例​

🚨 エラーハンドリング​

代表的なエラーコード​

エラーレスポンス形式​

🔗 関連ドキュメント​