バージョン: 0.9.0 (最新)

🚀 組織機能

組織機能は、Nodeblocksアプリケーションで組織管理操作の完全な事前合成機能を提供します。これらの機能は、スキーマ、ルート、ハンドラーを組み合わせて、組織CRUD操作、ユーザー管理、メンバーシップ処理のための即座に使用可能なAPIエンドポイントを作成します。

🎯 概要

組織機能は以下の目的で設計されています：

完全なCRUD操作で完全な組織管理を提供 - 完全な管理機能を実装
組織内のユーザーメンバーシップとロール管理をサポート - メンバーシップ管理を提供
安全な組織操作のためのバリデーションとルーティングを含める - セキュリティを確保
組織とユーザー一覧のフィルタリングとページネーションをサポート - 検索機能を提供
組織-ユーザー関係とアクセス制御を処理 - アクセス制御を実装

📋 機能構造

各組織機能は一貫した合成パターンに従います：

Schema: 組織入力データとパラメータをバリデーション
Route: 組織ハンドラー付きのHTTPエンドポイントを提供
Composition: compose関数を使用してスキーマとルートを組み合わせる

🔧 利用可能な組織機能

`createOrganizationFeature`

スキーマバリデーションとルーティング付きの組織作成機能。

目的: 完全なバリデーションで組織作成を処理

合成:

Schema: createOrganizationSchema - 名前、説明、contact_email、およびオプションフィールドをバリデーション
Route: createOrganizationRoute - 作成ハンドラー付きのPOST /organizations

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.createOrganizationFeature, [{ dataStores: db }])));

API Endpoint: POST /api/organizations

`getOrganizationFeatures`

個別の組織データを取得するための組織取得機能。

目的: 適切なバリデーションで組織情報を取得

合成:

Schema: getOrganizationSchema - パスパラメータをバリデーション
Route: getOrganizationRoute - 取得ハンドラー付きのGET /organizations/:organizationId

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.getOrganizationFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/organizations/:organizationId

`findOrganizationsFeatures`

フィルタリングとページネーション付きの組織検索機能。

目的: 検索機能付きで組織一覧を提供

合成:

Schema: findOrganizationsSchema - フィルタリング用のクエリパラメータをバリデーション
Route: findOrganizationsRoute - 検索とページネーション付きのGET /organizations

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.findOrganizationsFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/organizations

`editOrganizationFeatures`

スキーマバリデーションとルーティング付きの組織更新機能。

目的: 適切なバリデーションで組織情報を変更

合成:

Schema: updateOrganizationSchema - 部分的な組織プロパティをバリデーション
Route: updateOrganizationRoute - 更新ハンドラー付きのPATCH /organizations/:organizationId

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.editOrganizationFeatures, [{ dataStores: db }])));

API Endpoint: PATCH /api/organizations/:organizationId

`deleteOrganizationFeatures`

ルーティング付きの組織削除機能。

目的: アクセス制御とクリーンアップで組織を削除

合成:

Schema: deleteOrganizationSchema - パスパラメータをバリデーション
Route: deleteOrganizationRoute - 削除ハンドラー付きのDELETE /organizations/:organizationId

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.deleteOrganizationFeatures, [{ dataStores: db }])));

API Endpoint: DELETE /api/organizations/:organizationId

`getOrganizationMemberFeatures`

組織内のメンバーロールを取得するための組織メンバーロール取得機能。

目的: 特定の組織内のメンバーロールを取得

合成:

Schema: getOrganizationMemberRoleSchema - パスパラメータをバリデーション
Route: getOrganizationMemberRoleRoute - ロール取得ハンドラー付きのGET /organizations/:organizationId/members/:identityId/role

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.getOrganizationMemberFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/organizations/:organizationId/members/:identityId/role

`checkOrganizationMemberExistenceFeatures`

メンバーメンバーシップをバリデーションするための組織メンバー存在チェック機能。

目的: 組織内のメンバーメンバーシップをバリデーション

合成:

Schema: checkOrganizationMemberExistenceSchema - パスとクエリパラメータをバリデーション
Route: checkOrganizationMemberExistenceRoute - GET /organizations/:organizationId/members/check-existence

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.checkOrganizationMemberExistenceFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/organizations/:organizationId/members/check-existence

`findOrganizationMembersFeatures`

フィルタリングとページネーション付きの組織メンバー検索機能。

目的: 検索機能付きで組織メンバー一覧を提供

合成:

