Non-Functional Requirements

非機能要件

Non-Functional Requirements

1. パフォーマンス — Performance

NFR-001レスポンス時間 Response Time

2秒
用語一覧 初回ロード
Term list initial load
100ms
検索（キャッシュヒット時）
Search (cache hit)
500ms
検索（キャッシュミス時）
Search (cache miss)

NFR-002クライアントサイドキャッシュ Client-side Cache

  • クライアントサイドでサーバーレスポンスをキャッシュするCache server responses on the client side.
  • staleTime: 30秒（30 秒間はキャッシュを新鮮とみなす）staleTime: 30s — cache is treated as fresh for 30 seconds.
  • gcTime: 5分（未使用キャッシュは 5 分後に破棄）gcTime: 5m — unused cache is discarded after 5 minutes.
  • 同一クエリパラメータでは再フェッチを回避するAvoid re-fetching for identical query parameters.

NFR-003デバウンス処理 Debounce

  • 検索入力に 300ms のデバウンスを設けてリクエスト過多を防ぐApply a 300ms debounce to search input to prevent excessive requests.

2. 保守性・品質 — Maintainability & Quality

NFR-004コード品質 Code Quality

  • Lint / Format ツールを使用するUse Lint / Format tools.
  • コミット前に Lint / Format チェックを通過することを必須とするLint / Format checks must pass before committing.

NFR-005型安全性 Type Safety

  • TypeScript を使用し、strict モードを有効にするUse TypeScript with strict mode enabled.
  • ORM で生成された型を API・フロントエンド間で共有するShare ORM-generated types between the API and frontend.

NFR-006テストカバレッジ Test Coverage

  • ビジネスロジック（検索フィルタ・バリデーション・認証）のカバレッジ 80% 以上を目標とするTarget 80%+ coverage for business logic (search filters, validation, authentication).
  • ユニット・統合テストフレームワーク + E2E テストフレームワークを使用するUse unit/integration test framework + E2E test framework.

3. テスト要件 — Testing Requirements

NFR-007TDD（テスト駆動開発） TDD (Test-Driven Development)

Red → Green → Refactor t-wada スタイル
  • t-wada 氏推奨の TDD スタイルを適用するApply the TDD style recommended by t-wada.
  • Red → Green → Refactor サイクルを遵守するFollow the Red → Green → Refactor cycle.
  • テストは実装より先に書く（テストファースト）Write tests before implementation (test-first).

NFR-008ユニット・統合テスト Unit & Integration Tests

  • 検索フィルタロジックの単体テストUnit tests for search filter logic.
  • ORM クエリロジックの D1 統合テストD1 integration tests for ORM query logic.
  • グローバル状態（atoms）の状態変化テストState change tests for global state (atoms).
  • カスタム hooks（useTermList 等）のテストTests for custom hooks (useTermList, etc.).
  • 認証ロジック（HMAC セッション）のテストTests for authentication logic (HMAC session).
  • ユニットテストはソースファイルと同ディレクトリに配置する（*.test.ts / *.test.tsx）Unit test files are co-located with source files in the same directory (*.test.ts / *.test.tsx).

NFR-009E2E テスト E2E Tests

テストシナリオ / Test Scenario 検証内容 / Verification
用語一覧表示 Term List Display テーブル・カードに用語が表示されることTerms are displayed in the table and card view.
インクリメンタル検索（単語名） Incremental Search (Term name) 入力ごとに結果が絞り込まれることResults are filtered with each keystroke.
インクリメンタル検索（説明文） Incremental Search (Description) スイッチ切り替え後に説明文で絞り込まれることAfter switching, results are filtered by description.
カテゴリフィルター Category Filter チップ選択でカテゴリが絞り込まれることSelecting a chip filters by category.
ページング操作 Pagination 次ページ・前ページで表示が変わることDisplay changes on next / previous page.
詳細ダイアログ Detail Dialog 行クリックでダイアログが開き、Esc で閉じることDialog opens on row click and closes with Esc.
未ログイン時 UI Guest UI CRUD ボタンが非表示、「管理者ログイン」ボタンが表示CRUD buttons are hidden; "Admin Login" button is visible.
管理者ログイン・CRUD Admin Login & CRUD ログイン後に用語の追加・編集・削除ができることAfter login, terms can be added, edited, and deleted.
認証 API Auth API login / logout / session エンドポイントの HTTP 動作HTTP behavior of login / logout / session endpoints.
画像アップロード Image Upload 認証保護・形式バリデーション・R2 保存Auth protection, format validation, and R2 storage.

4. セキュリティ — Security

NFR-010入力値バリデーション Input Validation

バリデーション方針 Validation Policy
  • フロントエンド・バックエンド双方でバリデーションを実施するValidate on both frontend and backend.
  • SQL インジェクション対策として ORM のパラメータバインドを使用するUse ORM parameter binding to prevent SQL injection.
  • XSS 対策として React のエスケープ処理に依存するRely on React's built-in escaping for XSS prevention.

NFR-011認証・認可 Authentication & Authorization

