fusion-core-services

Fusion Core Services

使用する場面

タスクが1つ以上のFusion CoreサービスAPIに関わり、個別のスキルを別途インストールすることなく、エージェントが適切なサービスのガイダンスを特定する必要がある場合に使用します。

一般的な例：

• Fusion APIクライアントを実装する
• Fusionバックエンドサービスとの統合を設定する
• どのFusion Coreサービスがワークフローを担当するか確認する
• コンテキストとユーザー、ロールと通知、アプリとサービスメッセージなど、複数サービスにまたがるタスクを解決する

使用しない場面

• fusion-core-services 内のコードを変更する場合
• Fusionサービスレイヤーを伴わない、Fusion以外のAPIや一般的なMicrosoft Graph／Power BIの作業
• Fusion Coreサービス以外の、別の専用スキルですでにカバーされている単独の製品ワークフロー

必須入力

• 対象のワークフローまたはユーザーの目標
• 対象コンシューマーの形式（react、typescript client、csharp httpclient、backend service、その他）
• 分かっている場合は、対象サービスのヒント
• 該当する場合は、バージョン管理や認可に関する要件

手順

1. まず、リクエストの範囲を特定します。

• ワークフローが単一のサービスに関係するのか、複数のサービスに関係するのかを確認します。
• サービスが曖昧な場合は、実装のガイダンスを提示する前に agents/service-router.md を使って、ワークフローに該当する可能性のあるサービスを特定します。

2. 関連するサービスのリファレンスのみを読みます。

• Combined API surface から始めます。
• 次に、該当するサービスごとのリファレンスファイルを開きます。
• 回答に実質的に関係するサービスに限り、エンドポイントカタログとモデルアセットを参照します。

3. 正確な名前や形式を信頼する前に、最新の OpenAPI ドキュメントを取得します。

• すべての Fusion Core サービスは、JWT 不要で、現在の OpenAPI ドキュメントを公開しています。 https://{service}.api.fusion.equinor.com/openapi/api-v{version}.json（例： https://people.api.fusion.equinor.com/openapi/api-v3.json、 https://context.api.fusion.equinor.com/openapi/api-v1.json）。
• 同梱のリファレンスファイルは、どのサービス／コントローラーが存在するか、どのように調べるかをまとめた厳選されたインデックスであり、正確なスキーマ名や型名の信頼できる情報源ではありません。サービスの変更に伴い、これらの名前は変わることがあります。対象サービスの最新ドキュメントを取得し、実際の型名については components.schemas を確認してください。レスポンスは一般に Api{Entity}、リクエストボディは単純な {Verb}{Entity}Request という名前ですが、パターンよりも最新ドキュメントに記載された正確な名前を常に優先してください。components.schemas に存在しない Dto 接尾辞付きの名前を決して作らないでください。
• 最新の OpenAPI ドキュメントを取得できない場合（Web フェッチツールまたはネットワークアクセスがない場合）は、その制約を明示し、同梱のリファレンス／アセットは可能な範囲での参考情報として扱い、正確なスキーマ名／型名や必須フィールドを断定しないでください。
• サービスカタログにサブドメインが記載されていない場合は、サービスアドレスを決めつけないというプラットフォーム全体のルールに従い、推測するのではなく、Fusion サービスディスカバリーを使って特定してください。

4. ソースに基づいたガイダンスを維持します。

• 最新の OpenAPI ドキュメントと同梱リファレンスの「suggested model」一覧が異なる場合は、最新の OpenAPI ドキュメントを優先してください。最新ドキュメントが常に現行の情報であり、同梱ファイルは古くなっている可能性があります。
• リリース前にソースを直接確認する必要があるルートやモデル領域があれば、明記してください。

5. 機能を明確に扱います。

• サービスが OPTIONS またはその他のアクセス確認用ルートを公開している場合は、それを使って機能に応じた UI や変更処理を実装します。
• 安定した確認用エンドポイントが公開されていない場合は、クライアント側で保守的に動作するよう記述し、403 Forbidden を機能判定のフォールバックシグナルとして扱います。

6. サブスクリプションは、リファレンスに別途記載がない限り、バックエンド専用として扱います。

• /subscriptions/... ルートは、アプリケーショントークンによるイベント登録と CloudEvent 形式の変更処理を目的としたものであり、通常のフロントエンド CRUD フロー向けではありません。

7. 利用者がそのまま使えるガイダンスを返します。

• フロントエンドの利用者には、実際のスキーマ名（Dto 接尾辞付きではない名前）を使った TypeScript 対応モデルと、最小限のクライアント／フックのパターンを提示します。
• .NET の利用者には、公開されている場合、手書きの代替レコードではなく、最新ドキュメントに記載された実際のスキーマ型（一般に Api{Entity} ですが、components.schemas に記載された名前を使用）に直接デシリアライズする、型付き HttpClient の方針を提示します。
• 複数のサービスにまたがるタスクでは、サービスの呼び出し順序とサービス間でのデータ受け渡しを説明します。

サービスカタログ

• Apps: リファレンス、エンドポイントカタログ、モデル
• Bookmarks: リファレンス、エンドポイントカタログ、モデル
• Context: リファレンス、エンドポイントカタログ、モデル
• Contract Personnel: リファレンス、エンドポイントカタログ、モデル
• Mail: リファレンス、エンドポイントカタログ、モデル
• Notification: リファレンス、エンドポイントカタログ、モデル
• People: リファレンス、エンドポイントカタログ、モデル
• Portal Config: リファレンス、エンドポイントカタログ、モデル
• Reports: リファレンス、エンドポイントカタログ、モデル
• RolesV2: リファレンス、エンドポイントカタログ、モデル
• Service Messages: リファレンス、エンドポイントカタログ、モデル
• Tasks: リファレンス、エンドポイントカタログ、モデル

想定される出力

次の順序で見出しを返してください。

1. スコープの確認
2. サービスの選定
3. エンドポイントのマッピング
4. モデルのマッピング
5. コンシューマー実装計画
6. 統合コードの概要
7. 検証およびテストに関する注意事項
8. リスクと前提条件

安全性と制約

次のことは決して行わないでください。

• サービスの所有権、ルート、モデルのフィールドを捏造する
• Dto が付いた型名や、ライブ OpenAPI ドキュメントの components.schemas に実際に存在しない名前を捏造する — パターンにかかわらず、実在する正確な名前を使用する
• 同梱されている Fusion のリファレンスに固有の情報があるのに、一般的な SaaS/API の前提に基づいて回答する
• バックエンドのサブスクリプションルートを、通常のフロントエンド操作フローとして扱う

必ず次のことを行ってください。

• 型名を挙げる前に、対象サービスのライブ OpenAPI ドキュメントを取得する — 同梱のリファレンスファイルは古くなっている場合がありますが、ライブドキュメントは最新です
• 複数のサービスが関係する場合は、サービス間の推論を明確に示す
• サービスが OPTIONS を公開している場合は、機能プローブの動作について触れる
• ユーザーのワークフローに必要な、最小限のサービスリファレンスを優先する