report-editor

レポートエディター

dxs CLI を使用して、Datex Studio ブランチ上の既存の RDLX-JSON レポートを変更するワークフローです。

重要な原則： 変更する前に内容を把握します。変更を加える前に、現在のレポートをダウンロードして確認してください。

作成方針：

• すべての変更には 段階的な CLI 操作（set／move／remove／batch／table add-column／dataset add-field）を使用します
• CLI で扱えない構造（PageHeader／PageFooter、複雑な Tablix グループ化）に限り JSON を直接編集します
• 最初から作り直さないでください -- 既存のファイルを使用します

参考資料（共通）

• ../datex-studio-shared/branch-setup.md -- ブランチと接続の選択
• ../datex-studio-shared/studio-management.md -- Studio のライフサイクル：確認、起動、クリーンアップ
• ../datex-studio-shared/report-authoring/design-standards.md -- Datex のデザイン言語：カラーパレット、タイポグラフィ、テーブルのスタイル、フィールドのラベルと値のパターン、グリッド配置、レポートのカテゴリ
• ../datex-studio-shared/report-authoring/design-patterns.md -- 座標系、レイアウトパターン、要素のサイズ
• ../datex-studio-shared/report-authoring/json-structure.md -- RDLX-JSON 形式：ドキュメントテンプレート、要素の JSON 形式、式のクイックリファレンス
• ../datex-studio-shared/report-authoring/cli-commands.md -- CLI の構文：一括操作、tablix、画像、データセット、set／move／remove、検証
• ../datex-studio-shared/report-authoring/sample-data.md -- ライブプレビュー用のサンプルデータ形式
• ../datex-studio-shared/report-authoring/dataset-rules.md -- DataSet 管理：CommandText の規則、コレクションの処理、日付アノテーション、機密性プロパティ
• ../datex-studio-shared/report-authoring/deploy-patterns.md -- アップロード、プレビュー、検証のパターン
• ../datex-studio-shared/report-authoring/troubleshooting.md -- RDLX-JSON と CLI でよくある間違いとその修正方法

依存関係

datasource-creator と schema-explorer は必要な場合（カテゴリ 4～5）にのみ呼び出します。レイアウトのみの編集（カテゴリ 1～3）には必要ありません。

オーケストレーションモデル

report-editor (this skill)
  |
  +-- Phase 1: Download & Inspect
  |     +-- Select branch + find report (branch-setup.md)
  |     +-- Download report folder (RDLX-JSON + datasources + manifest)
  |     +-- Inspect layout + DataSets + datasource fields
  |     +-- Output: report folder + structural understanding
  |
  +-- Phase 2: Triage -- Determine Change Depth
  |     +-- Classify user's request into category 1-5
  |     +-- Check DataSet fields vs datasource fields
  |     +-- Output: modification plan with category + steps
  |
  +-- Phase 3: Modify (conditional paths by category)
  |     +-- Cat 1-2: Layout-only --> set/move/remove/batch on folder/report.rdlx-json
  |     +-- Cat 3: Add from existing DataSet field --> table add-column
  |     +-- Cat 4: Datasource gap --> datasource-creator --> datasource add --> DataSet --> layout
  |     +-- Cat 5: New section --> schema-explorer --> datasource-creator --> datasource add --> DataSet --> layout
  |
  +-- Phase 4: Deploy & Verify (deploy-patterns.md)
  |     +-- assemble folder --> wrapper JSON
  |     +-- upload wrapper JSON

フェーズ 1：ダウンロードと確認

ブランチを選択してレポートを探す

ブランチと接続の選択については、branch-setup.md に従ってください。

次に、ブランチ上のレポートを一覧表示します。

dxs report list --branch <branch_id>

対象が曖昧な場合は、レポート一覧をユーザーに提示してください。ユーザーが特定のレポート名を指定した場合は、一覧と照合してください。

レポートフォルダーをダウンロードする

# Auto-names folder from reference name
dxs report download --branch <branch_id> --reference-name <reference_name>

# Or specify folder path explicitly
dxs report download <folder_path> --branch <branch_id> --reference-name <reference_name>