Schema: findOrganizationMembersSchema - フィルタリング用のクエリパラメータをバリデーション
Route: findOrganizationMembersRoute - 検索とページネーション付きのGET /organizations/:organizationId/members

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.findOrganizationMembersFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/organizations/:organizationId/members

`findOrganizationsForMemberFeatures`

アイデンティティIDで組織を検索するためのメンバー用組織検索機能。

目的: 特定のメンバー（アイデンティティ）に関連付けられた組織を検索し、オプションでロールフィルタリングと継承されたロールを含む

合成:

Schema: findOrganizationsForMemberSchema - パスとオプションのクエリパラメータをバリデーション
Route: findOrganizationsForMemberRoute - GET /organizations/members/:identityId

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.findOrganizationsForMemberFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/organizations/members/:identityId

`editOrganizationMembersFeatures`

メンバーをアップサートするためのスキーマバリデーション付きの組織メンバー管理機能。

目的: 組織内のメンバーメンバーシップとロールを管理

合成:

Schema: upsertOrganizationMembersSchema - idとroleを持つメンバーオブジェクトの配列をバリデーション
Route: upsertOrganizationMembersRoute - アップサートハンドラー付きのPATCH /organizations/:organizationId/members

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.editOrganizationMembersFeatures, [{ dataStores: db }])));

API Endpoint: PATCH /api/organizations/:organizationId/members

`deleteOrganizationMemberFeatures`

ルーティング付きの組織メンバー削除機能。

目的: 適切なクリーンアップで組織からメンバーを削除

合成:

Schema: deleteOrganizationMemberSchema - パスパラメータをバリデーション
Route: deleteOrganizationMemberRoute - DELETE /organizations/:organizationId/members/:identityId

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.deleteOrganizationMemberFeatures, [{ dataStores: db }])));

API Endpoint: DELETE /api/organizations/:organizationId/members/:identityId

`findOrganizationDescendantsFeatures`

特定の組織の子孫組織を取得します。

目的: ページネーションサポート付きですべての子孫を一覧表示

合成:

Schema: findOrganizationDescendantsSchema - organizationIdとオプションのdepthをバリデーション
Route: findOrganizationDescendantsRoute - GET /organizations/:organizationId/descendants

使用例:

import { features } from '@nodeblocks/backend-sdk';


