joe/h1-c2

Watch

Fork 0

Table of contents

Mattermost 連携アーキテクチャ

全体像
1. OpenCode Mattermost MCP Tools（外部コンポーネント）

概要
提供ツール一覧
プロトコル
実装場所
認証
用途（h-1-coreとの関係）

2. MmCommandService — MM Command Bridge（現行ポーリング）

アーキテクチャ
認証
ポーリング詳細
状態永続化（SharedPreferences）
利用可能コマンド一覧
DebugConsole（コマンドレジストリ）

3. ErrorReporter — エラー報告

3経路同時送信
メッセージフォーマット
送信トリガー

4. MattermostBridge — 旧ポーリングシステム

MmCommandServiceとの違い

5. APIエンドポイント使用一覧
6. 設定・認証情報の保存場所

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Mattermost 連携アーキテクチャ

全体像

┌──────────────────────────────────────────────────────────┐
│                    OpenCode (AI Agent)                     │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │  Mattermost MCP Tools (本リポジトリ外)              │    │
│  │                                                    │    │
│  │  mattermost_get_channel_messages()                 │    │
│  │  mattermost_get_user_status()                      │    │
│  │  mattermost_get_post() など全23ツール              │    │
│  │                                                    │    │
│  │  ※ MCP (Model Context Protocol) サーバーとして      │    │
│  │     OpenCode環境側で動作。h-1-coreのコードではない   │    │
│  └──────────────────┬───────────────────────────────┘    │
└──────────────────────┼────────────────────────────────────┘
                       │ MCP Protocol (stdio/HTTP)
                       │
┌──────────────────────▼────────────────────────────────────┐
│                 Mattermost Server                          │
│           https://mm.ka.sugeee.com                         │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │  Team: cyb                                       │    │
│  │  Channel: h1-debug                               │    │
│  └──────────────────────────────────────────────────┘    │
└───┬──────────────────────┬──────────────────────┬─────────┘
    │ PAT (Bearer Token)    │ Webhook              │ Bot Token
    ▼                       ▼                      ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│ MmCommandService   │  │ ErrorReporter     │  │ MattermostBridge │
│ (現行ポーリング)    │  │ (エラー報告)       │  │ (旧ポーリング)    │
│                    │  │                   │  │                  │
│ lib/services/      │  │ lib/services/     │  │ lib/services/    │
│ mm_command_        │  │ error_reporter    │  │ mattermost_      │
│ service.dart       │  │ .dart             │  │ bridge.dart      │
│                    │  │                   │  │                  │
│ 15秒間隔ポーリング   │  │ エラー発生時に    │  │ 10秒間隔ポーリング │
│ !opencode コマンド  │  │ PAT/Webhook/Gmail│  │ Bot Token方式    │
│ →スレッド返信       │  │ 3経路同時送信    │  │ 結果はWebhook経由 │
│ PAT認証            │  │                  │  │                  │
│                    │  │                  │  │                  │
│ 認証情報:          │  │ 認証情報:         │  │ 認証情報:         │
│ SecureStorage      │  │ SecureStorage     │  │ SecureStorage    │
└──────────────────┘  └──────────────────┘  └──────────────────┘

MCPツール: OpenCodeがmmcheckなどで使うMattermost操作用ツール群。MCPサーバーとして実装され、mattermost_get_channel_messages 等のツールをAIエージェントに提供する。実装コードは本リポジトリ外。
アプリ内3コンポーネント: h-1-coreアプリが自らMattermost APIを呼び出す実装。いずれもhttpパッケージでREST APIを直接叩く（MCPは使わない）。

1. OpenCode Mattermost MCP Tools（外部コンポーネント）

概要

OpenCodeの実行環境に組み込まれたMCPサーバー。AIエージェントがMattermostを操作するためのツールを提供する。

提供ツール一覧

ツール名	用途
`mattermost_get_channel_messages`	チャンネルのメッセージ履歴取得
`mattermost_get_user_status`	ユーザーのオンライン状態確認
`mattermost_get_post`	個別投稿の取得
`mattermost_get_thread`	スレッド全文取得
`mattermost_send_message`	メッセージ送信
`mattermost_search_posts`	投稿検索
`mattermost_add_reaction`	リアクション追加
`mattermost_upload_file`	ファイルアップロード
... 他15ツール

プロトコル

MCP (Model Context Protocol) で実装。stdio またはHTTPトランスポートを使用。

実装場所

本リポジトリ外（OpenCode実行環境/各種MCPサーバーパッケージ）。h-1-coreプロジェクトでは管理しない。

認証

Mattermost Personal Access Token（PAT）。opencode.json 等の設定ファイル経由でMCPサーバーに渡される。

用途（h-1-coreとの関係）

mmcheck: h1-debugチャンネルからエラー報告を取得し解析
エラーログ監視
開発者ステータス確認

2. MmCommandService — MM Command Bridge（現行ポーリング）

lib/services/mm_command_service.dart

Mattermostのh1-debugチャンネルをポーリングし、!opencode <cmd> 形式の投稿を検出してアプリ内コマンドを実行する。

アーキテクチャ

Mattermost h1-debugチャンネル
  │
  │ ユーザーが !opencode ping と投稿
  │
  ▼ 15秒間隔ポーリング
MmCommandService._poll()
  │
  ├─ GET /api/v4/channels/{chId}/posts?since={timestamp}
  │   ↑ since以降の新規投稿のみ取得
  │
  ├─ プレフィックス "!opencode" チェック
  ├─ スレッド返信（parent_id != null）はスキップ
  ├─ 処理済みID重複チェック
  │
  ▼
