shop-tools オペレーションマニュアル

• 対象: AWSバックエンド + Cloudflare Pages のデモ環境
• 作成日: 2026-10-31
• 状態: デプロイ済み（実Square・実Terminalは未検証）
• 関連: plans/demo-kit.md / plans/aws-cost-security.md / plans/refactor.md

Web版（docsサイト）では、認証・デプロイ・本番設定の手順を除外しています。完全版はこのファイルを参照してください。

1. 構成

スマホ/PC
  │
  ├─ Cloudflare Pages（静的配信・HTTPS）
  │    ├─ customer   顧客アプリ + /launcher
  │    ├─ staff      店員アプリ
  │    └─ terminal   Terminal（モック）
  │
  └─ AWS
       ├─ API Gateway HTTP API
       ├─ Lambda（API / WebSocket / Webhook / 同期）
       ├─ DynamoDB（注文・在庫・カタログキャッシュ）
       ├─ SSM Parameter Store
       └─ EventBridge（15分同期）

• ローカルにVite/Nodeを常駐させない
• 画面はCloudflare Pages、動的処理はAWS
• ブラウザはconfig.jsのapiBaseでAWS APIへ直接接続（CORS）
• WebSocketはAPI Gatewayへ直接接続
• Square WebhookはLambda Function URLで受信

2. 今回の環境

Cloudflare Side:

• shoptools-dev-customer
• shoptools-dev-staff
• shoptools-dev-terminal
• shoptools-dev-admin

3. 必要環境

ローカルPC

• Windows 10/11 + PowerShell 5.1
• Node.js 22以上 / npm
• Git

AWS

• AWS CLI v2
• AWS SAM CLI
• AWSアカウント
• 作業IAMユーザー（この環境では dev0）
• MFAデバイス（TOTP）
• CloudFormation / Lambda / API Gateway / DynamoDB / SSM / IAM / S3 / EventBridge / CloudWatch Logs の権限

Cloudflare

• Cloudflareアカウント（Free）
• API Token（Account → Cloudflare Pages → Edit）
• Account ID

任意

• Docker Desktop（sam local / ローカルDynamoDBを使う場合）

6. 動作確認

API

$api = "https://e0shjjq6ll.execute-api.ap-northeast-1.amazonaws.com"
Invoke-RestMethod "$api/api/health"
Invoke-RestMethod "$api/api/bootstrap"

CORSプリフライト

curl.exe -i -X OPTIONS "$api/api/staff/login" `
  -H "Origin: https://shoptools-dev-staff.pages.dev" `
  -H "Access-Control-Request-Method: POST" `
  -H "Access-Control-Request-Headers: authorization,content-type"

204とaccess-control-allow-originが返ればOKです。

画面

1. 起動パネルを開く
2. 顧客アプリで商品追加 → 注文
3. 店員アプリで6桁コード確認
4. Terminalで決済
5. 顧客画面がPAIDになる
6. 店員の「デモリセット」で初期化

7. 日常運用

7.1 起動・停止

npm run aws:demo:stop
npm run aws:demo:start
npm run aws:demo:status

• stop: Api/Webhook/Syncの同時実行0、同期ルール無効化
• start: 同時実行解除、同期ルール有効化
• データは保持
• Cloudflare Pagesの画面は停止中も開ける（APIはエラー）
• DynamoDBはプロビジョンドのため無料枠内で待機

7.2 ログ

aws logs describe-log-groups --profile shoptools --region ap-northeast-1 `
  --query "logGroups[?contains(logGroupName,'shoptools')].logGroupName" --output table

Lambdaログの追尾:

aws logs tail /aws/lambda/<FunctionName> --follow `
  --profile shoptools --region ap-northeast-1

7.3 カタログ同期

• EventBridge rate(15 minutes)で自動同期
• aws:demo:stop中は同期ルールも停止
• 店員アプリの手動同期・設定変更はadminロール限定のため、現状のPINログイン（staff）では403
• 手動確認が必要な場合は、同期ルールを有効化するか、Lambda SyncFunctionを直接Invokeする

7.4 データ操作

npm run aws:data:export
npm run aws:data:import -- -File .\backups\shoptools-dev-....json -Yes
npm run aws:data:reset -- -Yes

• export: DynamoDB全件をJSONへ保存
• import -- -Replace: 全削除後に復元（破壊的）
• reset: 全件削除＋店舗/レジ再作成
• 実行前にaws:demo:stopを推奨
• バックアップはbackups/（Git管理外）

7.5 アプリ更新

フロントエンド:

powershell -File scripts\pages.ps1 -Yes

バックエンド:

npm run deploy -- -Yes

両方:

npm run deploy -- -Yes
powershell -File scripts\pages.ps1 -Yes

8. トラブルシューティング

失敗スタックの削除

aws cloudformation delete-stack `
  --stack-name shoptools-dev `
  --profile shoptools `
  --region ap-northeast-1

