// ECサイトのリソース設計例
 
// ── コレクションリソース（一覧） ──
// GET /api/v1/products              商品一覧
// GET /api/v1/categories            カテゴリ一覧
// GET /api/v1/users                 ユーザー一覧（管理者のみ）
// GET /api/v1/orders                注文一覧
 
// ── 個別リソース（単体） ──
// GET /api/v1/products/prod_abc123  商品詳細
// GET /api/v1/users/usr_def456      ユーザー詳細
// GET /api/v1/orders/ord_ghi789     注文詳細
 
// ── サブリソース（親子関係） ──
// GET /api/v1/users/usr_def456/orders          ユーザーの注文一覧
// GET /api/v1/orders/ord_ghi789/items          注文の商品一覧
// GET /api/v1/products/prod_abc123/reviews     商品のレビュー一覧
 
// ── アクションリソース（動詞的操作、RESTの例外） ──
// POST /api/v1/orders/ord_ghi789/cancel        注文キャンセル
// POST /api/v1/orders/ord_ghi789/refund        返金処理
// POST /api/v1/users/usr_def456/verify-email   メール認証
 
// ── シングルトンリソース ──
// GET  /api/v1/users/me                        現在のユーザー
// GET  /api/v1/settings                        アプリ設定
// GET  /api/v1/users/usr_def456/cart            ユーザーのカート（1つ）
 
// ── 検索リソース ──
// GET  /api/v1/search?q=laptop&category=electronics  全文検索
// POST /api/v1/products/search                        複雑な検索（ボディ使用）

// プレフィックス付きID生成の実装例
const crypto = require('crypto');
 
const ID_PREFIXES = {
  user: 'usr',
  order: 'ord',
  product: 'prod',
  payment: 'pay',
  review: 'rev',
};
 
function generateId(resourceType) {
  const prefix = ID_PREFIXES[resourceType];
  if (!prefix) {
    throw new Error(`Unknown resource type: ${resourceType}`);
  }
  // 16バイトのランダム文字列を生成
  const random = crypto.randomBytes(16).toString('base64url');
  return `${prefix}_${random}`;
}
 
// 使用例
console.log(generateId('user'));    // usr_Ab3dEfGhIjKlMnOpQrSt0w
console.log(generateId('order'));   // ord_Xy9ZaBcDeFgHiJkLmNoPq2
console.log(generateId('product'));// prod_Rs4TuVwXyZaBcDeFgHiJk1

const express = require('express');
const router = express.Router();
 
// ── GET: コレクション取得（一覧） ──
router.get('/api/v1/products', async (req, res) => {
  const {
    page = 1,
    limit = 20,
    sort = '-created_at',
    category,
    min_price,
    max_price,
    q, // 検索クエリ
  } = req.query;
 
  const filters = {};
  if (category) filters.category = category;
  if (min_price) filters.price = { $gte: Number(min_price) };
  if (max_price) filters.price = { ...filters.price, $lte: Number(max_price) };
 
  const [products, total] = await Promise.all([
    Product.find(filters)
      .sort(parseSortParam(sort))
      .skip((page - 1) * limit)
      .limit(Number(limit)),
    Product.countDocuments(filters),
  ]);
 
  res.status(200).json({
    data: products.map(serializeProduct),
    meta: {
      page: Number(page),
      limit: Number(limit),
      total,
      total_pages: Math.ceil(total / limit),
    },
    links: {
      self: `/api/v1/products?page=${page}&limit=${limit}`,
      first: `/api/v1/products?page=1&limit=${limit}`,
      last: `/api/v1/products?page=${Math.ceil(total / limit)}&limit=${limit}`,
      ...(page > 1 && {
        prev: `/api/v1/products?page=${page - 1}&limit=${limit}`,
      }),
      ...(page < Math.ceil(total / limit) && {
        next: `/api/v1/products?page=${Number(page) + 1}&limit=${limit}`,
      }),
    },
  });
});
 
// ── GET: 個別リソース取得 ──
router.get('/api/v1/products/:id', async (req, res) => {
  const product = await Product.findById(req.params.id);
 
  if (!product) {
    return res.status(404).json({
      type: 'https://api.example.com/errors/not-found',
      title: 'Product Not Found',
      status: 404,
      detail: `Product with id '${req.params.id}' does not exist.`,
      instance: `/api/v1/products/${req.params.id}`,
    });
  }
 
  res.status(200)
    .set('ETag', `"${product.version}"`)
    .set('Last-Modified', product.updated_at.toUTCString())
    .set('Cache-Control', 'private, max-age=60')
    .json({
      data: serializeProduct(product),
      links: {
        self: { href: `/api/v1/products/${product.id}` },
        reviews: { href: `/api/v1/products/${product.id}/reviews` },
        category: { href: `/api/v1/categories/${product.category_id}` },
      },
    });
});
 
