Nucleus Studio 仕様書 v1.1
（プログラマー実装指示用）

1. はじめに

Nucleus Studioは、配信/ストリーミングに特化した拡張型デスクトップアプリケーションです。プラグイン（モジュール）・外観パックによる柔軟なカスタマイズが最大の特徴です。設計・実装にあたっては以下の構成・運用・セキュリティ・UX要件を必ず満たしてください。

2. ディレクトリ・システム構成

README.mdを参照

3. 外観システム（AppearancePack / テーマ）

.nclxa (ZIP拡張子)
├─ appearance.json          # メタデータ + トークン定義
├─ assets/                  # 画像・アイコン類
├─ qss/                     # Qt StyleSheet ファイル
├─ js/                      # 将来の動的挙動フック用
└─ signature.sig            # ECDSA署名ファイル
        

{
  "name": "MyTheme",
  "version": "1.0.0",
  "tokens": {
    "colors": {"bg.window":"#202020","accent":"#4a90e2"},
    "fonts": {"base":{"family":"Noto Sans","size":12}},
    "shapes": {"button.radius":6},
    "motion": {"click.scale":0.97}
  },
  "css": ["core.css"],
  "qss": ["core.qss"],
  "js": ["core.js"],
  "licence": "XXXXX-12345-ABCDE-67890-ZZZZZ",
  "signature": "signature.sig"
}

4. モジュールシステム

nucleus_studio/app/modules/<ModuleName>/
├─ module.json          # モジュール情報・通信定義
├─ ui.py                # ThemeableWidget 継承のUIクラス
├─ logic.py             # BaseModule 継承のロジック処理クラス
└─ default_tokens.json  # デフォルト外観トークン（オーバーライド用）
        

{
  "name": "ChatFetcher",
  "entry_point": "ui",
  "class_name": "Module",
  "publish": [
    {
      "topic": "chatfetcher.chat.v1",
      "description": "YouTube Live のチャットデータ",
      "payload_example": {"user":"Alice","text":"Hi!","stamp":1234567890}
    }
  ],
  "subscribe": [
    {"topic":"module_name.moduleA.v1","description":"フィルタ後チャット"}
  ]
}

5. レイアウト管理 (GridManager)

6. DataBridge（モジュール間連携）

from app.logic.core.databridge import db

# 最新メッセージのみ受信（デフォルト）
db.subscribe(
    "topic.id.v1",  # トピックID
    handler_fn      # コールバック (msg_dict, history=False)
)

# 履歴キュー有効化
db.subscribe(
    "topic.id.v1",
    handler_fn,      # コールバック (msg_dict, history: bool)
    queue=True,      # キュー機能ON
    maxlen=1000,     # 最大保持件数
    persist="disk"   # "memory" or "disk"
)

# メッセージ送信
db.publish(
    "topic.id.v1",
    {"key": value, ...}  # Python辞書形式
)
# queue=False → リアルタイムメッセージのみ通知（history=False）
# queue=True → キュー保存し、履歴含め通知（history=True）
# persist="disk" → userdata/bridge_queues/.db にSQLite永続化

7. ホットキー管理 (HotkeyManager)

グローバルホットキー登録と競合検知

• register(key, module, callback) でグローバル登録
• 競合検知：同一キーの重複登録時、既存・新規双方をdisableし設定画面の該当行を赤表示

設定ダイアログ（app/ui/dialogs/hotkey_dialog.py）:

• 列：モジュール名 / 説明 / キー入力欄 / 優先度上下ボタン
• キー入力は押下したキーをリアルタイムで記録 (例: Ctrl+Shift+T)

8. Streaming Mode

• マスクタグ固定: [MASK]...[/MASK]
• マスク設定で選択可能: * (星マーク)、透過、非表示、黒塗り
• 実行は BaseModule.set_streaming_mode(enabled) で動作切替

9. API Manager

.env と各 module.json の env_keys をGUIのテーブルに統合表示

• 列：モジュール / Key / Value
• Value列のみ編集可能
• 保存後、即 .env ファイルを書き換え

10. Marketplace & 決済

11. ライセンス管理

• 初回アクティベーションはLicense API経由で署名取得・token保存
• 起動から厳密に7日ごとにバックグラウンドで再検証自動実行
• 検証成功時は無通知、失敗時はダイアログ表示＋対象モジュールグレーアウト
• 再試行ボタンで即再検証可能、オフライン許容は最大7日間
• 署名鍵ローテーションは180日サイクル
• 公開キーはサーバーでアーカイブ、署名JSONに key_id 埋め込み
• サブスクプランに応じて認証端末数制限、切替UI実装

12. ログ & 監査

