代理店制度 — 2形態設計の仕様報告
💬 コメントのしかた: 各見出しの「コメント」ボタンからメモを残せます。コメントはこのブラウザに保存され (他の人には見えません)、右上「コメント書出」で Markdown ファイルとして回収できます。レビュー後に書出ファイルを送付してください。
目次
§1 エグゼクティブサマリー
第三者が「代理店」として toyomart プラットフォーム上で店舗を運営できる制度を、2つの形態で設計する。
| Bフランチャイズ | A独立店 | |
|---|---|---|
| 一言で | 本店の商品を「自分の看板」で紹介・販売し、コミッションを得る | プラットフォーム上に自分のお店を開く。商品・デザイン・発送を自分で定義 |
| 商品・価格 | 本店カタログ・本店価格 | 代理店が独自定義 |
| 代金の入金先 | 本店 (toyomart) が受け、コミッションを月次精算 | 代理店に直接入金 (Stripe Connect)。本店はプラットフォーム手数料のみ |
| 実装状況 | 設計+実装済み (draft) spec 120/121/122 — マージ裁定待ち | 未着手 新 epic 相当。本資料が初回提案 |
| 規模感 | 小 (残りはレビューと pilot 運用) | 大 (マルチテナント化 + 決済 + 店舗デザイン) |
推奨
B → A の順で進める。B は一番重い部分 (権限分離・顧客帰属・コミッション・月次精算) が ADR 込みで設計実装済みで、draft PR 3本の裁定とマージで pilot 開始できる。A は B の土台 (代理店登録・審査・ポータル) を約2〜3割流用できるが、カタログのマルチテナント化と Stripe Connect という新しい大きさが要るため、spec-kit で新規設計する。
本報告で裁定いただきたい事項 (詳細は §7): ① draft PR 3本のマージ最終承認、② B の拡張範囲 (店舗別商品選定を入れるか)、③ A の着手可否と時期、④ A の金銭フロー方式 (Stripe Connect 直接入金 vs 本店代理受領)、⑤ プラットフォーム手数料率、⑥ ドメイン戦略 (パス /a/<slug> vs サブドメイン)。
§2 背景と現状 — すでに設計済みの資産
2-1. 発端
2026-08-08 / 08-09 のオーナー会話で代理人制度が具体化し、epic issue #327 と子 issue 8本 (#328–#335) に分解された。当時の要件メモ (原文):
2026-08-09 オーナーヒアリング原文
代理店注册进去进入他的后台 / 代理人后台:出店、顾客、商品、通知、营业状况 / 给代理开店专属角色:能管自己店、看不到总店和其他店数据 / 二级域名、店铺模板信息、新增商品、新增客户、收款方式、佣金计算、营业额统计形式:代理名.主站域名(如 xxx.toyomart.shop)、独立访问、专属入口、别人打不开 / 商品:从总店商品库选(统一进价/售价)或自主新增 / 收款:款进总店再结算
2-2. epic #327 の子 issue と対応状況
| issue | 内容 | 状況 |
|---|---|---|
| #328 | 代理店ロールと店舗単位の権限・データ分離 | spec 120 で設計+実装 (draft #428) |
| #332 | 代理店顧客の帰属ルールと再割当 | spec 120 (帰属 cookie + referred_by_agency_id) 再割当は未設計 |
| #334 | コミッションの計算・改定・取消 | spec 121 (draft #437) |
| #335 | 売上・コミッション・精算ダッシュボード | spec 120/121 (代理人ポータル /agency + admin 精算画面) |
| #330 | 店舗テンプレートと店舗情報管理 | spec 122 (draft #435) — 入口ページ1枚の範囲 |
| #333 | 入金先・支払方法・本店精算モデル | 方針確定 (本店受領+精算)・実装は spec 121。Connect 採用判断は ADR 送りと明記済み |
| #331 | 代理店の商品選定と独自商品登録 | 未設計 (§4-5 で選択肢を提示) |
| #329 | 代理店ごとのサブドメインとアクセス分離 | 未設計 — 現状はパス方式 /a/<slug> (§7 裁定事項) |
2-3. draft PR 3本の状態 (2026-08-27 実装完了、保留中)
| PR | spec | 内容 | DB 変更 |
|---|---|---|---|
| #428 | 120 (P1) | 代理店ロール・データ分離・顧客帰属 (referral cookie)・売上一覧ポータル・admin 代理店 CRUD | migration 0045: agencies / agency_users 新表 + customers.referred_by_agency_id / orders.agency_id / orders.commission_snapshot 加法列 |
| #437 | 121 (P2) | コミッション計上 (注文確定時 snapshot)・料率ルール・月次精算台帳・取消調整・精算 CSV | migration 0049: agency_commission_rules / agency_settlements 新表のみ |
| #435 | 122 | 店舗入口ページ /a/<slug> (ロゴ・ヘッダー・挨拶文の公開/非公開、画像アップロード) | migration 0048: agency_profiles 新表のみ |
3本とも stacked PR (#428 → #437 / #435) で、型チェック・lint・全パッケージテスト緑・実 D1 integration テスト・敵対的 route テストまで実施済み。あとはオーナー裁定とマージだけの状態。
2-4. 現行システムの前提 (A 形態の設計に影響)
- 単一店舗前提: 商品 (products/variants)・在庫・注文・配送設定・カテゴリはすべて「toyomart 本店」1店舗分。店舗を表す列は存在しない。
- 決済: Stripe は本店アカウント 1本 (B2C カード・WeChat Pay 等) + B2B 掛売。入金先は常に本店。
- 会計: 会計マスタは弥生側 (constitution 原則)。注文の弥生 export は本店分のみ。
- 認証: Cognito。account type (b2c/b2b/admin) に代理店ロールを追加する形が spec 120 で確定済み。
- 検索: FTS + search-worker は本店カタログ全体が対象。
§3 2形態の定義と比較
| 観点 | B フランチャイズ | A 独立店 |
|---|---|---|
| 業態の例え | 紹介・販売代理店制度 (アフィリエイト+歩合制営業) | マーケットプレイス出店 (BASE / Shopify / Amazon マーケットプレイス型) |
| 売る商品 | 本店カタログ (中華食材) | 代理店が自由に定義 (独自商品) |
| 価格決定権 | 本店 | 代理店 |
| 店舗デザイン | 共通テンプレート + 店舗情報 1枚 (ロゴ/ヘッダー/挨拶) | 代理店が定義 (自由度レベルは §5-4) |
| 在庫・発送 | 本店が担当 (既存の配送網・送料ゾーン) | 代理店が担当 (MVP)。本店発送代行は将来オプション |
| 顧客対応・返品 | 本店 (法令ページも本店のものを表示) | 代理店 (特定商取引法の表示主体も代理店) |
| 代金の流れ | 顧客 → 本店。本店 → 代理店へコミッションを月次精算 | 顧客 → 代理店 (Stripe Connect 直接入金)。本店は手数料を自動徴収 |
| 本店の収益 | 商品売上そのもの (コミッションは販売促進費) | プラットフォーム手数料 (売上に対して数%) または月額利用料 |
| 代理店になる想定 | 既存得意先・中華食材を扱いたい飲食店関係者など | 自社商品を持つ事業者 (食材に限らない可否は §7) |
| 法的主体 (販売者) | toyomart 本店 | 各代理店 (本店は場所と決済基盤を提供するのみ) |
重要な区別
B は「本店の売上を代理店が伸ばす」モデル、A は「代理店の売上から本店が場所代を取る」モデルで、金銭の流れの向きが逆。だから決済・精算・法的主体の設計を共有できず、A は B の延長では作れない (流用できるのは代理店登録/審査/権限分離の骨格のみ、§5-7)。
§4 形態B: フランチャイズ — 詳細仕様 設計+実装済み (draft)
4-1. ビジネスモデルと金銭の流れ
顧客B2C / B2B
──注文・支払──▶
toyomart 本店商品・在庫・発送・入金
──月次精算 (コミッション)──▶
代理店紹介・販売促進
- 代理店は専用の入口ページ
/a/<slug>(店舗名・ロゴ・挨拶) を持つ。購入自体は本店サイトで行われる。 - 入口ページを経由した顧客には referral cookie (
agency_ref、有効30日、HttpOnly / SameSite=Lax) が焼かれ、以降の注文が代理店実績として顧客と注文の両方に帰属する。 - 入金・返金・チャージバックはすべて本店の既存決済 (Stripe / 掛売) が処理する。代理店はお金を触らない。
4-2. 具体例で見る全体フロー
例: 代理店「大阪中華商行」(slug:
osaka-chuka、コミッション料率 5%)- 登録・審査: 店主が代理店を申請 → toyomart admin が審査し承認 (
agencies.status = active)、料率 5% を設定。店主は専用ポータル/agencyにログインできるようになる。 - 入口ページの公開: 店主がポータルで店舗名「大阪中華商行」・ロゴ・挨拶文を登録して公開 → URL
toyomart.jp/a/osaka-chukaを名刺・SNS・WeChat で配布。 - 顧客の来店: 9/1、田中さんが URL を開く → 入口ページから本店へ → cookie
agency_ref=osaka-chuka(30日) が焼かれる。田中さんはcustomers.referred_by_agency_idとして大阪中華商行に帰属。 - 注文とコミッション確定: 9/3、田中さんが ¥12,000 の注文。注文が
confirmedになった瞬間、その時点の料率でorders.commission_snapshot = {料率: 5%, 基礎額: ¥12,000, 金額: ¥600}が焼き込まれる (後から料率を変えても過去分は動かない = 非遡及)。 - 取消: 9/15、別の注文 ¥8,000 がキャンセル → snapshot が void 印になる。精算済み期間の取消なら次期精算で adjustment −¥400 として控除 (同じ取消を2度引かないガード付き)。
- 月次精算: 9月末、確定済みコミッション合計 12件 ¥7,400 − 取消調整 ¥600 = ¥6,800 の精算書が
pendingで生成される。代理人はポータルで「今月の見込み ¥7,400 / 確定済み精算履歴」をいつでも閲覧可能。 - 確定・振込: 10月上旬、admin が精算画面で内容を確認し「確定」→ CSV を出力 → 銀行振込。確定は二重実行できない (409)。
4-3. 機能詳細 (実装済み範囲)
| モジュール | 仕様 |
|---|---|
| 代理店登録・審査 | admin が代理店を作成 (slug は作成時のみ設定・変更不可)。状態: active / suspended / draft / expired。代理人アカウント (agency_users) を紐付け。 |
| 権限・データ分離 | 専用 gate が毎リクエスト DB で代理店と代理人の status を確認 (キャッシュしない) → 停止は再ログインなしで即座に効く。代理店向け API は代理店 ID を必須引数で強制する専用経路のみ。他店・総店のデータには型レベルで到達不能。admin トークンで代理人 API は 403 (兼務を暗黙に許さない)。 |
入口ページ /a/<slug> | 公開条件は店舗名のみ必須。ロゴ/ヘッダー/挨拶は任意で、未入力の区画は表示しない。画像は R2 に保存。未公開・停止中・存在しない slug はすべて同じ 302 を返すため、応答から代理店の存在を探れない。noindex + sitemap 非掲載。 |
| 顧客帰属 | referral cookie 30日。agencies.status = active なら入口ページが未公開でも cookie は焼く (URL を先に配った代理人の実績を消さない)。帰属は customers.referred_by_agency_id と orders.agency_id の両方に記録し監査可能。 |
| コミッション | 注文確定の全経路 (前払い決済通知 / 掛売の admin 状態変更 / 取消) で snapshot を焼く・void する。料率未設定なら焼かない (「0%と決めた」と「決め忘れ」を区別)。冪等: 決済通知再送・状態往復・backfill 連打でも二重計上なし (条件付き UPDATE)。 |
| 料率ルール | 率 1方式のみ (bps 単位)。agency_commission_rules は追記専用 (UPDATE/DELETE を発行するコードが 1行も無い) = 改定履歴が完全に監査可能。適用は注文確定時点の最新ルール。 |
| 月次精算 | agency_settlements (代理店×期間)。明細表は持たず、snapshot への stamp から導出 (金額の正は常に snapshot 1箇所)。基準日はコミッション確定日。取消は次期 adjustment。payable が負でも負のまま確定 (自動繰越という隠れ状態を作らない)。二重確定は 409。 |
代理人ポータル /agency | 売上・見込みコミッション・精算履歴。ja のみ。 |
| admin 画面 | 代理店一覧/詳細・料率設定・精算一覧/詳細・欠落回収 (backfill)・精算 CSV・注文詳細にコミッション行 (本店注文は null)。 |
| 会計境界 | 精算は弥生に出さない (会計マスタは弥生側の constitution 原則を維持。精算 CSV が振込根拠)。 |
4-4. 設計上の重要裁定 (ADR-0042 / ADR-0043)
- コミッションは「率」のみ: 粗利分配は原価データが無いため計算不能、階段式 (売上越多率越高) は非遡及 snapshot と両立しないため却下。
- snapshot 方式: 金額の正は注文に焼き込まれた JSON 1箇所。後からの料率改定・取消の影響範囲が限定され、監査に強い。
- 分離は gate + 型 の二重: 忘れやすい「スコープ条件」を port の必須引数にして、付け忘れを型エラーにする。
4-5. 未決の拡張 (B をどこまでやるかの選択肢)
| 拡張 | 内容 | 規模 | 論点 |
|---|---|---|---|
| ① 店舗別商品選定 (issue #331) | 代理店が「扱う商品」を本店カタログから選び、入口ページに並べる。独自商品の審査付き登録も可。 | 中 (新 spec) | 価格・在庫は本店固定か、上書き可にするか。上書き可にすると B と A の境界が曖昧になる。 |
| ② サブドメイン (issue #329) | osaka-chuka.toyomart.shop 形式の専用入口。 | 中 | wildcard DNS・host 解決・認証 cookie/OAuth の origin 問題・fail-closed 設計が要る。SEO 的にはパス方式でも大きな差はない。MVP は現行のパス方式 /a/<slug> で十分という判断が可能。 |
| ③ 店舗別ショッピング体験 | 入口ページから「その店の品揃え」を browse して注文する体験。 | 大 | ①の先。注文は本店カートに入るため、見た目だけ店舗化する形も可能。 |
| ④ 顧客帰属の再割当 (#332 後半) | 代理店同士の顧客引き継ぎ・紛争時の裁定 UI。 | 小〜中 | pilot で帰属紛争が実際に起きてからで良い (YAGNI)。 |
推奨まず現行 draft 3本 (= コミッション型フランチャイズの完成形) をマージし、1〜3店舗の pilot で運用を確認 (epic #327 の完了条件)。拡張 ①〜③ は pilot の実績を見てから個別裁定。
4-6. 残作業
- draft PR #428 → #437 / #435 の内容レビューとマージ裁定 (実装・テストは完了済み)
- マージ後、本番 deploy (migration 0045/0048/0049 はすべて加法のみ — 既存データ無変更で安全)
- pilot 代理店の選定・料率の決め方 (営業判断) ・審査基準の明文化
§5 形態A: 独立店 — 詳細仕様 (提案) 未着手・新 epic
5-1. ビジネスモデルと金銭の流れ
代理店が自分の商品・自分のデザイン・自分の発送で店舗を運営する。本店は「場所と決済基盤」を提供し、売上に対してプラットフォーム手数料を取る。
顧客
──支払 ¥5,000──▶
Stripe決済基盤
──売上入金 (処理手数料差引後)──▶
代理店「神戸食材店」商品・発送・返品対応
Stripe
──プラットフォーム手数料 (例: 8% = ¥400)──▶
toyomart (本店)場所・決済基盤の提供
本店は代金を受け取らないため、資金決済法上の資金移動 (他人の売上金を預かって後日払う) に該当しない形になる (下記 5-2 の方式比較を参照。最終判断は法務確認事項)。
5-2. 決済設計 — Stripe Connect
Stripe Connect は「プラットフォーム + 複数の販売者」向けの Stripe 公式機構で、代理店ごとの connected account を作り、入金を自動的に振り分ける。
| 方式 | 販売者 (merchant of record) | お金の流れ | 返金・チャージバック | 評価 |
|---|---|---|---|---|
| Direct charges (推奨) | 代理店。レシート・カード明細に代理店名が出る | 顧客 → 代理店へ直接入金。本店は手数料 (application fee) を自動徴収。Stripe 処理手数料は代理店負担 | 代理店の残高から。対応も代理店 | 「商品も店も自分で定義する」= 代理店が販売者、という A 形態の定義と一致。本店が資金を預からないので法的に最もクリーン。実装も最小 |
| Destination charges | 本店 (プラットフォーム) | 顧客 → 本店 balance → 代理店へ自動送金。Stripe 処理手数料は本店負担 (手数料に上乗せ計算が必要) | 本店の残高から。対応も本店 | チェックアウト体験を完全に本店統一したい場合の選択肢。不正・紛争の最終責任を本店が負う (Radar 必須) |
| 本店が代理受領 + 自社精算 (Connect 不使用) | 本店 | 顧客 → 本店 → 月次で代理店へ振込 | 本店 | 非推奨: 他人の売上金を預かって後日支払う形は資金決済法の資金移動業登録が問題になり得る (要法務確認)。精算・返金・税務の運用負荷も本店に集中 |
推奨構成 (Direct charges)
Stripe 最新の Accounts v2 API で
本店の収益 =
dashboard: full (代理店が自分の Stripe ダッシュボードで入金明細を確認できる) / 手数料・ 부정残高の責任: Stripe 側 / オンボーディング: embedded components (代理店の KYC 入力画面を本店サイト内に埋め込む。Stripe が要件収集と法対応の更新を面倒見る)。本店の収益 =
application_fee_amount (売上に対する率) または月額利用料、あるいは両方。Stripe 処理手数料は代理店負担なので、手数料率は「本店の取り分」としてそのまま残る (Destination 方式と違い処理手数料を被らない)。金銭例: 顧客が「神戸食材店」で ¥5,000 をカード払い (プラットフォーム手数料 8% の場合)
- 顧客のカード請求: ¥5,000 (明細表示は「神戸食材店」名義)
- 代理店への入金: ¥5,000 − Stripe 処理手数料 (率と額は stripe.com/pricing 参照・代理店負担) − プラットフォーム手数料 ¥400
- 本店の収益: ¥400 (application fee)
- 返金時: 代理店残高から返金。手数料の返却有無は設定で選択可能
留意
B2B 掛売 (請求書払い) は A 形態の MVP では対象外とする (掛売は本店与信管理そのものなので、代理店店舗に持たせると与信審査・債権回収の主体が崩れる)。A 店舗は前払いカード決済のみで開始。
5-3. アーキテクチャへの影響 (なぜ新 epic なのか)
現行システムは単一店舗前提 (§2-4)。A 形態は以下の広範な変更を伴う:
| 領域 | 必要な変更 | 規模 |
|---|---|---|
| カタログ | products / variants に店舗 (tenant) 次元を追加。商品所有権・審査フロー。画像は R2 prefix を店舗別に分離 (既存の store_<id>/agency-profiles/ 方式の延長) | 大 |
| 注文 | 注文に店舗 ID。店舗別 admin (注文管理・出荷)。注文番号体系。精算は Connect 側なので弥生 export は本店分のまま (会計境界は不変) | 大 |
| 決済 | Stripe Connect: connected account 作成・embedded onboarding・direct charges・application fee・返金/紛争 webhook・入金状態の同期 | 大 |
| 検索 | FTS / search-worker のインデックスを店舗単位に分離 (店舗内検索) + 横断検索をするか | 中 |
| 認証・権限 | agency_users の拡張 (店舗スタッフ複数人?)、代理店ポータルのスコープを「売上閲覧」から「店舗運営」へ拡大 | 中 |
| 配送 | 店舗別の発送 = 送料設定・配送ゾーンが店舗ごと (現行は本店 1式)。MVP は「店舗ごとの固定送料 or 送料無料」までで開始し、ゾーン別料金表は後続 | 中〜大 |
| ストアフロント | /shop/<slug>/* (またはサブドメイン) の店舗ページ群: 商品一覧・PDP・カート・決済。テーマ機構 (§5-4) | 大 |
| 法令表示 | 特定商取引法表示は各代理店が販売者として掲載 (店舗ごとに事業者名・住所・返品条件)。プラットフォームの役割も明記 | 小 (ただし全店必須) |
ここが一番の分岐点
「商品を tenant 化する」ことは DB スキーマ・検索・admin・ETL (ECMall 同期は本店専用)・注文取込 AI (本店商品マスタ前提) に波及する。既存 catalog の単純な tenant 化は issue #331 でも戒められており (「既存catalogを単純にtenant化せず、商品所有と在庫・価格のsource of truthをplan/ADRで決める」)、A0 フェーズで ADR を先に書く。
5-4. 店舗デザインの自由度 — 3レベル
| レベル | 内容 | コスト | 例 |
|---|---|---|---|
| L1: テンプレート + ブランディング (MVP 推奨) | 共通レイアウトの上に、ロゴ・メインカラー・バナー・店舗紹介文・SNS リンクを店舗別に設定。spec 122 の agency_profiles の延長で、平面テキスト+画像のみ (サニタイザ不要・XSS 面ゼロ) | 小 | BASE の「テーマ共通・色とロゴだけ変える」イメージ |
| L2: 複数テーマ | 数種類のレイアウトテーマを用意し店舗が選択 + L1 のブランディング | 中 (テーマ 1種作るごとにデザイン+実装+テスト) | Shopify の無料テーマ群 |
| L3: 完全カスタム (CSS/HTML 自由) | 店舗が独自 HTML/CSS を注入 | 大 + セキュリティリスク (XSS)・レスポンシブ保証・保守が本店に降りかかる | — |
推奨L1 で開始。「デザインを完全に自分で定義」の要望は L1 の範囲 (ロゴ・色・バナー・レイアウト内の自由) でも大部分満たせる。L2 は出店数が伸びて差別化要求が実際に出てから。
5-5. 具体例で見る開店フロー
例: 「神戸食材店」が出店する
- Day 0 — 申請: 事業者が代理店登録申請 (会社情報・販売予定品目)。admin が審査 (出品規約・禁止品目チェック)。
- Day 0 — Stripe オンボーディング: 承認後、ポータル内の埋め込みフォームで Stripe KYC (本人確認・口座登録)。所要 10〜30分程度、審査は Stripe 側。完了で connected account が active になり、入金可能状態になるまで「開店準備中」表示。
- Day 1 — 店舗設定: 店舗名・ロゴ・メインカラー・紹介文 (L1 ブランディング)、送料設定 (例: 全国一律 ¥800 / ¥10,000 以上無料)。
- Day 1-2 — 商品登録: 独自商品 30点を登録 (CSV 一括 or 1件ずつ)。本店カタログとは完全分離 — 本店の商品検索・取込 AI・ETL には一切現れない。
- Day 3 — 公開:
toyomart.jp/shop/kobe-shokuzai(またはkobe-shokuzai.toyomart.shop、§7 裁定) が公開。特定商取引法表示ページは店舗情報から自動生成。 - 運用: 顧客が ¥5,000 購入 → 入金と手数料分配は自動 (5-2 の例)。代理店はポータルで注文を確認し、自分で発送。返品・問い合わせも代理店が対応。
5-6. フェーズ案
| Phase | 内容 | 依存 |
|---|---|---|
| A0 テナント基盤 | 店舗スコープの ADR (商品所有・在庫・価格の source of truth)。catalog/orders の tenant 化。データ分離の gate 拡張 (spec 120 の方式を流用) | — |
| A1 決済 (Connect) | connected account + embedded onboarding + direct charges + application fee + webhook + 返金。Connect の ADR (issue #333 が「Connect 使う/使わないの判断は ADR に記録」と要求済み) | A0 |
| A2 店舗運営ポータル | 商品 CRUD・注文管理・出荷登録・売上/入金ダッシュボード (Stripe embedded components で入金明細を表示) | A1 |
| A3 ストアフロント | 店舗ページ群 (一覧/PDP/カート/決済)・L1 テーマ・法令表示・noindex 方針・URL 戦略 | A2 |
| A4 拡張 | 店舗別送料ゾーン・店舗内検索・複数スタッフ・本店発送代行オプション・L2 テーマ | A3 + pilot 実績 |
規模感: 各 Phase が既存 spec 1本分 (spec-kit 1サイクル) 以上。A 全体は B の比ではなく、月単位のプログラム。まず A0+A1 の spec を書き、pilot 1店舗で最小開店 → 反応を見て A2 以降を判断、を推奨。
5-7. 既存資産の流用
- 流用可 (~2-3割):
agencies/agency_users(代理店登録・審査・状態管理の registry として両形態共通)、agency-gate の分離パターン、/agencyポータルの骨格、agency_profiles(L1 ブランディングの入れ物)、R2 の prefix 分離方式。 - 流用不可: コミッション精算機構 (spec 121) — A では Connect が自動分配するため月次精算は不要 (B 専用として残る)。本店の配送ゾーン・送料 — 店舗別に再設計。
§6 2形態の関係とアップグレードパス
- 両立する:
agencies表を共通の代理店 registry とし、B (コミッション型) と A (出店型) はその上の2プラン。1つの代理店が B から始めて後で A を追加することも可能 (plan 列の追加で表現)。 - 自然な成長経路: B の代理店が「自分の商品も売りたい」となったとき、A への移行先がある。B 時代に獲得した顧客帰属 (
referred_by_agency_id) はそのまま維持できる。 - 順序が重要な理由: B を先にマージすれば、A の設計は「B で確定した分離・審査・ポータルの土台の上」に建てられる。逆に A から作ると B の draft 3本の前提 (単一カタログ・本店決済) を作り直しになる。
§7 リスクと未決の判断事項 (裁定リスト)
7-1. 上層部の裁定が必要な事項
| # | 事項 | 選択肢 | 推奨 |
|---|---|---|---|
| D1 | draft PR 3本 (#428/#437/#435) のマージ | 承認してマージ / 内容を見直して修正 / 保留継続 | 承認してマージ → B pilot 開始 |
| D2 | B の拡張範囲 | コミッション型のまま / 店舗別商品選定 (#331) を追加 / サブドメイン (#329) を追加 | pilot 後に個別裁定 (まずは現行範囲) |
| D3 | A の着手 | B pilot と並行して A0 spec 開始 / B pilot 完了後 / 見送り | B pilot の反応を見て A0 spec 着手 |
| D4 | A の金銭方式 | Direct charges (代理店が入金の主体) / Destination (本店が主体) / 本店代理受領 | Direct charges (5-2) |
| D5 | プラットフォーム手数料率 (A) | 数%〜十数%。月額利用料との併用可否 | 営業判断。初期出店を促すなら低率 or 無料期間 |
| D6 | URL 戦略 | パス /a/<slug>・/shop/<slug> / サブドメイン <slug>.toyomart.shop | MVP はパス方式。サブドメインは #329 の要件 (認証 cookie・OAuth・fail-closed) を満たす設計ができてから |
| D7 | 出店資格 | 既存得意先のみ / 法人限定 / 個人事業主も可 | A は審査基準を明文化した上で法人+個人事業主 (Stripe KYC が本人確認を担保) |
| D8 | A の取扱品目範囲 | 中華食材関連のみ / 制約なし | まずは食材関連 (プラットフォームのブランドと審査能力の範囲内) |
7-2. リスク一覧
| 区分 | リスク | 緩和 |
|---|---|---|
| 法務 | 本店が代理店の売上金を預かる形 (Destination / 代理受領) は資金決済法 (資金移動業) の問題があり得る | Direct charges 方式 (D4 推奨) なら資金が本店を通らない。最終確認は弁護士へ |
| 法務 | A 形態で各店舗の特定商取引法表示・返品条件・個人情報の取扱い (購入者情報は誰のものか) | 販売者=代理店として表示を必須化 (公開ゲート)。プラットフォーム規約で個人情報取扱いを定義 |
| 税務 | A の手数料収益の仕訳・インボイス制度 (適格請求書発行事業者は本店か代理店か) | Direct 方式なら代理店が販売者=請求書発行主体。本店は手数料分のみの請求。税理士確認 |
| ブランド | A 店舗の商品品質・発送遅延・紛争が toyomart ブランドに波及 | 出店審査 + 出品規約 + 停止機構 (spec 120 の毎リクエスト status 確認がそのまま効く) + 店舗評価の可視化 (将来) |
| 運用 | A は審査・サポート・紛争対応の運用コストが本店に発生 | pilot 1〜3店舗で運用コストを実測してから拡大 (epic #327 の完了条件と同じ思想) |
| 技術 | catalog の tenant 化は波及が広い (検索・取込 AI・ETL・admin)。設計を誤ると本店側の回帰リスク | A0 で ADR 先行。「加法のみ・本店経路を触らない」を migration 原則に (draft 3本が実証済みの作法) |
| 技術 | Connect は webhook (入金・紛争・アカウント状態) が増え、既存決済 webhook と並行管理になる | A1 で決済経路を provider 抽象 (spec 111 の 3軸分離) に載せる |
§8 ロードマップ提案
| Step | 内容 | 前提 | 規模 |
|---|---|---|---|
| 1 | B: draft 3本をレビュー・裁定・マージ・deploy | D1 | S (実装済み) |
| 2 | B: pilot 1〜3店舗で運用 (料率設定・精算サイクル・サポート負荷の実測) | Step 1 | S〜M (営業・運用が主) |
| 3 | B: 拡張裁定 (#331 商品選定 / #329 サブドメイン / 店舗別体験) | pilot 実績 | 裁定による |
| 4 | A: A0 spec (テナント基盤 ADR) + A1 spec (Connect 決済) を spec-kit で作成 | D3・D4 | M (設計) |
| 5 | A: A0/A1 実装 → pilot 1店舗で最小開店 | Step 4 | L |
| 6 | A: A2 (店舗運営ポータル) → A3 (ストアフロント+L1テーマ) → 出店拡大 | pilot 反応 | L |
| 7 | A: A4 拡張 (送料ゾーン・検索・スタッフ複数人・発送代行) | 出店数 | M〜L |
§9 付録
9-1. 既存資産一覧 (コード・issue・ドキュメント)
| 種別 | ID | 内容 |
|---|---|---|
| epic | issue #327 | 代理人登録・出店審査・代理人ダッシュボード (完了条件: pilot 1〜3店舗) |
| 子 issue | #328–#335 | ロール/サブドメイン/テンプレート/商品選定/顧客帰属/入金・精算/コミッション/ダッシュボード (§2-2) |
| draft PR | #428 (spec 120) | P1: ロール・帰属・売上一覧。migration 0045 |
| draft PR | #437 (spec 121) | P2: コミッション・月次精算。migration 0049 |
| draft PR | #435 (spec 122) | 店舗入口ページ /a/<slug>。migration 0048 |
| ADR | ADR-0042 | コミッション設計 (率1方式・snapshot・非遡及) |
| ADR | ADR-0043 | 代理店データ分離 (gate + 必須引数の二重) |
| 関連 spec | 111 / 113 | 決済 provider 抽象・決済手段 admin 切替 (A1 で接続点になる) |
9-2. 用語集
| 用語 | 意味 |
|---|---|
| コミッション snapshot | 注文確定時に「その時点の料率で計算したコミッション額」を注文行に JSON で焼き込む方式。後日の料率改定の影響を受けない (非遡及) |
| 精算 (settlement) | 期間内の確定コミッションを代理店ごとにまとめた台帳。pending → confirmed の2状態。取消は次期 adjustment で控除 |
| referral cookie | /a/<slug> 経由の来訪者に焼く 30日有効の帰属 cookie (agency_ref)。以降の注文を代理店実績にする |
| slug | URL に使う店舗識別子 (例: osaka-chuka)。作成時のみ設定・変更不可 |
| Stripe Connect | プラットフォーム + 複数販売者向けの Stripe 機構。販売者ごとに connected account を作り入金を自動分配する |
| connected account | Connect 上で代理店ごとに作られる Stripe アカウント。KYC (本人確認) は Stripe が実施 |
| merchant of record | 顧客に対する法的な販売者 (レシート・カード明細に出る名前、返品・紛争の責任主体) |
| Direct charges | connected account 上で課金する方式。販売者が merchant of record。Stripe 処理手数料は販売者負担 |
| Destination charges | プラットフォーム上で課金し販売者へ自動送金する方式。プラットフォームが merchant of record。Stripe 処理手数料はプラットフォーム負担 |
| application fee | Connect でプラットフォームが徴収する手数料 (売上に対する率 or 固定額) |
| embedded onboarding | Stripe 提供の KYC フォームを自サイト内に埋め込む方式。要件収集と法対応の更新を Stripe が担う |
| テナント (tenant) | 1つの DB・アプリを複数店舗で共用する際の「店舗」の単位。データ分離の境界 |