// ── POST: リソース作成 ──
router.post('/api/v1/products', authenticate, authorize('admin'), async (req, res) => {
  // バリデーション
  const { error, value } = productSchema.validate(req.body);
  if (error) {
    return res.status(422).json({
      type: 'https://api.example.com/errors/validation',
      title: 'Validation Error',
      status: 422,
      detail: 'One or more fields failed validation.',
      errors: error.details.map(d => ({
        field: d.path.join('.'),
        message: d.message,
        code: 'INVALID_VALUE',
      })),
    });
  }
 
  const product = await Product.create({
    ...value,
    id: generateId('product'),
    created_by: req.user.id,
  });
 
  res.status(201)
    .set('Location', `/api/v1/products/${product.id}`)
    .json({
      data: serializeProduct(product),
      links: {
        self: { href: `/api/v1/products/${product.id}` },
      },
    });
});
 
// ── PUT: リソース完全置換 ──
router.put('/api/v1/products/:id', authenticate, authorize('admin'), async (req, res) => {
  const { error, value } = productSchema.validate(req.body);
  if (error) {
    return res.status(422).json({
      type: 'https://api.example.com/errors/validation',
      title: 'Validation Error',
      status: 422,
      errors: error.details.map(d => ({
        field: d.path.join('.'),
        message: d.message,
      })),
    });
  }
 
  // 楽観的ロック
  const ifMatch = req.headers['if-match'];
  const existing = await Product.findById(req.params.id);
 
  if (!existing) {
    return res.status(404).json({
      type: 'https://api.example.com/errors/not-found',
      title: 'Product Not Found',
      status: 404,
    });
  }
 
  if (ifMatch && ifMatch !== `"${existing.version}"`) {
    return res.status(412).json({
      type: 'https://api.example.com/errors/precondition-failed',
      title: 'Precondition Failed',
      status: 412,
      detail: 'The resource has been modified since your last request.',
      currentETag: `"${existing.version}"`,
    });
  }
 
  const updated = await Product.findByIdAndUpdate(
    req.params.id,
    { ...value, version: existing.version + 1 },
    { new: true }
  );
 
  res.status(200)
    .set('ETag', `"${updated.version}"`)
    .json({ data: serializeProduct(updated) });
});
 
// ── DELETE: リソース削除 ──
router.delete('/api/v1/products/:id', authenticate, authorize('admin'), async (req, res) => {
  const product = await Product.findById(req.params.id);
 
  if (!product) {
    return res.status(404).json({
      type: 'https://api.example.com/errors/not-found',
      title: 'Product Not Found',
      status: 404,
    });
  }
 
  // 論理削除（推奨）
  await Product.findByIdAndUpdate(req.params.id, {
    deleted_at: new Date(),
    deleted_by: req.user.id,
  });
 
  // 物理削除の場合: await Product.findByIdAndDelete(req.params.id);
 
  res.status(204).end();
});

// RFC 9457 準拠のエラーレスポンス構造
 
// 基本構造
{
  "type": "https://api.example.com/errors/validation",     // エラー種別のURI
  "title": "Validation Error",                              // 人間可読なタイトル
  "status": 422,                                            // HTTPステータスコード
  "detail": "The 'email' field is not a valid email address.", // 具体的な説明
  "instance": "/api/v1/users"                               // エラーが発生したリクエストURI
}
 
// 拡張フィールド付き（バリデーションエラー）
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "instance": "/api/v1/users",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address.",
      "code": "INVALID_FORMAT",
      "rejected_value": "not-an-email"
    },
    {
      "field": "age",
      "message": "Must be between 0 and 150.",
      "code": "OUT_OF_RANGE",
      "rejected_value": -5
    }
  ]
}
 
// レート制限エラー
{
  "type": "https://api.example.com/errors/rate-limit",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute.",
  "instance": "/api/v1/products",
  "retry_after": 30,
  "limit": 100,
  "remaining": 0,
  "reset": "2025-01-15T10:30:00Z"
}

// エラーハンドリングのミドルウェア実装
 
class ApiError extends Error {
  constructor(type, title, status, detail, extensions = {}) {
    super(detail);
    this.type = type;
    this.title = title;
    this.status = status;
    this.detail = detail;
    this.extensions = extensions;
  }
 
  toJSON() {
    return {
      type: this.type,
      title: this.title,
      status: this.status,
      detail: this.detail,
      ...this.extensions,
    };
  }
}
 
// 定義済みエラーファクトリ
const Errors = {
  notFound: (resource, id) =>
    new ApiError(
      'https://api.example.com/errors/not-found',
      `${resource} Not Found`,
      404,
      `${resource} with id '${id}' does not exist.`
    ),
 
  validation: (errors) =>
    new ApiError(
      'https://api.example.com/errors/validation',
      'Validation Error',
      422,
      'One or more fields failed validation.',
      { errors }
    ),
 
  unauthorized: () =>
    new ApiError(
      'https://api.example.com/errors/unauthorized',
      'Unauthorized',
      401,
      'Authentication is required to access this resource.'
    ),
 
  forbidden: () =>
    new ApiError(
      'https://api.example.com/errors/forbidden',
      'Forbidden',
      403,
      'You do not have permission to access this resource.'
    ),
 
  conflict: (detail) =>
    new ApiError(
      'https://api.example.com/errors/conflict',
      'Resource Conflict',
      409,
      detail
    ),
 
  rateLimited: (retryAfter, limit) =>
    new ApiError(
      'https://api.example.com/errors/rate-limit',
      'Rate Limit Exceeded',
      429,
      `Rate limit of ${limit} requests exceeded.`,
      { retry_after: retryAfter, limit }
    ),
};
 