HMAC-SHA256 セッション認証 HMAC-SHA256 Session Authentication
  • 管理者認証: HMAC-SHA256 署名付き Cookie セッションを実装するAdmin authentication: implement HMAC-SHA256 signed cookie session.
  • セッション Cookie は HttpOnly・SameSite=Lax・Secure（本番のみ）属性で保護するProtect the session cookie with HttpOnly, SameSite=Lax, and Secure (production only) attributes.
  • セッション有効期限は 7 日（60 * 60 * 24 * 7 秒）— ペイロード { exp } に署名して改ざん検出Session expires after 7 days; tampering is detected by signing the { exp } payload.
  • CRUD 操作・画像アップロード API は requireAdminSession ミドルウェアで保護するCRUD and image upload APIs are protected by the requireAdminSession middleware.
  • 認証情報（ADMIN_EMAIL・ADMIN_PASSWORD・AUTH_SECRET）は環境変数で管理するAuthentication credentials (ADMIN_EMAIL, ADMIN_PASSWORD, AUTH_SECRET) are managed via environment variables.
  • ADMIN_EMAIL / ADMIN_PASSWORD の照合はタイミング安全比較を適用するConstant-time comparison is used for ADMIN_EMAIL / ADMIN_PASSWORD matching.

5. 運用・デプロイ — Operations & Deployment

NFR-012実行環境 Runtime Environment

  • デプロイ先: Cloudflare Workers（OpenNext Workers アセット出力。main = ".open-next/worker.js" + [assets] directory = ".open-next/assets"）Deploy target: Cloudflare Workers (OpenNext Workers asset output: main = ".open-next/worker.js" + [assets] directory = ".open-next/assets").
  • ローカル開発: Node.js 24 以上 + Next.js 開発サーバー + D1 / R2 / Queues のローカルエミュレーションLocal development: Node.js 24+ + Next.js dev server + local emulation of D1 / R2 / Queues.
  • Next.js の Cloudflare 対応: OpenNext の Cloudflare アダプターを使用Cloudflare support for Next.js: use the OpenNext Cloudflare adapter.

NFR-013データ永続性 Data Persistence

  • データベース: Cloudflare D1（SQLite 互換のサーバーレス DB）Database: Cloudflare D1 (serverless SQLite-compatible DB).
  • 画像ストレージ: Cloudflare R2（バケット名: aws-glossary-images）Image storage: Cloudflare R2 (bucket name: aws-glossary-images).
  • マイグレーション管理: wrangler d1 migrations apply で実施Migration management: run via wrangler d1 migrations apply.
  • ローカル D1 は wrangler dev 実行時に .wrangler/state/ 配下に自動生成されるLocal D1 is auto-generated under .wrangler/state/ when wrangler dev is run.

NFR-014公開形態（推奨パターン） Deployment Pattern (Recommended)

本システムの最終形態の公開先は Cloudflare Workers（OpenNext の Workers アセット出力）とする。 The final production target is Cloudflare Workers (OpenNext Workers asset output).

  • 推奨スタック: Cloudflare Workers + D1 + R2 + QueuesRecommended stack: Cloudflare Workers + D1 + R2 + Queues
  • OpenNext の Cloudflare アダプターにより .open-next/worker.js + .open-next/assets/ として出力Outputs as .open-next/worker.js + .open-next/assets/ via the OpenNext Cloudflare adapter.
  • Route Handler から getCloudflareContext({ async: true }) 経由でバインディングにアクセスAccess bindings via getCloudflareContext({ async: true }) from Route Handlers.

NFR-015デプロイフロー Deploy Flow

  1. OpenNext ビルド / OpenNext Build
    .open-next/ 配下に Workers 成果物を出力 Outputs Workers build artifacts under .open-next/.
  2. Workers へのデプロイ / Deploy to Workers
    pnpm deploy に集約 Aggregated into pnpm deploy.
  3. 画像最適化 Worker のデプロイ / Deploy Image Optimization Worker
    pnpm deploy:image-worker（wrangler deploy -c wrangler.image-optimizer.toml） Runs wrangler deploy -c wrangler.image-optimizer.toml.

NFR-016Cloudflare Workers / Edge 上の制約 Cloudflare Workers / Edge Constraints

制約 / Constraint 内容 / Details
Node.js 互換 Node.js Compatibility next start 前提のパッケージは動作しないことがある。compatibility_flags = ["nodejs_compat", "global_fetch_strictly_public"] を指定する Packages requiring next start may not work. Specify compatibility_flags = ["nodejs_compat", "global_fetch_strictly_public"].
CPU・実行時間 CPU & Execution Time リクエストあたりの CPU 時間に上限あり。画像軽量化のような重い処理は Queues で別 Worker に分離する CPU time per request is limited. Offload heavy processing (e.g., image optimization) to a separate Worker via Queues.
バインディング Bindings D1・R2・Queues は getCloudflareContext({ async: true }) で取得した env から参照する Access D1, R2, and Queues bindings through env obtained via getCloudflareContext({ async: true }).

NFR-017参照ドキュメント（公式） Reference Documentation (Official)