trades-builder

取引業務スキル

このスキルでできること

このスキルでは、建設業の専門工事業者や現場サービス事業者が日々運用する、見積もりから支払いまでのワークフローを管理する取引業務ツールの構築方法を定義します。

汎用的なプロジェクト管理ツール（Jira／Asana）ではありません。CPQ ツール（製品構成の設定機能）でもありません。次のような業務を行う事業者に特化したワークフロー管理ツールです。

• 実測した作業項目（平方フィート、リニアフィート、数量）に基づいて見積もりを作成する
• 現場作業を職人チームや下請け業者に割り当て、スケジュールを設定する
• 作業項目と場所ごとに進捗を追跡する
• 実測した作業の完了状況に基づいて下請け業者に支払う
• 顧客に請求し、支払いを回収する

一般的な業種： 石膏ボード、屋根工事、HVAC、配管、電気工事、塗装、床工事、コンクリート、造園、総合建設。

ビルダーはこのスキルと、業種固有の用語を記載したDOMAIN.mdを読み、顧客が実際に使用している作業項目、価格、ワークフローの各段階を用いた動作するプロトタイプを生成します。

このスキルを使用する場合

トランスクリプトまたはDOMAIN.mdに、次のような手がかりが含まれている場合にこのスキルを使用してください。

手がかり	例
測定値を伴う作業項目	平方フィート、リニアフィート、ボードフィート、面積あたりの数量
現場のスケジュール管理	職人チームの割り当て、作業カレンダー、現場作業の計画
下請け業者への支払い	下請け業者への支払い、専門工事業者への支払い、平方フィートあたりの支払単価
見積もりから請求書までのワークフロー	見積もり → スケジュール設定 → 作業 → 請求書のサイクル
業種固有の作業範囲	断熱材、石膏ボード、テーピング、屋根工事、骨組み、配管の粗工事
場所に基づく仕様	階、部屋、ゾーンごとの異なる仕様
二重の請求処理	専門工事業者への請求書（下請け業者への支払い）と顧客への請求書（顧客からの入金）の両方

次の場合には、このスキルを使用しないでください。

• 依存関係を伴う製品構成 → cpq-builder を使用
• 在庫と資材の管理 → erp-builder を使用（今後対応）
• 汎用CRMまたは連絡先管理 → crm-builder を使用

---

テンプレートの仕様

構築を始める前に、テンプレートが提供するものと、このスキルで追加するものを把握してください。以下が仕様です。

テンプレート（app/layouts/MainLayout.tsx）に含まれるもの：

• SidebarProvider、Sidebar、SidebarContent、SidebarInset、SidebarTrigger — すでに接続されています
• SidebarContent は空です — ここを実装の起点にします
• ヘッダーにブランド用スロットが1つあります（ロゴのプレースホルダーと会社名）
• ヘッダー右側のグループに ModeToggle とユーザーメニューがあります

このスキルで実装するもの：

• SidebarContent — 縦型ステッパーと保存済みプロジェクトを追加します（下記のレイアウトパターンを参照）
• ヘッダーのブランド用スロット — DOMAIN.mdに記載された顧客のロゴと会社名を追加します
• ヘッダー右側のグループ — 既存のユーザーメニューの前にロール切り替え用の DropdownMenu を追加します
• <main> 内の <Outlet /> — 5つのセクションそれぞれにルートコンポーネントを配置します

このスキルでは行わないこと：

• 2つ目の Sidebar コンポーネントを追加する。サイドバーは1つです。
• SidebarContent 内にブランドタイルを配置する。ブランドはヘッダーにのみ配置します。
• SidebarProvider を再接続したり、折りたたみ動作を置き換えたりする。既存のものを使用してください。
• メインコンテンツ領域にステッパーを横並びのタブとして配置する。ステッパーは SidebarContent 内の縦型リストです。

MainLayout.tsx を再構成したくなった場合は、いったん止めてください。ほとんどの場合、答えは SidebarContent を実装することです。

---

セクションの定義

trades-builder ツールには5つのセクションがあります。これらは固定であり、トランスクリプトに記載された業務プロセスではなく、このスキルによって定められています。

セクション 1：見積もり