// Express グローバルエラーハンドラー
function errorHandler(err, req, res, next) {
  if (err instanceof ApiError) {
    return res
      .status(err.status)
      .set('Content-Type', 'application/problem+json')
      .json({
        ...err.toJSON(),
        instance: req.originalUrl,
      });
  }
 
  // 予期しないエラー
  console.error('Unhandled error:', err);
  res
    .status(500)
    .set('Content-Type', 'application/problem+json')
    .json({
      type: 'https://api.example.com/errors/internal',
      title: 'Internal Server Error',
      status: 500,
      detail: 'An unexpected error occurred. Please try again later.',
      instance: req.originalUrl,
    });
}
 
// 使用例
router.get('/api/v1/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw Errors.notFound('User', req.params.id);
  res.json({ data: user });
});

// 注文リソースの状態遷移に応じたHATEOASリンク
 
function buildOrderLinks(order) {
  const base = `/api/v1/orders/${order.id}`;
  const links = {
    self: { href: base, method: 'GET' },
    items: { href: `${base}/items`, method: 'GET' },
  };
 
  switch (order.status) {
    case 'draft':
      links.submit = { href: `${base}/submit`, method: 'POST' };
      links.update = { href: base, method: 'PUT' };
      links.delete = { href: base, method: 'DELETE' };
      break;
 
    case 'pending':
      links.pay = { href: `${base}/pay`, method: 'POST' };
      links.cancel = { href: `${base}/cancel`, method: 'POST' };
      break;
 
    case 'paid':
      links.ship = { href: `${base}/ship`, method: 'POST' };
      links.refund = { href: `${base}/refund`, method: 'POST' };
      links.invoice = { href: `${base}/invoice`, method: 'GET' };
      break;
 
    case 'shipped':
      links.track = { href: `${base}/tracking`, method: 'GET' };
      links.return_request = { href: `${base}/return`, method: 'POST' };
      break;
 
    case 'delivered':
      links.review = { href: `${base}/review`, method: 'POST' };
      links.return_request = { href: `${base}/return`, method: 'POST' };
      break;
 
    case 'cancelled':
    case 'refunded':
      // 終端状態: 追加アクションなし
      break;
  }
 
  return links;
}
 
// レスポンス例: status = 'pending'
// {
//   "data": {
//     "id": "ord_abc123",
//     "status": "pending",
//     "total": 5000,
//     "items": [...]
//   },
//   "links": {
//     "self":   { "href": "/api/v1/orders/ord_abc123", "method": "GET" },
//     "items":  { "href": "/api/v1/orders/ord_abc123/items", "method": "GET" },
//     "pay":    { "href": "/api/v1/orders/ord_abc123/pay", "method": "POST" },
//     "cancel": { "href": "/api/v1/orders/ord_abc123/cancel", "method": "POST" }
//   }
// }

// 冪等性キーのサーバー実装（Redis使用）
const Redis = require('ioredis');
const redis = new Redis();
const crypto = require('crypto');
 
// 冪等性ミドルウェア
async function idempotencyMiddleware(req, res, next) {
  const idempotencyKey = req.headers['idempotency-key'];
 
  // キーなしの場合は通常処理（冪等性なし）
  if (!idempotencyKey) return next();
 
  // キーのフォーマット検証（UUIDv4推奨）
  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(idempotencyKey)) {
    return res.status(400).json({
      type: 'https://api.example.com/errors/invalid-idempotency-key',
      title: 'Invalid Idempotency Key',
      status: 400,
      detail: 'Idempotency-Key must be a valid UUID v4.',
    });
  }
 
  const cacheKey = `idempotency:${req.method}:${req.path}:${idempotencyKey}`;
 
  // ロック取得（同じキーの同時処理を防ぐ）
  const lockKey = `${cacheKey}:lock`;
  const lockAcquired = await redis.set(lockKey, '1', 'EX', 60, 'NX');
 
  if (!lockAcquired) {
    return res.status(409).json({
      type: 'https://api.example.com/errors/concurrent-request',
      title: 'Concurrent Request',
      status: 409,
      detail: 'A request with this idempotency key is currently being processed.',
    });
  }
 
  try {
    // キャッシュ確認
    const cached = await redis.get(cacheKey);
 
    if (cached) {
      // 処理済み → キャッシュした結果をそのまま返す
      const { statusCode, headers, body } = JSON.parse(cached);
      Object.entries(headers).forEach(([key, value]) => res.set(key, value));
      return res.status(statusCode).json(body);
    }
 
    // リクエストボディのハッシュを保存（同じキーで異なるボディを検出）
    const bodyHash = crypto
      .createHash('sha256')
      .update(JSON.stringify(req.body))
      .digest('hex');
 
    // レスポンスをインターセプトして保存
    const originalJson = res.json.bind(res);
    res.json = async (body) => {
      const responseHeaders = {
        'content-type': res.get('content-type'),
        'location': res.get('location'),
      };
 
      await redis.setex(cacheKey, 86400, JSON.stringify({
        statusCode: res.statusCode,
        headers: responseHeaders,
        body,
        bodyHash,
      }));
 
      return originalJson(body);
    };
 
    next();
  } finally {
    // ロック解放
    await redis.del(lockKey);
  }
}
 