これにより、以下を含む レポートフォルダー が作成されます。

• report.rdlx-json -- RDLX-JSON レイアウト（編集コマンドの対象）
• manifest.json -- すべてのバインディングメタデータ（データソース、パラメーター、データソースパラメーター、アクセス修飾子）
• ds_*.json -- 所有するデータソース設定ごとに 1 つのファイル（ラッパーから抽出）

マニフェストには、すべてのデータソースバインディング、パラメーターマッピング、メタデータが保持されます。再アップロード時に手動で抽出したり、フラグを再構成したりする必要はありません。

レポートフォルダーを確認する

データソースのバインディングを把握するために、マニフェストを確認します。

dxs report datasource list <folder>/

レイアウトを確認します。

dxs report inspect <folder>/report.rdlx-json

また、DataSets、要素の階層、式を把握するために RDLX-JSON を直接読み取ってください。

レイアウトを視覚的に確認する

--bbox を使用すると、色付きのバウンディングボックスを含むプレビューを生成できます。変更前に要素の位置を把握するのに役立ちます。

dxs report preview <file.rdlx-json> --bbox ElementName:red --bbox AnotherElement:blue -o /tmp/inspect.svg

現在のレイアウトを確認

dxs report inspect <file.rdlx-json>

これにより、すべての要素について、種類、名前、位置、サイズ、値／式、DataSet のバインドが表示されます。また、ファイルを直接読んで、以下を確認します。

• DataSet（名前、フィールド、CommandText のパターン）
• 要素の階層（子要素を含む長方形）
• 使用されている式
• ページ設定（サイズ、余白、向き）

使用可能なデータソースフィールドを特定する

レポートで使用されている各データソースについて確認します（dxs report datasource list <folder>/ を実行すると確認できます）。

# For standalone datasources
dxs report datasource-fields <datasource_ref> --branch <branch_id>

# For owned datasources
dxs report datasource-fields <datasource_ref> --branch <branch_id> --report <report_ref>

これにより、フィールドの全一覧、in_params、結果の型、コレクションがわかります。これがトリアージの判定基準です――フェーズ 2 では、要求されたフィールドがすでにここで使用可能かどうかを確認します。

レポートが見つからない場合

dxs report list に対象のレポートが表示されない場合：

1. ユーザーに「ブランチ X にそのレポートは見つかりませんでした。」と伝えます。
2. 「一から作成しますか？」と尋ねます。
3. はいの場合は、report-creator スキルを呼び出します。

フェーズ 2：トリアージ――変更の規模を判断する

要求された変更を、5 つのカテゴリのいずれかに分類します。カテゴリごとに必要なワークフローは異なります。

変更カテゴリ

カテゴリ	例	必要な作業	依存スキル
1. ラベル／スタイル	「SHIPPER」を「FROM」に変更する、「ヘッダーを青にする」、「フォントサイズを大きくする」	set／batch のみ	なし
2. 配置変更	「2 列目と 3 列目を入れ替える」、「住所ブロックを下に移動する」、「フッターを削除する」	move／remove／set	なし
3. 列の追加（DataSet にフィールドがある）	Status が DataSet に含まれている場合の「Status 列を追加する」	table add-column ＋ レイアウト	なし
4a. フィールドの追加（データソースにはあるが、DataSet にない）	フィールドがデータソースの出力には含まれているが、DataSet には含まれていない場合の「Material Description を追加する」	dataset add-field ＋ レイアウト	なし
4b. フィールドの追加（データソースに不足）	フィールドがデータソースの $select／$expand に含まれていない場合の「Material Description を追加する」	データソースの再生成 ＋ dataset add-field ＋ レイアウト	datasource-creator
5. 新しいデータセクション	適切なデータソースがない場合の「明細テーブルを追加する」	一連の作業：schema-explorer ＋ datasource-creator ＋ DataSet ＋ レイアウト	schema-explorer ＋ datasource-creator

判断ツリー

