ken_nogi/ClaudePleasanter/MSS回覧板システム/README.md

プリザンター サイト構成 取得・レビュー・反映ツール

全体の流れ

① 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が更新されているか・目的の文字列が含まれているかを確認する。