// 使用
app.post('/api/v1/payments', idempotencyMiddleware, paymentHandler);
app.post('/api/v1/orders', idempotencyMiddleware, orderHandler);

// Express でのコンテンツネゴシエーション実装
 
function contentNegotiation(formatters) {
  return (req, res, next) => {
    // req.accepts() は Express 組込みの Accept ヘッダー解析
    const format = req.accepts(Object.keys(formatters));
 
    if (!format) {
      return res.status(406).json({
        type: 'https://api.example.com/errors/not-acceptable',
        title: 'Not Acceptable',
        status: 406,
        detail: `Supported formats: ${Object.keys(formatters).join(', ')}`,
      });
    }
 
    // 選択されたフォーマッターを res に設定
    res.formatResponse = (data) => {
      const formatter = formatters[format];
      const { contentType, body } = formatter(data);
      res.set('Content-Type', contentType).send(body);
    };
 
    next();
  };
}
 
// フォーマッター定義
const userFormatters = {
  'application/json': (data) => ({
    contentType: 'application/json; charset=utf-8',
    body: JSON.stringify(data),
  }),
  'text/csv': (data) => ({
    contentType: 'text/csv; charset=utf-8',
    body: convertToCsv(data),
  }),
  'application/xml': (data) => ({
    contentType: 'application/xml; charset=utf-8',
    body: convertToXml(data),
  }),
};
 
// 使用
router.get(
  '/api/v1/users',
  contentNegotiation(userFormatters),
  async (req, res) => {
    const users = await User.find();
    res.formatResponse({ data: users });
  }
);

// Merge Patch の実装
 
// リクエスト:
// PATCH /api/v1/users/usr_abc123
// Content-Type: application/merge-patch+json
// {
//   "name": "Updated Name",    ← 値を更新
//   "address": null,            ← フィールドを削除
//   // email は含めない         ← 変更なし
// }
 
function applyMergePatch(original, patch) {
  if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
    return patch;
  }
 
  const result = { ...original };
 
  for (const [key, value] of Object.entries(patch)) {
    if (value === null) {
      // null → フィールドを削除
      delete result[key];
    } else if (typeof value === 'object' && !Array.isArray(value)) {
      // ネストされたオブジェクト → 再帰的にマージ
      result[key] = applyMergePatch(result[key] || {}, value);
    } else {
      // それ以外 → 値を設定
      result[key] = value;
    }
  }
 
  return result;
}
 
// Express ルート
router.patch('/api/v1/users/:id', authenticate, async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw Errors.notFound('User', req.params.id);
 
  // バリデーション（部分スキーマで検証）
  const { error, value } = userPatchSchema.validate(req.body, {
    allowUnknown: false,
    stripUnknown: true,
  });
  if (error) throw Errors.validation(error.details);
 
  const updated = applyMergePatch(user.toObject(), value);
  const savedUser = await User.findByIdAndUpdate(req.params.id, updated, { new: true });
 
  res.status(200).json({ data: serializeUser(savedUser) });
});

// JSON Patch のリクエスト例:
// PATCH /api/v1/users/usr_abc123
// Content-Type: application/json-patch+json
// [
//   { "op": "replace", "path": "/name", "value": "Updated Name" },
//   { "op": "add", "path": "/tags/-", "value": "vip" },
//   { "op": "remove", "path": "/address" },
//   { "op": "move", "from": "/old_field", "path": "/new_field" },
//   { "op": "copy", "from": "/name", "path": "/display_name" },
//   { "op": "test", "path": "/version", "value": 5 }
// ]
 
// JSON Patch の操作一覧:
//   add     — フィールド追加 / 配列要素の挿入
//   remove  — フィールド削除 / 配列要素の削除
//   replace — フィールドの値を置換
//   move    — フィールドを移動（remove + add）
//   copy    — フィールドをコピー
//   test    — 値の検証（一致しなければ操作全体を中止）
 
// fast-json-patch ライブラリを使用した実装
const jsonPatch = require('fast-json-patch');
 
router.patch('/api/v1/users/:id', authenticate, async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw Errors.notFound('User', req.params.id);
 
  const contentType = req.headers['content-type'];
 
  let updatedData;
 
  if (contentType === 'application/json-patch+json') {
    // JSON Patch
    const patchOps = req.body;
 
    // バリデーション
    const validationResult = jsonPatch.validate(patchOps, user.toObject());
    if (validationResult) {
      return res.status(422).json({
        type: 'https://api.example.com/errors/invalid-patch',
        title: 'Invalid JSON Patch',
        status: 422,
        detail: validationResult.message,
      });
    }
 
    // パッチ適用
    updatedData = jsonPatch.applyPatch(
      jsonPatch.deepClone(user.toObject()),
      patchOps
    ).newDocument;
 
  } else if (contentType === 'application/merge-patch+json') {
    // Merge Patch
    updatedData = applyMergePatch(user.toObject(), req.body);
 
  } else {
    return res.status(415).json({
      type: 'https://api.example.com/errors/unsupported-media-type',
      title: 'Unsupported Media Type',
      status: 415,
      detail: 'Use application/json-patch+json or application/merge-patch+json.',
    });
  }
 
  const savedUser = await User.findByIdAndUpdate(req.params.id, updatedData, { new: true });
  res.status(200).json({ data: serializeUser(savedUser) });
});

