taruvi-app-developer

Taruvi アプリ開発者（バックエンド）

Taruvi 向けの単一バックエンドスキルです。次の 2 つのレイヤーを扱います。

• コントロールプレーン（MCP） — データテーブル、ポリシー、ロール、バケット、シークレット、関数メタデータ、分析クエリ、監査対象の生 SQL をプロビジョニングします。
• データプレーン（関数ランタイム） — 認証済みの sdk_client を使用して Celery ワーカー上で実行される、シグネチャが def main(params, user_data, sdk_client) の Python 本文です。

フロントエンドで React／Refine のプロバイダーやフックを接続するタスクの場合は、taruvi-refine-providers に切り替えてください。

判断：関数を使うか、MCP のプロビジョニングだけでよいか？

次の作業はプロビジョニングだけで十分です。スキーマの変更、ポリシー／ロール／ユーザーの管理、バケットの作成、シークレットの管理、分析クエリの登録、単発の管理者 SQL。

次のいずれかを含むタスクでは、関数本文が必要です。

• 実行時に 2 つ以上のリソースを扱う（DB とストレージ、ユーザーと DB など）
• イベントトリガー（RECORD_CREATE、RECORD_UPDATE、RECORD_DELETE、POST_USER_CREATE、…）
• スケジュール／cron
• 保存済みのシークレットを使用した外部 API 呼び出し
• 長時間実行される処理（30 秒超 → async_mode=True）
• 公開された未認証エンドポイント（is_public=True）
• 通常の Cerbos リソースポリシーを超える認可ゲート
• 関数間のパイプライン

判断に迷った場合は、when-not-to-use-functions.md を参照してください。

ワークフロー

1. ランタイムの分離については architecture-overview.md を一度読みます。新規アプリの場合は、agents-md-template.md を使って AGENTS.md も作成します。
2. 関数とプロビジョニングのどちらを使うか判断します（上記を参照）。関数コードを書く前に、function-authoring.md と function-sdk-reference.md の該当箇所を読みます。
3. MCP の作業では、mcp-tool-quickref.md と、以下のタスク固有のリファレンスを開きます。
4. 破壊的操作では、破壊的操作の手順（以下）に従います。
5. リソースを再度読み込み（get_datatable_schema、manage_policies(action="get") など）、関数／分析クエリをエンドツーエンドで実行して検証してから、完了を報告します。

リファレンス一覧

タスク	読むもの
MCP ツールのシグネチャ	mcp-tool-quickref.md
フリクションレスなスキーマ（外部キー、インデックス、階層、グラフ）	datatable-schema-patterns.md
Cerbos ポリシーの作成	cerbos-policy-cookbook.md — または get_ai_docs(category="policies", topic="guide")
シークレットとカスタムシークレットタイプ	secrets-and-types.md
監査対象の生 SQL	raw-sql-safety.md
分析クエリ（登録と Jinja2 パラメーター）	analytics-queries.md
フィルター演算子／クエリ機能	backend-capabilities.md
関数ランタイムの契約、モード、トリガー	function-authoring.md
sdk_client のモジュールとメソッド	function-sdk-reference.md
イベントトリガー、CEL フィルター	function-events.md
関数の実例（8 つのシナリオ）	function-scenarios.md
レイヤー横断の機能実例	feature-workflow-examples.md
統合時の注意点	integration-pitfalls.md
フロントエンド Worker のデプロイ	frontend-worker-deploy.md
バックエンド設定のエクスポート	backend-export.md
環境変数の設定	env-setup.md

絶対に守るべき事項

これらのほとんどは参照資料にも組み込まれていますが、守らないと実際のバグにつながるため、ここに記載しています。

1. 記憶ではなく、MCP ツールを信頼してください。 ツールの応答には、次の操作に必要な ID、スラッグ、ステータスが含まれています。エンドポイントやメソッド名を推測で作らないでください。
2. create_update_schema は、ペイロードに含まれていないフィールドを削除します。 必ず最初に get_datatable_schema を実行し、保持するフィールドをすべて含めて送信してください。
3. manage_policies(action="create_update") は既存のポリシーを置き換えます。マージはしません。 まず既存のポリシーを取得して変更し、本文全体を送り返してください。
4. 関数シグネチャは def main(params, user_data, sdk_client): でなければなりません。 これと異なる場合、直ちに SandboxError が発生します。
5. sdk_client を再認証しないでください。 事前に認証済みです。client.auth()、client.login() を呼び出したり、API キーを渡したりしないでください。
6. シークレットをハードコードしないでください。 sdk_client.secrets.get("KEY") を使用してください。
7. 関数からは JSON にシリアライズ可能な値を返してください。 datetime、set、Decimal、カスタムクラスを返すとエラーになるため、事前に変換してください。
8. 30 秒を超えるタスクには is_async=True が必要です。 同期呼び出しは 30 秒でタイムアウトし、UI のスピナーが止まったままになります。
9. print() ではなく log() を使用してください。 print() は構造化されていない標準出力であり、クエリできません。
10. フロントエンドで複数リソースにまたがる連鎖処理を行うのはバグの原因です。 関数に移してください。処理の途中でブラウザーが遷移すると、DB の整合性が失われます。

破壊的操作の手順

対象：delete_datatable（特に force=True の場合）、既存ポリシーに対する manage_policies(action="create_update")、user_attributes_schema(action="update")、manage_secret_types(action="delete")、manage_function(action="delete")、manage_roles(action="delete")、および DROP、TRUNCATE、破壊的な ALTER、または WHERE を伴わない DELETE を含む execute_raw_sql。

1. 計画 — 現在の状態を確認し（get_datatable_schema、manage_policies(action="get") など）、何が削除または置換され、それに何が依存しているかを明示します。
2. 検証 — 影響範囲を平易な言葉で示します（「これにより orders と、invoices 内の依存する外部キー 3 件が削除されます」）。ユーザーから明示的な確認を得てください。
3. 実行 — 確認を得てから実行します。ツールの応答をそのまま報告してください。

テストユーザー — 必ず作成

プロビジョニング後、アプリが動作することをユーザーが確認できるよう、テストユーザーを作成してください。

• アクセス制御あり： ロールごとにテストユーザーを 1 人作成し、qa_<role_slug>_<YYYYMMDD> の形式で名前を付けます（例：qa_warehouse_staff_20260422）。大文字、小文字、数字、記号を組み合わせた 12 文字以上の強力なパスワードを設定します。すべてのユーザー名とパスワードをユーザーに報告してください。
• アクセス制御なし： デフォルトのスーパー管理者テストユーザーを 1 人作成し、パスワードを報告してください。
• クリーンアップ方法を案内： 検証後に qa_* ユーザーを無効化または削除するか、パスワードを変更してください。

実行して検証 — 必ず行う

関数または分析クエリが完了したと報告する前に、次のことを行ってください。

1. execute_function(function_slug=..., params={...}) または execute_query(query_slug=..., params={...}) を、現実的なサンプルパラメーターで実行します。
2. 実際の応答形式を確認します。
3. フロントエンドのコードが、返されたフィールド名と構造を正確に使用していることを確認します。一致しない場合はフロントエンドを修正してください。

バージョンの差異チェック

node scripts/check-versions.js は、固定された SDK／プロバイダーのバージョンと PyPI／npm の最新バージョンに差異がある場合に警告します。