非機能要件定義書

HackⅡ — 性能・セキュリティ・可用性・拡張性

作成日: 2026-05-25 バージョン: 1.0

1. 性能要件（Performance）

1-1. レスポンスタイム目標

API / 処理	p50	p95	p99	測定条件
Hackall イベント収集（`POST /events`）	30ms	100ms	200ms	通常負荷時
ダッシュボードサマリー取得	100ms	300ms	500ms	通常負荷時
ダッシュボードタイムライン取得	200ms	500ms	1000ms	90日分データ
Tsukull ポリシー判定（Workersメモリ内）	1ms	5ms	10ms	エッジ処理
Pay per Crawl 課金イベント記録	5ms	20ms	50ms	非同期キュー経由
Misell 1記事パッチ生成	1s	3s	5s	5,000文字記事
Misell 100記事一括生成	20s	45s	60s	並列8ワーカー

1-2. スループット目標

対象	目標値	測定基準
Hackall イベント収集API	10,000 req/min（全顧客合計）	負荷テスト
Tsukull ゲートウェイ	1,000 req/sec（Cloudflare Workersの制限内）	Cloudflare Analytics
ダッシュボードAPI（同時接続）	500同時接続でレスポンスタイム目標を維持	負荷テスト

1-3. データ量想定

データ種別	初年度想定	3年後想定	対策
crawl_events 行数	1億行/年	5億行/年	月次パーティション + 古いデータは集計テーブルへ移行
user_events 行数	5000万行/年	2億行/年	同上
ai_patch JSONファイル数	10万ファイル	100万ファイル	CDN + オブジェクトストレージ（階層管理）
ダッシュボードセッション	1万/日	10万/日	Redisセッション + CDNキャッシュ

2. 可用性・信頼性要件（Availability & Reliability）

2-1. SLA定義

コンポーネント	SLA目標	月間許容ダウンタイム	対策
Hackall 計測API	99.9%	43分	マルチAZ + ヘルスチェック自動フェイルオーバー
Tsukull ゲートウェイ	99.99%	4.3分	Cloudflare Workers（SLA準拠）
ダッシュボードUI	99.5%	3.6時間	計画メンテナンス時間を含む
Misell パッチ生成	99.0%	7.2時間	ジョブキューによる非同期処理（即時失敗しない）
Pay per Crawl 課金	99.99%	4.3分	二重課金リスクのため最高SLAを設定

2-2. 障害回復目標

指標	定義	目標値
RTO（Recovery Time Objective）	障害検知から復旧までの時間	30分以内
RPO（Recovery Point Objective）	データ欠損の許容範囲	直近1時間のイベントデータのみ許容

2-3. バックアップ要件

データ種別	バックアップ頻度	保持期間	復元テスト
PostgreSQL 全データ	日次（フル）+ 1時間毎（WAL）	30日間	月次復元テスト必須
Redisデータ	日次スナップショット	7日間	不要（揮発性データ）
S3/R2 パッチファイル	バージョニング有効	無期限（世代管理）	不要

3. セキュリティ要件（Security）

3-1. 認証・認可

機能	認証方式	認可設計
顧客ダッシュボード	メール+パスワード + MFA（TOTP）必須	JWT（有効期限1時間）+ Refresh Token
管理者ダッシュボード	メール+パスワード + MFA 強制	管理者ロール分離（RBAC）
AI事業者 APIキー	APIキー（`hk_live_xxx`形式）	APIキーはハッシュ化して保存
内部サービス間通信	mTLS	Cloudflare Zero Trust

3-2. データ保護

データ	保護方針	実装方法
IPアドレス	生IPを保存しない	受信時にSHA-256ハッシュ化（塩付き）してから保存
APIキー	平文保存禁止	bcrypt or Argon2 でハッシュ化
顧客メールアドレス	暗号化保存推奨	AES-256-GCM
DBパスワード	環境変数 / Secrets Manager	AWS Secrets Manager or Cloudflare Secrets
AICS™アルゴリズム	ソースコード秘密保持	プライベートリポジトリ + NDA

3-3. OWASP Top 10 対応