// バッチリクエストの完全な実装例
 
// ── バッチ作成 ──
// POST /api/v1/users/batch
router.post('/api/v1/users/batch', authenticate, authorize('admin'), async (req, res) => {
  const { operations } = req.body;
 
  // バッチサイズの制限
  if (!operations || operations.length === 0) {
    throw Errors.validation([{
      field: 'operations',
      message: 'At least one operation is required.',
      code: 'REQUIRED',
    }]);
  }
 
  if (operations.length > 100) {
    throw Errors.validation([{
      field: 'operations',
      message: 'Maximum 100 operations per batch.',
      code: 'MAX_EXCEEDED',
    }]);
  }
 
  const results = [];
  let succeeded = 0;
  let failed = 0;
 
  for (const op of operations) {
    try {
      // 個別バリデーション
      const { error, value } = userSchema.validate(op.body);
      if (error) {
        results.push({
          status: 422,
          error: {
            type: 'https://api.example.com/errors/validation',
            title: 'Validation Error',
            detail: error.details[0].message,
          },
        });
        failed++;
        continue;
      }
 
      // リソース作成
      const user = await User.create({
        ...value,
        id: generateId('user'),
        created_by: req.user.id,
      });
 
      results.push({
        status: 201,
        data: serializeUser(user),
      });
      succeeded++;
 
    } catch (err) {
      results.push({
        status: 500,
        error: {
          type: 'https://api.example.com/errors/internal',
          title: 'Internal Error',
          detail: 'Failed to process this operation.',
        },
      });
      failed++;
    }
  }
 
  // 全体のHTTPステータス:
  //   全成功 → 200
  //   部分失敗 → 207 Multi-Status
  //   全失敗 → 422
  const overallStatus = failed === 0 ? 200 : succeeded === 0 ? 422 : 207;
 
  res.status(overallStatus).json({
    results,
    meta: {
      total: operations.length,
      succeeded,
      failed,
    },
  });
});
 
// ── 一括削除 ──
// POST /api/v1/users/batch-delete
router.post('/api/v1/users/batch-delete', authenticate, authorize('admin'), async (req, res) => {
  const { ids } = req.body;
 
  if (!ids || ids.length === 0) {
    throw Errors.validation([{
      field: 'ids',
      message: 'At least one ID is required.',
    }]);
  }
 
  if (ids.length > 100) {
    throw Errors.validation([{
      field: 'ids',
      message: 'Maximum 100 IDs per batch delete.',
    }]);
  }
 
  const result = await User.updateMany(
    { id: { $in: ids } },
    { deleted_at: new Date(), deleted_by: req.user.id }
  );
 
  res.status(200).json({
    meta: {
      requested: ids.length,
      deleted: result.modifiedCount,
      not_found: ids.length - result.modifiedCount,
    },
  });
});
 
// ── 一括更新 ──
// PATCH /api/v1/users/batch
router.patch('/api/v1/users/batch', authenticate, authorize('admin'), async (req, res) => {
  const { ids, update } = req.body;
 
  if (!ids || ids.length === 0 || !update) {
    throw Errors.validation([{
      field: 'ids',
      message: 'IDs and update fields are required.',
    }]);
  }
 
  const result = await User.updateMany(
    { id: { $in: ids } },
    { $set: update }
  );
 
  res.status(200).json({
    meta: {
      requested: ids.length,
      updated: result.modifiedCount,
    },
  });
});

// 楽観的ロックの完全な実装
 
router.put('/api/v1/users/:id', authenticate, async (req, res) => {
  const ifMatch = req.headers['if-match'];
  const user = await User.findById(req.params.id);
 
  if (!user) throw Errors.notFound('User', req.params.id);
 
  // If-Match ヘッダーが指定されている場合、ETag を検証
  if (ifMatch) {
    const currentETag = `"${user.version}"`;
    if (ifMatch !== currentETag) {
      return res.status(412).json({
        type: 'https://api.example.com/errors/precondition-failed',
        title: 'Precondition Failed',
        status: 412,
        detail: 'The resource has been modified since your last request. '
          + 'Please retrieve the latest version and retry.',
        current_etag: currentETag,
        your_etag: ifMatch,
      });
    }
  }
 
  // バリデーション
  const { error, value } = userSchema.validate(req.body);
  if (error) throw Errors.validation(error.details);
 
  // 更新（version をインクリメント）
  const updated = await User.findOneAndUpdate(
    { _id: req.params.id, version: user.version }, // version も条件に含める
    { ...value, version: user.version + 1 },
    { new: true }
  );
 
  // DB レベルでも競合検出（findOneAndUpdate が null を返す場合）
  if (!updated) {
    return res.status(409).json({
      type: 'https://api.example.com/errors/conflict',
      title: 'Resource Conflict',
      status: 409,
      detail: 'The resource was modified by another request during processing.',
    });
  }
 
  res.status(200)
    .set('ETag', `"${updated.version}"`)
    .json({ data: serializeUser(updated) });
});

