117 lines
12 KiB
Markdown
117 lines
12 KiB
Markdown
# プリザンター サイト構成 取得・レビュー・反映ツール
|
||
|
||
## 全体の流れ
|
||
|
||
```
|
||
① 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` 参照 |
|
||
| `generate-process-flowchart.js` | `processes.json`とStatus列`ChoicesText`から、プロセス設定のStatus遷移を横向きMermaidフローチャートとして標準出力へ表示（ファイル書き込み・API送信なし）。`node generate-process-flowchart.js site-{SiteId}`。出力は仕様書「8. プロセス設定」節へ手動で組み込む |
|
||
| `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`が更新されているか・目的の文字列が含まれているかを確認する。
|