12.1. クライアント側

例外・警告を userdata/logs/YYYYMMDD_HHMMSS.log にテキスト出力

12.2. サーバー側（管理API）

以下イベントをDB+ファイル保存、送信:

• ユーザー登録
• ログイン (IP付き)
• ユーザーパック購入履歴と時間
• パッケージアップロード
• 署名処理
• 管理者操作 (IP付き)

13. アップデート

• 検知方法: バックエンド比較 or manifest 更新チェック
• UIにバッジ表示で通知
• 適用方法: 手動 / 自動選択可能
• 自動アップデートはバックグラウンドでダウンロード後、再起動促し

14. CI / CD

• GitHubのリポジトリは https://github.com/cqroyabasty/Nucleus-studio.git
• ディレクトリはルート nucleus_studio/ 配下にコード配置（api/ と app/ に分離）
• 変更を加えたら python -m py_compile $(git ls-files '*.py') と pytest -q を実行
• プルリクエスト前に git pull --rebase で競合解消
• GitHub Actions利用: Windows runner で pytest, pytest-qt 実行
• PyInstallerでEXE作成、成功時はGitHub Releaseにアセット追加
• macOS向けジョブは後日追加予定
• API/SDKドキュメントは公式リポジトリで公開
• バージョン管理はAPIごとに v1/v2 表示、非互換時はDeprecation告知
• CI/CD失敗時はデベロッパーと管理画面へ通知

15. 管理用API (運営外不出)

15.1. 認証・ユーザー管理系（確定）

15.2. マーケットプレイス & ライセンス系（確定）

15.3. 開発者API（確定）

エンドポイント一覧:

• /dev/upload-sign 未署名 .ncxlm / .nclxa をClamAVスキャン後HSM署名、devpack.sig返却
• /dev/stats 自身の売上・ダウンロード数照会
• /dev/publish/{id}/promote 公開ステータス切替・価格変更

認可: JWT role=developer + 2FA

15.4. 親ソフト固有API（確定）

• /profile/push プロファイルをクラウドにアップロード（現状は無効）
• /profile/pull/{id} プロファイル共有URL→JSON返却
• /backup/upload バックアップアップロード（後日有効化予定）

15.5. 運営用ローカルAPI（8100ポート・確定）

16. Undo / Redo & カラーバリエーション

UI配色のUndo/Redoバッファ数はサブスクプランにより異なる：

• Free: 20
• Basic: 30
• Pro, Team: 50
• Team Pro: 70

個人設定で上限の増減可（メモリ使用注意警告付き）。カラーバリエーションプリセットは10種＋無制限カスタム可能。自作テーマの保存も対応。

17. ログ・監査・エラー共有

• 設定・変更・エラーはローカルとサーバー双方に自動記録
• エラー・統計共有はユーザー同意制（初回起動時ダイアログでON/OFF設定可）
• 共有OFF時はローカル保存のみ、ON時は管理APIに匿名送信
• ユーザーは「マイアカウント」画面で自分のログと共有状況を確認・ダウンロード可能

18. クラウドバックアップ・複数端末同期

• プロファイル・モジュール・外観パックをクラウドに自動/手動バックアップ可能
• バックアップ数上限はプランにより異なる：
  • Free: 0
  • Basic: 3
  • Pro: 10
  • Team, Team Pro: 20
• 復元は世代指定、部分復元、全上書きから選択可
• 同期時はサーバーとローカルの競合を自動検知し、ユーザー選択ダイアログで解決
• バックアップ/同期履歴から自動ロールバック・世代管理

19. アクセシビリティ・VoiceVox連携

• カラーバリアフリー・高コントラストモード対応
• 全UIラベル・説明必須、スクリーンリーダー対応
• キーボード操作100%対応
• フォントサイズ変更、拡大鏡サポート
• テキスト読み上げON/OFF、VoiceVox連携対応
• エラー・警告・操作ガイドの読み上げ粒度を設定可能
• 将来的に読み上げOFF個別通知も実装予定

20. Marketplace / パッケージング / セキュリティ

個人開発者は、Githubのオープンソースよりモジュールを開発し販売することが可能。(正式リリース後ソースを公開。それまでの支援者β版は、公式モジュールのみの提供となる)

• .ncxlm（モジュール）、.nclxa（外観）は署名付きZIP形式の独自拡張子
• 自動スキャン対象拡張子: .py, .js, .qss, .json, .html, .svg, .ttf, .otf, .png, .jpg
• 禁止API・コード例: os.system, subprocess, eval, exec, 書込を伴う open, requests, socket, JSの eval 等
• 文字列検索＋サーバー側ウイルス・マルウェアスキャン（ClamAV等API）
• 異常検出時は運営通知扱いで二重チェック
• 管理画面・APIから承認・公開制御