// Express でのキャッシュヘッダー設定
 
// 不変リソース（ビルドアセット、画像等）
app.use('/static', express.static('public', {
  maxAge: '365d',
  immutable: true,
  setHeaders: (res) => {
    res.set('Cache-Control', 'public, max-age=31536000, immutable');
  },
}));
 
// API レスポンスのキャッシュミドルウェア
function cacheControl(options = {}) {
  return (req, res, next) => {
    const {
      visibility = 'private',   // 'public' or 'private'
      maxAge = 0,               // 秒数
      sMaxAge,                  // CDN キャッシュ秒数
      mustRevalidate = false,
      noCache = false,
      noStore = false,
    } = options;
 
    const directives = [];
 
    if (noStore) {
      directives.push('no-store');
    } else if (noCache) {
      directives.push(`${visibility}`, 'no-cache');
    } else {
      directives.push(visibility);
      directives.push(`max-age=${maxAge}`);
      if (sMaxAge !== undefined) directives.push(`s-maxage=${sMaxAge}`);
      if (mustRevalidate) directives.push('must-revalidate');
    }
 
    res.set('Cache-Control', directives.join(', '));
    next();
  };
}
 
// 使用例
// 商品一覧: 60秒キャッシュ、CDNは300秒
router.get('/api/v1/products',
  cacheControl({ visibility: 'public', maxAge: 60, sMaxAge: 300 }),
  productListHandler
);
 
// ユーザー情報: キャッシュなし、毎回サーバー確認（ETagで304活用）
router.get('/api/v1/users/me',
  cacheControl({ visibility: 'private', noCache: true }),
  currentUserHandler
);
 
// 決済情報: キャッシュ禁止
router.get('/api/v1/payments/:id',
  cacheControl({ noStore: true }),
  paymentHandler
);
 
// 設定マスタ: 1時間キャッシュ
router.get('/api/v1/settings',
  cacheControl({ visibility: 'public', maxAge: 3600 }),
  settingsHandler
);

// ── オフセットベースのページネーション ──
router.get('/api/v1/products', async (req, res) => {
  const page = Math.max(1, parseInt(req.query.page) || 1);
  const limit = Math.min(100, Math.max(1, parseInt(req.query.limit) || 20));
  const offset = (page - 1) * limit;
 
  const [products, total] = await Promise.all([
    db.query('SELECT * FROM products ORDER BY created_at DESC LIMIT $1 OFFSET $2', [limit, offset]),
    db.query('SELECT COUNT(*) FROM products'),
  ]);
 
  const totalPages = Math.ceil(total.rows[0].count / limit);
 
  res.json({
    data: products.rows,
    meta: { page, limit, total: parseInt(total.rows[0].count), total_pages: totalPages },
    links: {
      self: `/api/v1/products?page=${page}&limit=${limit}`,
      first: `/api/v1/products?page=1&limit=${limit}`,
      last: `/api/v1/products?page=${totalPages}&limit=${limit}`,
      ...(page > 1 && { prev: `/api/v1/products?page=${page - 1}&limit=${limit}` }),
      ...(page < totalPages && { next: `/api/v1/products?page=${page + 1}&limit=${limit}` }),
    },
  });
});
 
// ── カーソルベースのページネーション ──
router.get('/api/v1/products', async (req, res) => {
  const limit = Math.min(100, Math.max(1, parseInt(req.query.limit) || 20));
  const cursor = req.query.cursor; // Base64エンコードされたカーソル
 
  let query = 'SELECT * FROM products';
  const params = [limit + 1]; // 1つ多く取得（next の有無判定用）
 
  if (cursor) {
    const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString());
    query += ' WHERE (created_at, id) < ($2, $3)';
    params.push(decoded.created_at, decoded.id);
  }
 
  query += ' ORDER BY created_at DESC, id DESC LIMIT $1';
 
  const result = await db.query(query, params);
  const hasNext = result.rows.length > limit;
  const items = hasNext ? result.rows.slice(0, limit) : result.rows;
 
  const nextCursor = hasNext
    ? Buffer.from(JSON.stringify({
        created_at: items[items.length - 1].created_at,
        id: items[items.length - 1].id,
      })).toString('base64url')
    : null;
 
  res.json({
    data: items,
    meta: {
      limit,
      has_next: hasNext,
    },
    links: {
      self: `/api/v1/products?limit=${limit}${cursor ? `&cursor=${cursor}` : ''}`,
      ...(nextCursor && {
        next: `/api/v1/products?limit=${limit}&cursor=${nextCursor}`,
      }),
    },
  });
});

// 論理削除と物理削除の共存設計
 