機能： プロジェクトの詳細を入力し、作業範囲に基づく見積もりを作成します。

プロジェクトの詳細（インライン編集可能）：

• プロジェクト名 — インライン編集可能なテキスト（クリックして編集し、フォーカスを外すと保存）
• 顧客名 — インライン編集可能なテキスト
• 住所 — インライン編集可能なテキスト
• 見積もり番号 — 自動生成、読み取り専用
• リードの獲得元 — DOMAIN.md で獲得元が定義されている場合は Select ドロップダウン、定義されていない場合は自由入力
• 見積もり担当者のメモ — Textarea、常に編集可能

作業範囲項目のテーブル（このセクションの中心）： このテーブルはアプリ内で最も重要な要素です。各行は、数量を測定した作業範囲を表します。

列	種類	編集可能	備考
作業範囲	Select ドロップダウン	はい	DOMAIN.md の選択肢：断熱材、乾式壁、テーピング、サンディング、清掃、下塗りなど
場所	テキスト入力	はい	例：「メインフロアのリビングルーム」「地下室のスイート」
仕様／種類	テキスト入力または Select	はい	例：「Type X」「耐湿性」「R-20 バット断熱材」「レベル 4 仕上げ」
平方フィート	数値入力	はい	この場所における作業範囲の面積
単価	数値入力	はい	1 平方フィートあたりの金額（CAD）
行合計	計算値	いいえ	平方フィート × 単価。自動計算
アクション	削除ボタン	—	ゴミ箱アイコンで行を削除

• テーブルの下にある 「行を追加」ボタン で作業範囲項目を追加
• 作業範囲の種類ごとに複数行を追加可能 — 例：場所や種類の異なる乾式壁の行を 2 つ追加
• 自動計算されるフッター： 小計、税（GST 5%）、合計 — セルの変更ごとに更新
• すべてのセルを直接編集可能 — セルをクリックして入力し、フォーカスを外すと保存されます。インライン編集のパターンについては frontend-design skill を参照してください。

使用する DOMAIN.md のデータ：

• Entity Registry → Job Specification のサブ項目を「作業範囲」ドロップダウンの選択肢にする
• Business Rules → 単位（平方フィート、直線フィート）、税の種類と税率、支払い条件
• Terminology Glossary → 正確な作業範囲名（一般的なラベルではなく）

セクション 2：スケジュール

機能： 現場作業の担当者と順序を計画します。

フィールド（編集可能）：

• 担当する役割／人物 — DOMAIN.md の Stakeholder Map から選択する Select ドロップダウン。自由入力にはしないでください
• 作業範囲の順序 — 各作業範囲をどの順番で実施するかを示す、並べ替え可能なリスト
• 開始日 — 日付ピッカー、編集可能
• 完了予定日 — 日付ピッカー、編集可能
• 現場作業員向けメモ — Textarea、編集可能

DOMAIN.md にスケジュール管理ツールが記載されている場合（例：「スケジュール管理には Bold」）、セクションの説明に記載してください：「Bold を使って現場作業員の予定を調整します。」

セクション 3：進行中

機能： 作業範囲項目と場所ごとの作業完了状況を追跡します。

表示内容：

• 見積もりの作業範囲項目から作成されるテーブル — 同じ行を使って、完了状況を追跡します

列	種類	編集可能	備考
作業範囲	テキスト	いいえ	見積もりから取得
場所	テキスト	いいえ	見積もりから取得
平方フィート	数値	いいえ	見積もりから取得
ステータス	Select ドロップダウン	はい	未着手／進行中／完了

• ステータスの変更は localStorage に即時保存
• 一括更新用の「すべて完了にする」ボタン
• 進捗インジケーター：「5 件中 3 件の作業範囲項目が完了」

セクション 4：精算

機能： 二重の支払いフロー（下請け業者への支払いと顧客への請求）に対応します。

表示 — 2 つの請求セクションを横並びに表示：

業者請求セクション：

• 下請け業者への支払い額 — 完了した作業項目から自動計算（平方フィート × 単価）
• ステータス：Select ドロップダウン — 支払い準備完了 / 支払い済み
• 支払日 — 日付選択。ステータスが「支払い済み」の場合に編集可能
• DOMAIN.md に記載がある場合は Bold を参照

