make-app-service

make-app-service

管理者へのお問い合わせに関するフィードバックでは、make-app-auth/references/access-help.md で説明されている公開済みの認証名前空間プロキシを再利用してください。完了済みの拒否ステータスと本文（理由と permissionKey を含む）、Cookie、信頼された転送先のホスト／プロトコルを保持してください。お問い合わせヘルプの表示をビジネスリクエストの成功条件にせず、汎用的なゲートウェイプロキシを追加しないでください。

このスキルは、apps/service における Make App Service API の作業に使用します。

make-app-service は、apps/ui と apps/service 間の Service API コントラクト、薄い Make Data API オーケストレーション、Service のルート形状、Make アダプターのランタイム設定のセマンティクス、Make のレスポンスの直接パススルー、Service 側のバリデーション、境界ログ、Service API テストを担当します。

レコードアクションの動作（make-app-actions）、ソートの動作（make-app-sort）、フィルタリングの動作（make-app-filter）、グルーピングの動作（make-app-group）、Make AI アシスタントの通信セマンティクス（make-ai-assistant）、UI レイアウト（makeui）、認証の実装（make-app-auth）、単一アプリの権限ロジック（make-app-permission）、ランタイムのビルド／起動コントラクト（make-app-runtime）、DSL のモデリング（makedsl）、Make CLI の実行（makecli）、CanvasTable のレンダリング／編集（canvas-table-integration）は担当しません。

クイックスタート

