customware-email

Customer Email

Customware が生成したアプリに、一貫性のある Customware メール機能を実装します。この機能は、プロビジョニング済みの Postmark インバウンド Webhook を通じて顧客からの返信を受け取り、同じ開発用 Postmark サーバーの HTTPS API を通じて顧客向けメッセージを送信します。

このタスクでは、プロジェクト固有のアドレスが指定されます。2 つの管理対象サーバー ENV 値で認証情報を指定します。このスキルでは、実装方法、永続的な動作、検証の契約を定めます。

既存のアプリに合わせて実装してください。 Hono のルート、Drizzle のスキーマ、SQLite データベース、ロギング、エラー処理、Result のパターンを再利用してください。ネイティブな小規模インテグレーションのほうが、2 つ目のメールフレームワークを導入するよりも把握しやすく、安全です。

---

最初に読む資料

ソースファイルを編集する前に、次の資料を読んでください。

1. references/common-architecture.md — タスクの入力、プラットフォームの境界、認証情報、スタック、共通のインテグレーション構成。
2. references/inbound.md — 固定 Webhook、認証、受信記録の永続化、重複排除、復旧の契約。
3. references/outbound.md — Postmark API への直接送信、メッセージ形式、送信者と返信先のルーティング、障害処理。
4. references/common-quality.md — 検証、安全なロギング、マイグレーション、テスト、最終検証。

タスクが最初は一方向の機能に思えても、インバウンドとアウトバウンドの両方の資料を読んでください。返信を扱うには、両方向が 1 つの機能として連携する必要があります。インバウンドメールがアプリに届き、アウトバウンドメールの返信先が同じ仮想アドレスにルーティングされなければなりません。

<read_order>

実装前に、対象リポジトリの AGENTS.md、Builder タスクの全文、関連するプロジェクトドキュメント、既存のデータベース／ルート／サービスの契約も読んでください。フレームワークの詳細がここでの例と異なる場合は、対象リポジトリを正としてください。

</read_order>

固定プラットフォーム契約

項目	必須の決定事項
Postmark サーバー	このプロジェクト用にすでにプロビジョニングされている開発サーバーを 1 つ使用します。アプリからサーバーを作成、削除、設定してはいけません。
インバウンドルート	POST /api/email/inbound
インバウンド認証	HTTP Basic Auth を使用します。ユーザー名は customware、パスワードは POSTMARK_INBOUND_WEBHOOK_SECRET から取得します。
サーバー認証情報	サーバー上でのみ POSTMARK_INBOUND_WEBHOOK_SECRET と POSTMARK_SERVER_TOKEN を読み取ります。
インバウンドアドレス	タスクで指定された正確な仮想アドレスを使用します。このアドレス用の ENV を作成してはいけません。
アウトバウンド送信者	タスクで指定された正確な送信者を使用します。現在は [email protected] です。このアドレス用の ENV を作成してはいけません。
アウトバウンドストリーム	Postmark の既存の Default Transactional ストリーム（outbound）を使用します。
通信方式	サーバーコードから、HTTPS リクエストを直接 Postmark の Email API に送信します。
SMTP	SMTP を有効にしたり、使用したりしてはいけません。
Customware ゲートウェイ	Customware の送信エンドポイント、プロキシ、メールゲートウェイを追加してはいけません。
本番環境	タスクで説明されている開発機能を実装します。本番サーバー、公開、環境分岐の動作を追加してはいけません。

<address_source_of_truth>

タスクの説明を、仮想インバウンドアドレスとアウトバウンドの From アドレスの正とします。各値はサーバー側で管理する 1 つの定数／モジュールに置き、送信者、返信先のルーティング、レビュアーが確認できるコードの間で値が食い違わないようにしてください。どちらの値もプレースホルダー、推測したアドレス、新しい ENV に置き換えてはいけません。

</address_source_of_truth>

絶対に守ること

• Postmark の認証情報は両方ともサーバー専用にしてください。ブラウザーコード、VITE_*、HTML、JSON レスポンス、タスク出力、ログ、クライアントの状態には絶対に含めないでください。
• .env と .env.* はアクセスできないものとして扱ってください。ファイル操作コマンドで調べないでください。実行時の確認には、環境変数の値を出力せずに node --env-file=.env ... を使用できます。
• 静的ファイルの配信と SPA フォールバックより前に、受信ルートを登録してください。
• 受信したメールを確認応答する前に永続化してください。200 レスポンスは、生の受信データを復旧できる状態にあることを示すものであり、アプリケーションでの処理が完了したことを示すものではありません。
• データベースで MessageID の一意性を保証してください。読み取り後に挿入する方式で重複排除を実装しないでください。
• クラッシュや再起動の後も受信処理を復旧できるようにしてください。インメモリのコールバックだけを作業の記録として使わないでください。
• 受信リファレンスに記載された契約上のステータスを返してください。この受信処理で Postmark に 403 を絶対に返さないでください。
• 送信メールはサーバーコードからのみ送信し、X-Postmark-Server-Token と MessageStream: "outbound" を使用してください。
• タスクの仮想受信アドレスを ReplyTo に設定し、顧客からの返信が既存のウェブフックに戻るようにしてください。
• メッセージの内容と認証情報をログに出さないでください。安全な運用識別子とエラーカテゴリーだけを記録してください。
• 既存の契約とエラー／結果の規約を再利用してください。重複するバリデーション、推測に基づく抽象化、互換性のための分岐、2 つ目の永続化フレームワークは避けてください。

