# 機能設計書 87-CMSアプリケーションパッケージ

## 概要

本ドキュメントは、Decap CMSの再利用可能なアプリケーションパッケージ（`decap-cms-app`）の機能設計について記述する。本パッケージはReactをピア依存として、全てのバックエンド、ウィジェット、エディタコンポーネント、ロケールをCMSコアに登録する統合パッケージである。

### 本機能の処理概要

**業務上の目的・背景**：Decap CMSをReactプロジェクトに組み込む場合、CDNバンドル（`decap-cms`）ではなく、Reactをピア依存とした再利用可能なパッケージが必要となる。本パッケージは全構成パッケージの統合・登録を行い、既存のReactアプリケーションにCMSを埋め込むことを可能にする。ReactやReactDOMを二重バンドルせず、ホストアプリケーションのReactインスタンスを共有する。

**機能の利用シーン**：Reactベースのウェブアプリケーションにカスタムのコンテンツ管理機能を組み込む場合。`npm install decap-cms-app`でインストールし、Reactコンポーネントとして使用する。

**主要な処理内容**：
1. `decap-cms-core`からCMSコアオブジェクトを取得
2. 全バックエンド（GitHub、GitLab、Bitbucket、GitGateway、Azure、Gitea、Proxy、AWS Cognito、Test）の登録
3. 全ウィジェット（string、number、text、image、file、select、markdown、list、object、relation、boolean、map、datetime、code、colorstring）の登録
4. エディタコンポーネント（image、code-block）の登録
5. 全ロケールの登録
6. バージョン番号のコンソール出力

**関連システム・外部連携**：decap-cms-core、全バックエンドパッケージ、全ウィジェットパッケージ、decap-cms-locales

**権限による制御**：権限制御はない。

## 関連画面

本パッケージは全画面の基盤であるため、全画面に関連する。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面 | 主機能 | 全バックエンド・ウィジェット・ロケールの登録 |

## 機能種別

パッケージング / プラグイン登録

## 入力仕様

### 入力パラメータ

本パッケージは入力パラメータを持たない。モジュール読み込み時に自動的に登録処理が実行される。

### 入力データソース

各パッケージのエクスポートオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DecapCmsApp | object | CMSオブジェクト（全APIメソッドを含む、CMSコアのスプレッド） |

### 出力先

ESモジュールエクスポート、CDN配布パッケージ（decap-cms）

## 処理フロー

### 処理シーケンス

```
1. extensions.js読み込み（自動実行）
   ├─ 9つのバックエンド登録（registerBackend）
   ├─ 15のウィジェット登録（registerWidget）
   ├─ 2つのエディタコンポーネント登録（registerEditorComponent）
   └─ 全ロケール登録（registerLocale）

2. index.js
   ├─ decap-cms-coreからCMSオブジェクト取得
   ├─ extensions.js読み込み（ステップ1が実行される）
   └─ DecapCmsAppとしてエクスポート
```

### フローチャート

