ケーススタディ1: 多言語のランディング + 決済ページ
アイデア
ある友人が、韓国へ移住する駐在員向けに29ドルのPDFガイドを売っています。彼女は、世界中で速く読み込まれ、英語・韓国語・中国語に対応し、サーバーに一切触れずにカード決済ができる1枚のページが欲しいと考えていました。
仕様
コードを書く前に、仕様は1段落に収めました。
29ドルのデジタル商品向けの1ページのマーケティングサイトを作って。
3言語(en/ko/zh)。ブラウザから自動検出するが、トグルで切り替え
可能にする。1つの「購入」ボタンでStripe Checkoutを開き、成功時に
サンクスページへリダイレクトする。私が保守するバックエンド
サーバーは無し。どこからでも速く読み込めること。
仕様が何を言っていないかに注目してください。フレームワーク無し、デザインシステム無し、アナリティクス無し、メール収集無し。そのどれもがもっともな機能だったでしょうし、そのどれもが最初のローンチを遅らせたでしょう。1段落の仕様という規律は、その大部分が何かを削ぎ落とす規律です。
スタック
「私が保守するバックエンドは無し」と「世界中で速く」という条件は、エッジCDN上の静的ホスティングと、唯一シークレットを必要とすること(Stripeセッションの作成)のための小さなサーバーレス関数を、まっすぐ指し示していました。私たちはCloudflare Pages上の静的サイトと、1つのPages Functionを選びました。アーキテクチャ全体が一文に収まります — 1つの関数を呼び、その関数がStripeと話す静的ページ — そしてその単純さこそが、後でデバッグ可能にしたものでした。
鍵となったプロンプト
広い指示から始め、AIに構造を提案させました。
静的なランディングページ(素のHTML/CSS/JS、フレームワーク無し)を
en/ko/zhの言語トグル付きでスキャフォールドして。文言は言語をキーと
した1つのJSオブジェクトに格納する。デフォルトはnavigator.languageから
検出する。index.html 1つと main.js 1つに収めること。
それから、シークレットが存在する決済パスです。
/api/checkout に Cloudflare Pages Function を追加して。29ドルの単一
商品のStripe Checkoutセッションを作成し、リダイレクトURLを返す。
STRIPE_SECRET_KEY は環境変数から読み、絶対にハードコードしない。
購入ボタンはこの関数にPOSTし、返ってきたURLへ window.location する。
「絶対にハードコードしない」という一句は、その居場所をきちんと得ています。デフォルトに任せると、AIは例を「動く」ように見せるためにプレースホルダーのキーを平気でインラインに置き、プレースホルダーはやがて本物のキーとなって出荷される傾向があります。プロンプトの中で一度声に出して言うほうが、レビューで捕まえるより安上がりです。
障害
最初のライブテストは失敗しました。購入ボタンは何も起きず、ブラウザのコンソールにCORSエラーが出ました。私たちは推測しませんでした。正確なエラーを貼り戻したのです。
購入をクリックすると次のログが出る: 「Access to fetch at
'/api/checkout' blocked by CORS policy.」 関数とページは同じ
ドメインにある。これが関数のコード: [貼り付け]。実際の原因は何?
AIは即座に見抜きました。関数はStripeのURLをJSONで返していましたが、関数の OPTIONS プリフライトが処理される前にfetchが行われていたのです。なぜなら、私たちが静的ページと関数を誤って2つの別々のPagesプロジェクトにデプロイしていたからでした。本当の修正はコードではなく、デプロイのトポロジーでした。関数を同じプロジェクトの /functions ディレクトリに移動すると、エラーは消えました。
この教訓は噛みしめる価値があります。症状はコードにありましたが(fetchから出たCORSエラー)、原因はインフラにありました(1つではなく2つのプロジェクト)。もし構成を貼り付けずにAIに「CORSエラーを直して」と任せていたら、AIは Access-Control-Allow-Origin ヘッダーを付け足したでしょう — コンパイルは通り、症状を覆い隠し、本当のバグを生かしたままにする修正です。文字どおりのエラーとともに周辺のコンテキストを貼り付け、自分の構成に合わない最初のもっともらしい説明を鵜呑みにしないこと。
ローンチ
私たちは本番のStripeキーを暗号化された環境変数としてPagesのダッシュボードに追加し(リポジトリには絶対に入れない)、彼女のドメインのDNSをPagesに向け、カードで本物の29ドルのテスト購入を1回実行してから返金しました。失敗パスもわざとクリックしてみました — 拒否されるテストカード — 彼女が課金されず、空白の画面ではなくまともなメッセージを見られることを確認するためです。午後のうちにライブになりました。彼女はその晩に最初の売上を上げました。