mygit-admin/ken_nogi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
db25941158
ken_nogi/Pleasanter/README.md
Kenichiro NOGI ce58cb4be4 初回コミット: dev配下(NodeSrv/Pleasanter等)をGitea管理下に統合 
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>
2026-09-04 15:37:06 +09:00

154 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# プリザンター サイト構成 取得・レビュー・反映ツール
全ツール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`更新・目的文字列含有を確認
Reference in New Issue View Git Blame Copy Permalink