syntax = "proto3";

package yuan_core;

// YuanRequest 是从 Avatar Host 或其他 Yuan 模块发送到 Yuan 核心的通用请求信封。
// 所有的操作请求都将通过这个信封传递。
message YuanRequest {
  string id = 1; 

  // 官方方法类型，用一个枚举值表示
  // 即使不使用，也建议预留一个 UNKNOWN/UNSPECIFIED 的默认值
  MethodType method_type = 2; 

  // 非官方方法类型，用于动态扩展。当 method_type 是 UNKNOWN 时，检查此字段
  // 或者作为额外的、更具体的字符串标识
  string custom_method = 3; 

  bytes payload = 4; 
}

// YuanResponse 是从 Yuan 核心发送回 Avatar Host 或请求发起方的通用响应信封。
message YuanResponse {
  string id = 1; // 响应对应的请求ID
  
  // 响应的状态码，建议使用枚举或预定义常量来表示成功、失败等
  int32 status_code = 2; 

  // 响应的载荷，使用 bytes 存储序列化后的具体响应消息或错误信息
  bytes payload = 3; 
}

// AvatarEvent 是 Yuan 核心或其内部服务模块向 Avatar Host 广播的通用事件信封。
// Avatar Host 将监听这些事件并做出相应处理。
message AvatarEvent {
  string id = 1; 

  // 官方事件类型
  EventType event_type = 2; 

  // 非官方事件类型
  string custom_event = 3; 

  bytes payload = 4;
}

// 示例：通用的错误消息结构 (可在 payload 中使用)
message ErrorMessage {
  string code = 1;    // 错误代码，如 "INVALID_ARGUMENT", "PERMISSION_DENIED"
  string message = 2; // 用户友好的错误描述
}

// --- 新增枚举定义 ---

// 定义所有 Yuan 核心能够处理的请求方法类型
enum MethodType {
  // 最佳实践：枚举的第一个值应该是 0，并且通常是 UNKNOWN 或 UNSET
  // 这有助于处理未知或默认值
  METHOD_TYPE_UNSPECIFIED = 0; 
  
  // 身份服务 (Identity Service)
  IDENTITY_CREATE_DID = 1;
  IDENTITY_RESOLVE_DID = 2;
  IDENTITY_SIGN_MESSAGE = 3;

  // 文件系统服务 (Filesystem Service)
  FILESYSTEM_READ_FILE = 100; // 通常会为每个服务模块的枚举预留一个范围，方便管理
  FILESYSTEM_WRITE_FILE = 101;
  FILESYSTEM_LIST_DIRECTORY = 102;

  // P2P 服务 (P2P Service)
  P2P_SEND_MESSAGE = 200;
  P2P_CONNECT_NODE = 201;

  // 通信服务 (Communication Service)
  COMMUNICATION_JOIN_ROOM = 300;
  COMMUNICATION_SEND_TEXT = 301;
  
  // ... 更多服务方法 ...
}

// 定义所有 Yuan 核心可能广播的事件类型
enum EventType {
  // 最佳实践：枚举的第一个值应该UNSPECIFIED
  EVENT_TYPE_UNSPECIFIED = 0;

  // 身份事件
  IDENTITY_DID_CREATED = 1;
  IDENTITY_CREDENTIAL_ISSUED = 2;

  // 文件系统事件
  FILESYSTEM_FILE_CHANGED = 100;
  FILESYSTEM_DIRECTORY_SYNCED = 101;

  // P2P 事件
  P2P_MESSAGE_RECEIVED = 200;
  P2P_NODE_CONNECTED = 201;

  // 通信事件
  COMMUNICATION_ROOM_MESSAGE = 300;
  COMMUNICATION_USER_JOINED = 301;

  // ... 更多事件类型 ...
}