shop-tools（仮称）

店舗向けのツール（セルフレジアプリ＋POS/PSP連携＋非換金ポイント）。決済そのものは自前運用せず、資金と指図を持たないことで規制外に寄せ、ソロで回せる形を狙う。

コンセプト

  1. セルフレジアプリを店舗に提供（レジSIM・会計UX・タブレット/スマホ）。
  2. 店舗と銀行/PSPをつなぐが、資金と指図は持たない（決済は店舗の口座/PSPに委譲）。
  3. **ポイントは「換金しない」**店舗内ポイントとして台帳管理。
  4. 提供者はソフトウェアベンダーに徹する（＝規制の外に寄せる）。

V1 設計の要点（2026-10）

  • カートは顧客PWA、確認と決済開始は店員PWA、決済は Square Terminal
  • 顧客が6桁コードを表示 → 店員が入力 → BE が注文をそのレジに claim → Terminal へ
  • 商品マスタ・在庫・税・売上レポートは Square を正とし、BE は参照＋キャッシュ
  • 構成：CloudFront（PWA）＋ API Gateway/Lambda/DynamoDB（BE）＋ SSM
  • デモは Terminal モック（店舗PCの Node）で配布キット化
  • 本番は Cognito・既存 Square アカウント／ロケーションを使用
  • 現金は V1.1 で追加可（Terminal 非対応。Payments API で記録。ドロワーは手動／Square POS 併用）
  • 対象：SKU 〜100 程度、量り売りなし、1店舗1〜数レジ
  • イベント物販は派生モード：予約（在庫引当）→ 受取時に検品＋決済。事前決済なし（event-merch.md）

詳細は design.md を参照。

ソロ適性（大枠）

項目 評価
型 B（ツール/サービス）＋D依存（銀行API/PSP、運用は持たない）
ライブオペ 中（店舗導入・POS連携・サポート）→ BaaS/PSPで軽減可
発見 中（SaaSは棚が混む。店舗向けは事例/紹介/営業が効く）
経済・コミュニティ 低〜中（B2B単体は可。ポイント横断流通を狙うと一気に重くなる）
規制・信託・不正 設計次第（下記「やらないこと」を守れば軽い）
総合 ○〜◎

やらないこと（非目標 / 規制線）

  • 資金移動（預かって送る）
  • 収納代行・決済代行（振込先/金額を銀行へ伝達）→ 電子決済等代行業の登録が必要になり得る
  • 換金できるポイント（前払式支払手段/資金移動に抵触し得る）
  • 与信・立替・前払い

→ これらは V2（パートナー必須・ソロ不可に近い） として切り分ける。

V1 の決済は店舗の Square 口座に直接入金され、当方は資金を預からない。SaaS 化する場合は店舗ごとに OAuth でトークンを分離する（production-migration.md）。

V1スコープ

含む 含まない
顧客PWAのカート・合計・6桁コード 現金決済（V1は対象外、V1.1で追加可）
店員PWAの確認・決済開始 返金UI（Square Dashboard）
Square Terminal 決済／モック 在庫管理・発注
Square カタログ参照 重量・量り売り
店舗別・レジ別の分離、2レジ同時 オフライン決済
本番移行を見据えた環境分離 非換金ポイント（別フェーズ）
店舗・イベントの物販（単一の販売主体） フリーマーケット（個人出品・現金中心・古物市場主許可）

ファイル索引

ファイル 内容
../OPERATIONS.md 運用マニュアル（AWS/Cloudflareデプロイ、MFA、起動/停止、データ操作、障害対応）
business-case.md 事業性・強みの整理（模倣性、コンテンツ文脈、運用知、データ、販路、事業モデル、ソロ適性、検証質問）
design.md V1 設計書（アーキテクチャ、データモデル、状態遷移、API、認証、拡張、リスク、M0–M8）
staff-pos.md 店員POSモード（V1のカート/検索/決済、共通パッケージ、スキャンの将来対応）
terminal-options.md 端末選定・制約・調達（Square Terminal/POS/Reader比較、切替時間、キャンペーン）
catalog-inventory.md カタログ・在庫・引当（Square Catalog/Inventory、同期、可用数、カート下書き）
aws-cost-security.md AWSコスト・セキュリティ（無料枠、削減策、DoS段階、認証/署名/IAM）
refactor.md 共通化リファクタ（共有パッケージ、サーバーヘルパー、店員アプリ分割、スクリプト共通化）
square-terminal.md Square Terminal API の連携詳細（ペアリング、Orders/Terminal、Webhook、Sandbox テストID、日本固有事項、エラー）
demo-kit.md 配布キット仕様（Windows/Mac、Terminal モック、GMeet 台本、受入条件）
production-migration.md 本番移行（環境分離、SSM/Cognito、マルチ店舗、既存 Square アカウント、切替フェーズ）
event-merch.md イベント物販モード（予約・在庫引当・受取枠・検品・受取時決済・残数表示）
pilot-league.md リーグ戦物販パイロット計画（ソロの線引き、RACI、KPI、当日 Runbook、相談事項）
cost-scale.md 費用感と規模（物販1ブース基準の比較。LivePocket/TIGETは「無理に乗せた場合」の参考である旨を注記）
auction.md オークション用途の可能性（ロット・入札・時間窓・落札・受取時決済、法務・KPI。現行テストでは未実施）
concept.md 初期コンセプト詳細（V1/V2 の分岐、規制の線引き、MVP、リスク、未解決の問い）

実装状況（ローカル）

  • ローカル開発: npm run dev（Docker の DynamoDB Local、mock、AWS不要）
  • AWS MFA: MFA_TOTP_SECRETはAuthenticatorの秘密鍵と同等。.envを共有・コミットしない
  • AWSデモ: npm run aws:mfa → npm run aws:check → npm run deploy -- -Yes → powershell -File scripts\pages.ps1 -Yes。起動/停止は npm run aws:demo:*、データは npm run aws:data:*
  • 注文・claim・ロック・checkout・カタログ/在庫・引当・カート下書き・同期設定・Square webhook は実装済み
  • AWSバックエンド＋Cloudflare Pages（管理画面含む）をデプロイ済み。本番Square/実Terminalは未検証
  • PWA は manifest とアイコンのみ。Service Worker 未登録のため、現状はブラウザ運用
  • スマホは Cloudflare Pages（HTTPS・*.pages.dev）から開く。ローカル常駐は不要（demo-kit.md）
  • 検証: npm run verify（unit 57 / integration 14 / local 29 / UI 20）。SAM E2E は npm run test:e2e

次のアクション

  • M0：基盤（SAM、DynamoDB、SSM、health、config）
  • M1：core（状態機械・claim・ロック）＋ unit テスト
  • M2：Catalog（seed/Square）＋注文API（実Squareは未検証）
  • M3：Adapter（mock/Square）＋checkout＋webhook（実Terminalは未検証）
  • M4：Cognito（現状はPIN/JWT。staff APIは実装済み）
  • M5：PWA登録（顧客/店員のWeb画面・タイル・検索は実装済み）
  • M6：Terminal モック＋起動パネル（Win/Mac。実機Terminalは未対応）
  • M7：契約テスト→sandbox→本番パイロット
  • M8：スキャン実機検証（iOS/Android）
  • V1.1：現金対応（Payments API、ドロワー運用、返金・日締め）
  • 店舗との合意：既存 Terminal の再ペアリング、レシート運用、返金運用