267 lines
18 KiB
Markdown
267 lines
18 KiB
Markdown
---
|
||
name: pleasanter-site-spec
|
||
description: Pleasanterのサイト設定JSON（get-site-config.js / api-site-get の getsite レスポンス）から、SiteSettingsを読み解いたMarkdown仕様書を生成し、Scripts/Styles/ServerScripts/Processesの抽出・編集・反映（extract-site-config.js / build-desired-config.js / apply-site-config.js）を行う。また、技術仕様書とは別に業務担当者向けの概要書（docs/site-{SiteId}_{サイト名}_overview.md）を作成し、md-to-pdf.jsでPDF化する。「仕様書を作って」「サイト仕様書」「SiteSettingsをドキュメント化」「スクリプトを抜き出して」「プロセス設定を直して反映して」「概要書を作って」「PDFにして」「site-spec」等の依頼で使う。
|
||
---
|
||
|
||
# Pleasanter サイト仕様書生成
|
||
|
||
`./siteSettingJsons/site-{SiteId}_latest.json`（`getsite` APIレスポンス、`Response.Data` 配下にサイト情報）と、
|
||
`./configs/site-{SiteId}_{サイト名}/`（`extract-site-config.js` による抽出済みScripts/Styles/ServerScripts/Processes）を
|
||
読み解き、`./docs/site-{SiteId}_{サイト名}_spec.md` として日本語のMarkdown仕様書を出力する。
|
||
|
||
この仕様書はClaudeが対話的に読み解いて執筆するものであり、機械的なテンプレート処理で自動生成するものではない
|
||
（`generate-site-documentation.js` は過去に試みられた機械生成版で、サイト間の暗黙的な関連や業務的な類推まではできず
|
||
品質面の問題があったため現在のワークフローでは使用しない。削除はされていないが参照しないこと）。
|
||
|
||
## 入力の特定
|
||
|
||
1. ユーザーがJSONファイルパスやSiteIdを指定した場合はそれを使う。
|
||
2. 指定がなければ `./siteSettingJsons/site-*_latest.json` を探す。複数ある場合はユーザーに確認する。
|
||
3. `./siteSettingJsons/site-{SiteId}_latest.json` が無ければ、先に `node get-site-config.js` の実行を提案する
|
||
（エンドポイントは `/api/items/{SiteId}/getsite` を使うこと。`/api/items/{SiteId}/get` はアイテム一覧取得APIであり別物なので注意）。
|
||
|
||
## 出力ファイル
|
||
|
||
`./docs/site-{SiteId}_{サイト名}_spec.md`（サイト名は `configs/site-{SiteId}_{サイト名}/` のフォルダ名と揃える。既存があれば上書きしてよい）。
|
||
`docs/`フォルダが無ければ作成する。
|
||
|
||
## 仕様書の構成（この順番・見出しレベルを踏襲する）
|
||
|
||
```markdown
|
||
# サイト仕様書：{Title}（SiteId: {SiteId}）
|
||
|
||
- 取得元データ: [site-{SiteId}_latest.json](../siteSettingJsons/site-{SiteId}_latest.json)
|
||
- 取得日時: {UpdatedTime}（サイト更新日時）／設定バージョン `Ver: {Ver}`
|
||
|
||
## 1. サイト基本情報
|
||
（TenantId, Title, ReferenceType, ParentId, InheritPermission, Publish,
|
||
DisableCrossSearch, Creator/Updator, CreatedTime, SiteSettings.Version を表形式で）
|
||
|
||
## 2. アクセス権限（Permissions）
|
||
（Permissions配列を 種別/対象ID/権限レベル の表に分解。
|
||
「権限値はビットフラグの加算方式のため正確な意味は環境のロール定義に依存する」旨を注記）
|
||
|
||
## 3. 画面構成
|
||
### 3.1 一覧画面（GridColumns）
|
||
（GridColumns配列を 順番/列名/表示ラベル の表に。ラベルはColumns配列から解決、
|
||
無ければ「項目種別の判定ルール」のデフォルト名を使う）
|
||
|
||
### 3.2 編集画面レイアウト（EditorColumnHash / Sections）
|
||
（EditorColumnHashの各タブ配列を 順番/項目名（内部名）/ラベル名 の表に。
|
||
`_Section-N` はラベル名欄に「―（セクション「{LabelText}」開始）」と記載。
|
||
続けてSections配列を Id/ラベル/AllowExpand/Expand の表で示す）
|
||
|
||
### 3.3 タイトル表示（TitleColumns / TitleSeparator）
|
||
（TitleColumns配列をTitleSeparatorで連結した式を明記）
|
||
|
||
## 4. 項目定義（Columns）
|
||
（Columns配列を 列名（内部）/種別/表示ラベル/説明・入力ガイド/備考 の表に。
|
||
種別は下記「項目種別の判定ルール」で推定。
|
||
備考にはNoWrap, FieldCss, ExtendedHtmlAfterControlの有無などを記載）
|
||
|
||
### 4.1 項目ごとの補足HTML（ExtendedHtmlAfterControl）
|
||
（該当項目があれば 列名/色（styleやclassから読み取れれば）/内容 の表。無ければこの節は省略）
|
||
|
||
## 5. 作成・更新権限（フィールド単位）
|
||
（PermissionForCreating / PermissionForUpdating を表で。無ければ「設定なし」と明記）
|
||
|
||
## 6. 集計設定（Aggregations）
|
||
（存在する場合のみ。Id/GroupBy/Type/Target を表で）
|
||
|
||
## 7. 他サイト連携（Links / ルックアップ）
|
||
（存在する場合のみ。起点列/参照先SiteId/参照先の値→自コピー先/JsonFormat を表で。
|
||
「参照先サイトの{From}列の値を、このサイトの{To}列にコピーする」という関係性を文章でも補足）
|
||
|
||
## 8. プロセス設定（Processes）
|
||
（存在する場合のみ。定義ファイルへのリンク configs/site-{SiteId}_{サイト名}/processes.json を明記した上で、
|
||
Id/Name・DisplayName/実行条件(CurrentStatus→ChangedStatus)/動作(OnClick等)/成功メッセージ を表で）
|
||
|
||
## 9. スタイル（Styles）
|
||
（存在する場合のみ。Id/Title/適用範囲(New/Edit/Index等のフラグ)/ファイルへのリンクを表で。
|
||
CSS本体はMarkdownに貼らず、抽出済みファイルへのリンクのみとする）
|
||
|
||
## 10. スクリプト（Scripts）／サーバースクリプト（ServerScripts）
|
||
（存在する場合のみ。Id/Title/適用画面/ファイルへのリンクを表で。
|
||
スクリプト本体はMarkdownに貼らず、抽出済みファイルへのリンクのみとする。
|
||
概要は「何をするスクリプトか」を1〜2行で要約。
|
||
本文中にAPIキー・Webhook URL・パスワード等の秘密情報らしき文字列（`API_KEY`, `SECRET`, `Bearer `,
|
||
URLに埋め込まれたトークン等）を見つけた場合は、値そのものをMarkdownに転記せず、
|
||
「気になる点」に必ずセキュリティ上の指摘として記載する）
|
||
|
||
## 11. その他設定
|
||
（NoDisplayIfReadOnly, HideLink, SectionLatestId, 各種ガイド文の設定有無, Commentsの使用有無など）
|
||
|
||
---
|
||
|
||
## 気になる点（レビュー観点）
|
||
（プレースホルダーらしき文言、権限設定の偏り、項目単位の権限の抜け、
|
||
未設定のガイド文など、気づいた点を箇条書きで）
|
||
```
|
||
|
||
## 項目種別の判定ルール（Columns内 ColumnName のプレフィックスから推定）
|
||
|
||
| プレフィックス/名前 | 種別 |
|
||
|---|---|
|
||
| ClassA〜Z | 文字列（分類） |
|
||
| Class001〜040等（3桁連番） | 文字列（拡張分類）。`Hide: true`の場合が多く、他項目のルックアップ先の値を裏で保持する用途が多い |
|
||
| NumA〜Z | 数値 |
|
||
| DateA〜Z | 日付 |
|
||
| DescriptionA〜Z | 説明（複数行文字列） |
|
||
| CheckA〜Z | チェックボックス |
|
||
| AttachmentsA〜Z | 添付ファイル |
|
||
| Owner, Manager, Assignee等 | ユーザー選択 |
|
||
| Status | 状態 |
|
||
| {対象}Id（ResultId, IssueId等） | 自動採番ID |
|
||
| Title | タイトル |
|
||
| Comments | コメント欄 |
|
||
|
||
## 注意事項
|
||
|
||
- SiteSettingsに存在しない項目・空の設定（例: `ClassHash`, `NumHash` などのラベル定義ハッシュが `{}`）は
|
||
「標準ラベルのまま」として仕様書に明記し、存在しないかのように省略しない。
|
||
- 表形式を基本とし、箇条書きより表を優先する（今回のレビューで「編集画面レイアウトは項目名とラベル名を併記」との
|
||
指摘を受けた経緯があるため、内部名とラベル名は必ず併記する）。
|
||
- 出力言語は日本語。
|
||
- 複数サイトが関連する仕様書（「関連するテーブルと合わせて」等の依頼）を作る場合は、対象サイトの`Links`設定だけでなく、
|
||
ServerScripts内で`items.Get(masterTableId)`のように直接SiteIdをハードコードして参照している「正式なLinks設定に現れない
|
||
暗黙的なテーブル参照」も洗い出し、別セクションとして明記する。あわせて`ParentId`を辿ってサイトツリー上の位置関係も
|
||
簡潔に図示するとレビューしやすい。
|
||
|
||
## 概要書（業務担当者向け機能説明）の生成
|
||
|
||
技術仕様書（spec.md）とは別に、「概要書を作って」「機能的な説明がほしい」等の依頼があった場合は、
|
||
`ColumnName`（ClassA, DateB, Class001等の内部コード）やJSON設定値・スクリプト実装といった技術的要素を一切排除し、
|
||
ラベル名と業務フローのみで構成した概要書を作成する。
|
||
|
||
### 出力ファイル
|
||
|
||
`./docs/site-{SiteId}_{サイト名}_overview.md`（`siteSettingJsons/`・`configs/`ではなく`docs/`フォルダに置く。
|
||
これらは秘密情報を含み得るため`.gitignore`済みだが、`docs/`配下のspec.md・概要書・PDFは共有物としてGit管理対象にする想定）。
|
||
`docs/`フォルダが無ければ作成する。
|
||
|
||
### 概要書の構成
|
||
|
||
```markdown
|
||
# 概要書：{Title}
|
||
|
||
- 技術仕様（項目のシステム上の名称・設定値等）は [{spec.mdへのリンク}](./site-{SiteId}_{サイト名}_spec.md) を参照。
|
||
本書は業務担当者向けに、機能面のみを平易に説明するものです。
|
||
|
||
## 1. これは何か
|
||
（業務的にこのサイトが何のためのものかを2〜4文で）
|
||
|
||
## 2. 登場する情報（入力項目）
|
||
（分類/項目（ラベル名のみ）/内容 の表。ColumnNameは記載しない。Hide項目でも
|
||
業務上意味のあるもの（自動反映される裏項目等）は「内容」欄で触れる）
|
||
|
||
## 3. 業務の流れ（ボタン操作）
|
||
（操作/状態の変化（ラベル値同士、例:「新規作成→図確回覧」）/説明 の表。
|
||
Processesの内部処理・スクリプト名には触れず、「何が起きるか」を業務言葉で説明する）
|
||
|
||
## 4. 通知される場面
|
||
（Notificationsを「◯◯時に誰に何が届くか」という箇条書きに変換。メール本文・件名の技術的書式は転記しない）
|
||
|
||
## 5. 関連する仕組み（マスタ連携）
|
||
（Links・暗黙的テーブル参照を「◯◯マスタ：何を自動反映するか」という業務目線の箇条書きに変換。
|
||
SiteIdやColumnNameは書かず、サイト名（Title）とその役割のみ記載。
|
||
兄弟サイト（同じ設計パターンの別サイト）があれば、違いを1文で触れる）
|
||
```
|
||
|
||
### 作成時の注意
|
||
|
||
- 表内の「項目」列は必ずラベル名（LabelText）のみ。ラベル未設定の項目は概要書には載せない（業務上意味を説明できないため）。
|
||
- Statusの遷移は内部コード（100/300/900等）を書かず、ラベル値（新規作成／完了 等）同士の矢印で表現する。
|
||
- スクリプト内で見つけた秘密情報（APIキー等）は概要書には一切転記しない（そもそも概要書はスクリプト実装に触れない）。
|
||
- 複数サイト分をまとめて依頼された場合、共通する業務フローは重複して書いてよいが、各サイト固有の違い（段階数の違い、
|
||
追加の管理項目など）を各概要書の末尾で明示し、他サイトとの差分が一目で分かるようにする。
|
||
|
||
## 複数サイトの全体関連図（site-relations_overview.md）
|
||
|
||
`config.json` の `SiteId` に複数サイトが列挙されている場合など、「全体の関連図を作って」「サイト間の連携をまとめて」
|
||
等の依頼があれば、個々のサイト仕様書とは別に `./docs/site-relations_overview.md` を作成する。対象は
|
||
`config.json` の `SiteId` に列挙された全サイト（または依頼で指定された範囲）。
|
||
|
||
### 出力ファイルと構成
|
||
|
||
`./docs/site-relations_overview.md`（同名`.pdf`も作成対象）。以下を1枚で俯瞰できるようにまとめる。
|
||
|
||
```markdown
|
||
# サイト関連図：{システム名など}
|
||
|
||
## 1. サイトツリー（ParentId）
|
||
（`ParentId` を辿った親子関係を、簡易的なツリー表記かMermaid `graph` で図示。
|
||
各ノードにSiteIdとサイト名（Title）を併記）
|
||
|
||
## 2. サイト一覧
|
||
（SiteId/サイト名/役割（1行）の表。概要書へのリンクも併記）
|
||
|
||
## 3. 明示的な連携（Links）
|
||
（各サイトの`Links`設定を 起点サイト/起点列/参照先サイト/参照先の値→コピー先 の表にまとめる。
|
||
Idではなくサイト名で表現し、業務的に何を自動反映しているかも一言添える）
|
||
|
||
## 4. 暗黙的な連携（ServerScriptsのハードコード参照）
|
||
（ServerScripts内で`items.Get(SiteId)`等により直接SiteIdを指定して他サイトを参照している箇所を洗い出し、
|
||
起点サイト/参照先サイト/該当スクリプトファイル/目的（推測） の表にまとめる。
|
||
正式なLinks設定には現れないため、レビュー上重要な情報として明記する）
|
||
```
|
||
|
||
### 作成時の注意
|
||
|
||
- 各サイトの `spec.md`（7. 他サイト連携）で洗い出した内容を集約すればよい。個別spec.mdより先に全サイト分の
|
||
spec.mdを作成しておくと効率的。
|
||
- サイト名はTitleを使い、SiteIdは補助情報として併記する（概要書と違い、こちらは技術仕様書寄りの位置づけのため
|
||
SiteId自体は隠さなくてよい）。
|
||
|
||
## PDF化
|
||
|
||
概要書（または他のMarkdown）をPDF化する依頼があった場合は、プロジェクトルートの `md-to-pdf.js` を使う。
|
||
|
||
```
|
||
node md-to-pdf.js ./docs/site-{SiteId}_{サイト名}_spec.md ./docs/site-{SiteId}_{サイト名}_overview.md
|
||
```
|
||
|
||
- 追加npmパッケージ非依存（本プロジェクトに`package.json`が無いことに合わせた設計）。Markdown→HTML変換は
|
||
スクリプト内の簡易パーサ（見出し/表/太字/リンク/箇条書き/水平線/段落）で行い、PDF化はOS標準のMicrosoft Edge
|
||
（無ければGoogle Chrome）のヘッドレス印刷機能を使う。
|
||
- 出力は入力と同じフォルダに`{同名}.pdf`（中間HTMLは一時フォルダに作成し、変換後に自動削除）。
|
||
- 複数ファイルを一度に渡せる（`node md-to-pdf.js ./docs/*.md`）。
|
||
- **既知の落とし穴**: フォルダパスに`#`を含む場合（例: `#GitHub`）、素朴に`file://` + パス文字列を連結すると
|
||
`#`以降がURLフラグメントと誤認識され、無関係なページが開かれてPDFの中身が空／別物になる。
|
||
`md-to-pdf.js`は`url.pathToFileURL()`で正しくエンコードしているため通常は問題にならないが、
|
||
同種のブラウザ自動化コードを新たに書く場合は同じ罠に注意する。
|
||
|
||
## 関連ツール：Scripts/Styles/ServerScripts/Processesの抽出・編集・反映
|
||
|
||
仕様書化とは別に、「スクリプトを個別ファイルに分けて」「プロセス設定を直して反映して」等の依頼では、
|
||
以下のツールチェーンを使う（詳細は `README.md` 参照）。
|
||
|
||
1. `node get-site-config.js` … `siteSettingJsons/site-{SiteId}_latest.json` を取得し、続けて自動的に抽出も行う
|
||
（`extract-site-config.js` が内部から呼ばれ、`configs/site-{SiteId}_{サイト名}/` に以下を分割保存する。未取得なら先にこれを実行）
|
||
- `scripts/{Id}_{Title}.js`（クライアントスクリプト本体）
|
||
- `styles/{Id}_{Title}.css`（スタイル本体）
|
||
- `serverscripts/{Id}_{Title}.js`（サーバースクリプト本体）
|
||
- `html/{GuideName}.html`（GridGuide等のガイドHTML。SiteSettingsではなくサイトデータ直下の項目）
|
||
- `processes.json`（`SiteSettings.Processes` の定義ファイル、1ファイルにまとめる。分割しない）
|
||
- `manifest.json`（上記ファイルとId/Titleの対応表。再構成に必須）
|
||
- 抽出だけをやり直したい場合（`latest.json`は既に取得済み）は `node extract-site-config.js` を単独実行してもよい
|
||
2. ユーザーの指示に従い、`scripts/*.js` 等の中身を直接編集する（`manifest.json` のId/メタ情報は変更しない）。
|
||
新規追加の場合は `manifest.json` に対応エントリ（`Id`は既存と重複しない値、`File`名）を追加してからファイルを作成する。
|
||
3. `node build-desired-config.js site-{SiteId}` … 分割ファイルを再構成し `desired_config.json` を生成（送信なし）。
|
||
フォルダ名はサイト名まで含む正式名（`site-{SiteId}_{サイト名}`）だが、`site-{SiteId}` の前方一致指定でも
|
||
`configs/`配下から自動解決される
|
||
4. `node apply-site-config.js` … ドライラン確認（差分・送信Body・curlコマンド表示のみ、送信なし）
|
||
5. 内容をユーザーに確認してもらい、問題なければ表示されたcurlコマンドをユーザー自身が手動実行する
|
||
|
||
### 厳守事項（安全設計）
|
||
|
||
- **`apply-site-config.js` は常にドライラン。Claude自身がAPIへ実送信することはしない**
|
||
（`ENABLE_ACTUAL_SEND` を有効化する改修や、curlコマンドの代理実行も行わない）。
|
||
反映の最終実行はユーザー自身に委ねる。
|
||
- `build-desired-config.js` が作る `desired_config.json` は `Mode:"partial"`（`updatesitesettings`）専用。
|
||
Scripts/Styles/ServerScripts/Processes以外のサイト設定には触れない。
|
||
- ガイドHTML（`html/*.html`）は `updatesitesettings` では反映できない（サイト直下の項目のため）。
|
||
反映が必要なら `Mode:"full"`（`updatesite`）用の別JSONが要ることをユーザーに伝える。自動生成はしない。
|
||
- 抽出したスクリプト・サーバースクリプトの中に **APIキーやWebhook URL等の秘密情報がハードコードされている場合がある**
|
||
（実例あり）。抽出・編集作業でこれらの値を見つけたら、チャット上にそのまま貼り付けず、ユーザーに直接ファイルを確認してもらう。
|
||
また `siteSettingJsons/` フォルダ・`configs/` フォルダ・`config.json` は `.gitignore` 済みだが、誤ってコミットしないよう注意喚起する。
|