User request
  |
  +-- Does the change involve data fields?
  |   +-- NO --> Is it positional/structural (move, swap, remove)?
  |   |   +-- YES --> Category 2 (rearrangement)
  |   |   +-- NO  --> Category 1 (label/style)
  |   |         --> Proceed to Phase 3
  |   |
  |   +-- YES --> Does the needed field exist in a report DataSet?
  |       +-- YES --> Category 3 (add column/element from existing DataSet field)
  |       |         --> Proceed to Phase 3
  |       |
  |       +-- NO --> Is the field in the datasource output? (from datasource-fields)
  |           +-- YES --> Category 4a (field in datasource, missing from DataSet)
  |           |         --> Add to DataSet, then layout
  |           |
  |           +-- NO --> Is the field reachable from the datasource's entity?
  |               |     (just missing from $select/$expand)
  |               |
  |               +-- YES --> Category 4b (datasource needs regeneration)
  |               |         --> Modify datasource --> re-upsert --> DataSet --> layout
  |               |
  |               +-- NO --> Category 5 (entirely new data requirement)
  |                         --> schema-explorer --> datasource-creator --> DataSet --> layout

トリアージ結果を提示する

フェーズ 3 に進む前に、分類結果をユーザーに提示し、承認を得てください。ユーザーの計画への確認なしに、レポートの変更を開始してはいけません。

### Modification Plan