顧客請求セクション：

• 請求額 — Estimate の小計 + 税

• ステータス：Select ドロップダウン — 送信準備完了 / 送信済み / 支払い済み

• 請求日 — 日付選択。編集可能

• DOMAIN.md に記載がある場合は Arvest を参照

• プロジェクトを完了としてマークする「案件を精算」アクションボタン

• 両方の請求ステータスを localStorage に保存する必要があります

DOMAIN.md に請求ツールについて記載がある場合、セクション見出しでそれらを参照します：「業者請求（Bold）」と「顧客請求（Arvest）」。

セクション 5：案件サマリー

機能： 完了したプロジェクトの読み取り専用サマリーです。最終出力を表示します。

レイアウト（上から下へ）：

1. 会社ヘッダー — domain.md の Brand Logos セクションにあるブランドロゴ（指定されたロゴの URL またはパスを使用）+ 会社名 + 仮の住所（「123 Main St, City, Province, Postal Code — 設定で更新してください」）
2. プロジェクトのメタデータ — プロジェクト名、顧客、住所、見積番号、日付、担当者。ラベルと値を 2 列のグリッドで表示します。
3. 作業範囲サマリーテーブル — すべての作業項目について、作業範囲の種類、場所、仕様／種類、平方フィート、単価、明細合計を表示します。数値列を右揃えにした見やすい Table を使用します。
4. 合計ブロック — 小計、税（GST 5%）、合計。合計は大きく太字で表示します。
5. 支払いステータス — 業者請求ステータスバッジと顧客請求ステータスバッジを横並びで表示します。
6. 条件 — 支払条件（Net 30）、通貨（CAD）。

このビューは完全な読み取り専用です。 編集コントロール、入力欄、ドロップダウンはありません。変更する場合は、ステッパーで Estimate または Schedule に戻ります。案件サマリーは出力であり、作業画面ではありません。

レイアウトパターン

trades-builder ツールは、5 つのセクションから成る3 パネルレイアウトを使用します（4 つではありません）。ビルダーはこのレイアウトに従う必要があります。

左サイドバー（常に表示、折りたたみ可能）

テンプレートには SidebarProvider、Sidebar、SidebarContent、SidebarTrigger がすでに app/layouts/MainLayout.tsx に設定済みです。SidebarContent は空で、このスキルが内容を配置する場所です。サイドバーを再設定したり、2 つ目の Sidebar コンポーネントを追加したり、ブランドタイルをその中に配置したりしないでください。ブランドアイデンティティはヘッダーにのみ配置します（上記の Template Contract を参照）。

サイドバーの見出し：「ワークフロー」や「プロジェクトワークフロー」など、文脈に合ったラベルを使用します。会社名は使用しません。見出しにはナビゲーションの内容を記述します。

コンポーネント	内容
ステッパー	SidebarContent 内に 5 つすべてのセクションを縦に並べます：（1）Estimate、（2）Schedule、（3）In Progress、（4）Close Out、（5）Job Summary。各ステップには、ステップ番号、ラベル、セクションの説明から取ったサブタイトル、完了状態を表示します。サイドバー内の縦型ステッパーを使用します。メインコンテンツ領域に横並びのタブを配置してはいけません。
保存済みプロジェクト	localStorage に保存されたプロジェクトのリスト。各項目には、名前 + 顧客 + ステータスバッジ（見積済み / 予定済み / 進行中 / 完了）を表示します。このセクションをサイドバーの下部に固定し、スクロールしなくても常に表示されるようにします。プロジェクト名をダブルクリックすると、インラインで名前を変更できます。

重要：ステッパーのラベルは DOMAIN.md ではなく、このスキルから取得します。 DOMAIN.md の状態モデルには estimated, scheduled, in progress, completed が記載されている場合があります。これらはバッジに使用するプロジェクトのステータス値です。ステッパーのラベルは、このスキルのセクション名である Estimate、Schedule、In Progress、Close Out、Job Summary です。この 2 つは別のものです。ステッパーは 5 ステップ、ドメインのステータスは 4 つです。ステッパーのラベルにドメインのステータス一覧を使用しないでください。5 ステップではなく 4 ステップになり、Close Out と Job Summary が抜けてしまいます。