21. 重大バグ・違反通報・エスカレーション

• バグ報告・通報時にユーザーが重要度を選択可能
• 重大バグ・違反はDiscord＋管理パネルで自動タグ付け→Botが即時通知
• 未対応時はリーダーに再通知
• 管理者は優先度フラグで「処理中」「対応完了」を管理
• 重大基準例：「全体利用不能」「データ消失」「セキュリティリスク」「著作権侵害」など
• 管理者は基準の追加・変更が可能

22. サポート・運用

• Discordスレッド＋Botコマンド＋Google Sheets連携で問い合わせ・フィードバック集計
• チケット管理・FAQ・マニュアルはWebサイトに常時公開
• FAQ・マニュアルには投票機能を設置し、役立つ/役立たないで優先順位を把握・改善

23. 法令・プライバシー・個人情報対応

• GDPR等の法規制準拠
• 「個人情報取得・消去」機能をマイアカウント画面で実装（消去は30日保留後完全消去）
• 同意済みユーザーのみエラー・統計ログを匿名収集
• 同意は初回ダイアログ＋設定画面で管理

24. その他機能・仕様

CodeX Plusプラン活用による実装プラン

1. 全体戦略

CodeXは自然言語から高品質Python、TypeScript、SQLなど多言語のコードを自動生成可能。大規模仕様の分割対応が得意で、単機能ごとに細かく分割して設計・コーディングできる。CLIはローカル環境で高速反復開発・テスト可能、IDE連携も容易。Plusプラン利用により十分なAPIリクエスト量とレスポンス品質が得られる。ChatGPT CodeXはコメント付きでわかりやすいコード生成ができるため、保守性・拡張性が高い。

2. 全体開発の流れ

3. タスク分割・コーディング自動化

仕様書を複数ファイルに分割し、1タスク1プロンプト化。例：「外観パック管理機能」「ホットキー登録管理クラス」「DataBridge通信モジュール」。CodeXに自然言語指示でクラスや関数設計案、実装コードを生成。生成コードはGit管理し、段階的に結合・修正を加え反復テスト。

3.1. テスト自動生成

各関数のDocstringや仕様説明を基に、pytest形式の単体テストコードを自動生成。例：「GridManagerのレイアウト割り当てテスト」。CLIでテスト実行→結果レポート自動生成。

3.2. CI/CDパイプライン生成

GitHub Actions用YAMLファイルをCodeXに作成依頼。ビルド、テスト、PyInstallerビルド、リリース登録まで一括管理。

3.3. APIドキュメント自動化

FastAPI等利用時はOpenAPI仕様の生成とマークダウン化をCodeXで自動作成。利用者向けドキュメントやSDKも生成支援。

4. 機能別実装プラン（重点）

5. 開発フェーズ詳細

1. フェーズ1：設計と仕様分割（1週間）
   • 仕様書を機能単位に分割
   • CodeXで各機能ごとに詳細設計案を生成
   • 実装すべきクラス・APIエンドポイント一覧作成
2. フェーズ2：コア機能実装（4週間）
   • UI基盤（PyQt6ベース）作成
   • DataBridge, HotkeyManager, Streaming Modeの骨格実装
   • 外観システムの初期機能（トークン展開・QSS適用）実装
3. フェーズ3：管理API・認証機能実装（3週間）
   • FastAPIによる管理API構築
   • 認証・ユーザー管理・マーケットプレイスAPI実装
   • Stripe決済連携とパッケージ管理
4. フェーズ4：テストとCI/CD整備（2週間）
   • CodeXでテストコード自動生成し単体テスト整備
   • GitHub ActionsによるCI/CDパイプライン構築
   • PyInstallerでビルド、リリース作成
5. フェーズ5：ドキュメント作成と運用準備（1週間）
   • APIドキュメント、ユーザーマニュアル生成
   • FAQ、運用フロー整備
   • Discord連携Bot・問い合わせ管理構築

6. 開発環境推奨

• Python 3.11以上
• PyQt6
• FastAPI + Uvicorn
• SQLite（ローカル永続化用）
• GitHubリポジトリでバージョン管理
• OpenAI CodeX APIアクセス (Plusプラン)
• GitHub ActionsでCI/CD

7. 運用と保守

• CodeX CLIを継続的活用し、新機能・バグ対応のコード生成と修正を迅速化
• GitHub PRベースでコードレビュー・QA
• バージョニング管理を厳格に実施しAPI互換を維持
• 運営用管理APIのログ・監査機能を活用して安定運用