**Requested change:** [user's request]
**Category:** [1-5] -- [description]

**Steps:**
1. [what will happen]
2. [what will happen]
...

**Impact:** [layout-only / DataSet change / datasource modification / new datasource]

Proceed?

フェーズ 3：変更

ライブプレビュー用に Studio で開く

レイアウトを伴う変更（カテゴリ 1～3、またはカテゴリ 4～5 のレイアウト部分）では、変更を加える前に Studio が起動しており、レポートがライブプレビュー用に開かれていることを確認します。

../datex-studio-shared/studio-management.md に従って Studio を自動管理します。状態を確認し、必要ならバックグラウンドで起動し（準備完了を確認）、レポートを開き、フェーズ 4 の後にクリーンアップします。

カテゴリ 1～2：レイアウトのみの変更

cli-commands.md に従って CLI コマンドを使用します。

# Change a label
dxs report set <file> ElementName --value "New Label Text"

# Change styling
dxs report set <file> ElementName --font-size 12pt --color Navy --font-weight Bold

# Move an element
dxs report move <file> ElementName --left 1in --top 2in

# Resize an element
dxs report set <file> ElementName --width 3in --height 1in

# Remove an element
dxs report remove <file> ElementName

# Batch operations (for multiple changes)
cat > /tmp/ops.json << 'OPEOF'
[
  {"action": "set", "name": "Title", "value": "New Title", "font-size": "18pt"},
  {"action": "set", "name": "SubTitle", "color": "DimGray"},
  {"action": "move", "name": "AddressBlock", "left": "0in", "top": "1.5in"},
  {"action": "remove", "name": "OldElement"}
]
OPEOF

dxs report batch <file> --ops-file /tmp/ops.json

バッチの上限：1 回の呼び出しにつき最大 25 操作です。 25 操作を超える場合は、複数回のバッチ呼び出しに分けます。論理的にまとめます（例：最初のバッチで位置を変更し、2 回目のバッチでスタイルと新しい要素を設定します）。

新規または変更する要素には、design-standards.md を適用します。Arial フォントファミリー、公式カラーパレット、0.25 インチのグリッド配置を使用します。

線は特別な扱いが必要です。 線では left／top／width／height ではなく、StartPoint／EndPoint と start-x／start-y／end-x／end-y を使用します。線には move コマンドは機能しません。JSON を直接編集して線の位置を変更するか、エンドポイントフラグを使って set をバッチ実行します。

カテゴリ 3：既存の DataSet フィールドから列を追加する

フィールドはすでに DataSet に存在します。テーブルに列を追加するだけです。

dxs report table add-column <file> --table <TablixName> --shrink \
  --header-cell "New Header" \
  --detail-cell '=Fields!ExistingField.Value' \
  --header-style 'font-family:Arial;font-size:10pt;font-weight:Bold;border-bottom-width:1.5pt;border-bottom-style:Solid;border-bottom-color:#5B08B2;padding:2pt;vertical-align:Bottom' \
  --detail-style 'font-family:Arial;font-size:10pt;padding:2pt;vertical-align:Middle;border-bottom-width:0.25pt;border-bottom-style:Solid;border-bottom-color:LightGray'

--shrink フラグを指定すると、既存の列幅を比例して縮小し、テーブル全体の幅を変えずに新しい列を追加できます。

テーブル以外の要素（単独のテキストボックス）には、add アクションを指定して dxs report batch を使用し、新しいフィールドをレイアウトに配置します。

新しい列には Datex のデザイン標準を適用し、テーブル内の既存の列とスタイルを合わせてください。

カテゴリ 4a：データソースにフィールドはあるが、DataSet に含まれていない

フィールドはデータソースの出力に含まれていますが、レポートの DataSet 定義には含まれていません。追加してください。

dxs report dataset add-field <file> --dataset <DataSetName> --field "New.Field.Path"

dataset-rules.md に従ってください。

• 日付の注釈：日付フィールドに [Date|YYYY-MM-DDTHH:mm:ss.fffffff] を付加します
• コレクションの処理：単一結果の DataSet では、コレクションフィールドを単一の DataSet フィールドとして追加できません
• CommandText：結果の種類に応じて、DataSet の CommandText パターンが正しいことを確認します

次に、新しいフィールドを参照するレイアウト要素（列またはテキストボックス）を追加します。レポートに対応する .data.json がある場合は、新しいフィールドのサンプル値を追加して更新してください。

カテゴリ 4b：データソースの再生成が必要

フィールドは OData エンティティに存在しますが、データソースの $select または $expand に含まれていません。データソースの設定を更新する必要があります。

スタンドアロンの OData データソースの場合：

1. 現在のデータソース設定を取得します：dxs datasource get <ref> --branch <id>
2. 不足しているフィールドのパスを特定します（例：$expand に Material/Description が必要）
3. datasource-creator を呼び出して、更新したクエリで再生成します
4. dxs configuration upsert datasource -D <file.json> --branch <id> でブランチを更新します
5. dxs report dataset add-field でフィールドを DataSet に追加します
6. レイアウト要素を追加します

所有 OData データソースの場合：

1. 現在の設定はすでにレポートフォルダーにあります（ダウンロード時に ds_*.json として抽出されています）
2. datasource-creator を呼び出して、更新したクエリで再生成します
3. フォルダー内で置き換えます：dxs report datasource remove <folder> <alias> を実行し、次に dxs report datasource add <folder> --owned <new_ds.json>:<alias> を実行します
4. dxs report dataset add-field でフィールドを DataSet に追加します
5. レイアウト要素を追加します

フローデータソースの場合：

1. 必要なフィールドがフローのソース OData データソースのいずれかにあるか確認します
2. ある場合：戻り値の型にフィールドを含めるようにフローコードを更新し、型定義 YAML を更新します
3. ない場合：まずソース OData データソースを更新してから、フローコードを更新する必要がある場合があります
4. dxs datasource generate-flow で再生成します
5. 再度 upsert するか（スタンドアロン）、フォルダー内で置き換えます：dxs report datasource remove/add（所有データソース）
6. DataSet とレイアウトにフィールドを追加します

カテゴリ 5：新しいデータセクション

新しいセクションで、既存のデータソースでは対応していないエンティティまたはリレーションシップのデータが必要な場合です。

1. 新しいセクションの要件を収集します（必要なデータ、レイアウト）。通常は簡単な会話で十分です。セクションが複雑な場合にのみ、requirements-gathering を呼び出してください。
2. schema-explorer を呼び出し、適切な OData エンティティとフィールドを見つけます。
3. datasource-creator を呼び出してデータソース設定を作成し、続けて dxs report datasource add <folder> --owned <file>:<alias> を実行します（owned を優先し、共有されている場合は standalone を使用します）。
4. dataset-rules.md に従って DataSet を追加します。フィールド名の主な情報源として datasource-creator のフィールド概要を使用し、すべてのフィールドを含めます。
5. dxs report batch を使ってレイアウト（四角形のコンテナー、テキストボックス、または tablix）を構築します。
6. プレビューに必要な場合は、sample-data.md に従ってサンプルデータを作成または更新します。

DataSet を作成するには：

dxs report dataset add <file> --name ds_new_section \
  --field Id --field LookupCode --field Status \
  --field "Account.Name" \
  --field "OrderDate[Date|YYYY-MM-DDTHH:mm:ss.fffffff]"

レイアウトセクションを構築する際は、グループ化に四角形のコンテナーを使用します。

cat > /tmp/new-section-ops.json << 'OPEOF'
[
  {"action": "add", "type": "rectangle", "name": "NewSectionBox",
   "left": "0in", "top": "4in", "width": "7.5in", "height": "2in"},
  {"action": "add", "type": "textbox", "name": "NewSectionTitle",
   "parent": "NewSectionBox", "left": "0in", "top": "0in",
   "width": "7.5in", "height": "0.3in",
   "value": "Section Title", "font-size": "14pt", "color": "DimGray"}
]
OPEOF

dxs report batch <file> --ops-file /tmp/new-section-ops.json

テーブルには dxs report add tablix を使用します。グループ化、フッター行、並べ替え式を含む完全な構文については、cli-commands.md を参照してください。

フィードバックに基づく反復

変更を加えるたびに、Studio での表示についてユーザーに尋ねます。調整には set／move／remove を使用します。承認されるまで繰り返してください。

ユーザーが Studio でレイアウトを確認し、問題ないと承認するまで、Phase 4（組み立て／アップロード）に進んではいけません。明示的に次のように尋ねてください：「Studio での表示はいかがですか？アップロードしてよいですか、それとも調整が必要ですか？」

Phase 4：デプロイと検証

組み立てとアップロード

レポートフォルダーには必要なものがすべて揃っています。マニフェストには、ダウンロード時のすべてのデータソースバインディング、パラメーター、メタデータが保持されています。フラグを再構築する必要はありません。

# Assemble folder into wrapper JSON
dxs report assemble <folder>/ -o <reference_name>.json

# Upload wrapper to branch
dxs report upload <reference_name>.json --branch <branch_id>

Phase 3 でデータソースを追加または削除した場合、その変更は dxs report datasource add/remove によってすでにマニフェストに反映されています。

追加のアップロードパターンと検証については、deploy-patterns.md に従ってください。

検証

dxs report get <reference_name> --branch <branch_id>

レポートがブランチにあり、想定どおりの構造、データソースバインディング、パラメーターになっていることを確認します。

パラメーターの検出テスト

データソースに in_params がある場合は、deploy-patterns.md に従って実際のテスト値を検出し、Studio でユーザーがテストできるよう JSON として出力します。

トラブルシューティング

よくある RDLX-JSON の式の問題や、レイアウト／CLI の間違いについては、troubleshooting.md を参照してください。

エディター固有の問題

間違い	修正方法
最初にダウンロードせずにレポートを変更する	必ず dxs report download を実行して最新バージョンを取得してください。古いローカルファイルを編集すると、他の変更が失われます
DataSet にフィールドを追加してもサンプルデータを更新しない	Studio のプレビューでは新しいフィールドが空白になります。.data.json をサンプル値で更新してください
確認せずにデータソースにフィールドがあると思い込む	必ず datasource-fields を実行して確認してください。フィールドが $select に含まれていない場合があります
フィールド式を変更しても DataSet フィールドを更新しない	DataField のパス名を変更する場合は、一致するように DataSet フィールドも更新する必要があります
まだ参照されているデータソースフィールドを削除する	削除する前に、レポート内のすべての式で Fields!RemovedField.Value が使われていないか確認してください
コレクションパスのフィールドをフラットな DataSet フィールドとして追加する	コレクションのナビゲーションプロパティは、単一結果の DataSet では警告なく空白として解決されます。フローデータソースを使用してフラット化するか、CommandText: "$.ds.result.Collection.*" を指定した子データセットを作成してください

---

編集後に post-edit-verification を呼び出して、説明／JSON／スキーマ違反を検出してください。最終確認には component-validator を呼び出してください。