docs(i18n): re-sync reference/security and restore three audit pages after #460 (#461)

content/docs/build/interface/actions.ja.mdx

@@ -0,0 +1,208 @@
+---
+title: アクション
+seoTitle: "アクション：REST エンドポイント、ボタン、AI ツール"
+description: プラットフォームが 1 つの宣言から REST エンドポイント、ボタン、AI ツールとして公開する、名前付きの操作。
+editions: [community, cloud, enterprise]
+translation:
+  source_sha: 73eec6615157785e3ccf58c23a1ce2aa1a34a601ec3398faa639318fe20e584d
+  guide_rev: 1
+  mode: auto
+---
+
+**アクション**は、オブジェクトに対する名前付きの操作です。一度宣言すると、次のものとして現れます。
+
+- `/api/v1/actions/<object>/<action>` の **REST エンドポイント**
+- レコード詳細ページの**ボタン**
+- エージェントと AI Builder 向けの **AI ツール**（`action_<name>`）。AI に公開したとき（`ai.exposed`、[下記](#from-an-ai-agent)）に限ります
+
+3 つの画面で同じことを繰り返す必要はありません。1 つの宣言で、3 通りの呼び出し方ができます。作業が 1 ステップで終わらないときは、アクションから[フロー](/docs/build/automation/flows)を開始することもできます（`type: 'flow'`）。
+
+## アクションを宣言する [#declare-an-action]
+
+```ts
+// src/actions/approve_invoice.action.ts
+import { Action } from '@objectstack/spec/ui';
+
+export const approveInvoice = Action.create({
+  name: 'approve_invoice',          // lowercase snake_case (machine id)
+  label: 'Approve Invoice',
+  objectName: 'invoice',            // attaches to the invoice object
+  icon: 'check',
+  variant: 'primary',
+  locations: ['record_header'],     // where the button shows
+  description: 'Approve this invoice?',  // shown in the param dialog
+  successMessage: 'Invoice approved',
+  refreshAfter: true,
+
+  // collect input before running
+  params: [
+    { name: 'note', label: 'Approval note', type: 'textarea' },
+  ],
+
+  // only show the button when the record is still pending
+  visible: 'record.status == "pending"',
+
+  // expose it to agents and the AI Builder as `action_approve_invoice`
+  ai: {
+    exposed: true,
+    description: 'Approve a pending invoice, recording the approver and an optional note.',
+  },
+
+  // what it does — a sandboxed script body. `input` is the params bag;
+  // `ctx.record` is a read-only snapshot, so the write goes through `ctx.api`,
+  // which needs the `api.write` capability
+  type: 'script',
+  body: {
+    language: 'js',
+    capabilities: ['api.write'],
+    source: `
+      await ctx.api.object('invoice').update({
+        id: ctx.recordId,
+        status: 'approved',
+        approved_by: ctx.user.id,
+        approved_at: new Date().toISOString(),
+        approval_note: input.note,
+      });
+    `,
+  },
+});
+```
+
+`os dev` が再コンパイルした後：
+
+- `POST /api/v1/actions/invoice/approve_invoice` が動作します
+- 請求書のレコードページに **Approve Invoice** ボタンが表示されます
+- AI アシスタントは、スキルが許可していれば `action_approve_invoice` を呼び出せます。AI に公開されているからです
+
+## アクションの種類 [#action-types]
+
+`type` フィールドが、アクションが何をするかを決めます。
+
+| `type` | 実行されるもの | 用途 |
+|---|---|---|
+| `script` | `body`：L1 の数式、またはサンドボックス化された L2 の JavaScript | ほとんどの場合。サーバー側のロジックで、監査でき、公開すれば AI から呼び出せます |
+| `api` | `target` エンドポイントへの HTTP 呼び出し（`method`、`bodyExtra`） | データ API やプラットフォームのエンドポイントの再利用 |
+| `flow` | `target` で名前を指定したフローを実行します | 多段階のビジネスプロセス |
+| `url` | `target` の URL に移動します | ディープリンク、リダイレクト型のアクション |
+| `modal` | `target` で名前を指定したページ / モーダルを開きます | カスタムのダイアログ |
+| `form` | `target` で名前を指定した FormView を開きます | ガイド付きのデータ入力 |
+
+```ts
+// api type — reuse a data-API endpoint
+Action.create({
+  name: 'archive_order',
+  objectName: 'order',
+  label: 'Archive',
+  locations: ['list_item'],
+  type: 'api',
+  method: 'PATCH',
+  target: '/api/v1/data/order/{id}',
+  bodyExtra: { archived: true },
+});
+```
+
+`script` 以外の種類には `target` が必要です。どの種類でも 1 つの宣言ですが、`url`、`modal`、`form` のアクションは UI でしか実行されないので、AI ツールになることはありません。
+
+## アクションを呼び出す [#calling-an-action]
+
+### REST [#rest]
+
+```bash
+# the record id can go in the body, or in the path
+curl -X POST https://app.example.com/api/v1/actions/invoice/approve_invoice/inv_123 \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"note": "LGTM"}'
+```
+
+パラメータはリクエスト本文にフラットに入れて送ります。レコード ID は、末尾のパスセグメント（`.../approve_invoice/:recordId`）としても本文の中でも指定できます。レスポンスは、スクリプト本体の戻り値です（`api` の種類のアクションでは呼び出しの結果）。
+
+### UI から [#from-the-ui]
+
+ボタンをどこに表示するかはアクション自身で宣言します。`locations`（`record_header`、`record_more`、`list_item`、`list_toolbar` など）と `order` です。その後、`visible` の述語がレコードごとにレンダリングするかどうかを決めます。リストビューでも、各行と行の選択に対するアクションを名前で指定できます。
+
+```ts
+// One list view; the container and `data` are omitted (see Views).
+{
+  type: 'grid',
+  columns: ['number', 'customer', 'amount', 'status'],
+  rowActions: ['approve_invoice', 'reject_invoice'],
+  bulkActions: ['send_to_customer'],
+}
+```
+
+### フローとともに [#with-a-flow]
+
+アクションを呼び出すフローのノードはありません。逆向きにしてください。多段階のロジックをフローに置き、`type: 'flow'` と、`target` にフローの名前を指定したアクションからそれを開始します。
+
+```ts
+// flow type — start a flow by name
+Action.create({
+  name: 'run_invoice_approval',
+  objectName: 'invoice',
+  label: 'Run approval',
+  locations: ['record_more'],
+  type: 'flow',
+  target: 'approve_invoice',
+});
+```
+
+### AI エージェントから [#from-an-ai-agent]
+
+アクションがエージェントに届くのは、作成者が AI に公開したときだけです。上の例のように、UI なしで実行される種類（`script`、`flow`、`api`）で、`ai: { exposed: true }` と 40 文字以上の `ai.description` を指定します。公開されたアクションは、ObjectOS 自身のエージェントと AI Builder では `action_<name>` ツールになり、[MCP クライアント](/docs/configure/mcp)では `run_action` になります。公開されていなければ、エージェントからは見えず、呼び出されても拒否されます。
+
+`approve_invoice` が公開されていて、エージェントが持つスキルに含まれていれば、LLM はそれを呼び出せます。入力は会話から得られ、ユーザーがボタンを押した場合と同じ呼び出し時のチェックが適用されます。
+
+> *「請求書 INV-2042 を、メモ『電話で確認済み』を付けて承認して。」*
+
+## 権限 [#permissions]
+
+誰がアクションを実行できるかは、呼び出されたときに、呼び出し元としてチェックされます。REST からでも、ボタンからでも、エージェントからでも同じです。
+
+1. **`requiredPermissions`**：呼び出し元の[権限セット](/docs/configure/permissions/permission-sets)が持っていなければならない機能です。1 つでも欠けている呼び出し元は `403` を受け取ります。
+2. **対象のレコード**：呼び出し元として読み込まれます。呼び出し元が読めないレコードは、見つからないものとして応答されます。
+3. **AI への公開**：エージェントが届くのは、AI に公開されたアクションだけです。
+4. **UI のゲート**：`visible` と `disabled` の述語（CEL。`record`、`os.user`、パラメータに対して評価されます）が、ボタンをレンダリングするか、グレーアウトするかを制御します。
+
+その後アクションが行うことは、信頼されたアプリのコードです。`script` 本体の読み書きはアプリの権限で実行され、レコードアクセスとフィールドレベルのセキュリティはそれを制限**しません**。`flow` アクションはフローの `runAs` に従います。そのため、機密性のあるものには `requiredPermissions` を宣言し、アクションを書くことはコードレビューに値する行為として扱ってください。
+
+## 組み込みのアクション [#built-in-actions]
+
+すべてのオブジェクトには、これらが無償で用意されます。
+
+| アクション | 働き |
+|---|---|
+| `create` | レコードを挿入します |
+| `update` | レコードを更新します |
+| `delete` | レコードを削除（またはソフト削除）します |
+| `restore` | ソフト削除を取り消します |
+| `clone` | レコードをディープコピーします |
+| `share` | ユーザー、チーム、ポジション、事業単位、または単位とその配下に直接共有します |
+
+これらを再宣言しないでください。オブジェクトの[ライフサイクルと機能のフラグ](/docs/build/data)に従います。
+
+## 監査 [#auditing]
+
+プラットフォームのイベントは、読み取り専用の証跡である `sys_audit_log` に記録されます。次のようなフィールドがあります。
+
+- `user_id`：操作を起こしたユーザー
+- `action`：アクションの名前
+- `object_name` と `record_id`：何に触れたか
+- `old_value` / `new_value`：変更内容
+- `ip_address` / `user_agent`：リクエストの発信元
+- `created_at`：いつ起きたか
+
+*「誰がボタンを押したのか？」* という質問には、まずここを見てください。
+
+## AI Builder でアクションを生成する [#generating-actions-with-the-ai-builder]
+
+> *「`support_ticket` に `escalate_ticket` というアクションを作って。優先度を urgent に設定し、オンコールのエンジニアに割り当てるもの。」*
+
+[AI Builder](/docs/build/ai-builder) はアクションのメタデータを生成し、変更を承認待ちのキューに入れます。承認後、アクションは REST、UI、そして再帰的に AI 自身から呼び出せるようになります。
+
+## 次に進む [#where-to-go-next]
+
+- [フロー](/docs/build/automation/flows)：`type: 'flow'` のアクションが開始する多段階のロジック
+- [エージェント](/docs/build/agents)：アクションを AI ツールとして公開する
+- [API アクセス](/docs/configure/api-access)：外部システムからアクションを呼び出す
+- [権限](/docs/configure/permissions)：誰が何を呼び出せるかをゲートする