ErisPulse アダプタ標準化返却仕様

1. 説明

なぜこの規格があるのでしょうか？

各プラットフォームの送信インターフェースが一貫性とOneBot12との互換性を確保するため、ErisPulseアダプターはAPIレスポンス形式においてOneBot12が定義するメッセージ送信返却構造の標準を採用しています。

ただしErisPulseのプロトコルにはいくつかの特殊な定義があります:

• 1. 基本フィールドにおいて、message_idは必須ですが、OneBot12の標準にはこのフィールドはありません。
• 2. 返却内容には、{platform_name}_raw フィールドを追加する必要があります。このフィールドには、元のレスポンスデータを格納します。

2. 基礎レスポンス構造

すべてのアクションレスポンスには、以下の基本フィールドを含める必要があります。

オプションフィールド：

3. 完全なフィールド仕様

3.1 一般的なフィールド

成功時のレスポンス例

{
    "status": "ok",
    "retcode": 0,
    "data": {
        "message_id": "1234",
        "time": 1632847927.599013
    },
    "message_id": "1234",
    "message": "",
    "echo": "1234",
    "telegram_raw": {...}
}

失敗時のレスポンス例

{
    "status": "failed",
    "retcode": 10003,
    "data": null,
    "message_id": "",
    "message": "必要なパラメータが不足しています: user_id",
    "echo": "1234",
    "telegram_raw": {...}
}

3.2 戻り値コードの仕様

0 成功（OK）

• 0: 成功（OK）

1xxxx 動作リクエストエラー（Request Error）

2xxxx 動作ハンドラーエラー（Handler Error）

3xxxx 動作実行エラー（Execution Error）

保留エラーセグメント

• 4xxxx、5xxxx: 保留セグメント、使用しないでください
• 6xxxx～9xxxx: 他のエラーセグメント、実装が独自に使用するためのものです

4. 実装要件

1. すべてのレスポンスには status、retcode、data、message フィールドが含まれている必要があります。
2. リクエストに非空の echo フィールドが含まれている場合、レスポンスには同じ値の echo フィールドが含まれている必要があります。
3. 戻り値コードは OneBot12 規格に厳密に従う必要があります。
4. エラーメッセージ(message)は人間に読みやすい説明文である必要があります。

5. 拡張仕様

ErisPulse は OneBot12 標準の返却構造に以下の拡張を加えています。

5.1 message_id 必須フィールド

OneBot12 標準では message_id は data オブジェクト内にあり、必須ではありません。ErisPulse ではこれをトップレベルの必須フィールドに昇格させています：

• message_id を取得できない場合は、空文字列 "" を設定する
• message_id が常に存在することを保証し、モジュールは null チェックを行う必要がない

5.2 {platform}_raw 原始レスポンスフィールド

返却値には、プラットフォームの原始レスポンスデータの完全なコピーを保持する {platform}_raw フィールドを含める必要があります：

{
    "status": "ok",
    "retcode": 0,
    "data": {"message_id": "1234", "time": 1632847927},
    "message_id": "1234",
    "message": "",
    "telegram_raw": {
        "ok": true,
        "result": {"message_id": 1234, "date": 1632847927, ...}
    }
}

要件：

• {platform}_raw は原始レスポンスのディープコピーである必要があり、参照ではありません
• platform はアダプター登録時のプラットフォーム名と完全に一致する必要があります（大文字小文字を区別）
• エラーメッセージも保持し、デバッグに役立つようにする

5.3 フレームワーク拡張返却コード（34xxx プラットフォームエラーセグメントの下3桁をカスタム）

OneBot12 規格では、実装が 3xxxx の下3桁をカスタムに使用することが許可されています。34xxx の意味は Platform Error（ロボットプラットフォームエラー、プラットフォーム制限による失敗など）です。34xxx 内部では役割ごとに分層して使用されます：

ErisPulse フレームワークで現在使用している 346xx コード：

役割の区別：34601 はフレームワークが呼び出し前にブロック（モジュールはそもそもアクションを発行する資格がない）です。 34004 / 34xxx プラットフォームコードはアクションは発行されたがプラットフォームが拒否（Bot に権限がない、リスク管理対象など）です。 モジュールは権限の問題を判断する際に、これら2つを同時にチェックする必要があります：まず 34601（自分のモジュールが scope によって禁止されているか）を確認し、次に 34xxx（プラットフォーム側の制限）を確認します。

返却構造は §2 の標準失敗レスポンスに従います：

{
    "status": "failed",
    "retcode": 34601,
    "data": null,
    "message_id": "",
    "message": "action 'send' denied by scope.actions"
}

5.4 アダプター実装チェックリスト

• status, retcode, data, message_id, message フィールドを含む
• 返却コードは OneBot12 規格に従う（§3.2 参照）
• message_id が常に存在する（取得できない場合は空文字列）
• {platform}_raw にプラットフォームの原始レスポンスデータを含む

6. 注意事項

• 3xxxxエラーコードについては、下位3桁は実装側で独自に定義可能です。
• 予約エラーセグメント（4xxxx、5xxxx）は使用しないでください。
• 34600 / 34601 は ErisPulse フレームワーク用に予約されたコードです（§5.3を参照）。アダプタやモジュールでは使用しないでください。
• エラーメッセージは簡潔かつ明瞭にし、デバッグしやすいようにしてください。