プラグインエコシステム Round 3 安定性・拡張性計画（v0.4.x）

本計画は Round 2（M1-M6）の後続フェーズです。sharelife を「機能実装済み」から「長期運用可能な品質」に引き上げます。

1. 目標と境界

1.1 目標

1. 同時実行、障害、バージョンドリフト下での安定性確保。
2. 将来拡張時の再設計コスト削減。
3. プロダクト方針（高精度複製 + 厳格ガバナンス）との整合。

1.2 非目標

1. 本フェーズでの重量級 SPA への全面移行は行わない。
2. 分散 DB への移行は行わない。
3. install/review ガードを緩和する方針は採らない。

2. 提案の採否

2.1 採用（実装対象）

1. vanilla モジュールを維持したまま Vite を導入。
2. UI 状態同期を単一イベントバス（EventTarget）へ集約。
3. ユーザー由来 HTML を DOMPurify でサニタイズ。
4. ARIA、キーボード操作、フォーカストラップの基線実装。
5. 永続化を Repository 抽象 + SQLite 実装 + JSON フォールバックへ移行。
6. scan/diff 重処理をバックグラウンド化（asyncio.to_thread など）。
7. 認証依存、レート制限、CORS、セキュリティヘッダーを強化。
8. structlog による構造化ログと Prometheus 指標を追加。
9. 公式 Docker（multi-stage）+ compose の配布パス整備。
10. CI にカバレッジ/ i18n / docs / protocol 整合ゲートを追加。

2.2 保留

1. PWA オフライン対応。
2. 無限スクロール中心の UI モデル。
3. Tailwind での全画面再スタイル。
4. SQLite 前に PostgreSQL/asyncpg へ直行する移行。

2.3 本フェーズで不採用

1. 重量級 SPA への全面書き換え。
2. ガバナンス門番を弱める高速化施策。

3. 技術方針（ADR 要約）

ADR-1: フロントエンド進化方針

決定:

1. vanilla JS の責務分割を維持。
2. Vite でビルドと成果物管理を標準化。
3. 状態同期にイベントバスを導入。

理由:

1. 破壊的変更を避けながら保守性を改善できる。
2. グローバルスクリプト依存を縮小できる。
3. 将来の宣言的更新に段階的に移行しやすい。

ADR-2: 永続化方針

決定:

1. market/profile-pack/audit/trial を Repository 抽象へ統一。
2. 既定実装を SQLite に切替。
3. JSON 実装をフォールバックとして残す。

理由:

1. 低コストで同時書き込み耐性を改善できる。
2. 既存レイヤード構造を維持できる。
3. 段階移行が可能で運用リスクを抑えられる。

ADR-3: セキュリティ・可観測性優先

決定:

1. 認証/制限/例外処理を先に強化。
2. 同フェーズでログとメトリクスを導入。

理由:

1. 機能拡張前に露出リスクを下げられる。
2. 観測不能な状態での拡張を防げる。

4. マイルストーン（N1-N5）

N1（整合性クローズ）

範囲:

1. プラグイン・API・メタデータ・文書のバージョン整合。
2. Round 2 状態表記を実装実態に合わせる。
3. エラーコード文書の正準化。

受け入れ:

1. バージョンドリフト検証テストが通る。
2. 文書状態の整合テストが通る。

N2（フロント保守性・安全性）

範囲:

1. Vite 導入。
2. 主要状態フローをイベントバスへ移行。
3. DOMPurify 適用。
4. ARIA/キーボード/フォーカス制御を実装。

受け入れ:

1. node --test tests/webui/*.js 緑。
2. market -> drawer -> wizard -> compare E2E が緑。
3. XSS 回帰ケースが無害化される。

N3（バックエンド永続化・並行性基線）

範囲:

1. SQLite Repository と移行ユーティリティ実装。
2. サービス層の Repository 抽象化適用。
3. pack_id/status/risk_level/created_at へ索引追加。

受け入れ:

1. JSON/SQLite 双方の回帰テストが通る。
2. 同時書き込み時に状態破損がない。

N4（セキュリティ・可観測性強化）

範囲:

1. ログイン/API レート制限。
2. セキュリティヘッダーと厳格 CORS。
3. 構造化ログスキーマ統一。
4. 指標エンドポイントと基本監視項目追加。

受け入れ:

1. 認可/総当たり/CORS の回帰テスト合格。
2. 障害時の原因特定がログと指標で可能。

N5（配布・運用）

範囲:

1. 公式 Docker イメージと compose サンプル。
2. データボリュームとヘルスチェック整備。
3. デプロイ/ロールバック手順書更新。

受け入れ:

1. コンテナ起動で WebUI と主要 API が再現可能。
2. ローカル/コンテナ両方の手順が文書化済み。

5. リスクとトレードオフ

1. ビルド導入で前端複雑性は上がる。 対策: 責務分割維持、重フレームワークは導入しない。
2. ストレージ移行で互換リスクがある。 対策: 移行ツール、段階切替、照合テストを先行。
3. セキュリティ既定強化でローカル利便性が下がる。 対策: dev/prod 設定プロファイルを明示。

6. 進捗スナップショット（2026-04-02 時点）

1. N1 完了: バージョン/文書整合テストを CI に導入済み。
2. N2 完了: イベントバス、i18n 同期、アクセシビリティ焦点制御、ブラウザ E2E 主経路が通過。
3. N3 完了: MarketService、ProfilePackService、PreferenceService、RetryQueueService、TrialService、TrialRequestService、AuditService、InMemoryNotifier は Repository 抽象へ移行済みで、JSON/SQLite 実装、SQLite 索引、legacy 移行経路を提供。
4. N4 基線完了: ログイン/API レート制限、セキュリティヘッダー、Request ID 追跡、構造化リクエストログ、統一エラーフォーマット（internal_server_error フォールバック含む）、auth/rate-limit 専用カウンタを含む /api/metrics を実装し、メトリクス path 基数ガードとエラーストーム時のスクレイプ回帰テストを追加。
5. N5 基線完了: 公式 Dockerfile/compose、ヘルスチェック、スタンドアロン WebUI 起動スクリプトに加え、可観測性/ロールバック runbook を整備。
6. N5+ 運用閉鎖を完了: docker-compose 可観測性オーバーレイ、smoke 自動検証スクリプト（scripts/smoke_observability_stack.sh）、および定期/手動実行 + 診断 artifact 保存付きの ops-smoke GitHub Actions ワークフローを追加。
7. N5++ 診断高速化を完了: smoke 診断で構造化サマリ/データ（output/ops-smoke/triage.md + triage.json）を自動生成し、Job Summary 反映 + signal/action annotations 出力まで実施。

7. 推奨実行順

1. N1 -> N2 -> N3 -> N4 -> N5。
2. N1-N2 完了までは大規模機能拡張を抑制。
3. 各マイルストーンでテスト・文書・ロールバック手順を同時出荷。

8. 既存ロードマップとの関係

1. Round 2 の機能面は維持。
2. Round 3 は品質・運用基盤の強化フェーズ。
3. ガバナンス不変条件（dry-run 先行、rollback 可能、監査可能）を維持。