01背景
Fayman（فیمن）は、スーツ、ブレザー、パンツ、シャツ、靴、小物といったテーラードのメンズウェアをオンラインで販売しており、サイズガイド、生地ガイド、オーダーメイドのサービスも備える。ストアは2026年6月23日、Payload公式のecommerceテンプレートに最初の整理を加えたところから始まった。491コミットを経た9月15日には、その大半が置き換えられていた。
テンプレートには、動く商品カタログ、カート、注文モデルがあった。一方で、Stripe、米ドル、メールアカウント、ホスティング型のツールを前提にしていた。課題は、イランの顧客が最初の検索から返品申請まで使え、ストアのスタッフが開発者なしで運営できるストアに作り変えることだった。
最終的な518のソースファイルのうち、テンプレートから変わっていないのは80だった。決済、ログイン、購入手続き、通貨はまるごと置き換え、顧客アカウント、管理ツール、25のページブロックのうち17は新しく作った。
02課題
国際的なコマーステンプレートの前提は、設定で済ませるのではなく、どれも置き換える必要があった。
03私の役割
私はプロダクトをデザインし、その構築を指揮した。コードの大半は、書面の仕様をもとにAIコーディングエージェントが書いた。スコープ、デザインの方向性、そして本番へのリリースはすべて人が決めた。
生のコメントは、実際のコードと照らし合わせて調査し、エージェントが追加の質問なしに実装できる仕様にしてから渡した。本番へのリリースはすべて、追記専用のデプロイ台帳に記録される。
04システム
衣料品ストアは、検索から注文の配達までの道筋と、その道筋が途切れたときに何が起きるかで評価される。以下の各部分はデータを共有している。商品カードのバッジ、ショップのセールフィルター、カートの合計、銀行に送る金額は、すべてひとつの価格ルールから来る。
デザインには独自のレビューのループがあった。問題のスクリーンショット、コードとデザイン言語に照らした診断、カード、そして実装。9月12日までにデザインカードは63枚になり、そのうち55枚が完了していた。
ひとつの価格リゾルバーが商品カード、カート、明細、支払いチェックに値を渡すので、顧客が目にする価格が、そのまま銀行に請求される価格になる。
05商品探し
顧客は、シーン、カテゴリ、セール、検索、共有されたリンクなど、さまざまな問いからスーツにたどり着く。ホームページはそのいくつかに答え、どの答えも同じショップにつながる。
ホームの商品レールはひとつのブロック、Product Sectionから作られ、ソースは4種類ある。セール品のみ・在庫ありのみの切り替えが付いたカテゴリのルール、手動で選んだ商品、貼り付けたショップのURL、商品リンクのリスト。レイアウトはレール、グリッド、スポットライトの3種類。どのソースもショップ自身のクエリを通るので、何がセール中で何が在庫ありかについて、レールとショップの表示が食い違うことはない。編集者は現在、本番のホームページで、割引されたフルセットや単一サイズといったレールにこれを使っている。
シーンの列はカテゴリの列の上にある。顧客は「ブレザーが欲しい」ではなく「結婚式がある」から始める、というストアからのフィードバックに従った。ショップでは、すべてのフィルターがURLに保存される。生地、シーン、スタイル、トマンでの価格帯、在庫ありのみ、セール品のみ。在庫、セール、価格は同じサイズについて判定するので、セール中でも売り切れのサイズが商品を結果に引き込むことはない。スマートフォンではフィルターがシートとして開き、適用中のフィルターは外せるチップとして表示され続ける。
検索は最も弱い入口だ。商品タイトルにしか一致せず、アラビア語とペルシア語の字形の違いをまだ同じ文字として扱えない。ルックブックは編集コンテンツで、各ルックは単一の商品ではなく、絞り込まれたショップページにつながる。
フィルターはシートとして開く。
06商品ページ
テーラードの服をオンラインで買うときには、3つの疑問が生じる。サイズは合うか、何でできているか、合わなかったらどうなるか。商品ページはこの3つを軸に作り直した。ギャラリーの横に留まる購入カラム、在庫表示、配送と7日間返品の条件を示す信頼の列、サイズ・手入れ・配送のアコーディオン、そしてスマートフォンで常に手の届く購入バー。
サイズは事実を示す必要があった。8月13日の時点で、サイズのある25商品のうち23商品が、裏付けとなる在庫がなく販売できないサイズを少なくともひとつ提示していた。現在はひとつの共通ルールで、その商品では作られていないサイズを非表示にし、売り切れのサイズを選択不可にし、何も残っていない商品には«ناموجود»と表示する。残りが10点を下回ると、あと何点残っているかをページに表示する。
サイズガイドのSize Finderは、衣類の種類、好みのフィット、体の寸法を受け取り、ストアのサイズ表から答えを出す。2つのサイズの間なら大きいほうを選ぶ。詰めるほうが出すより安全だからだ。範囲外なら採寸の相談を案内し、シャツについては文字のサイズを推測する代わりに首回りの数値を示す。生地ガイドは生地を季節と用途に対応させ、各生地からその生地で絞り込んだショップへリンクしている。
未完成の部分が2つある。Size Finderは商品ページになく、各商品が実際に販売しているサイズを読み取らない。また、商品ページには各商品の生地が表示されない。
ローカルビルド、テストデータ。売り切れで選択不可のサイズがひとつ、選択したサイズ、在庫の確認、ボタン横の条件。
本番のストア。旧価格に取り消し線を引いた割引商品。
Size Finder。衣類の種類、フィット、寸法を入力すると、サイズが出る。
配送。方法、日数、送料無料の基準額。
07購入手続き
カートは、支払いチェックと同じリゾルバーでサーバー側で価格計算されるので、カートと銀行の金額が食い違うことはない。カートを開くと、現行のカタログから価格を計算し直す。本番環境では、未決済のカート15件のうち4件が古くなった合計を保持していた。明細には定価、商品割引、クーポンを別々の行で表示する。
購入手続きは1ページで完結する。スマートフォンでは注文の概要が最初に来る。ログインしていない顧客は、ページを離れずに携帯番号と6桁のコードでログインでき、新しい番号にはアカウントが作られる。保存済みの最初の住所があらかじめ選択される。表示するのはその注文で使える支払い方法だけで、ボタンには金額が入る。«پرداخت … تومان»。まだ使えないものは、グレーアウトしたコントロールではなく一文で説明する。たとえば、ウォレット残高が具体的にいくら足りないかを示す。
支払いは、イランのすべてのゲートウェイに共通のひとつのアダプターを通る。Zarinpal、Zibal、Torob Pay、SnappPay、DigiPay、そしてストアのウォレットだ。顧客を銀行へ送る前に、サーバーが合計を計算し直し、カートと1リアル単位まで一致しない限り請求を拒否する。注文は、ゲートウェイが支払いを確認して初めて作成される。コールバックが繰り返されても2件目の注文は作られず、10分ごとのジョブが、コールバックが届かなかった支払いを拾い上げる。
アダプターの形は、実際の不具合から生まれた。9月の2日間で、DigiPayには7件の修正が必要だった。購入手続きを壊した空のエンドポイント設定、正しい認証情報を無効に見せてしまうリクエスト形式、存在しないルートに当たったゲートウェイからの戻り、そして本番の支払いでリアルであることを確かめる必要があった金額の単位。それぞれがルールになった。DigiPayのエンドポイントは必須の設定で、空のときはゲートウェイを表示しない。どのゲートウェイも両方の種類の戻りリクエストを受け付ける。金額の単位は決して推測しない。
カート。定価、商品割引、クーポンを別々の行で表示。
08主要な意思決定
どれも、テンプレートの既定を、それが無視していた制約に合わせたものへ置き換えている。
価格は口頭ではトマンで伝えられるが、決済はリアルで行われる。すべての金額を整数のリアルで保存し、表示のための換算は1か所だけで行うので、10倍の誤りが請求に届くことはない。
ログイン、新規登録、購入手続きでは、携帯番号とワンタイムコードを受け取る。メールとパスワードのページは廃止した。どれもメールサービスなしには動かず、本番環境にはそれが一度もなかった。
09アカウント
再訪した顧客は同じ電話番号でログインし、人が戻ってくる目的に合わせて作ったダッシュボードにたどり着く。進行中の注文、ウォレット残高、保存した商品、未完了の返品、直近3件の注文。以前のページは設定フォームで、注文のステータスは上から3番目のパネルにあった。
注文一覧はステータスで絞り込め、商品サムネイルを表示する。顧客は注文をその中身で見分けるからだ。注文ページには、3段階の進捗（注文済み、処理中、完了）、購入時に支払った価格、住所、そして7日間の返品ボタンを表示する。表示するのはデータが裏付けるものだけだ。進捗の後の段階に日付がないのは、それぞれの変更がいつ起きたかをシステムが記録していないからだ。
返品申請では商品、数量、理由を選び、サーバーが所有者、7日間の期限、すでに返品された分を確認する。申請のステータスはスタッフが進める。お金が自動的に動くことはなく、スタッフが手作業で返金を顧客のウォレットに加えられる。ウォレットページは「なぜ残高がこの金額なのか」という疑問に明細で答える。各項目には理由、注文へのリンク、その時点の残高が付く。チャージボタンはない。チャージ機能は存在せず、ボタンを置けばそれを約束することになるからだ。
ここで保存した住所は、購入手続きで使うものと同じレコードだ。お気に入りは、ログインしている顧客の商品を保存する。設定には名前があり、確認済みの電話番号が表示されるが、そこでは変更できない。通知設定は保存されるが、まだそれに基づいてメッセージを送る仕組みはない。ログインコードを除けば、顧客にSMSは届かない。
ダッシュボード。進行中の注文、ウォレット、お気に入り、未完了の返品、最近の注文。
10コマースのルール
割引には2つの層がある。商品またはカテゴリに、ペルシア暦で開始日と終了日を設定した割引を付けられる。商品自体の割引が優先され、2つが重なることはない。その上でクーポンが、割引後の合計に対してカートごとに1回だけ適用され、支払いが確認されて初めて使用済みになる。٪のバッジ、取り消し線付きの価格、ショップのセールフィルター、セールのレールは、すべて同じルールを参照する。
この順序は、実際の買い物かごから学んだ。8月の6日間、クーポンが定価に適用されて商品割引を置き換えていたため、顧客に過大な請求が生じていた。弱いクーポンでは価格が上がることさえあった。現在、クーポンはカタログの割引の後に適用される。
在庫はサイズごとに管理する。支払いの開始時に確認し、銀行の確認後にひとつの保護された更新で差し引くので、最後の1点を2人が同時に買えてしまうことはない。その間に在庫が尽きた場合は、注文を返金済みとし、支払いの取り消しを試み、その注文のためにすでに差し引いた在庫を戻す。
スタッフは、各割引を有効、予定、期限切れ、オフ、使い切りのいずれかで表示する割引コンソールと、キャンペーン用の1回限りのコードを作るジェネレーターで、これを管理する。
11運営
スタッフがイランにいるため、管理画面はデフォルトでペルシア語になっており、割引の日付はペルシア暦で選ぶ。ページはブロックで組み立てる。テンプレートには8つ、ストアには25あり、そのうち17は新しく、Product Sectionからサイズガイド、FAQ、返品ポリシーまである。ヘッダーのリンク、フッターの列、SNSのリンク、カテゴリの順序は管理画面で編集する。
運営ツールは、スタッフが実際に行う作業のために作った。支払い済みの注文はオペレーターの確認を待ち、誰かが確認するまで赤で表示され続ける。サイズと在庫の画面は、各カテゴリのサイズ別在庫を示し、注文でまだ使われているサイズを削除する前に警告する。ウォレットのクレジットはリアルで入力し、入力欄の下にトマンでの金額を文字で表示する。クレジットは取り消せないからだ。
SMSは3つのイベントを扱う。ログインコード、スタッフへの販売通知、法人販売の新規リード。それぞれに編集できるテンプレートと専用の受信者がある。法人販売ページは50点以上の問い合わせをリードとして受け付ける。まとめ買いの価格設定や見積もりの仕組みはない。
2つの制約が残っている。管理者のロールはひとつだけで、権限を絞ったスタッフアカウントはない。また、Size Finderの裏にあるサイズ表はコードの中にある。
12イラン向け
右から左への対応は、direction属性だけでは終わらなかった。レイアウトは、テンプレートがまったく使っていなかった論理プロパティに移行した。カルーセルとギャラリーはキーボード操作でも読む方向に従う。電話番号、郵便番号、クーポンコードは、ペルシア語のフォームの中で左から右の入力欄に入る。価格はペルシア数字で表示し、日付はライブラリではなくブラウザ自身の暦のサポートを使ってペルシア暦で表示する。
デザイン言語は新しく作ったのではなく、既存のものを調整した。英語のソフトウェア向けに書かれた既存のシステムの上に調整レイヤーを置き、ペルシア語のメンズウェアストアと食い違う点を明記して、その場合は調整が優先すると定めた。最も明確なルールは、ペルシア語の字間をゼロにすることだ。字間を空けると、つながった文字が切れてしまうからだ。フォントはセルフホストしているので、ストアがGoogleを待つことはない。
お金は現地のルールに従う。整数のリアルで保存し、トマンで表示する。価格比較サイトが正しい数字を載せるよう、Torobの価格タグもトマンで出す。フッターにはE-namadの認証マークがあり、顧客はクリックしてイランの電子商取引登録簿を確認できる。9月27日の時点で、ストアの公開された購入手続きの設定には、Zibal、ウォレット、Torob Pay、DigiPayが並んでいた。
インフラは国内にとどまる。コードとイメージはセルフホストのGitサーバー、メディアはArvanCloudのストレージ、デプロイはCoolify経由、アナリティクスはセルフホストのUmami。アーキテクチャのメモは、このルールを率直に書いている。本番サイトがビルドとデプロイの時点で依存するものは、すべて国内から到達できなければならない。
ここに挙げた項目のうち、数字が抜け落ちるのではなく、自信満々に間違った数字を出すのはこれだけだ。
13信頼性
8月10日、ストアから、管理画面には表示されているのに404を返す商品が1件あるという報告があった。本番環境を読み取り専用で一斉点検すると、実際の規模がわかった。公開済みの166商品のうち113件にアクセスできなかった。2つのバグが重なっていた。Payloadのデフォルトのスラッグ関数がペルシア文字をすべて落とし、さらにNext.jsがペルシア語のスラッグをパーセントエンコードされたままページに渡していたため、正しいスラッグでも失敗した。まずコードを修正し、次に本番で113件のスラッグを修復した。2回目の点検では、166件すべてが200を返した。
リリースはひとつのローカルのゲートを通る。生成された型とインポートマップを確認し、続いて型チェック、lint、テスト、本番ビルドを行う。テストスイートは9月1日に約1,086件で、そのうち772件がユニットテストだった。9月12日には1,354件になった。本番へのリリースはすべて、追記専用のデプロイ台帳に記録される。その後、スモークスクリプトが各ゲートウェイの戻りルート、アナリティクス、ショップを確認する。スクリプト内のチェックはどれも、その不具合がかつて本番に到達したことがあるから存在する。
9月1日の依存関係の一斉点検では、古くなった58パッケージのうち54を更新した。検証済みの2回のバッチと、単独で行った9件のメジャーアップグレードに分け、残り4つを見送った理由も記録した。ページ速度の数値は一度も測定していないので、ここでも示さない。測定したビルドの変化はコンパイル工程のひとつだけで、88秒から18.2秒になった。
…顧客に見えるものは何も変わらなかっただろう。正しいペルシア語のスラッグでも404になっていたからだ。
14成果
2026年7月7日からfaymen.irで稼働し、決済を受け付けている。商業上の数値は公開していない。以下の数字は測定した修正で、それ以外は提供したスコープだ。
15学んだこと
「Docker Hubに到達できない」は、セール中に修正をリリースできるかどうかを決める。「メールサービスがない」は、本人確認、購入手続き、ニュースレターを書き換えさせた。
管理画面には表示されているのに404を返す商品が1件あるという報告は、コードとカタログに照らし合わせてみると、ストアの3分の2と、2つの別々のバグだった。
注文の進捗に日付がないのは、記録されていないからだ。読み込みに失敗した件数はゼロではなくダッシュで表示する。ウォレットにはチャージボタンがない。Size Finderは、ショップで売れないサイズを提示しない。
既存のデザイン言語を調整するほうが、新しく書くより安上がりだった。そして、ペルシア語の字間やイラストを使わないことといった食い違いが、その最も役に立つ部分になった。
戻る： 01 · 報告
適用中のシーンのフィルターは外せるチップとして残り、ボタンに件数が付く。
検索結果は、クエリで絞り込まれたショップそのものだ。
生地ガイド。どの生地がどの季節、用途、手入れに合うか。
FAQ。トピック別にまとめ、ペルシア語で検索できる。
ログイン前。まず概要、続いて携帯番号でのログイン。
6桁のコード。事前のアカウント登録は必要ない。
ログイン後。保存済みの住所、支払い方法、ウォレット残高の不足を文章で示す表示、ボタン上の金額。
テンプレートはブラウザから注文を確定していた。ここではサーバーが金額も含めてゲートウェイに支払いを検証し、その後で初めて注文を作成し、在庫を差し引く。
ウォレットはゲートウェイと同じアダプターに接続されるので、同じ合計チェック、重複防止、回復ジョブが適用される。台帳は追記専用で、管理者を含め誰も項目を編集・削除できない。
スタッフは支払い済みの注文を管理画面で1件ずつ確認する。これは5つ目のステータスではなく、確認ボタン付きの別のフラグだ。ステータスは顧客に表示されるので、内部の工程が顧客に届くべきではないからだ。
コード、コンテナイメージ、メディアストレージ、デプロイ、アナリティクスはすべてイラン国内で動くので、GitHubやDocker Hubに到達できないときでも修正をリリースできる。
ウォレット明細。ギフトクレジット、ウォレットで支払った注文、返品の返金。