// ── 標準の DELETE: 論理削除 ──
// DELETE /api/v1/users/usr_abc123
// → deleted_at を設定、データは残存
router.delete('/api/v1/users/:id', authenticate, async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw Errors.notFound('User', req.params.id);
 
  // 既に論理削除済みの場合
  if (user.deleted_at) {
    return res.status(410).json({
      type: 'https://api.example.com/errors/gone',
      title: 'Resource Gone',
      status: 410,
      detail: 'This resource has already been deleted.',
      deleted_at: user.deleted_at,
    });
  }
 
  await User.findByIdAndUpdate(req.params.id, {
    deleted_at: new Date(),
    deleted_by: req.user.id,
  });
 
  res.status(204).end();
});
 
// ── 物理削除（GDPR対応）: 別エンドポイント ──
// DELETE /api/v1/users/usr_abc123/permanent
// → データを完全に抹消
router.delete('/api/v1/users/:id/permanent',
  authenticate,
  authorize('admin'),
  requireMfa,  // MFA必須
  async (req, res) => {
    const user = await User.findById(req.params.id);
    if (!user) throw Errors.notFound('User', req.params.id);
 
    // 監査ログに記録
    await AuditLog.create({
      action: 'PERMANENT_DELETE',
      resource_type: 'User',
      resource_id: req.params.id,
      performed_by: req.user.id,
      reason: req.body.reason, // 削除理由（必須）
      timestamp: new Date(),
    });
 
    // 関連データの削除
    await Promise.all([
      Order.updateMany(
        { user_id: req.params.id },
        { $set: { user_id: null, user_name: '[deleted]' } }
      ),
      Review.deleteMany({ user_id: req.params.id }),
      User.findByIdAndDelete(req.params.id),
    ]);
 
    res.status(204).end();
  }
);
 
// ── 論理削除されたリソースの取得 ──
// GET /api/v1/users?include_deleted=true (管理者のみ)
router.get('/api/v1/users', authenticate, async (req, res) => {
  const filters = {};
 
  // 通常ユーザーは削除済みを見れない
  if (req.query.include_deleted === 'true' && req.user.role === 'admin') {
    // フィルタなし（削除済みも含む）
  } else {
    filters.deleted_at = null;
  }
 
  const users = await User.find(filters);
  res.json({ data: users.map(serializeUser) });
});
 
// ── 論理削除の復元 ──
// POST /api/v1/users/usr_abc123/restore
router.post('/api/v1/users/:id/restore',
  authenticate,
  authorize('admin'),
  async (req, res) => {
    const user = await User.findById(req.params.id);
    if (!user) throw Errors.notFound('User', req.params.id);
 
    if (!user.deleted_at) {
      return res.status(409).json({
        type: 'https://api.example.com/errors/conflict',
        title: 'Resource Not Deleted',
        status: 409,
        detail: 'This resource is not in a deleted state.',
      });
    }
 
    await User.findByIdAndUpdate(req.params.id, {
      $unset: { deleted_at: 1, deleted_by: 1 },
    });
 
    const restored = await User.findById(req.params.id);
    res.status(200).json({ data: serializeUser(restored) });
  }
);

// 非同期操作のパターン
 
// ── Step 1: ジョブの開始 ──
// POST /api/v1/reports
// → 202 Accepted を即座に返し、バックグラウンドで処理
router.post('/api/v1/reports', authenticate, async (req, res) => {
  const { type, date_range, format } = req.body;
 
  // バリデーション
  const { error } = reportRequestSchema.validate(req.body);
  if (error) throw Errors.validation(error.details);
 
  // ジョブを作成
  const job = await Job.create({
    id: generateId('job'),
    type: 'report_generation',
    status: 'queued',
    params: { type, date_range, format },
    created_by: req.user.id,
    created_at: new Date(),
    progress: 0,
  });
 
  // キューに追加（実際の処理はワーカーが行う）
  await queue.add('generate-report', {
    jobId: job.id,
    ...req.body,
  });
 
  res.status(202)
    .set('Location', `/api/v1/jobs/${job.id}`)
    .json({
      data: {
        job_id: job.id,
        status: 'queued',
        message: 'Report generation has been queued.',
      },
      links: {
        status: { href: `/api/v1/jobs/${job.id}`, method: 'GET' },
        cancel: { href: `/api/v1/jobs/${job.id}/cancel`, method: 'POST' },
      },
    });
});
 
// ── Step 2: ジョブの進捗確認 ──
// GET /api/v1/jobs/job_abc123
router.get('/api/v1/jobs/:id', authenticate, async (req, res) => {
  const job = await Job.findById(req.params.id);
  if (!job) throw Errors.notFound('Job', req.params.id);
 
  const response = {
    data: {
      id: job.id,
      type: job.type,
      status: job.status,   // queued | processing | completed | failed | cancelled
      progress: job.progress, // 0-100
      created_at: job.created_at,
      updated_at: job.updated_at,
    },
    links: {
      self: { href: `/api/v1/jobs/${job.id}` },
    },
  };
 
  switch (job.status) {
    case 'queued':
    case 'processing':
      // ポーリング間隔を Retry-After で指示
      res.set('Retry-After', '5'); // 5秒後に再確認
      response.links.cancel = { href: `/api/v1/jobs/${job.id}/cancel`, method: 'POST' };
      break;
 
    case 'completed':
      response.data.result_url = job.result_url;
      response.links.result = { href: job.result_url, method: 'GET' };
      break;
 
    case 'failed':
      response.data.error = job.error_message;
      response.links.retry = { href: `/api/v1/reports`, method: 'POST' };
      break;
  }
 
  res.status(200).json(response);
});
 
