ce58cb4be4
GitHub(nextgroup2706/ken_nogi)は今後使わず自社Gitea運用に切替え。 NodeSrvは旧リポジトリの履歴を破棄しファイルのみ統合(Dokploy用サービスアカウントは 別途mygit-admin/NodeSrv.gitに履歴あり)。notepmエクスポート(12GB)とPleasanter インストーラzip(208MB)はサイズが大きいため.gitignoreで除外。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
154 lines
14 KiB
Markdown
154 lines
14 KiB
Markdown
# プリザンター サイト構成 取得・レビュー・反映ツール
|
||
|
||
全ツールClaudePleasanter直下`.claude/js/`集約。各プロジェクトフォルダ（サイト単位）は`siteid.json`（対象SiteId）と`configs/{production|development}/`（取得データ、サーバー環境ごと物理分離）のみ残す。移動・改名されても影響なし。
|
||
|
||
接続先サーバー情報（BaseUrl/ApiKey/ApiVersion）はリポジトリルート直下`config_production.json`（本番）/`config_development.json`（テスト）に集約。全ツール`--env=production|development`必須指定（デフォルト値なし。誤送信事故防止のため未指定・不正値はエラー終了）。
|
||
|
||
## 全体の流れ
|
||
|
||
```
|
||
① node .claude/js/get-site-config.js --project="<プロジェクトフォルダ名>" --env=production
|
||
→ {プロジェクト}/configs/production/site-{SiteId}_{サイト名}/sitesettings/site-{SiteId}_latest.json に構成保存
|
||
→ 続けて自動で extract-site-config.js 実行
|
||
Scripts / Styles / ServerScripts / Processes / ガイドHTML/補足HTML を
|
||
configs/production/site-{SiteId}_{サイト名}/ 配下に個別ファイル分割保存
|
||
→ siteid.json の SiteId カンマ区切りで複数サイト一括ループ取得
|
||
→ InheritPermission が自サイト以外を指していれば継承元サイトも自動追跡取得
|
||
|
||
② latest.json をClaudeのチャットへアップロード
|
||
→ Claudeが構成レビュー・仕様書化（configs/production/site-{SiteId}_{サイト名}/docs/site-{SiteId}_spec.md）
|
||
|
||
③ configs/production/site-{SiteId}_{サイト名}/ 配下ファイルを直接編集、
|
||
またはClaudeへ「このスクリプトを◯◯に直して」等指示
|
||
|
||
④ node .claude/js/build-desired-config.js --project="<プロジェクトフォルダ名>" --env=production site-{SiteId}
|
||
→ 分割ファイル再構成し desired_config.json 生成（送信なし）
|
||
|
||
⑤ node .claude/js/apply-site-config.js --project="<プロジェクトフォルダ名>" --env=production
|
||
→ 送信せず差分・送信予定Body・curlコマンド表示のみ（常にドライラン）
|
||
|
||
⑥ 内容確認後、表示curlコマンド手動実行
|
||
または node .claude/js/apply-desired-config-full.js --project="<プロジェクトフォルダ名>" --env=production --execute
|
||
```
|
||
|
||
（テスト環境=`neo999.next-hd.net`対象プロジェクトは`--env=development`指定）
|
||
|
||
`extract-site-config.js`は`get-site-config.js`内から自動実行→通常単独実行不要
|
||
（取得済み`latest.json`から抽出やり直したい時のみ単独実行）。
|
||
|
||
上記はScripts/Styles/ServerScripts/Processes反映フロー（単一サイト内完結）。項目追加・連番リネーム・別サイト丸ごと適用・権限名前指定追加等の構造変更は`.claude/skills/pleasanter-site-spec/SKILL.md`「クロスサイト構造変更」節参照。
|
||
|
||
## 初回セットアップ（新規プロジェクトフォルダ作成時）
|
||
|
||
1. リポジトリルート直下`config_production.json`/`config_development.json`（サーバー接続情報）存在確認（無ければ`config.example.json`参考に作成）
|
||
2. 対象プロジェクトフォルダへ`siteid.json`新規作成
|
||
```json
|
||
{ "SiteId": "12345" }
|
||
```
|
||
- `SiteId`単一なら数値または文字列（例`"12345"`）、複数一括取得ならカンマ区切り文字列（例`"12345,23456,34567"`）
|
||
- APIキー発行: https://pleasanter.org/manual/api-key （テナント管理者権限必要、サイト設定更新系API使用時）
|
||
3. Node.js 18以降確認（組み込みfetch使用、追加パッケージ不要）
|
||
4. `get-page-html.js`（画面HTML取得）使う場合のみ、`config_{env}.json`側に`LoginId`/`Password`追記（後述）
|
||
|
||
## --project / --env 指定方法
|
||
|
||
- `--project`: フォルダ名フル指定推奨: `--project="IC(東京)【引継依頼】"`
|
||
- 部分一致（大文字小文字無視）で候補1件に絞れれば省略形も可: `--project=IC東京`（曖昧なら候補一覧表示→フル指定要求）
|
||
- 複数コマンド同一プロジェクト連続実行時、環境変数`PLEASANTER_PROJECT_ROOT`にプロジェクトフォルダ絶対パス設定でも代替可（`--project`指定あればそちら優先）
|
||
- `--env`: `production`（本番: nextoffice.next-hd.co.jp）または`development`（テスト: neo999.next-hd.net）必須指定。デフォルト値なし
|
||
- 環境変数`PLEASANTER_ENV`でも代替可（`--env`指定あればそちら優先）
|
||
|
||
## ツール一覧（`.claude/js/`配下）
|
||
|
||
| ファイル | 役割 |
|
||
|---|---|
|
||
| `resolve-project.js` | `--project`/`--env`指定からプロジェクトフォルダ・サーバー環境解決する共通ヘルパー（`loadServerConfig(env)`/`loadSiteId(baseDir)`も提供。他スクリプトから内部利用） |
|
||
| `site-paths.js` | `configs/{env}/`配下フォルダ構成解決の共通ヘルパー |
|
||
| `get-site-config.js` | サイト構成取得（`getsite`）→`latest.json`保存→`extract-site-config.js`自動実行。SiteIdカンマ区切りで複数一括、InheritPermission自動追跡 |
|
||
| `extract-site-config.js` | `latest.json`からScripts/Styles/ServerScripts/Processes/ガイドHTML/補足HTMLを個別ファイル分割 |
|
||
| `build-desired-config.js` | 分割ファイル再構成し`desired_config.json`生成（送信なし） |
|
||
| `apply-site-config.js` | 希望構成JSONとの差分・送信内容確認（常にドライラン、送信なし） |
|
||
| `apply-desired-config-full.js` | Scripts/Styles/ServerScripts/Processesを現状サイト全体へ上書きマージし`updatesite`で反映。デフォルト差分プレビューのみ、`--execute`指定時のみ実送信 |
|
||
| `get-master-data.js` | ユーザー/組織/グループのマスターデータ取得→`configs/{env}/master/`保存（ページング自動対応） |
|
||
| `resolve-names.js` | マスターデータでID⇔名前相互変換（`require`して使用） |
|
||
| `get-page-html.js` | プリザンター画面そのもの（HTML）をセッションログイン経由で取得。API不可のためフォームログイン→Cookie確立→GET |
|
||
| `diff-excel-vs-site.js` / `extract-excel-def.js` / `extract-site-columns-flat.js` | サイト定義書Excelと実サイトColumns設定の突き合わせ・差分確認（読み取り専用） |
|
||
| `generate-process-flowchart.js` | processes.jsonからMermaid横向きフローチャート（Status遷移図）生成、標準出力のみ |
|
||
| `generate-site-documentation.js` | サイト構成から技術仕様書＋業務向け概要書（PDF化込み）生成（基本版） |
|
||
| `generate-site-documentation-full.js` | 上記拡張版。権限InheritPermission考慮・グリッド列ラベル解決・レガシー配置対応 |
|
||
| `md-to-pdf.js` / `md-to-docx.js` | MarkdownをPDF/docxへ変換（OS標準Edge/Word使用、外部npm非依存） |
|
||
| `site-scripts/{プロジェクト名}/` | 特定SiteId・案件限定の一回限りスクリプト（過去の構造変更実例）。`PROJECT_NAME`/`ENV`ファイル冒頭ハードコード済み。次回同様依頼時コピーして書き換え |
|
||
|
||
## リポジトリルートに置くもの
|
||
|
||
| ファイル | 役割 |
|
||
|---|---|
|
||
| `config_production.json` | 本番サーバー接続情報（BaseUrl/ApiKey/ApiVersion、任意でLoginId/Password）※Git管理・共有厳禁 |
|
||
| `config_development.json` | テストサーバー接続情報（同上） |
|
||
| `config.example.json` | 上記2ファイルのひな形 |
|
||
|
||
## プロジェクトフォルダに残るもの
|
||
|
||
| ファイル/フォルダ | 役割 |
|
||
|---|---|
|
||
| `siteid.json` | 対象SiteId（`{"SiteId": "..."}`のみ）※Git管理・共有厳禁 |
|
||
| `desired_config.json` | `build-desired-config.js`生成「希望構成」（Git管理外） |
|
||
| `configs/{env}/master/master_{users,depts,groups}.json` | マスターデータ |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/sitesettings/site-{SiteId}_latest.json` | 直近取得の現状構成（Claudeアップロード対象） |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/sitesettings/site-{SiteId}_{timestamp}.json` | 取得時点ごと履歴 |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/docs/site-{SiteId}_spec.md` | 仕様書。他ドキュメントもここ |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/manifest.json` | 分割ファイル一覧対応表 |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/scripts/*.js` `styles/*.css` `serverscripts/*.js` | クライアントスクリプト/スタイル/サーバースクリプト本体 |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/guide/*.html` | 画面ガイド（GridGuide等、サイトデータ直下） |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/html/*.html` | 項目ごと補足HTML（Columns配下ExtendedHtmlAfterControl） |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/processes.json` | プロセス設定定義 |
|
||
| `configs/{env}/site-{SiteId}_{サイト名}/modify/{ラベル}/` | 修正依頼ごと新規作成。変更前後config・差分プレビュー・送信結果保管 |
|
||
| `configs/{env}/html-dump/{ホスト名}/` | `get-page-html.js`取得結果 |
|
||
|
||
`{env}`は`production`または`development`。本番/テストデータ物理的に別ディレクトリ保存、混在・上書きなし。
|
||
|
||
## Scripts/Styles/ServerScripts/Processes 反映について
|
||
|
||
- `build-desired-config.js`生成`desired_config.json`は`Mode:"partial"`（`updatesitesettings`）。Scripts/Styles/ServerScripts/Processes4項目のみ対象、他設定（GridColumns等）不変
|
||
- ガイドHTML（`guide/*.html`）・補足HTML（`html/*.html`）はSiteSettingsでなく**サイトデータ直下/Columns配下**の項目→`updatesitesettings`不可。反映は`Mode:"full"`（`updatesite`）用別JSON要、Title/ReferenceType等必須項目も指定
|
||
- 抽出はスナップショット。元サイトが他画面から変更されている可能性あれば、反映前に`get-site-config.js`→`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
|
||
|
||
## 画面HTML取得（get-page-html.js）について
|
||
|
||
APIキーは画面HTML取得に使えない（APIはJSON専用）→`/users/login`へフォームログインしCookie確立後GET。
|
||
|
||
事前準備: 対象サーバー環境の`config_{env}.json`に`LoginId`/`Password`追記
|
||
```json
|
||
{ "BaseUrl": "...", "ApiKey": "...", "LoginId": "ログインID", "Password": "パスワード" }
|
||
```
|
||
ログインフォーム項目名が既定（LoginId/Password）と違う場合`LoginIdField`/`PasswordField`で上書き可。パスワードをファイルに置きたくなければ環境変数`PLEASANTER_LOGIN_PASSWORD`で渡してもよい（config_{env}.jsonの値より優先）。
|
||
|
||
```
|
||
node .claude/js/get-page-html.js --project="<プロジェクトフォルダ名>" --env=production /items/12345/edit
|
||
```
|
||
|
||
保存先: `{プロジェクト}/configs/{env}/html-dump/{ホスト名}/`（Git管理外）
|
||
|
||
## 安全設計について
|
||
|
||
- `apply-site-config.js`**常にドライラン**。デフォルトで実際のAPI呼び出しコードへ到達しないようガード（`ENABLE_ACTUAL_SEND = false`固定）
|
||
- 反映時は表示curlコマンド自身で実行、または内容確認の上スクリプト改修（Claudeが安全策なしに自動実行することはない）
|
||
- APIキーはリポジトリルート`config_{env}.json`のみ保持、Claudeアップロード対象`latest.json`には含まれない（getレスポンスにAPIキー含まれないため）。念のためアップロード前目視確認推奨
|
||
- サーバー環境（`--env`）は誤送信事故防止のためデフォルト値持たない。未指定・不正値は必ずエラー終了
|
||
- `site-scripts/`配下の一回限りスクリプトは、ユーザーがその場で明示許可した場合限定の例外（`--execute`指定時のみ実送信）。依頼ごと一回限りの許可、標準運用（ドライラン＋手動反映）を恒久変更するものではない
|
||
|
||
## 注意事項
|
||
|
||
- プリザンターのバージョンにより`get`レスポンス構造（`Response.Site.SiteSettings`の位置等）異なる場合あり。初回実行時コンソール出力キー構造確認要
|
||
- サイト設定更新系APIは**テナント管理者権限のAPIキー**必要（一般ユーザーAPIキーは403等）
|
||
- ★重要: この環境では`updatesitesettings`（部分更新）が**HTTP 200・成功メッセージを返すにもかかわらず実際にはScripts/Styles/ServerScriptsの内容がDBに反映されないことを確認済み**（2026-07-16、SiteId 496626で発生。直後`getsite`し直しても内容・Ver・UpdatedTime不変）。実反映は`updatesitesettings`でなく`updatesite`（全体更新。Title/ReferenceType/ParentId/InheritPermission/Permissionsは現状のまま再送信、SiteSettingsは現状取得の上Scripts/Styles/ServerScriptsのみ差し替え）を使うこと。反映後は必ず`getsite`し直し`UpdatedTime`更新・目的文字列含有を確認
|