📋 Developer Cheat Sheet - 2分で問題解決

🎯 目標: よく使うコード・コマンド・トラブル解決を超高速で見つける

---

⚡ API Quick Reference

🔥 よく使うエンドポイント

// 📸 写真アップロード
POST /api/photos/upload
Content-Type: multipart/form-data
Headers: { Authorization: `Bearer ${firebaseToken}` }

// 🛒 注文作成 (Queue経由)
POST /api/orders/create  
Body: { brand: "neko", photo_ids: ["photo_123"], shipping_address_id: "addr_456" }
Response: { order_id: "order_789", status: "processing" }

// ✅ ヘルスチェック
GET /api/health
Response: { status: "ok", version: "v1.0.0-beta", timestamp: "2025-08-23T17:22:00Z" }

🔑 認証ヘッダー

// Firebase Token
headers: { 
  'Authorization': `Bearer ${await user.getIdToken()}`,
  'Content-Type': 'application/json'
}

// Brand Context
headers: { 
  'X-Brand': 'neko', // 'neko' | 'tokinoe' | 'dog'
  'X-Request-ID': uuidv4() // デバッグ用
}

---

🗄️ Database Quick Queries

🔥 よく使うD1クエリ

-- 📊 ユーザーセッション確認
SELECT * FROM user_sessions WHERE firebase_uid = ?

-- 📦 注文ステータス確認  
SELECT * FROM orders WHERE id = ? AND brand = ?

-- 🔄 Queue処理済み確認
SELECT * FROM processed_events WHERE idempotency_key = ?

-- 📈 ブランド別統計
SELECT brand, COUNT(*) as order_count 
FROM orders 
WHERE created_at >= date('now', '-7 days')
GROUP BY brand

🔧 D1開発コマンド

# ローカルD1セットアップ
npx wrangler d1 create nekomata-db-dev
npx wrangler d1 execute nekomata-db-dev --local --file=./schema.sql

# マイグレーション実行
npx wrangler d1 migrations apply nekomata-db-dev --local

# データ確認
npx wrangler d1 execute nekomata-db-dev --local --command="SELECT * FROM orders LIMIT 5"

---

🔄 Queue Operations

🚀 Queue送信パターン

// 📦 注文確定イベント
await env.ORDER_QUEUE.send({
  type: 'ORDER_CONFIRMED',
  order_id: 'order_123', 
  brand: 'neko',
  idempotency_key: `neko:create:order_123:${Date.now()}`,
  metadata: { photo_count: 5, user_tier: 'premium' }
})

// 📧 メール送信イベント  
await env.EMAIL_QUEUE.send({
  type: 'EMAIL_ORDER_CONFIRMED',
  template_id: 'order_confirmation_v2',
  recipient_shopify_id: 'customer_456',
  brand: 'neko',
  context: { order_number: '#NK-1001', delivery_date: '2025-09-01' }
})

// 🔄 データ同期イベント
await env.SYNC_QUEUE.send({
  type: 'SYNC_PRODUCTS',
  brand: 'neko', 
  resource_type: 'products',
  cursor: 'eyJsYXN0X2lkIjoiZ2lk...',
  batch_size: 50
})

🔍 Queue Consumer Template

export default {
  async queue(batch: MessageBatch, env: Env) {
    for (const message of batch.messages) {
      try {
        const event = message.body as QueueEvent
        
        // Idempotency確認
        const existing = await checkProcessed(event.idempotency_key, env)
        if (existing) {
          message.ack()
          continue
        }
        
        // 実処理
        await processEvent(event, env)
        await markProcessed(event.idempotency_key, env)
        
        message.ack()
      } catch (error) {
        console.error('Queue処理エラー:', error)
        message.retry() // 自動リトライ
      }
    }
  }
}

---

🛠️ TypeScript型定義集

🏷️ Core Types

// 🏢 ブランド関連
type Brand = 'neko' | 'tokinoe' | 'dog'

// 📸 写真・注文関連
interface PhotoUpload {
  id: string
  firebase_uid: string
  brand: Brand
  filename: string
  r2_key: string
  upload_status: 'uploading' | 'completed' | 'failed'
  created_at: string
}

interface OrderCreate {
  brand: Brand
  photo_ids: string[]
  shipping_address_id: string
  user_notes?: string
}

interface OrderResponse {
  order_id: string
  status: 'processing' | 'confirmed' | 'failed'
  estimated_delivery?: string
  tracking_url?: string
}

// 🔄 Queue Event Types
interface BaseQueueEvent {
  type: string
  idempotency_key: string
  brand: Brand
  created_at: string
}

