Pleasanter Script Deploy

基本方針

Pleasanter のサイト設定やクライアントスクリプトを変更するときは、dry-run や見た目だけの成功扱いで終わらせない。対象 SiteId、API キー、ログインユーザー、権限、反映結果、実画面挙動を確認してから完了とする。

失敗した API 呼び出し、保存失敗、権限不足、画面未反映は成功として扱わない。エラーは握りつぶさず、ユーザーに原因候補と次の確認点を短く報告する。

スタートアップ確認

作業開始時に、既存ファイルやユーザー指示から以下を確認する。不明で、ローカルファイルや実画面から判定できないものだけユーザーへ質問する。

• 対象 Pleasanter URL。例: http://localhost:50001
• 対象 SiteId。フォルダー、テーブル、ガント対象テーブルを区別する。
• 変更対象がサイト設定、クライアントスクリプト、ビュー、リンク、ガント、レコードのどれか。
• .env または安全な環境変数に、対象 Pleasanter URL、API キー、SiteId、ブラウザ検証用ログイン情報が設定されていること。認証情報をチャットへ貼らない。
• ブラウザ検証用ログインユーザーとパスワード。
• そのユーザーが対象サイトを閲覧、編集、設定変更、レコード更新できるか。
• 作業してよい環境か。SiteId や環境名が曖昧なら変更前に確認する。
• 既存の要件定義、レビュー、検証記録、エクスポート、投入スクリプトの場所。

事前調査

1. docs/、exports/、scripts/、既存投入スクリプトを確認する。
2. 対象 SiteId と親子関係を混同しない。フォルダー SiteId とテーブル SiteId は別物として扱う。
3. 既存のサイト設定取得 API またはエクスポートから、SiteSettings.Scripts、ガント設定、リンク設定、列設定を確認する。
4. 既存スクリプトがある場合は、丸ごと上書きしてよいか、同一タイトルのスクリプトだけ置換すべきか判断する。
5. ユーザーが触っていない別サイトや本番環境には変更を広げない。

.env 運用

API 反映スクリプトは、ベース URL、API キー、SiteId をコードへ固定しない。原則としてプロジェクトに .env.example を用意し、ユーザーにはそれを .env にコピーして値を入れてもらう。

最低限のテンプレート:

PLEASANTER_BASE_URL=
PLEASANTER_API_KEY=
PLEASANTER_TARGET_SITE_ID=
PLEASANTER_LOGIN_ID=
PLEASANTER_LOGIN_PASSWORD=

複数サイトを扱う場合は、用途が分かる名前で PLEASANTER_ROOT_SITE_ID、PLEASANTER_TASK_SITE_ID などを追加する。.env は Git 管理、成果物、チャット貼り付けに含めない。.env.example には空値またはローカル開発用の非秘密値だけを書く。

反映対象がサブパス配下の Pleasanter の場合は、PLEASANTER_BASE_URL に API が届くベースパスを含める。クライアントスクリプト内で編集画面の相対パスを組み立てている場合は、EDIT_PATH_PREFIX などの設定が対象環境のパス構成に合うか確認する。

API 反映手順

実 API で反映する。一般的な流れは以下。

1. .env または環境変数から、ベース URL、API キー、対象 SiteId を取得する。未設定なら処理を中断し、成功扱いにしない。
2. POST /api/items/{siteId}/getsite で現在のサイト設定を取得する。
3. SiteSettings 内の対象設定だけを変更する。
4. POST /api/items/{siteId}/updatesite に Title、Body、SiteSettings を含めて送る。
5. レスポンスの StatusCode が成功であることを確認する。
6. 反映後に再取得またはエクスポートを行い、変更後の設定が保存されていることを確認する。

API レスポンスが失敗した場合は中断し、成功扱いにしない。フォールバック実装で失敗を隠さない。

ブラウザ検証

反映後は、実ブラウザで確認する。ユーザーがアプリ内ブラウザを指定している場合は、外部ブラウザではなくアプリ内ブラウザを使う。

検証の基本観点:

• ログインできること。
• 対象 URL を開けること。
• 対象ユーザーで表示、編集、保存ができること。
• 変更した UI が DOM と見た目に反映されていること。
• 操作後に実データまたは画面再読み込みで最新状態が見えること。
• 保存失敗時にエラーが表示されること。
• 標準の再描画操作、Ajax 更新、画面再読み込み、戻る/次へ/期間変更などで追加 UI が壊れないこと。
• ガントやチャートの場合、長期表示と短期表示の両方で座標ズレがないこと。

ブラウザ検証では、必要に応じて DOM 数値も確認する。例: 追加ボタン数、対象バー数、標準グリッドとの差分、メッセージ件数、iframe モーダル状態。

権限確認

テストユーザーが対象操作を実行できるか確認する。最低限、以下を区別する。

• 画面閲覧だけできる。
• レコード編集できる。
• サイト設定を変更できる。
• API キーで対象 SiteId の取得、更新ができる。

権限不足が疑われる場合は、API レスポンス、画面メッセージ、ユーザー権限設定のどこで失敗しているかを切り分ける。

スクリプト実装の注意

• SiteId、API キー、特定テーブル ID などをクライアントスクリプト内へ不要に固定しない。
• コピー利用を想定するスクリプトは、冒頭に日本語コメントで前提と変更可能な設定を明記する。
• Pleasanter 標準 DOM に依存する場合は、必要な DOM ID をコメントに書く。
• 標準再描画に追従する必要がある UI は、$p.events.on_gantt_load、Ajax 完了、MutationObserver、画面再読み込みのどれで再生成するかを明確にする。
• 表示だけ成功してデータが失敗する状態を避ける。保存失敗時はロールバックまたは再読み込みで矛盾を消す。
• setMessage などの標準 API は、対象環境の実ランタイム実装を確認する。公式情報が見つからない場合は、その旨を記録する。

検証記録

作業後は、必要に応じて docs/reviews/、docs/verification/、またはプロジェクトの既存ルールに沿う場所へ記録する。

記録には以下を含める。

• 対象 URL と SiteId。
• 反映したファイルまたはスクリプト名。
• 実 API 反映の結果。
• ブラウザで確認した操作。
• 生成したエクスポートやスクリーンショット。
• 未確認事項、残リスク、ユーザー確認が必要な点。

詳細チェックリスト

必要なときだけ references/checklist.md を読む。初回の確認項目、API 実装例、ブラウザ検証の観点を詳しくまとめている。