@rex0220/kintone-sql-tools 1.12.1 → 1.13.1

package/README.md

@@ -16,9 +16,13 @@ kintone アプリを SQL 風の構文で操作するツールセットです。
   - プラグイン: read-only バッチのみ（最終結果を表示）
 - **`ASSERT`（実行時ゲート。DML 前の件数ガード / CLI ヘルスチェック）**（v1.10.0）
 - サブテーブル仮想テーブル（`APP100$明細`）
-- CLI 拡張 `APP@profile`
-  - 同一 SQL 内で同一 APP の profile 混在を許可
-  - `INSERT/UPDATE/UPSERT` 対応、`DELETE` は未対応
+- CLI 拡張 `APP@profile`
+  - 同一 SQL 内で同一 APP の profile 混在を許可
+  - `INSERT/UPDATE/UPSERT` 対応、`DELETE` は未対応
+- CLI / MCP の論理アプリ参照 `LAPP_<NAME>`
+  - profile ごとの `logicalApps` で、同じ SQL を異なる物理アプリ ID へ安全に解決
+  - `APP100` は常に物理 ID 100 のまま（暗黙変換なし）
+  - `allowPhysicalAppRefs: false` で、その profile の物理 `APPxxx` 直接参照を禁止可能
 - `FROM` 省略 SELECT（例: `SELECT 'xxx' AS a`）
 
 ## インストール
@@ -46,10 +50,11 @@ npm run build:plugin
 
 ## 使い分け（CLI / Plugin）
 
-- CLI を使うケース:
+- CLI を使うケース:
   - DML を含むバッチ実行・SQL ファイル実行（`-f`）
   - CI/CD 連携
-  - `APP@profile` を使った環境切替
+  - `APP@profile` を使った環境切替
+  - `LAPP_<NAME>` を使った配置非依存 SQL
   - `--dry-run` / `EXPLAIN` による安全確認
 
 - Plugin を使うケース:
@@ -57,13 +62,14 @@ npm run build:plugin
   - 非エンジニア向けの運用
   - UI で結果確認したい場合
 
-- MCP を使うケース:
+- MCP を使うケース:
   - Claude 等の AI クライアントから kintone を照会・更新
-  - 一時テーブルで中間結果をサーバー内に保持し、AI のコンテキスト消費を抑えたい場合
+  - 一時テーブルで中間結果をサーバー内に保持し、AI のコンテキスト消費を抑えたい場合
+  - validation / EXPLAIN で論理名から最終的な物理アプリ ID への解決を確認したい場合
 
 注意:
 
-- `@profile` は CLI 拡張です。plugin 側では非対応です。
+- `APP@profile` と `LAPP_<NAME>[@profile]` は Node.js runtime（CLI / MCP）の拡張です。plugin 側では非対応です。
 
 ## 最短実行例（CLI）
 
@@ -98,11 +104,39 @@ node dist-cli/ksql.js --console --base-url https://example.cybozu.com --token xx
 - 既定: `./ksql.config.json`
 - profile 切替: `--profile <name>`
 
-例:
+例:
 
 ```bash
-node dist-cli/ksql.js --config ./ksql.config.json --profile dev -e "SELECT * FROM APP100"
-```
+node dist-cli/ksql.js --config ./ksql.config.json --profile dev -e "SELECT * FROM APP100"
+```
+
+論理アプリ参照を使う場合、profile ごとに論理名と物理 ID を定義します。
+
+```json
+{
+  "defaultProfile": "dev",
+  "profiles": {
+    "dev": {
+      "baseUrl": "https://dev.example.cybozu.com",
+      "logicalApps": { "ORDERS": 100 },
+      "tokenMap": { "APP100": "env:DEV_ORDERS_TOKEN" }
+    },
+    "prod": {
+      "baseUrl": "https://prod.example.cybozu.com",
+      "allowPhysicalAppRefs": false,
+      "logicalApps": { "ORDERS": 1200 },
+      "tokenMap": { "APP1200": "env:PROD_ORDERS_TOKEN" }
+    }
+  }
+}
+```
+
+```bash
+node dist-cli/ksql.js --config ./ksql.config.json --profile dev -e "SELECT * FROM LAPP_ORDERS"
+node dist-cli/ksql.js --config ./ksql.config.json --profile prod -e "SELECT * FROM LAPP_ORDERS"
+```
+
+どちらも同じ SQL ですが、前者は `APP100`、後者は `APP1200` に解決されます。`logicalApps` のキーは `LAPP_` を付けない ASCII 論理名です。`APP100`、`100`、`LAPP_ORDERS` は設定キーとして拒否されます。
 
 ## CLI オプション
 
@@ -202,7 +236,7 @@ Options:
 - [CLI / Console 仕様](docs/ksql_cli_console_spec.md)
 - [バッチ実行・一時テーブル仕様](docs/ksql_batch_temp_table_spec.md)
 - [MCP サーバー仕様](docs/ksql_mcp_server_spec.md) / [Claude Desktop への導入（MCPB）](docs/ksql_mcpb_claude_desktop_install.md)
-- [APP@profile 仕様](docs/cli_app_profile_spec.md)
+- [APP@profile 仕様](docs/cli_app_profile_spec.md)
 - [公開前チェックリスト](docs/internal/public_release_checklist.md)
 
 ## ライセンス