1. apps/docs/api.md、apps/service/src、apps/service/src/config.ts（またはホストに相当する設定エントリ）、既存のテスト、ホストプロジェクトで宣言されているデータフローを確認します。
2. ホストの API 契約を維持します。Service のルートやレスポンス形式を変更する場合は、変更前または変更と同時に apps/docs/api.md を更新します。
3. Make Deploy のデフォルトのルート分割では、公開されるブラウザー向け Service ルートを /api/** として扱います。プレフィックスのない /app/**、/auth/**、/health ルートは、ローカルでの互換性を目的とする場合に限ります。デプロイルートで実際に公開されていない限り、公開 UI の契約として記載しないでください。
4. 実装前にすべてのルートを分類します。通常の直接的な Make プロキシでは、完了した 2xx、4xx、5xx のステータス、Content-Type、本文をそのまま維持します。ファイルのダウンロードでは、Content-Disposition も維持し、バイト列をストリーミングします。Make AI アシスタントでは、エラーの扱いが明示的に例外となります。 一般的な生エラーのパススルーではなく、以下に定める選択したアダプターの安全な公開エラー契約を適用します。実際の集約／正規化ルートでは、apps/docs/api.md に非プロキシとして記載されている場合に限り、独自の成功結果を定義できます。通常の Make エラーは変更しません。
5. 新しい Make POC Service では、デフォルトでプラットフォームのレイヤー化されたソースツリーを使用します。構成は app.ts、server.ts、config.ts、logger.ts、make-client/、services/、utils/ とし、テストは対象のルート／アダプター／ヘルパーの近くに配置します。
6. 公開ランタイムのデータソースとして、ローカルの DSL／YAML を読み込まないでください。ランタイムのスキーマとデータは、Make／バックエンド API またはホストの Service アダプターから取得します。
7. Make Meta／Data／Preset 呼び出し、候補 API、ルックアップ、ファイル、スキーマ正規化には共有アダプターを使用します。Make アダプターの URL と appKey は、ルートごとのドメインや UI 入力ではなく、正規化されたランタイム設定から構築します。
8. デフォルトの単一アプリ権限プロキシは make-app-permission を介して実装し、/api/make/app/principal/permission も含めます。生成またはリファクタリングする Make App から省略しないでください。
9. 権限に応じて絞り込まれた Schema コレクションは個別に維持します。fields と createFields は別々に正規化します。createFields が存在しない場合、fields にフォールバックせず、空の作成コレクションとして扱います。editableFields を含む不明なレスポンスプロパティは維持しますが、その権限上の意味は make-app-permission に委ねます。
10. Schema をキャッシュする場合は、権限に応じて絞り込まれた結果をテナント、プリンシパル／セッション、App、アクセス世代ごとに分離し、権限更新のための明示的な無効化手段を設けます。
11. Make レコードのアクションでは、編集 UI の実装前に文書化された record-write-permission ルートを、バッチ編集用に records/bulk ルートを実装します。対象、権限、単一リクエストのセマンティクス、および確立済みの完全な UI-Service レスポンス契約には make-app-actions を使用します。成功時、HTTP200 の一部拒否時、全件選択時の403レスポンスの各形式を維持します。それ以外の完了した HTTP エラーでは、ステータス、Content-Type、本文を維持し、reason、permissionKey、管理者の連絡先もそのまま保持します。汎用的な code／message のラッパーに置き換えないでください。
12. キャンセルまたは置き換えが可能なリクエストでは、Service の境界から下流のすべてのアダプターへ、リクエストスコープの AbortSignal を伝播させます。実装前に references/service-api-contracts.md をお読みください。
13. Make App Service の変更が Make AI 助手、AI助手、AI 对话框、SSE、Agent Gateway、または @qfei-design/make-ai-assistant に関するものである場合は、まず Make App AI Chat プロトコルに make-ai-assistant を使用します。その後、Service では文書化されたルートハンドラー、プロキシアダプター、設定検証、ログ記録、キャンセル処理、テストのみを実装します。
14. 変更したすべてのルート、アダプター、検証経路、エラー経路について、Service のテストを追加または更新します。
15. 以下のマップから、必要な参照ファイルのみを読みます。

トピックの参照先マップ

タスク／トピック	参照先
サービスのルート形式と UI-Service のレスポンス契約	references/service-api-contracts.md
リクエストのキャンセル、クライアント切断の処理、下流への AbortSignal の伝播	references/service-api-contracts.md
スキーマキャッシュの更新、進行中のリクエストの再利用、キャンセルを組み合わせるシナリオ	references/service-api-contracts.md、references/testing-and-safety.md
サービスのフォルダー構成、レイヤー構造、ロギング、エラー	references/service-layering.md
Make Data API アダプターのルール、スキーマの fields／createFields、レコード、ファイル、ルックアップ、候補	references/make-data-adapter.md
テスト要件、契約チェック、安全性レビュー	references/testing-and-safety.md
単一アプリの権限プロキシ、Make IAM プリンシパルの権限、アプリスコープの権限ペイロード	make-app-permission を使用
認証プロキシ、Cookie、統合ログイン、401／403 の動作	make-app-auth を使用
サービスのビルド出力、ポート 3000、dist/server.js、パッケージスクリプト、公開準備	make-app-runtime を使用
UI レイアウト、フォーム、詳細表示、視覚的な状態	makeui を使用
CanvasTable での Make フィールド／テーブルのレンダリング	canvas-table-integration を使用
レコードの並べ替え、並べ替え可能な機能、Preset の並べ替え、レコードの並べ替え	make-app-sort を使用
高度なフィルターパッケージの動作と Preset フィルター	make-app-filter を使用
レコードのグループ化、グループ化可能な機能、Preset のグループ化、record-groups、groupFilter	make-app-group を使用
レコードアクションの事前チェック、厳密な選択対象、単一リクエストでの一括更新	make-app-actions を使用
Make App AI アシスタント、AI アシスタント、AI ダイアログ、SSE、Agent Gateway、アシスタント機能、インターフェースドメイン設定	確認済みの /api/make/app/ai/v1/** 18 操作プロトコルには make-ai-assistant を使用します。サービスがルート、検証、ログ、キャンセル、ランタイム設定の読み込みを担います

スコープの境界

• make-app-service は、スキーマ、レコード、候補、ルックアップオプション、ファイルプロキシ、薄いカスタムオーケストレーションなど、Service が所有するアプリ API を定義します。
• 新しい Make App Service はすべて、デフォルトのリクエスト Trace ID に make-app-observability を使用します。境界で検証または作成し、X-Log-Id を返し、安全なコンテキストをログに引き継ぎ、検証済みのトレースヘッダーのみを Make Gateway に転送します。この Skill はルートとアダプターの実装を担当し、make-app-observability は境界をまたぐ不変条件と監査を担当します。
• ルート名、クエリ／本文の形式、レスポンスのエンベロープ、アダプターの動作を記載できます。
• Service のソースで使う MAKE_APP_KEY や MAKE_API_BASE_URL などの環境変数名と、Service 側の Make アダプター設定のセマンティクスを定義できます。ただし、デプロイ時の注入はランタイム／運用に委ねます。
• 認証の実装や OAuth／セッションの仕組みを決定してはなりません。これらは make-app-auth の担当です。ただし、ホストの契約で必要とされる App Service 認証プロキシのパスはマウントして記載できます。通常、gatewayBaseUrl: "/api/make" を使用する Make Deploy の Service 前面型 Apps では、/api/make/auth/** と /api/make/oauth/** を使用します。
• 単一アプリの権限ロジック、IAM 権限の照合、ルートガード、操作ボタン、フィールドの編集可否を定義してはなりません。これらは make-app-permission の担当です。権限プロキシに必要な Service のレイヤリング、ログ、テスト、ドキュメントは引き続き提供してください。
• ビルド出力、Service のポート、Docker／K8s のエントリーポイント、パッケージスクリプト、ワークスペースマニフェスト、公開準備の可否を決定してはなりません。これらは make-app-runtime の担当です。
• ビジネスモデル、エンティティ、フィールドの意味、リレーション、DSL YAML を定義してはなりません。これらは makedsl の担当です。
• UI レイアウト、コンポーネントの選択、Drawer のレイアウト、CanvasTable のレンダリングを決定してはなりません。これらは makeui と canvas-table-integration の担当です。
• Make AI アシスタントの SSE イベントのセマンティクスや機能ネゴシエーションを定義してはなりません。これらは make-ai-assistant の担当です。現在の Make App AI アダプターは Artifact ペイロードを伝送しません。
• 環境からドメインへのマッピングをハードコードしてはなりません。Make API のベース URL、ゲートウェイルーティング、シークレットの注入は、ランタイム設定、バックエンド／運用、または Make ツールから提供されます。

Service のデフォルトの責務

承認による新規作成、bpmDefinitionKey、起動フィールド、初回の申請、プロセス状態の伝送には、make-app-approval を使用します。Service はオブジェクトのトップレベルキーと、レコードのシステム状態／ロックフィールドを保持します。承認による新規作成で書き込み可能なフィールドは、権威ある起動設定に基づきます。通常の新規作成では従来の createFields／IAM 契約を引き続き使用し、既存レコードの編集では従来の更新経路を引き続き使用します。通常のソースフィールドの共通部分によって承認済みのフィールドが再度削られることがないようにし、クライアントが宣言した承認モードを信頼しないでください。

生成またはリファクタリングされた Make App Service コードは、UI が必要とし、ホストプロジェクトに同等のルートがすでにない場合、次の機能を提供します。

• パブリックなヘルスチェック／設定：公開済み UI からアクセスするための /api/health、/api/config。ローカル環境または k8s プローブとの互換性のために /health が存在してもかまいません。
• ランタイムスキーマ：/api/schema、/api/entities/:entityKey/fields
• デフォルトの単一アプリ権限：make-app-permission 経由の /api/make/app/principal/permission
• Make App AI アシスタントのルートは、ホストから要求され、make-ai-assistant で指定されている場合に限ります。機能、ページネーション対応 Agents、複数セッションのチャット、フィードバック、メッセージ／履歴、レスポンスイベント／スナップショット／キャンセル、アップロード／パーツ／完了、コンテンツのバイトデータを扱う、厳密に指定された /api/make/app/ai/v1/** の 18 オペレーションの許可リストを公開します。汎用プロキシは使用しないでください。
• レコード：一覧取得、取得、新規作成、更新、削除、セル更新
• レコードアクション（一覧が書き込み可能な場合）：行書き込み権限の事前チェックと、1 リクエストでのフィールド一括更新を make-app-actions 経由で行います。
• 現在のユーザーの Entity Preset：取得、およびフィルターまたはソートが有効な場合のスパースなフィルター／ソート更新
• ルックアップオプションと安全なルックアップリレーションの更新
• ユーザー候補と部門候補
• ファイルのアップロード／削除／ダウンロードプロキシ
• 要求に応じた薄いカスタムオーケストレーション。たとえば、OCR 結果の作成などです。

ルートハンドラーは小さく保ってください。Make／バックエンドの呼び出しはアダプターモジュールに、ルートをまたぐビジネスオーケストレーションは services/ に、純粋なスキーマ／値ヘルパーは utils/ に配置してください。

Hard rules

• apps/docs/api.md は UI-Service 契約の正本です。更新せずに Service のルート動作を変更しないでください。
• gatewayBaseUrl: "/api/make" を使用する Make Deploy Service-fronted Apps では、apps/docs/api.md に /api/make/** 配下の公開ブラウザーパスを記載する必要があります。例：/api/make/auth/**、/api/make/oauth/**、/api/make/app/**。deploy HTTPRoute が公開していない限り、プレフィックスのない /app/** を公開パスとして記載しないでください。古い /api プロジェクトでは、明示的なレガシー契約としてのみ /api/auth/** と /api/app/** を維持できます。
• 新しく生成する Make POC Service と、重要な変更を伴う生成・リファクタリング後の apps/service コードでは、フラットなルート／アダプタ／ヘルパーファイルではなく、レイヤー化されたコンポーネント構成のソース構造を使用する必要があります。新しい Make POC Service では、プラットフォームツリーをデフォルトとします：app.ts、server.ts、config.ts、logger.ts、Make／バックエンドアダプタ用の make-client/、複数ステップのオーケストレーション用の services/、純粋なヘルパー用の utils/、および各ファイルに隣接するテスト。
• ルート登録、Make リクエストの構築、スキーマの正規化、レコード検索／ファイルのオーケストレーション、設定の解析、ログ記録、ヘルパーが並列して混在するフラットな apps/service/src ツリーは、生成 POC 作業における準備不足です。Service の完了を報告する前に分割してください。
• app.ts または routes/ のルートハンドラーは、入力を検証し、サービス／アダプタを呼び出し、Service が所有する事前チェックエラーをマッピングし、安全な境界コンテキストをログに記録して、文書化されたレスポンスを返すだけにしてください。通常の Make 直接プロキシでは、2xx、4xx、5xx のいずれでも、処理済みの HTTP ステータス、Content-Type、本文をそのまま維持します。選択された Make AI assistant アダプタは、明示された安全なエラー契約に従います。Make ペイロードの直接構築、スキーマバリアントの解析、レコード検索のオーケストレーション、ファイルプロキシのマッピング、カスタムワークフローの手順をルートハンドラーに入れないでください。
• UI 向けの集約ルートが、文書化された正規化済み成功形状を使用できるのは、apps/docs/api.md で非プロキシとして明示されている場合だけです。references/service-api-contracts.md のデフォルトのルートレスポンスモード表を起点とし、ホスト固有の例外とその移行を文書化してください。通常の処理済み Make エラーは変更せずに維持します。選択された Make AI assistant のエラー契約は、別途文書化された例外です。
• Service のルートハンドラーは、Make アダプタを呼び出す前にクエリ／本文／パスパラメーターを検証し、クライアント入力が無効な場合は 400 を返します。
• Service アダプタは、appKey、X-Make-Target、Make レスポンスコードのチェック、ページネーションの変換、ファイル本文のマッピング、準備済みのログイン／セッション転送コンテキストの利用など、Make リクエストの詳細を担います。認証／セッションの仕組みと共有転送ヘルパーは make-app-auth に属します。公開ランタイムのプロキシヘッダー契約は make-app-runtime に属します。
• 成功レスポンスはエンドポイント契約に従って解析してください。既存の auth current-context の利用箇所は make-app-auth/references/service-fronted-mode.md#current-context-consumption に従います。Meta/Data エンベロープパーサーを再利用しないでください。
• Make のレコード読み取り API は、Service の Make アダプタを通じて Make gateway Data API を呼び出す必要があります。公開ランタイムでは k8s 内部の /make/data/v1/record を使用します。MAKE_APP_LOCAL_PREVIEW=true のローカルプレビューでは、makecli configure resolve --target local-preview --output=json の make_api_origin と /api/make/data/v1/record を使用します。これは、レコード一覧、レコード詳細、検索対象レコードの読み取り、および Make レコードを読み取るカスタム Service ルートに適用されます。
• Service の Make アダプタは、Make によるデータの読み書きに際して、受信リクエストで確立済みのログインコンテキストを Make gateway に転送する必要があります。最低限、ホストが Cookie／統合ログイン認証を使用する場合は、ブラウザーの Cookie セッションヘッダーを維持してください。既存のホスト契約がベアラー認証を使用する場合に限り、既存の Authorization ヘッダーを維持してください。また、共有 auth/runtime ヘルパーを通じて、X-Forwarded-Host や X-Forwarded-Proto などのホスト gateway コンテキストヘッダーを適用してください。ここで認証ポリシーを独自に定めないでください。認証の仕組みには make-app-auth を使用しますが、gateway 呼び出し前にログインコンテキストを落とさないでください。
• 公開／ランタイムの Service API は、データソースとして makecli を決して使用してはいけません。公開 Apps でスキーマ、レコード、候補、検索オプション、ファイル、またはカスタム API データを提供するために、makecli、npx makecli、ローカルの makecli 設定、makecli の JSON 標準出力をシェルから呼び出さないでください。オンラインの Service コンテナには makecli がないため、ランタイムデータは Make gateway／API アダプタから取得する必要があります。
• Make 対応 Service の設定では、デプロイ時に注入される MAKE_APP_KEY から、正とする appKey を読み取る必要があります。生成される本番コードでは、このスコープを独自に設定したり、ハードコードしたり、UI 入力で上書きしたりしてはいけません。文書化されたプロトコルルートでクエリまたは本文に appKey を含められるのは、アダプタ呼び出し前に Service が MAKE_APP_KEY との完全一致を検証する場合に限ります。
• Make Meta/Data API を呼び出す Service で MAKE_APP_KEY が欠落している場合、Service の準備完了を報告する前に、設定の読み込みを明確で機密情報を含まないエラーで失敗させる必要があります。ローカルテスト用フィクスチャでは、MAKE_APP_KEY を明示的に注入できます。
• 新しく生成する Service コードでは、apps/service/src/config.ts またはホスト側の同等箇所から Make アダプタのランタイム設定を読み取ります。公開 gateway のオリジンを表す環境変数には MAKE_API_BASE_URL を優先します。MAKE_SERVER_URL は互換性のためのエイリアスに限ります。ローカルプレビューではデプロイ環境変数ではなく、makecli configure resolve --target local-preview --output=json から公開 gateway オリジンを導出します。
• Make 対応 Service で MAKE_API_BASE_URL と MAKE_SERVER_URL のどちらも設定されていない場合、Service の準備完了を報告する前に、設定の読み込みを明確で機密情報を含まないエラーで失敗させる必要があります。
• 公開される MAKE_API_BASE_URL／MAKE_SERVER_URL の値は、http://make-gateway.make-dev のような厳密な k8s gateway オリジンです。新しく生成する Service コードでは、この環境変数に /make、/api/make、/meta、/data、/auth、その他のサービスパススコープを含めてはいけません。ローカルプレビューの resolve 出力は make_api_origin として使用してください。古い makecli のフォールバックがパススコープ付きの公開 /api/make API ベースを返す、または読み取る場合は、ローカルプレビューアダプタ内だけで正規化してください。
• Make プラットフォームアダプタがサービスパススコープを管理します。生成される Service コードは、明示的なランタイムモードに基づいて上流 URL を導出します。ローカルプレビューでは公開 gateway オリジンに /api/make/** を付加します。公開環境では k8s gateway オリジンに /make/** を付加します。例：http://make-gateway.make-dev/make/meta/**、http://make-gateway.make-dev/make/data/**。
• Make App AI assistant アダプタには make-ai-assistant を使用してください。ブラウザーは同一オリジン経由で固定の /api/make/app/ai/v1/** 18 操作ファミリーを呼び出します。ローカルプレビューの Service 上流 URL は make_api_origin に /api/make/app/ai/v1/** を付加します。公開環境の Service 上流 URL は、MAKE_API_BASE_URL または互換エイリアスの MAKE_SERVER_URL に設定された厳密なオリジンに /make/app/ai/v1/** を付加します。Service はデプロイ済みスコープを MAKE_APP_KEY から読み取り、これと異なるすべてのクエリ／本文の appKey を拒否する必要があります。GET／HEAD 以外のすべてのリクエストでは、選択された Host に対して検証済みの、同一オリジンの HTTP(S) Origin が 1 つ必要です。assistant 専用／AI Gateway／Agent Gateway のオリジン、トークン、環境変数、ハードコードされたドメインを追加しないでください。単独の JSON オブジェクト、空の 204 レスポンス、Make-AI-Api-Version、SSE、バイト列を、それぞれ別の成功モードとして維持してください。また、ホスト側バリデーターで有効なプロトコル DTO を過度に制限しないでください。AI エラーでは、拡張可能な未知のコードを含め、スキーマに適合する範囲内の {code,message,requestId?,details?} を HTTP ステータスとともに維持します。不正な形式の上流エラーまたは非公開の上流エラーは、生の診断情報を漏らさない安全な Service エラーに変換します。有効な公開型エラーを 502 に再マッピングしてはいけません。
• 同じ Service が他の gateway サービスも呼び出す場合、それらのアダプタは同じ gateway オリジンから、各サービス固有のスコープを明示的に定義します。MAKE_API_BASE_URL から /make を削除したり、パススコープ付きのベース URL を無関係なサービスへのアクセスに流用したりしないでください。
• クラスター内の Service から gateway への呼び出しでは、ブラウザー向けの /api/make プレフィックスを使用してはいけません。/api/make/** は、同一オリジンのブラウザーアクセス、Service ingress、ローカルプレビューの公開 gateway 呼び出し用です。公開環境で Service が使用する内部上流 URL は、gateway オリジンに /make を付加します。
• Service ソースでは、具体的な Make の dev／test／prod ドメインをハードコードしたり、namespace 内の gateway アドレスを推測したり、デプロイ環境をドメインに対応付けたりしてはいけません。
• ランタイムの Service コードは、公開 Apps で起動したりスキーマ／データを提供したりするために apps/dsl/**、/dsl/**、またはコピーされた *.yaml ファイルを必要としてはいけません。
• スキーマ API は、UI に渡す前にバックエンドのスキーマバリアントを正規化します。entity.properties.fields、entity.fields、またはホストで文書化された同等の形式など、既知のバリアントを Service／API 境界で処理し、並べ替えとグループ化のためにフィールドの capabilities.sortable／capabilities.groupable を維持してください。
• 権限でトリミングされたスキーマを正規化する際は、fields と createFields を別個のコレクションとして維持します。各コレクションを個別に正規化してください。欠落または無効な createFields は [] とし、fields にフォールバックしてはいけません。ホスト契約で損失のない転送が必要な場合は、レスポンスメタデータとして editableFields を維持してください。ただし、現在の編集動作を導出するために使用してはいけません。
• スキーマのキャッシュおよび処理中リクエストの再利用では、権限でトリミングされたエンティティを異なるプリンシパル間で共有してはいけません。テナント、プリンシパル／セッション ID、App、アクセス世代をキーにするか、リクエスト単位のキャッシュを使用してください。また、権限の更新後にデータを更新する前に呼び出せる、無効化／再読み込みの経路を用意してください。
• レコード一覧と詳細は別々の契約です。単一レコード用の Make 呼び出しがある場合に、一覧を呼び出して先頭行を推測することで詳細を実装してはいけません。
• Entity Preset の GET／PATCH ルートでは、Make Preset /preset/v1/entity アダプタと MakeService.GetResource／MakeService.UpdateResource を使用し、確立済みのログインコンテキストを維持して、送信されたディメンションだけを更新してください。ディメンションのセマンティクスには make-app-sort、make-app-filter、make-app-group を使用してください。
• Preset の並べ替えとレコードの並べ替えでは、形状の検証を共通化し、現在のランタイムスキーマの capabilities.sortable === true に照らしてフィールドを正とする形で検証する必要があります。Make を呼び出す前に、無効なルール、重複ルール、並べ替え不可のルール、5 件を超えるルールを拒否してください。
• Preset の部分更新では、兄弟ディメンションを維持する必要があります。並べ替えの保存時にフィルター／グループを送信せず、フィルターの保存時に並べ替え／グループを送信せず、グループの保存時にフィルター／並べ替えを送信しないでください。
• ユーザーと部門の候補は、GET /api/users や GET /api/departments などの Service ルート、またはホスト側の同等ルートから取得します。生成される Service でローカルのデモ配列を使用してはいけません。
• 検索オプション API はスキーマメタデータから対象オブジェクト／フィールドを解決し、{ options, total } を返す必要があります。デフォルトでは、セレクター UI に対象レコード全体を公開しないでください。
• ファイルルートでは、Service 経由でアップロード／削除／ダウンロードをプロキシします。Service のダウンロードプロキシが利用できる場合、UI でバックエンドの生のファイル URL を公開してはいけません。
• <img src> などのブラウザーリソースタグには Authorization を付加できません。Make のファイルダウンロードにベアラートークンが必要な場合は、URL を Service のダウンロードプロキシ経由でブラウザーに公開し、まず現在の App セッションを検証して、デプロイ時に注入されたトークンを Service アダプタだけが付加するようにしてください。Make トークンや生の /data/v1/download/** URL を、UI 状態、公開設定、JSX、ログに含めないでください。
• ルート／アダプタの入口、成功、失敗時に境界ログを追加してください。トークン、Cookie、Authorization、API キー、署名付きダウンロードのクエリ文字列、不要な個人データはマスキングしてください。
• キャンセル可能または置き換え可能な処理では、クライアントの切断時に、リクエストスコープの AbortSignal を通じて下流処理を中断する必要があります。古いレスポンスを無視するだけで終わらせないでください。また、想定内の AbortError をユーザーに表示する 5xx エラーとして扱わないでください。
• ルート契約、無効な入力、アダプタのペイロード、Make レスポンスのステータス／本文を直接引き継ぐ動作、およびこのスキルで追加するスキーマ／値の正規化には、テストが必要です。
• make-app-permission によるデフォルトのプリンシパル権限プロキシと必須テストがない状態で、生成またはリファクタリングされた Make App Service の完了を報告してはいけません。
• record-write-permission と records/bulk では make-app-actions に従ってください。 Make /data/v1/permission の呼び出しを 1 回行って、対象全体を事前チェックします。明示的選択に対する HTTP 200／業務コード 20000032 の拒否と、その noPermissionRecordIds は、JavaScript の Number による型強制および一般的な Make エラーのマッピングより前に、生のレスポンスから損失なく解析します。全件選択の 403 拒否では ID を含めません。対象を再利用して Make /data/v1/field を 1 回呼び出し、診断情報を分割したり、単一レコード更新をループしたりしてはいけません。

デフォルトルートの基本方針

ホストプロジェクトに同等のルートがすでに記載されている場合を除き、新しい Make App Service プロジェクトでは、以下の UI-Service コントラクトを優先してください。

GET    /api/health
GET    /health
GET    /api/config
GET    /api/make/app/principal/permission
GET    /api/schema
GET    /api/entities/:entityKey/fields
GET    /api/entities/:entityKey/preset
PATCH  /api/entities/:entityKey/preset
GET    /api/entities/:entityKey/records
GET    /api/entities/:entityKey/records/:recordID
POST   /api/entities/:entityKey/records
POST   /api/make/app/entities/:objectKey/record-write-permission
POST   /api/make/app/entities/:objectKey/records/bulk
PATCH  /api/entities/:entityKey/records/:recordID
DELETE /api/entities/:entityKey/records/:recordID
PATCH  /api/entities/:entityKey/records/:recordID/cells/:fieldKey
GET    /api/users
GET    /api/departments
GET    /api/lookup-options
POST   /api/entities/:entityKey/records/:recordID/files/:fieldKey
DELETE /api/entities/:entityKey/records/:recordID/files/:fieldKey
GET    /api/files/download/*

Lookup relation の更新ルートは任意です。UI で編集可能な Lookup relationship が必要で、Service が完全な qfei_relation スナップショットを安全に保持できる場合にのみ生成してください。

連携ルール

• makeui との連携：このスキルは Service コントラクトと正規化された API 形式を提供し、UI での表示方法は makeui が決定します。
• make-app-permission との連携：このスキルは Service レイヤリングとテストを提供し、プリンシパルの権限ルート、IAM の上流パス、App スコープのペイロード、フロントエンドの権限コントラクトは make-app-permission が担当します。
• canvas-table-integration との連携：このスキルはスキーマ／レコード／候補 API を提供し、Service 側の切断から下流へのキャンセルを担当します。テーブルの表示、編集 UI、ブラウザー側の仮想ページのスケジューリングは canvas スキルが担当します。
• make-app-sort との連携：このスキルは Preset／records ルートと Make アダプターを実装・テストし、並べ替え可能なルール、ドラフト／保存のタイミング、ヘッダーとの連携は make-app-sort が担当します。
• make-app-filter との連携：このスキルは Preset／records ルートと Make アダプターを実装・テストし、パッケージのフィルター動作、水和、保存のタイミングは make-app-filter が担当します。
• make-app-group との連携：このスキルは Preset group、record-groups、records groupFilter、Make アダプターを実装・テストし、グループ化可能なルール、groupFilter の合成、グループ化データのタイミング、CanvasTable のグループ化フローの調整は make-app-group が担当します。
• make-app-actions との連携：このスキルは record-write-permission、records/bulk、厳密なターゲット解析、Make アダプター、エラーマッピングを実装・テストし、選択の意図、アクションのタイミング、権限キーの選択、固定スナップショット、UI フィードバックは make-app-actions が担当します。
• make-ai-assistant との連携：このスキルは Make App AI ルートハンドラー、プロキシアダプター、ランタイム設定の検証、安全なログ、AbortSignal の伝播、Service テストを実装し、パッケージ統合、v1 の 18 操作に関する DTO／レスポンス／ストリームのセマンティクス、複数セッションの動作、インターフェースドメインのルールは make-ai-assistant が担当します。
• make-app-auth との連携：このスキルは Service を経由するアプリルートの形式を維持できますが、認証プロキシとセッションの動作は auth の担当です。
• make-app-runtime との連携：このスキルは Service のソースとテストを作成し、ランタイムのビルド／起動／ポートの確認は runtime の担当です。