1k-architecture

OneKey アーキテクチャ概要

プラットフォーム構成

• apps/desktop/ - Electron デスクトップアプリ（Windows、macOS、Linux）
• apps/mobile/ - React Native モバイルアプリ（iOS、Android）
• apps/ext/ - ブラウザー拡張機能（Chrome、Firefox、Edge、Brave）
• apps/web/ - プログレッシブウェブアプリケーション
• apps/web-embed/ - 埋め込み可能なウォレットコンポーネント

コアパッケージ

• packages/core/ - ブロックチェーンプロトコルの実装、暗号技術、ハードウェアウォレットとの通信
• packages/kit/ - アプリケーションロジック、状態管理、API 統合
• packages/kit-bg/ - バックグラウンドサービスとワーカー
• packages/components/ - Tamagui ベースのクロスプラットフォーム UI コンポーネント
• packages/shared/ - プラットフォーム抽象化、ユーティリティ、ビルド設定
• packages/qr-wallet-sdk/ - エアギャップウォレットの QR 通信

主なアーキテクチャパターン

• マルチチェーン対応：40 以上のブロックチェーンに対応し、チェーン実装をプラグインで追加できます
• クロスプラットフォーム UI：プラットフォーム固有の調整を加えた共通コンポーネントに Tamagui を使用
• プラットフォーム固有ファイル：.native.ts、.desktop.ts、.web.ts、.ext.ts のサフィックスを使用
• ハードウェアウォレット統合：カスタムの @onekeyfe/hd-* SDK パッケージ
• 状態管理：アトミックな状態管理に Jotai を使用

コード構成

ファイル命名規則

• プラットフォーム固有の実装には、.native.ts、.web.ts、.desktop.ts、.ext.ts のサフィックスを使用します
• コンポーネントファイルには PascalCase を使用します：ComponentName.tsx
• フックファイルには、use を接頭辞とする camelCase を使用します：useHookName.ts
• ユーティリティファイルには camelCase を使用します：utilityName.ts

インポートパターン

• ワークスペース参照を使用します：@onekeyhq/components、@onekeyhq/core、@onekeyhq/kit
• @onekeyhq/shared/src/platformEnv でプラットフォームを判定します
• プラットフォームの機能に基づいて条件付きでインポートします

インポート階層のルール - 厳守

重要：これらのルールに違反すると、ビルドが壊れ、循環依存が発生します。

階層（この順序には絶対に違反しないでください）：

• @onekeyhq/shared - 他の OneKey パッケージからのインポートは禁止
• @onekeyhq/components - shared からのインポートのみ許可
• @onekeyhq/kit-bg - shared と core からのインポートのみ許可（components と kit からは禁止）
• @onekeyhq/kit - shared、components、kit-bg からインポートできます
• アプリ（desktop/mobile/ext/web） - すべてのパッケージからインポートできます

インポートを追加する前に：

1. 上記の階層に従っていることを確認します
2. インポートによって循環依存が発生しないことを確認します
3. 判断に迷う場合は、階層に従う別の方法を探します

よくある違反例：

• ❌ @onekeyhq/components から @onekeyhq/kit をインポートする
• ❌ @onekeyhq/kit-bg から @onekeyhq/components をインポートする
• ❌ @onekeyhq/core から @onekeyhq/kit をインポートする
• ❌ 階層上の「上位」へのインポート全般

コンポーネント構成

• UI コンポーネントは packages/components/src/ に配置します
• ビジネスロジックは packages/kit/src/ に配置します
• チェーン固有のコードは packages/core/src/chains/ に配置します

詳細分析とアーキテクチャ一貫性フレームワーク

変更前の分析プロトコル

必須の分析手順（コードを変更する前に実施してください）：

1. 影響範囲の評価

   • 変更の影響を受けるすべてのパッケージ／アプリを特定します
   • 影響を受ける依存関係を把握します（必要に応じて yarn why <package> を使用します）
   • クロスプラットフォームへの影響を評価します（デスクトップ／モバイル／ウェブ／拡張機能）
   • 後方互換性の要件を確認します

2. パターンの一貫性の検証

   • コードベース内の類似した既存の実装を調べます
   • 確立されたパターンと規約を特定します
   • 新しいコードが同じパターンに従っていることを確認します
   • 命名規則が既存のコードと一致していることを確認します

3. アーキテクチャの整合性チェック

   • モノレポのインポート階層ルールに準拠していることを確認します
   • 関心の分離が維持されていることを確認します
   • プラットフォーム固有のコードで適切なファイル拡張子が使用されていることを確認します
   • ビジネスロジックが適切なパッケージに配置されていることを確認します

4. パフォーマンスへの影響の評価

   • バンドルサイズへの影響を考慮します（特にウェブ／拡張機能）
   • 実行時のパフォーマンスへの影響を評価します
   • メモリ使用量への影響を評価します
   • アプリケーションの起動時間への影響を考慮します

コードパターン認識フレームワーク

新しい機能を追加する場合：

1. 類似例を探す：コードベースで類似した実装を検索します
2. パターンを抽出する：一般的なアプローチ、命名、構造を特定します
3. 規約に従う：既存のパターンをそのまま踏襲します
4. 一貫性を検証する：新しいコードが既存のコードと同じように見えることを確認します

既存のコードを変更する場合：

1. コンテキストを把握する：周辺のコードとインポートを読みます
2. パターンを維持する：既存のアーキテクチャ上の判断を維持します
3. スタイルを統一する：既存のコードスタイルと構造に合わせます
4. 統合を検証する：変更がシームレスに統合されることを確認します

アーキテクチャ検証チェックリスト

変更をコミットする前に：

• インポート階層ルールを遵守している（上位へのインポートがない）
• プラットフォーム固有のファイルで適切な拡張子を使用している
• セキュリティパターンを維持している（特に暗号処理）
• 確立されたパターンに従ってエラーを処理している
• 状態管理パターンを一貫して適用している
• UI コンポーネントのパターンに従っている（Tamagui の使用）
• 翻訳パターンを適切に実装している
• テストパターンを維持し、拡張している