// データベース設定付き
app.use('/api', defService(partial(features.findOrganizationDescendantsFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/organizations/:organizationId/descendants

`getCertificateUploadUrlFeature`

スキーマバリデーションとルーティング付きの組織証明書アップロードURL生成機能。

目的: 証明書ファイルアップロード用の安全な署名付きURLを提供

合成:

Schema: getCertificateUploadUrlSchema - 証明書アップロード用のコンテンツタイプとファイルサイズをバリデーション
Route: getCertificateUploadUrlRoute - 署名付きURL生成付きのGET /organizations/:organizationId/certificate-upload-url

使用例:

import { features } from '@nodeblocks/backend-sdk';

// 設定にファイルストレージサービスを含む:
app.use('/api', defService(partial(features.getCertificateUploadUrlFeature, [{ configuration: { fileStorageDriver } }])));

API Endpoint: GET /api/organizations/:organizationId/certificate-upload-url?contentType=application/pdf&contentLength=102400

主な機能:

自動UUIDオブジェクトID生成
PDFと画像形式のサポート（PDF、GIF、JPEG、PNG）
ファイルサイズバリデーション（最大10MB）
オーナー専用アクセス制御

`createChangeRequestFeature`

スキーマバリデーションとルーティング付きの組織変更リクエスト作成機能。

目的: バリデーション、監査追跡、自動ステータス更新で組織変更リクエストを処理

合成:

Schema: createChangeRequestSchema - organizationIdパスとJSONボディフィールド（名前、住所行、typeId、certificateImage、certifiedQualifications）をバリデーション
Route: createChangeRequestRoute - 作成ハンドラー付きのPOST /organizations/:organizationId/change-requests

使用例:

import { features } from '@nodeblocks/backend-sdk';

// DBと認証シークレットで直接使用:
app.use('/api', defService(partial(features.createChangeRequestFeature, [{
  dataStores: {
    organizations: db.collection('organizations'),
    organizationChangeRequests: db.collection('organizationChangeRequests'),
    onetimetokens: db.collection('onetimetokens')
  },
  configuration: { authSecrets }
}])));

API Endpoint: POST /api/organizations/:organizationId/change-requests

Request Body:

{
  "name": "Updated Organization Name",
  "addressLine1": "123 Main Street",
  "certificateImage": {
    "objectId": "uuid-here",
    "type": "application/pdf"
  },
  "certifiedQualifications": [
    {
      "name": "ISO 9001",
      "status": "approved",
      "value": "2024"
    }
  ]
}

Response: 204 No Content - 成功時に空のレスポンスボディ

主な機能:

自動組織名一意性バリデーション
作成者追跡のためのトークンベースアイデンティティ抽出
waiting_for_reviewへの自動監査ステータス更新
objectId参照による証明書画像アップロードサポート
構造化データによる認定資格の追跡
特定のエラークラスによる包括的なエラーハンドリング
オーナー専用アクセス制御

エラーレスポンス:

400 Bad Request - 無効な入力、重複名、またはバリデーション失敗
401 Unauthorized - 認証失敗
500 Internal Server Error - データベースまたは処理エラー

ワークフロー:

組織が存在し、ユーザーがオーナーロールを持っていることをバリデーション
名前変更がリクエストされている場合は組織名の一意性をチェック
アクセストークンからアイデンティティを抽出
送信されたすべてのフィールドで変更リクエストレコードを作成
組織の監査ステータスをwaiting_for_reviewに更新
成功時に204 No Contentを返す

`findChangeRequestsForOrganizationFeature`

スキーマバリデーションとルーティング付きの組織変更リクエスト取得機能。

目的: ページネーションとファイルURLエンリッチメント付きで組織変更リクエストを取得して正規化

合成:

Schema: findChangeRequestsForOrganizationSchema - 組織IDとページネーションパラメータをバリデーション
Route: findChangeRequestsForOrganizationRoute - 取得と正規化ハンドラー付きのGET /organizations/:organizationId/change-requests

使用例:

import { features } from '@nodeblocks/backend-sdk';

// 直接使用:
app.use('/api', defService(features.findChangeRequestsForOrganizationFeature));

// データベースとファイルストレージ付き（ハンドラーはdataStoresとfileStorageDriverが必要）:
app.use('/api', defService(partial(features.findChangeRequestsForOrganizationFeature, [{
  dataStores: {
    organizationChangeRequests: db.collection('organizationChangeRequests')
  },
  configuration: {
    fileStorageDriver
  }
}])));

API Endpoint: GET /api/organizations/:organizationId/change-requests

Query Parameters:

{
  page?: number;   // optional - pagination page (default: 1)
  limit?: number;  // optional - pagination limit (default: 10, max: 50)
}

Response: 200 OK - 正規化されたデータでページネーション付き変更リクエストを返す

Response Format:

{
  "data": [
    {
      "id": "string",
      "organizationId": "string",
      "identityId": "string",
      "name": "string",
      "certificateImage": {
        "objectId": "string",
        "type": "string"
      },
      "certificateImageUrl": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

主な機能:

設定可能なページサイズとナビゲーションメタデータでのページネーションサポート
レスポンスからの自動MongoDB _idフィールド削除
証明書画像の署名付きダウンロードURL生成
URL生成失敗時の適切なフォールバック（URLなしで変更リクエストを返す）
組織オーナーと管理者のみのアクセス制御
特定のエラークラスによる包括的なエラーハンドリング

認可:

認証が必要
管理者または組織オーナーがアクセス可能
組織メンバーシップとロールをバリデーション

エラーレスポンス:

401 Unauthorized - 認証失敗
403 Forbidden - ユーザーが管理者権限または組織所有権を持っていない
500 Internal Server Error - データベースクエリ失敗またはファイルURL生成エラー

使用例:

保留中の組織変更リクエストのレビュー
変更リクエスト履歴の監査
組織変更の管理者監視
変更リクエストリストを表示するクライアントアプリケーション

`updateOrganizationAsAdminFeature`

スキーマバリデーションとルーティング付きの組織管理者更新機能。

目的: 拡張フィールドアクセスと監査ステータスバリデーション付きで管理者専用の組織更新を提供

合成:

Schema: updateOrganizationAsAdminSchema - 部分更新用の管理者専用フィールドと共通フィールドをバリデーション
Route: updateOrganizationAsAdminRoute - 管理者専用更新ハンドラー付きのPATCH /admin/organizations/:organizationId/

使用例:

import { features } from '@nodeblocks/backend-sdk';

// 直接使用:
app.use('/api', defService(features.updateOrganizationAsAdminFeature));

// データベース付き（ハンドラーはdataStoresが必要）:
app.use('/api', defService(partial(features.updateOrganizationAsAdminFeature, [{
  dataStores: {
    organizations: db.collection('organizations')
  },
  configuration: {
    fileStorageDriver
  }
}])));

API Endpoint: PATCH /api/admin/organizations/:organizationId/

Request Body:

{
  "name": "Updated Organization Name",
  "auditStatus": "approved",
  "certificateImage": {
    "objectId": "uuid-here",
    "type": "application/pdf"
  },
  "certifiedQualifications": [
    {
      "name": "ISO 9001:2015",
      "status": "approved",
      "value": "2024"
    }
  ]
}

Response: 200 OK - 正規化されたロゴURL付きで更新された組織を返す

主な機能:

管理者専用アクセス制御（管理者アイデンティティタイプが必要）
以下の拡張フィールドアクセス:
- 組織名変更
- 住所更新
- 証明書画像管理
- 認定資格の追跡
- ロゴ管理
- タイプID更新
- 監査ステータス更新
監査ステータスバリデーション（'approved'または'rejected'のみ許可）
レスポンスでの自動ロゴURL正規化
すべての共通フィールドが利用可能（連絡先情報、説明、支店名）
柔軟な部分更新（すべてのフィールドがオプション）
特定のエラークラスによる包括的なエラーハンドリング

認可:

管理者アイデンティティタイプが必要
通常の更新ルートよりも許可的
組織オーナーから制限されているフィールドの更新を許可

使用例:

auditStatusを介して変更リクエストを承認または拒否
管理上の組織データ修正
証明書画像と資格の更新
組織タイプ分類の管理
変更リクエストワークフローなしでの直接名前変更

エラーレスポンス:

400 Bad Request - 無効な監査ステータスまたはバリデーション失敗
401 Unauthorized - 認証失敗
403 Forbidden - 非管理者ユーザーが管理者更新を試行
404 Not Found - 組織が見つからない
500 Internal Server Error - データベースまたは処理エラー

`getLogoUploadUrlFeature`

スキーマバリデーションとルーティング付きの組織ロゴアップロードURL生成機能。

目的: 組織ロゴをアップロードするための事前署名付きURLを生成します。

合成:

Schema: getSignedImageUploadUrlSchema - 画像アップロード用のコンテンツタイプとファイルサイズをバリデーション
Route: getLogoUploadUrlRoute - 署名付きURL生成付きのGET /organizations/:organizationId/logo-upload-url

使用例:

import { features } from '@nodeblocks/backend-sdk';

// 設定にファイルストレージサービスを含む:
app.use(
  '/api',
  defService(partial(features.getLogoUploadUrlFeature, [{ configuration: { fileStorageDriver } }]))
);

API Endpoint: GET /api/organizations/:organizationId/logo-upload-url

`getOrganizationFollowersFeature`

スキーマバリデーション、ページネーション、ルーティング付きの組織フォロワー取得機能。

目的: バリデーション、ページネーション、アバター正規化付きで完全な組織フォロワー取得機能を提供。

合成:

Schema: getOrganizationFollowersSchema - 組織フォロワー取得リクエストのパスパラメータをバリデーション
Route: getOrganizationFollowersRoute - フォロワー取得とページネーション付きのGET /organizations/:organizationId/followers

使用例:

import { features } from '@nodeblocks/backend-sdk';
import { defService, partial, compose } from '@nodeblocks/backend-sdk/primitives';

const { getOrganizationFollowersFeature } = features;

// 直接使用:
app.use('/api', defService(getOrganizationFollowersFeature));

// データベース設定付き:
app.use('/api', defService(
  partial(getOrganizationFollowersFeature, [
    { dataStores: { organizations: db.collection('organizations'), users: db.collection('users') } }
  ])
));

API Endpoint: GET /api/organizations/:organizationId/followers

Response (200 OK):

{
  "data": [
    {
      "id": "user-123",
      "name": "John Doe",
      "avatar": {
        "url": "https://storage.example.com/avatars/avatar123.png",
        "type": "image/png"
      }
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "totalPages": 3
    }
  }
}

主な機能:

ページネーションサポート: カスタマイズ可能なページサイズで大きなフォロワーリストを効率的に処理
アバター正規化: ストレージ参照をアクセス可能なURLに自動変換
認証と認可: 認証されたユーザー（管理者または組織オーナー）に制限
包括的なバリデーション: 組織が存在し、リクエスト構造をバリデーション
詳細なエラーハンドリング: さまざまな失敗シナリオに対する明確なエラーレスポンスを提供
プロファイルブロックの再利用: 一貫性のために既存のfindProfilesとnormalizeFollowersを活用

認可:

認証が必要（isAuthenticated）
管理者または組織オーナーがアクセス可能（some(checkIdentityType(['admin']), hasOrgRole(['owner']))）

バリデーションルール:

パスパラメータorganizationIdは必須
組織はデータベースに存在する必要がある
オプションのクエリパラメータ: ページネーション制御用のpageとlimit

エラーレスポンス:

400 Bad Request: 無効なリクエストパラメータ
401 Unauthorized: 認証失敗
403 Forbidden: 権限不足（管理者または組織オーナーではない）
404 Not Found: 組織が存在しない
500 Internal Server Error: データベースまたはファイルストレージ操作が失敗

ハンドラープロセス:

認証と認可: ユーザーの認証情報と組織所有権の権限をバリデーション
組織バリデーション: 組織が存在することを確保
クエリ構築: 組織フォロワー用のMongoDBフィルターを構築
フォロワー取得: findProfilesを使用してページネーション付きでプロファイルを検索
アバター正規化: アバターobjectIdをアクセス可能なURLに変換
レスポンスフォーマット: フォロワーデータとページネーションメタデータを結合
レスポンス: ページネーション付き、正規化されたフォロワーリストで200 OKを返す

使用例:

組織分析: フォロワー数と成長を追跡
メンバーシップ管理: 組織の購読者を表示および分析
コンテンツ配信: フォロワーベースのコンテンツ配信をサポート
コミュニティ機能: 組織中心のソーシャル機能を構築

データフロー:

入力: 組織ID（パスパラメータ）とオプションのページネーションパラメータ（クエリ）
バリデーション: 認証、認可、組織存在チェック
データベース操作: $elemMatchを使用したMongoDBクエリでフォロワーを検索
アバター処理: ファイルストレージドライバーを介したアバターURLのバッチ正規化
レスポンス処理: ページネーションメタデータと正規化されたフォロワーデータのフォーマット
出力: ページネーション付き、正規化されたフォロワーリストで200 OK

パフォーマンスに関する注意事項:

効率的なフォロワークエリのためのMongoDB $elemMatch演算子の使用
大きなフォロワーリストのスケーラブルな取得のためのページネーションサポート
複数のフォロワーのバッチアバターURL正規化
必須のフォロワーデータ（id、name、avatar）のみを含む最小レスポンスペイロード
インデックス付きルックアップによる効率的なMongoDBクエリ

統合パターン:

完全な組織管理のために組織サービスと組み合わせる
アバターURL生成のためにファイルストレージドライバーと統合
スケーラブルなフォロワーリストのためにページネーションミドルウェアと連携
プロファイルと組織機能全体で一貫性のためにプロファイルブロック（findProfiles、normalizeFollowers）を再利用
リアルタイムのフォロワー数更新と分析をサポート

🎯 概要​

📋 機能構造​

🔧 利用可能な組織機能​

createOrganizationFeature​

getOrganizationFeatures​

findOrganizationsFeatures​

editOrganizationFeatures​

deleteOrganizationFeatures​

getOrganizationMemberFeatures​

checkOrganizationMemberExistenceFeatures​

findOrganizationMembersFeatures​

findOrganizationsForMemberFeatures​

editOrganizationMembersFeatures​

deleteOrganizationMemberFeatures​

findOrganizationDescendantsFeatures​

getCertificateUploadUrlFeature​

createChangeRequestFeature​

findChangeRequestsForOrganizationFeature​

updateOrganizationAsAdminFeature​

getLogoUploadUrlFeature​

getOrganizationFollowersFeature​

🎯 概要

📋 機能構造

🔧 利用可能な組織機能

`createOrganizationFeature`

`getOrganizationFeatures`

`findOrganizationsFeatures`

`editOrganizationFeatures`

`deleteOrganizationFeatures`

`getOrganizationMemberFeatures`

`checkOrganizationMemberExistenceFeatures`

`findOrganizationMembersFeatures`

`findOrganizationsForMemberFeatures`

`editOrganizationMembersFeatures`

`deleteOrganizationMemberFeatures`

`findOrganizationDescendantsFeatures`

`getCertificateUploadUrlFeature`

`createChangeRequestFeature`

`findChangeRequestsForOrganizationFeature`

`updateOrganizationAsAdminFeature`

`getLogoUploadUrlFeature`

`getOrganizationFollowersFeature`