```mermaid
flowchart TD
    A[index.js読み込み] --> B[decap-cms-coreインポート]
    B --> C[extensions.js実行]
    C --> D[バックエンド登録x9]
    D --> E[ウィジェット登録x15]
    E --> F[エディタコンポーネント登録x2]
    F --> G[ロケール登録]
    G --> H[バージョンログ出力]
    H --> I[DecapCmsAppエクスポート]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-87-01 | バックエンド登録名 | 各バックエンドはgit-gateway、azure、aws-cognito-github-proxy、github、gitlab、gitea、bitbucket、test-repo、proxyの名前で登録 | extensions.js読み込み時 |
| BR-87-02 | ウィジェットWidget()パターン | 各ウィジェットはWidget()ファクトリメソッドで登録オブジェクトを生成 | registerWidget呼び出し時 |
| BR-87-03 | コードブロックエディタコンポーネント | code-blockエディタコンポーネントはid='code-block'、widget='code'、type='code-block'で登録 | extensions.js読み込み時 |
| BR-87-04 | ReactはpeerDependency | React/ReactDOMはピア依存として宣言され、ホストアプリケーションのインスタンスを使用 | パッケージインストール時 |

### 計算ロジック

該当なし

## データベース操作仕様

該当なし

### 操作別データベース影響一覧

なし

## エラー処理

### エラーケース一覧

本パッケージは明示的なエラーハンドリングを行わない。各パッケージの登録処理はCMSコアのレジストリで管理される。

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- ReactとReactDOMをピア依存にすることで、バンドルサイズを削減
- ウィジェットはWidget()ファクトリで遅延生成可能

## セキュリティ考慮事項

- 全バックエンドが自動登録されるため、不要なバックエンドへのアクセスパスが存在する（設定により使用バックエンドは限定される）

## 備考

- パッケージバージョン: 3.10.0
- React ^19.1.0をpeerDependenciesとして要求
- TypeScript型定義（index.d.ts）を提供
- locales.jsでは英語ロケールのみをデフォルト登録するが、extensions.jsでは全ロケールを登録

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.js | `packages/decap-cms-app/src/index.js` | CMSコアの読み込みとエクスポート構造 |

**主要処理フロー**:
1. **1行目**: decap-cms-coreからCMSオブジェクト取得
2. **2行目**: extensions.js読み込み（全プラグイン登録）
3. **5-8行目**: バージョンログ出力
4. **11-13行目**: DecapCmsAppエクスポート

#### Step 2: 拡張機能登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | extensions.js | `packages/decap-cms-app/src/extensions.js` | 全バックエンド/ウィジェット/コンポーネント/ロケール登録 |

**主要処理フロー**:
- **2-13行目**: バックエンドパッケージのインポート
- **14-28行目**: ウィジェットパッケージのインポート
- **29-32行目**: エディタコンポーネント、ロケールのインポート
- **35-43行目**: バックエンドの登録（registerBackend x 9）
- **44-60行目**: ウィジェットの登録（registerWidget、15ウィジェット一括）
- **61-67行目**: エディタコンポーネント登録（image + code-block）
- **68-70行目**: 全ロケール登録（Object.keys(locales).forEach）

#### Step 3: ロケール登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | locales.js | `packages/decap-cms-app/src/locales.js` | 英語ロケールのデフォルト登録 |

**主要処理フロー**:
- **1-2行目**: CMSコアと英語ロケールインポート
- **4行目**: 英語ロケール登録

### プログラム呼び出し階層図

```
decap-cms-app/src/index.js
    |
    +-- decap-cms-core（CMSコアオブジェクト）
    |
    +-- extensions.js
    |      |
    |      +-- CMS.registerBackend('git-gateway', GitGatewayBackend)
    |      +-- CMS.registerBackend('azure', AzureBackend)
    |      +-- CMS.registerBackend('aws-cognito-github-proxy', ...)
    |      +-- CMS.registerBackend('github', GitHubBackend)
    |      +-- CMS.registerBackend('gitlab', GitLabBackend)
    |      +-- CMS.registerBackend('gitea', GiteaBackend)
    |      +-- CMS.registerBackend('bitbucket', BitbucketBackend)
    |      +-- CMS.registerBackend('test-repo', TestBackend)
    |      +-- CMS.registerBackend('proxy', ProxyBackend)
    |      |
    |      +-- CMS.registerWidget([...15 widgets...])
    |      |
    |      +-- CMS.registerEditorComponent(image)
    |      +-- CMS.registerEditorComponent({id:'code-block',...})
    |      |
    |      +-- locales.forEach → CMS.registerLocale(locale, data)
    |
    +-- DecapCmsApp エクスポート
```

### データフロー図

```
[入力]                          [処理]                       [出力]

decap-cms-core ─────────▶ index.js ──────────────▶ DecapCmsApp（ESM）
decap-cms-backend-* ────▶ extensions.js
decap-cms-widget-* ─────▶   |
decap-cms-locales ──────▶   +-- registerBackend x9
decap-cms-editor-* ─────▶   +-- registerWidget x15
                             +-- registerEditorComponent x2
                             +-- registerLocale x全ロケール
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `packages/decap-cms-app/src/index.js` | ソース | エントリーポイント、CMSオブジェクトのエクスポート |
| extensions.js | `packages/decap-cms-app/src/extensions.js` | ソース | 全バックエンド・ウィジェット・コンポーネント・ロケール登録 |
| locales.js | `packages/decap-cms-app/src/locales.js` | ソース | 英語ロケールのデフォルト登録 |
| package.json | `packages/decap-cms-app/package.json` | 設定 | パッケージ依存関係定義（peerDependencies: react） |