// ── Step 3: ジョブのキャンセル ──
// POST /api/v1/jobs/job_abc123/cancel
router.post('/api/v1/jobs/:id/cancel', authenticate, async (req, res) => {
  const job = await Job.findById(req.params.id);
  if (!job) throw Errors.notFound('Job', req.params.id);
 
  if (['completed', 'failed', 'cancelled'].includes(job.status)) {
    return res.status(409).json({
      type: 'https://api.example.com/errors/conflict',
      title: 'Job Cannot Be Cancelled',
      status: 409,
      detail: `Job is already in '${job.status}' state.`,
    });
  }
 
  await Job.findByIdAndUpdate(req.params.id, {
    status: 'cancelled',
    cancelled_at: new Date(),
    cancelled_by: req.user.id,
  });
 
  res.status(200).json({
    data: { id: job.id, status: 'cancelled' },
  });
});

// トークンバケットアルゴリズムによるレート制限
 
const Redis = require('ioredis');
const redis = new Redis();
 
async function rateLimitMiddleware(req, res, next) {
  const identifier = req.user?.id || req.ip; // 認証済みならユーザーID、未認証ならIP
  const key = `ratelimit:${identifier}`;
 
  // 設定
  const limit = req.user ? 1000 : 100;  // 認証済み: 1000/分, 未認証: 100/分
  const window = 60; // 60秒
 
  // Redisでカウント
  const multi = redis.multi();
  multi.incr(key);
  multi.ttl(key);
  const [[, count], [, ttl]] = await multi.exec();
 
  // 初回アクセス時にTTLを設定
  if (ttl === -1) {
    await redis.expire(key, window);
  }
 
  const remaining = Math.max(0, limit - count);
  const resetTime = new Date(Date.now() + (ttl > 0 ? ttl : window) * 1000);
 
  // レート制限ヘッダーを設定（RFC 6585 / Draft RateLimit Header）
  res.set({
    'RateLimit-Limit': limit.toString(),
    'RateLimit-Remaining': remaining.toString(),
    'RateLimit-Reset': Math.ceil(resetTime.getTime() / 1000).toString(),
    'RateLimit-Policy': `${limit};w=${window}`,
  });
 
  if (count > limit) {
    const retryAfter = ttl > 0 ? ttl : window;
    res.set('Retry-After', retryAfter.toString());
 
    return res.status(429).json({
      type: 'https://api.example.com/errors/rate-limit',
      title: 'Rate Limit Exceeded',
      status: 429,
      detail: `You have exceeded the limit of ${limit} requests per ${window} seconds.`,
      retry_after: retryAfter,
      limit,
      remaining: 0,
      reset: resetTime.toISOString(),
    });
  }
 
  next();
}
 
app.use('/api/', rateLimitMiddleware);

// バージョンルーティングの実装例
 
const express = require('express');
const app = express();
 
// バージョンごとにルーターを分離
const v1Router = require('./routes/v1');
const v2Router = require('./routes/v2');
 
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);
 
// バージョン非指定時のリダイレクト
app.use('/api/users', (req, res) => {
  // 最新安定版にリダイレクト
  res.redirect(307, `/api/v2${req.url}`);
});
 
// 非推奨バージョンの警告ヘッダー
function deprecationWarning(sunsetDate) {
  return (req, res, next) => {
    res.set({
      'Deprecation': 'true',
      'Sunset': sunsetDate,
      'Link': '</api/v2>; rel="successor-version"',
    });
    next();
  };
}
 
// v1 全体に非推奨警告を付与
v1Router.use(deprecationWarning('2025-12-31T23:59:59Z'));

// RFC 9457準拠のエラーレスポンス
{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The email field must be a valid email address.",
  "instance": "/api/v1/users",
  "errors": [
    {
      "field": "email",
      "code": "invalid_format",
      "message": "Must be a valid email address"
    }
  ],
  "trace_id": "abc123def456"  // デバッグ用の追跡ID
}

// 空のコレクション: 200 + 空配列（404ではない）
// GET /api/v1/users?status=vip （VIPユーザーがいない場合）
{
  "data": [],
  "meta": { "page": 1, "limit": 20, "total": 0, "total_pages": 0 }
}
 
// リソースが見つからない: 404
// GET /api/v1/users/nonexistent
{
  "type": "https://api.example.com/errors/not-found",
  "title": "User Not Found",
  "status": 404,
  "detail": "User with id 'nonexistent' does not exist."
}
 
// DELETE成功: 204 No Content（ボディなし）
// DELETE /api/v1/users/usr_abc123
// → 204 (空レスポンス)