interface OrderEvent extends BaseQueueEvent {
  type: 'ORDER_CONFIRMED' | 'ORDER_CANCELLED' | 'ORDER_FULFILLED'
  order_id: string
  metadata?: Record<string, any>
}

interface EmailEvent extends BaseQueueEvent {
  type: 'EMAIL_ORDER_CONFIRMED' | 'EMAIL_SHIPPED' | 'EMAIL_SUPPORT'
  template_id: string
  recipient_shopify_id: string
  context: Record<string, any>
}

🌍 Environment Types

interface Env {
  // Workers Bindings
  D1_DATABASE: D1Database
  R2_STORAGE: R2Bucket
  ORDER_QUEUE: Queue<OrderEvent>
  EMAIL_QUEUE: Queue<EmailEvent>
  SYNC_QUEUE: Queue<SyncEvent>
  
  // Secrets
  SHOPIFY_API_KEY: string
  SHOPIFY_API_SECRET: string
  FIREBASE_ADMIN_KEY: string
  
  // Environment Config
  ENVIRONMENT: 'development' | 'staging' | 'production'
  LOG_LEVEL: 'debug' | 'info' | 'warn' | 'error'
}

---

🐛 Debugging & Troubleshooting

🔍 よくあるエラーと解決法

// ❌ Error: Shopify 429 (Rate Limit Exceeded)
// 💡 Solution: Queue実装を確認、リクエスト頻度を調整
if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After') 
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
  // Queue経由で再実行
}

// ❌ Error: Firebase token expired  
// 💡 Solution: トークン更新確認
const token = await user.getIdToken(true) // force refresh

// ❌ Error: D1 "no such table"
// 💡 Solution: マイグレーション実行確認
// npx wrangler d1 migrations apply nekomata-db-dev --local

// ❌ Error: Queue DLQ accumulation
// 💡 Solution: Idempotency key重複、処理ロジックエラー確認
SELECT * FROM processed_events WHERE created_at >= date('now', '-1 hour')

📊 デバッグ用ログ確認

# Cloudflare Workers ログ
npx wrangler tail --format=json | jq '.logs[]'

# ローカル開発ログ  
npm run dev 2>&1 | grep -E "(ERROR|WARN|Queue)"

# D1クエリログ
npx wrangler d1 execute nekomata-db-dev --local --command="
SELECT created_at, level, message 
FROM system_logs 
WHERE created_at >= datetime('now', '-10 minutes')
ORDER BY created_at DESC LIMIT 20"

---

🚀 開発効率化コマンド

⚡ よく使うnpm scripts

# 🔄 開発サーバー (全機能)
npm run dev

# 🧪 テスト実行
npm test                    # 全テスト
npm run test:unit          # ユニットテスト  
npm run test:integration   # 統合テスト
npm run test:e2e          # E2Eテスト

# 🏗️ ビルド・デプロイ
npm run build              # 本番ビルド
npm run deploy:staging     # ステージング環境
npm run deploy:production  # 本番環境

# 🔍 品質チェック
npm run lint               # ESLint
npm run type-check         # TypeScript型チェック  
npm run test:coverage      # カバレッジ確認

🛠️ Cloudflare Wrangler コマンド

# 📊 Workers監視
wrangler tail --format=json                    # リアルタイムログ
wrangler analytics --from=1h                   # パフォーマンス分析

# 🗄️ D1管理  
wrangler d1 list                              # データベース一覧
wrangler d1 backup list nekomata-db-dev      # バックアップ確認

# 🔄 Queue管理
wrangler queues list                          # キュー一覧  
wrangler queues consumer add ORDER_QUEUE     # Consumer追加

---

📞 緊急時・サポート

🚨 緊急対応連絡先

Shopify API障害: 
  - Status: https://status.shopify.com
  - 対応: Queue処理一時停止、手動対応準備

Cloudflare障害:
  - Status: https://cloudflarestatus.com  
  - 対応: CDNフェイルオーバー、ローカル環境待機

Firebase障害:
  - Status: https://status.firebase.google.com
  - 対応: 認証バイパス準備、代替認証検討

📚 さらに詳しく知りたい時

トピック	詳細文書	緊急度
API全仕様	BFF API設計	⚡
Queue詳細	Queue System設計	⚡
DB詳細	D1 Database設計	🔥
セキュリティ	セキュリティ実装	🚨
デプロイ	開発環境構築	⚡

---

💡 Pro Tip: この Cheat Sheet をブックマークして、開発中の疑問を2分以内で解決！