実装ワークフロー

1. タスクの契約を確認する

1. タスク全体を読んでください。
2. 仮想受信アドレスと送信元アドレス（From）を正確に抽出してください。
3. タスクに customware-email と記載され、Postmark サーバーがすでにプロビジョニング済みであることを確認してください。
4. いずれかのアドレス、または管理対象の認証情報の契約が利用できない場合は、明確な action_required 結果を返して中止してください。値を推測してはいけません。

2. 生成されたアプリを調べる

Hono のエントリーポイント、ルートの登録順序、静的ファイルとフォールバックのハンドラー、Drizzle のスキーマとマイグレーション、クエリー／サービスの規約、環境変数ヘルパー、ログ記録の境界、既存の Result／Zod パターンを特定してください。受信メールをアプリの顧客ワークフローで処理する場所と、既存のビジネスアクションから送信メールを生成する場所も特定してください。

3. サーバー共通の基盤を構築する

タスクで指定されたアドレスと、管理対象の 2 つの ENV 読み取りを扱う、小規模なサーバー管理のメール設定モジュールを 1 つ作成してください。Postmark クライアント／アダプターは、アプリ既存の結果とエラーのパターンに従う、用途を絞ったものにしてください。ブラウザーからのリクエストによって、サーバートークン、From アドレス、ReplyTo アドレス、ストリーム、Postmark URL を選択できないようにしてください。

4. 受信と送信を実装する

受信処理と永続化可能なワーカーについては、references/inbound.md に従ってください。Postmark Email API アダプターと、アプリ向けの送信ヘルパーについては、references/outbound.md に従ってください。メール用の別システムを作るのではなく、両方を既存のドメインフローに統合してください。

5. 段階的に検証する

実装中は契約に関するチェックを重点的に実行し、その後、リポジトリ標準のフォーマット、lint、型チェック、ビルド、ユニットテスト、対話型チェックを実行してください。references/common-quality.md のテストマトリックスを使用してください。外部送信が求められる場合は、明示的に承認された安全な宛先だけを使用してください。それ以外の場合は、Postmark クライアントをスタブ化したテストとルートレベルのテストで、正確なリクエストを検証してください。

6. 最終監査を行う

最終差分から、認証情報名、ハードコードされたシークレット、SMTP の使用、POSTMARK_ACCOUNT_TOKEN、本番環境用の分岐、ブラウザーから Postmark への直接呼び出し、生のメールを記録するログ、2 つ目のゲートウェイを検索してください。タスクで指定されたアドレスだけが生成されたアプリケーションコードに埋め込まれていることを確認し、データベースのマイグレーションが含まれ、アプリ標準のコマンドで適用されていることを確認してください。

完了チェックリスト

• タスクで指定された正確な受信アドレスと送信アドレスが、サーバーが所有する単一の設定モジュールで使用されています。
• POSTMARK_INBOUND_WEBHOOK_SECRET で受信ルートを保護し、POSTMARK_SERVER_TOKEN で送信 HTTPS 呼び出しを認証しています。
• 受信ルートで生の JSON を取得し、MessageID を検証してから 200 を返す前に永続化しています。データベース制約で重複を防ぎ、保留中または古い処理を復旧します。
• 送信リクエストでは POST /email、X-Postmark-Server-Token、MessageStream: "outbound"、タスクで指定された From、およびタスクで指定された受信アドレスの ReplyTo を使用しています。
• SMTP、生メール、アカウントレベルのプロビジョニング、本番環境の動作、および Customware 送信ゲートウェイは含まれていません。
• 機密値とメッセージ内容は、ブラウザーバンドル、レスポンス、ログに含まれていません。
• マイグレーション、対象を絞ったテスト、リポジトリチェック、ビルド、および関連するブラウザー検証がすべて成功しています。
• サインオフ前に、最終差分とレビュアーの要件を読み返しています。

境界

生成されたアプリの Customware メール実装には、このスキルを使用します。Customware コントロールプレーンは、Postmark サーバーのプロビジョニング、暗号化、非表示 ENV のマテリアライズ、サンドボックス再起動時の Webhook URL の調整、クリーンアップ、および公開保護を担います。生成されたアプリでこれらの責務を重複して実装しないでください。

AI ゲートウェイまたは AI Elements の作業には customware-ai、サポートウィジェットには customware-support-widget、Builder タスクで完全なゲート付き実行プロトコルが必要な場合は task-workflow を使用します。これらのスキルはこのスキルを補完するものであり、ここに記載されたメールの契約に取って代わるものではありません。