# プリザンター サイト構成 取得・レビュー・反映ツール ## 全体の流れ ``` ① node get-site-config.js → configs/site-{SiteId}_{サイト名}/sitesettings/site-{SiteId}_latest.json に構成を保存 → 続けて自動的に extract-site-config.js が実行され、 Scripts / Styles / ServerScripts / Processes / ガイドHTML が configs/site-{SiteId}_{サイト名}/ 配下に個別ファイルとして分割保存される → config.json の SiteId をカンマ区切りにすると、複数サイトをまとめて①の処理でループ取得する → 取得したサイトの InheritPermission が自サイト以外を指していれば、権限の実体を持つ そのサイトも自動的に追いかけて取得する ② その latest.json をClaudeのチャットにアップロード → Claudeが構成をレビュー・仕様書化（configs/site-{SiteId}_{サイト名}/docs/site-{SiteId}_spec.md） ③ configs/site-{SiteId}_{サイト名}/ 配下のファイルを直接編集、 またはClaudeに「このスクリプトを◯◯に直して」等と修正を指示 ④ node build-desired-config.js site-{SiteId} → 分割ファイルを再構成し、desired_config.json を生成（送信は行わない） ⑤ node apply-site-config.js → 実際には送信せず、差分・送信予定Body・curlコマンドのみ表示（常にドライラン） ⑥ 内容を確認し、問題なければ表示されたcurlコマンドを手動実行 ``` `extract-site-config.js` は `node get-site-config.js` の中から自動実行されるため、通常は個別に実行する必要はありません （取得済みの `latest.json` から抽出をやり直したい場合のみ、単独で `node extract-site-config.js` を実行してください）。 上記はScripts/Styles/ServerScripts/Processesの反映フロー（単一サイト内で完結）です。項目の追加や連番リネーム、 別サイトへの丸ごと適用、権限の名前指定追加など、より大きな構造変更は `.claude/skills/pleasanter-site-spec/SKILL.md` の「クロスサイト構造変更」の節を参照してください。 ## 初回セットアップ 1. `config.example.json` を `config.json` にコピー 2. `BaseUrl` / `SiteId` / `ApiKey` を実環境の値に書き換え - `SiteId` は単一サイトなら数値（例: `12345`）、複数サイトをまとめて取得したい場合は カンマ区切りの文字列（例: `"12345,23456,34567"`）で指定できます - APIキーの発行方法: https://pleasanter.org/manual/api-key - APIキー発行にはテナント管理者権限が必要です（サイト設定の更新系APIを使う場合） 3. Node.js 18以降がインストールされていることを確認（組み込みfetchを使用、追加パッケージ不要） ## ファイル構成 | ファイル | 役割 | |---|---| | `config.json` | 接続情報（BaseUrl/SiteId/ApiKey）※Git管理・共有厳禁 | | `config.example.json` | 上記のテンプレート | | `site-paths.js` | `configs/` 配下のフォルダ構成（後述）を解決する共通ヘルパー。他のスクリプトから`require`して使う | | `get-site-config.js` | サイト構成取得（`getsite`） → `configs/site-{SiteId}_{サイト名}/sitesettings/site-{SiteId}_latest.json` に保存し、続けて `extract-site-config.js` を自動実行。`SiteId` をカンマ区切りにすると全サイトを1回の実行で順次取得。`InheritPermission` が自サイト以外を指していれば継承元サイトも自動追跡 | | `extract-site-config.js` | `latest.json` から Scripts/Styles/ServerScripts/Processes/ガイドHTML を `configs/site-{SiteId}_{サイト名}/` に個別ファイル分割（`get-site-config.js` から自動呼び出し、または単独実行も可） | | `build-desired-config.js` | 分割ファイルを再構成し `desired_config.json` を生成（**送信は行わない**） | | `apply-site-config.js` | 希望構成JSONとの差分表示・送信内容確認（**送信は行わない**） | | `apply-desired-config-full.js` | `desired_config.json`のScripts/Styles/ServerScripts/Processesを、現状サイト全体（getsite）に上書きマージし`updatesite`（全体更新）で反映する専用実行スクリプト。`updatesitesettings`（部分更新）がこの環境で反映されない問題（下記「注意事項」参照）を踏まえた標準の反映手段。Columns/GridColumns/Permissions等は現状のまま変更しない。デフォルトは差分プレビューのみ、`--execute`指定時のみ実際に送信する | | `get-master-data.js` | ユーザー/組織/グループのマスターデータを取得し `configs/master/` へ保存（ページング自動対応） | | `resolve-names.js` | `configs/master/` のマスターデータを使い、ID⇔名前を相互変換するユーティリティ（`require`して使う） | | `restructure-site-480111.js` / `apply-to-site-496626.js` / `apply-permission-grant.js` | クロスサイト構造変更（項目追加・連番リネーム・別サイトへの丸ごと適用・権限の名前指定追加）の実例。次回同様の依頼が来たらコピーして書き換える。詳細は `.claude/skills/pleasanter-site-spec/SKILL.md` 参照 | | `desired_config.json` | Claude、または `build-desired-config.js` が生成する「希望構成」 | | `configs/master/master_{users,depts,groups}.json` | ユーザー/組織/グループのマスターデータ | | `configs/site-{SiteId}_{サイト名}/sitesettings/site-{SiteId}_latest.json` | 直近取得した現状構成（Claudeへのアップロード対象） | | `configs/site-{SiteId}_{サイト名}/sitesettings/site-{SiteId}_{timestamp}.json` | 取得時点ごとの履歴（タイムスタンプ付き） | | `configs/site-{SiteId}_{サイト名}/docs/site-{SiteId}_spec.md` | SiteSettingsを読み解いたMarkdown仕様書。改善要望プラン等その他ドキュメントもここに置く | | `configs/site-{SiteId}_{サイト名}/manifest.json` | 分割ファイルの一覧（Id/Title/ファイル名の対応表） | | `configs/site-{SiteId}_{サイト名}/scripts/*.js` | クライアントスクリプト本体（1ファイル=1スクリプト） | | `configs/site-{SiteId}_{サイト名}/styles/*.css` | スタイル本体 | | `configs/site-{SiteId}_{サイト名}/serverscripts/*.js` | サーバースクリプト本体 | | `configs/site-{SiteId}_{サイト名}/html/*.html` | ガイドHTML（GridGuide等。値が空でないもののみ） | | `configs/site-{SiteId}_{サイト名}/processes.json` | プロセス設定（`SiteSettings.Processes` の定義ファイル） | | `configs/site-{SiteId}_{サイト名}/modify/{リクエストラベル}/` | 修正依頼ごとに新規作成。変更前後のconfig・差分プレビュー・送信結果をまとめて保管 | ## Scripts/Styles/ServerScripts/Processes の反映について - `build-desired-config.js` が生成する `desired_config.json` は `Mode:"partial"`（`updatesitesettings`）です。 Scripts / Styles / ServerScripts / Processes の4項目のみを対象とし、それ以外のサイト設定（GridColumns等）には触れません。 - ガイドHTML（`html/*.html`）はSiteSettingsではなく**サイトデータ直下**の項目のため、`updatesitesettings` では反映できません。 反映したい場合は `Mode:"full"`（`updatesite`）用の別の `desired_config.json` を用意し、`Title`/`ReferenceType` 等の必須項目とあわせて指定してください。 - 抽出（`extract-site-config.js`）はその時点のスナップショットです。抽出後に元サイトが他の人・画面から変更されている可能性がある場合は、 反映前に `node get-site-config.js` → `node extract-site-config.js` を再実行し、最新状態を取り直してから編集してください。 ## 参照した公式API仕様 - サイト情報取得: `POST {BaseUrl}/api/items/{SiteId}/getsite` https://pleasanter.org/ja/manual/api-site-get （※ `/api/items/{SiteId}/get` はアイテム一覧取得APIであり別物） - サイト全体更新: `POST {BaseUrl}/api/items/{SiteId}/updatesite` https://pleasanter.org/manual/api-site-update - サイト設定部分更新: `POST {BaseUrl}/api/items/{SiteId}/updatesitesettings` https://pleasanter.org/ja/manual/api-update-sitesettings - ユーザ取得（全て）: `POST {BaseUrl}/api/users/get` https://pleasanter.org/ja/manual/api-user-get-all （※ ページングはトップレベルの `Offset` パラメータで行う。`View.Offset` ではない点に注意） - 組織取得: `POST {BaseUrl}/api/depts/get` https://pleasanter.org/ja/manual/api-dept-get - グループ取得: `POST {BaseUrl}/api/groups/get` https://pleasanter.org/ja/manual/api-group-get ## 安全設計について - `apply-site-config.js` は **常にドライラン** です。デフォルトでは実際のAPI呼び出しコード自体に到達しないようガード（`ENABLE_ACTUAL_SEND = false` 固定）しています。 - 反映する際は、表示されたcurlコマンドをご自身で実行するか、内容を確認の上でスクリプトを改修してください（Claudeが安全策なしに自動実行することはありません）。 - APIキーは `config.json` にのみ保持し、Claudeにアップロードする `latest.json` には含まれません（get時のレスポンスにAPIキーは含まれないため）。念のためアップロード前に目視確認することをおすすめします。 - `apply-to-site-*.js` / `apply-permission-grant.js` のような、ユーザーがその場で明示的に許可した場合に限って 作成される「専用の直接実行スクリプト」は例外です（`--execute` 指定時のみ実送信）。これは依頼ごとの一回限りの 許可であり、標準運用（ドライラン＋手動反映）を恒久的に変更するものではありません。 ## 注意事項 - プリザンターのバージョンにより `get` レスポンスの構造（`Response.Site.SiteSettings` の位置など）が異なる場合があります。初回実行時にコンソールへ出力されるキー構造を確認してください。 - サイト設定の更新系APIは **テナント管理者権限のAPIキー** が必要です（一般ユーザーのAPIキーでは403等になります）。 - ★重要: この環境では `updatesitesettings`（部分更新）が **HTTP 200・成功メッセージを返すにもかかわらず、実際にはScripts/Styles/ServerScriptsの内容がDBに反映されないことを確認済み**です（2026-07-16、SiteId 496626で発生。直後に`getsite`し直しても内容・Ver・UpdatedTimeが変化しなかった）。 Scripts/Styles/ServerScriptsを実際に反映する専用スクリプトを書く場合は、`updatesitesettings`ではなく`updatesite`（全体更新。Title/ReferenceType/ParentId/InheritPermission/Permissionsは現状のまま再送信し、SiteSettingsは現状を取得した上でScripts/Styles/ServerScriptsだけ差し替える）を使うこと。反映後は必ず`getsite`し直し、`UpdatedTime`が更新されているか・目的の文字列が含まれているかを確認する。