メインコンテンツ（中央 — セクションごとに切り替わります）

アクティブなセクションのみを表示します。 すべてのセクションを、1 つのスクロールページに積み重ねて表示しないでください。複数のセクションを 1 つのパネルにまとめないでください（例：「Schedule / In Progress / Close Out」を 1 つのセクションにするのは誤りです。それぞれ独立したパネルにします）。横並びのタブは使用しないでください。ステッパーの各ステップでは、対応するパネルをメインコンテンツ領域の全幅で表示します。それ以外のパネルはすべて非表示にします。

実装：currentStep 状態変数（0–4）を使用します。currentStep に一致するパネルのみをレンダリングします。

// ALL FIVE panels, conditional rendering
{currentStep === 0 && <EstimatePanel />}
{currentStep === 1 && <SchedulePanel />}
{currentStep === 2 && <InProgressPanel />}
{currentStep === 3 && <CloseOutPanel />}
{currentStep === 4 && <JobSummaryPanel />}

セクション	表示内容
見積もり	プロジェクト詳細フォーム＋行の追加・削除、数量、単価、自動計算される合計を備えた作業範囲項目テーブル。「見積もりを保存」ボタンと「スケジュールへ進む」ボタン。
スケジュール	（DOMAIN.md に基づく）役割／作業員の割り当てドロップダウン、作業範囲の順序、日付フィールド、現場メモ。「進行中へ進む」ボタン。
進行中	行ごとのステータスを表示する、場所別の作業範囲追跡テーブル。「完了にする」ボタン。
完了処理	取引先請求書セクション＋顧客請求書セクションを横並びで表示。「案件を完了処理する」ボタン。
案件の概要	会社ヘッダー、作業範囲テーブル、合計、支払い状況を含む、読み取り専用の書式設定済みプロジェクト概要。

右サイドバー（常に表示）

コンポーネント	内容
プロジェクト概要	現在のステージ、見積もり番号、支払い条件、小計、税額、合計を含む、リアルタイムで更新されるサイドバー概要。作業範囲項目の変更時に更新します。
ワークフローメモ	DOMAIN.md のビジネスルールを、状況に応じたガイダンスとして表示します。BR-ID を参照します。
アクション	戻る、続行、プロジェクトを削除するボタン。主要なアクションにはブランドのアクセントカラーを使用します。

RBAC の動作

• DOMAIN.md の「User Roles」または「Stakeholder Map」に記載された役割で localStorage を初期化します。
• 役割切り替え機能には、ヘッダーバーに単一の DropdownMenu ドロップダウンを使用します。個別のボタンは使用しません。アクティブな役割名とバッジを表示します。
• 承認の制御：DOMAIN.md で完了処理または承認が特定の役割に限定されている場合、それ以外の役割では該当するボタンを無効にします。
• 役割ごとのビュー：役割によって特定のステージを担当する場合（例：見積もりは見積もり担当者、スケジュールはプロジェクトマネージャーが担当）、その役割がアクティブなときに関連するコンテキストを表示します。

価格の表示

• 「見積もり」パネルに価格を表示します。単価、明細合計、小計、税額、合計を含めます。
• 右サイドバーの「プロジェクト概要」に進行中の合計を表示します。
• DOMAIN.md に記載された通貨、税の種類、税率を使用します。
• 通貨コードを付けて価格を表示します（例：「$3,900.40 CAD」、または「$3,900.40」と表示し、概要に「CAD」を表示します）。

shadcn/ui コンポーネントのマッピング

カードは例外として扱い、デフォルトのレイアウト要素にはしないでください。可能な限り、コンテンツをページ本文に直接配置します。カードを使うのは、強調、分離、繰り返し、ダイアログや詳細の枠組みが本当に必要な場合だけです。カードを多用したダッシュボード、カード内のカード、浮遊パネルの汎用グリッドは作成しないでください。