リスク	対策
A01 アクセス制御の不備	RBAC実装・管理者/顧客データ完全分離
A02 暗号化の失敗	TLS 1.2以上必須・AES-256保存暗号化
A03 インジェクション	ORMのパラメータバインディング必須・生SQL禁止
A04 安全でない設計	レートリミット・CSRF保護・入力バリデーション
A05 セキュリティの設定ミス	本番環境デバッグモード無効・不要ポート閉鎖
A07 認証の失敗	MFA必須・ブルートフォース対策（5回失敗でロック）
A08 ソフトウェアの完全性不備	npm audit / Dependabot 週次実行
A09 ログ・監視の失敗	全認証イベント・課金イベントのログ必須

3-4. 脆弱性診断・ペネトレーションテスト

リリース前に第三者によるペネトレーションテストを実施（費用はRegalisが負担）
OWASP ZAP による自動スキャンをCI/CDに組み込む

4. 拡張性・保守性要件（Scalability & Maintainability）

4-1. スケール設計

コンポーネント	スケール方式	トリガー条件
APIサーバー（ECS）	水平スケール（Auto Scaling）	CPU 70% 超 or レスポンスタイム p95 > 1s
Misellワーカー（ECS）	ジョブキュー深さによる自動スケール	キュー深さ > 100件
PostgreSQL	Read Replica追加	リードスループット不足時
Redis	ElastiCache クラスターモード	メモリ使用率 80% 超

4-2. コード品質要件

項目	要件	ツール
型安全性	TypeScript strict モード必須	tsc –strict
テストカバレッジ	ユニットテスト ≥ 80%	Vitest + c8
E2Eテスト	主要ユーザーフロー全網羅	Playwright
コードスタイル	Biome（ESLint + Prettier統合）でリント	CI/CDで自動チェック
コードレビュー	全PRに最低1名のレビュー必須	GitHub Protected Branch
ドキュメント	全APIエンドポイントにOpenAPIドキュメント	Swagger UI

4-3. 将来の拡張を想定した設計方針

AIモデル識別テーブルは設定ファイル（JSON）で管理 — 新しいAIモデルが登場したらコード変更不要で追加できること
価格テーブルも設定ファイル化 — 料金改定時にコード変更不要
AICS™スコアの次元は拡張可能な設計 — 将来D7・D8が追加されてもスコアリングエンジンを大幅改修しなくて済むこと
マルチテナント設計を最初から — 全テーブルに site_id / account_id を必ず持たせる
イベントドリブン設計 — 機能間の依存はイベントキュー経由（直接呼び出しを避ける）

5. 監視・オブザーバビリティ要件

5-1. 必須メトリクス

カテゴリ	メトリクス	アラート閾値
インフラ	CPU使用率	> 80% が5分継続
インフラ	メモリ使用率	> 85% が5分継続
API	p95レスポンスタイム	> 1000ms が3分継続
API	エラー率	> 1% が1分継続
DB	コネクション数	> 80% of max_connections
DB	スロークエリ	> 1000ms のクエリ発生
ビジネス	課金イベント失敗	1件でもアラート
ビジネス	パッチ生成失敗	連続3件失敗でアラート

5-2. ログ設計

構造化ログ（JSON形式）で全アプリケーションログを出力すること。

必須フィールド：

{
  "timestamp": "2026-05-25T10:30:00Z",
  "level": "info",
  "service": "hackall-api",
  "trace_id": "trace_xxxxxxxx",
  "account_id": "uuid",
  "site_id": "site_abc123",
  "message": "crawl event recorded",
  "duration_ms": 45
}

ログ保持期間:

エラーログ: 90日
アクセスログ: 30日
監査ログ（認証・課金イベント）: 2年

6. 開発環境・デプロイ要件

6-1. 環境分離

環境	用途	データ
local	個人開発	Docker Compose でモック
staging	結合テスト・顧客デモ	本番と同等構成・テストデータ
production	本番	実データ・フルスケール

本番DBのデータをstagingに直接コピーしないこと（個人情報保護）

6-2. CI/CDパイプライン必須ステップ

PR作成
  → [Lint] Biome チェック
  → [Type] tsc --strict
  → [Test] Vitest ユニットテスト（カバレッジ80%ゲート）
  → [Security] npm audit + OWASP ZAP スキャン
  → [Build] Dockerイメージビルド
  → [Deploy to Staging] 自動デプロイ
  → [E2E Test] Playwright
  → [Manual Review] コードレビュー承認
mainにマージ
  → [Deploy to Production] GitHub Actions 自動デプロイ
  → [Smoke Test] 本番ヘルスチェック確認