_dispatch()
  │
  ├─ "!opencode " 以降を抽出
  ├─ スペース分割でコマンド名+引数に分解
  ├─ DebugConsole.call(name, args) で実行
  │
  ▼
  POST /api/v4/posts でスレッド返信（root_id = 元投稿のID）

認証

PAT (Personal Access Token) — SecureStorageService に保存（flutter_secure_storage）。従来のSharedPreferences平文保存から移行済み。

ポーリング詳細

項目	値
間隔	15秒（`Duration(seconds: 15)`）
コマンドプレフィックス	`!opencode`
対象チャンネル	`h1-debug`（固定）
チーム	`cyb`（デフォルト、環境変数`MATTERMOST_TEAM_NAME`で上書き可）
Base URL	`https://mm.ka.sugeee.com`（デフォルト、環境変数`MATTERMOST_BASE_URL`で上書き可）

状態永続化（SharedPreferences）

キー	用途
`mm_polling_enabled`	ON/OFF状態
`mm_polling_last_check`	最終チェック時刻（unix ms）
`mm_processed_posts`	処理済み投稿IDリスト（直近200件）

利用可能コマンド一覧

DebugConsole に登録された全コマンド。登録元によってグループ化：

コマンド	登録元	説明
`ping`	`main.dart:286`	`pong`
`mmcheck`	`main.dart:287`	MM接続診断
`system.status`	`main.dart:288`	DBサイズ表示
`system.dump`	`main.dart:289`	全テーブル行数ダンプ
`db.send`	`main.dart:290`	DBファイルをMMにアップロード
`db.snapshot`	`main.dart:291`	DBスナップショット作成
`db.restore`	`main.dart:295`	スナップショット復元
`documents.stats`	`documents_plugin.dart:86`	伝票統計
`db.repair`	`documents_plugin.dart:93`	DB修復
`db.purge`	`documents_plugin.dart:97`	DBパージ
`customers.stats`	`customers_plugin.dart:35`	顧客統計
`products.stats`	`products_plugin.dart:30`	商品統計
`purchase.stats`	`purchase_plugin.dart:27`	仕入統計
`company.info`	`company_plugin.dart:30`	自社情報
`pricing.dump`	`price_list_plugin.dart:31`	価格設定情報

DebugConsole（コマンドレジストリ）

lib/services/debug_console.dart

シンプルなコマンドレジストリ。register(name, fn) で追加、call(name, args) で実行。

特徴:

部分一致対応: db.s と入力しても db.send / db.snapshot が一意なら実行
曖昧一致検出: 複数マッチ時は候補一覧を返す
不明コマンド時は登録済み一覧を表示

3. ErrorReporter — エラー報告

lib/services/error_reporter.dart

アプリ内で発生したエラーを3経路同時にMattermostへ報告する。

3経路同時送信

エラー発生
  │
  ├─ PAT経由 (_sendViaPat)         ───→ MM API (Bearer Token)
  ├─ Webhook経由 (_sendViaWebhook) ───→ MM Incoming Webhook
  └─ Gmail経由 (sendErrorViaGmail) ───→ Gmail API (OAuth2)

メッセージフォーマット

### ⚠️ h-1-core エラー報告 (2026/06/19 12:34:56)
**version:** 1.2.3
**message:** Null check operator used on a null value
**screen:** D1
**detail:** ...
**stack:**
...

送信トリガー

FlutterError.onError — Flutterフレームワークエラー（main.dart:259）
PlatformDispatcher.instance.onError — ネイティブクラッシュ（main.dart:267）
tryWithReport() — 任意の非同期処理のエラーハンドリングラッパー

4. MattermostBridge — 旧ポーリングシステム

lib/services/mattermost_bridge.dart

MmCommandService の前身。現在はレガシー扱い。

MmCommandServiceとの違い

項目	MmCommandService	MattermostBridge
認証方式	PAT	Bot Token
対象ユーザー	全ユーザー	特定開発者（devUserId）
結果返信	スレッド返信（POST /api/v4/posts）	Webhook
取得方法	sinceパラメータで差分取得	全件取得＋ID比較
間隔	15秒	10秒
状態	現行	レガシー

5. APIエンドポイント使用一覧

h-1-coreが使用するMattermost REST APIエンドポイント：

エンドポイント	メソッド	使用コンポーネント
`/api/v4/system/ping`	GET	ErrorReporter, MmCommandService
`/api/v4/teams/name/{name}`	GET	全コンポーネント
`/api/v4/teams/{teamId}/channels/name/{name}`	GET	全コンポーネント
`/api/v4/channels/{channelId}/posts?since={ts}`	GET	MmCommandService
`/api/v4/channels/{channelId}/posts`	GET	MattermostBridge
`/api/v4/posts`	POST	全コンポーネント
`/api/v4/files`	POST (Multipart)	MmCommandService, ErrorReporter

6. 設定・認証情報の保存場所

キー定数	保存先	用途
`mattermost_pat`	SecureStorage	PATトークン
`mattermost_base_url`	SecureStorage	MMサーバーURL
`mattermost_team_name`	SecureStorage	チーム名
`mm_bot_token`	SecureStorage	Bot Token（旧）
`mm_dev_user_id`	SecureStorage	開発者ユーザーID（旧）
`mattermost_webhook_url`	SecureStorage	Webhook URL

環境変数からのデフォルト上書き：

環境変数	上書き対象
`MATTERMOST_BASE_URL`	Base URL（デフォルト: `https://mm.ka.sugeee.com`）
`MATTERMOST_TEAM_NAME`	チーム名（デフォルト: `cyb`）
`MATTERMOST_WEBHOOK_URL`	Webhook URL（デフォルト: 空）

認証情報の定数定義: lib/constants/secure_storage_keys.dart 環境変数の定義: lib/constants/env_config.dart