Trades-ops 要素	shadcn コンポーネント	使用上の注意
プロジェクト詳細フォーム	Input、Label、Select	プロジェクト名、顧客、住所。ラベルは入力欄の上に配置します。
作業範囲項目のテーブル	Table、TableHeader、TableRow、TableCell	行を追加／削除します。数値列は右揃えにします。
作業範囲項目のステータス	Badge	未着手 = outline、進行中 = blue、完了 = green。
プロジェクトのステータスバッジ	Badge	見積済み = amber、予定済み = blue、進行中 = blue、完了 = green。
役割バッジ	Badge	スタッフ = outline、承認者 = default。
担当者のドロップダウン	Select、SelectContent、SelectItem	DOMAIN.md に記載されたステークホルダー名を入力します。自由入力欄にはしないでください。
請求書のステータスセクション	Separator、Badge、Select、Input を使ったインラインセクション	業者請求書と顧客請求書を横並びにします。請求書をより明確に分離する必要がある場合のみ、カードを使います。
アクションボタン	Button	プライマリ：ブランドアクセント、「続行」。セカンダリ：outline、「戻る」。破壊的操作：「プロジェクトを削除」。
ステッパーナビゲーション	カスタムの縦型リスト	SidebarContent 内に配置します。円の中にステップ番号、ラベル、サブタイトル、完了チェックマークを表示します。状態の指定には cn() を使います。
役割切り替え	DropdownMenu	ヘッダー内にドロップダウンのトリガーを1つだけ配置します。
プロジェクト概要サイドバー	ラベルと値を縦に並べたインライン表示	ラベルは控えめに、値は太字にします。合計行は大きく目立たせます。
ワークフローメモ	コンパクトで控えめなメモブロック	BR-ID を記載した参照資料です。
日付フィールド	type="date" の Input	開始日、完了予定日。
メモ／テキストエリア	Textarea	見積担当者のメモ、現場作業員のメモ。
確認ダイアログ	AlertDialog	プロジェクトの削除、作業の完了処理。
トースト通知	Sonner / toast()	保存後、完了としてマークした後、完了処理の後に表示します。

決定論的なマッピングルール

エンティティ → 作業範囲項目のマッピング

Knowledge Agent がトランスクリプトからエンティティを抽出する際は、Trades-builder の構造にマッピングします。

DOMAIN.md のエンティティ	マッピング先	セクション
プロジェクト／作業	プロジェクトレコード（最上位）	すべてのセクション
見積もり	見積もりデータ（価格、条件）	見積もりパネル
作業仕様／作業範囲	作業範囲テーブルの行	見積もり + 進行中
請求書	顧客請求書セクション	完了処理
業者請求書	業者請求書セクション	完了処理
下請け業者への支払い	業者請求書の支払いステータス	完了処理
現場スケジュール	スケジュールデータ	スケジュールパネル

ビジネスルール → 検証のマッピング

DOMAIN.md のルールパターン	実装
「平方フィートで記録」	作業範囲テーブルの数量列に平方フィートを使用
「平方フィート単位で支払い」	業者請求書の金額 = 完了した作業範囲項目の（平方フィート × 単価）の合計
「場所ごとに異なる［タイプ］」	作業範囲テーブルに場所列を含め、作業タイプごとに複数行を用意
「ステージ：見積済み、予定済み、進行中、完了」	ステッパーのステージを正確に一致させる
「手動入力」	プロジェクト作成フォームを使用し、インポートフローは設けない
「GST/HST は X%」	見積もりと請求書に税額行を追加し、税種別をラベルとして表示
「Net 30/45」	支払い条件を概要と請求書に表示
「［役割］のみが［操作］可能」	該当するボタンに RBAC の制限を設ける

インテグレーション → 参照のマッピング

DOMAIN.md にインテグレーション先（例：Bold、Arvest、QuickBooks）が記載されている場合は、セクションの説明とワークフローメモで言及します。ただし、インテグレーション用の UI は作成しないでください。プロトタイプは localStorage のみを使用します。インテグレーションは完全版の構築時に実装します。

参照ファイル

このスキルでは、以下のファイルが存在することを想定しています。

ファイル	用途
DOMAIN.md または .tasks/domain.md	ビジネス用語、エンティティ、ルール、役割、ブランドデータ

ビルダーはコードを書く前に DOMAIN.md または .tasks/domain.md を読む必要があります。