aws cloudformation wait stack-delete-complete `
  --stack-name shoptools-dev `
  --profile shoptools `
  --region ap-northeast-1

9. セキュリティ

• .envはGit管理外。共有・バックアップ・スクリーンショットに注意
• TOTPシークレットはMFAデバイス同等。漏えい時はMFA再登録
• 長期アクセスキーは可能ならプロファイル/資格情報ストアへ移行
• CloudflareトークンはPages:Editの最小権限、期限を設定
• DEMO_ENABLED=trueと固定PINはデモ専用
• デモ終了後はaws:demo:stopまたはスタック削除
• APIは公開される。認証は注文トークン/スタッフトークン/署名で保護
• WAF・レート制限・アラームは未実装

10. コスト

• Cloudflare Pages: 静的配信はFreeで無制限。Functionsは未使用
• S3/CloudFront: 未使用
• Lambda/API Gateway: 低トラフィックなら無料枠内
• DynamoDB: 5 RCU/5 WCU × 2テーブル。無料枠25 RCU/25 WCU内
• CloudWatch Logs: 保持7日
• 新規AWSアカウントは6か月のクレジット制。期限後に料金発生

11. 破棄

1. 必要ならデータexport

npm run aws:data:export

2. 停止

npm run aws:demo:stop

3. AWSスタック削除

aws cloudformation delete-stack `
  --stack-name shoptools-dev `
  --profile shoptools `
  --region ap-northeast-1

4. Cloudflare Pages削除

npx --no-install wrangler pages project delete shoptools-dev-customer
npx --no-install wrangler pages project delete shoptools-dev-staff
npx --no-install wrangler pages project delete shoptools-dev-terminal

5. SAM管理スタック/成果物S3も不要なら削除

aws cloudformation delete-stack `
  --stack-name aws-sam-cli-managed-default `
  --profile shoptools `
  --region ap-northeast-1

DynamoDBデータはスタック削除で失われます。

12. 既知の制約

• PWAはmanifest/アイコンのみ。Service Worker未登録のためブラウザ運用
• 実Square / 実Terminalは未検証（デモはmock、本番接続コードは準備済み）
• 管理メニューはADMIN_PIN。開発環境では未設定時にSTAFF_PINへフォールバック
• Cloudflare Pagesのconfig.jsでAPIベースを切り替え
• CloudFront/WAF/アラームは未導入
• 固定PIN・デモリセットは公開デモ用

14. 関連ドキュメント

• plans/demo-kit.md
• plans/aws-cost-security.md
• plans/catalog-inventory.md
• plans/refactor.md
• plans/README.md

18. 既知の制約（本番接続）

• Square Terminal APIの本番利用にはSquare側の本番設定が必要
• Sandboxでは実Terminalのペアリング確認ができない（シミュレーターIDを使用）
• 端末ペアリングは1レジ1端末。Square POSとの併用不可
• 商品セットは同期済みLocationカタログに対する表示・注文制御
• 画像・税金・カテゴリ名以外の詳細は同期しない
• 返金・返品はSquare Dashboard / Refunds APIで運用
• PWAのService Workerは未実装

19. 管理メニュー

URL: https://shoptools-dev-admin.pages.dev/（本番は店舗ごとのadminプロジェクト）

• ADMIN_PINでログイン
• 開発環境ではADMIN_PIN未設定時にSTAFF_PINへフォールバック
• 本番ではADMIN_PIN必須

機能:

• 店舗情報（Squareから再取得）
• 商品セットの作成・編集・有効化・解除
• Square Terminalの登録コード発行・状態確認・登録解除
• 同期状態・手動同期
• 現在のCatalogSource/SquareEnv表示

AWSの起動/停止は管理メニューには置かず、ローカルCLIから実行します。

20. Webドキュメント

URL: https://shoptools-dev-docs.pages.dev/

• plans/*.mdとOPERATIONS.mdから静的サイトを生成
• 管理画面・起動パネルからリンク
• 公開用のため、認証・デプロイ・本番設定の手順はWeb版から除外
• 完全版はGitHubのOPERATIONS.md

生成・更新:

npm run docs
powershell -File scripts\pages.ps1 -Yes

pages.ps1はdocs生成とshoptools-<prefix>-docsへのデプロイも行います。

公開範囲:

• 設計・デモ・在庫・コスト・運用
• 秘密情報、アクセスキー、TOTPシークレット、APIトークン、PINの実値は含めない