app-cloudep-trade-service/generate/protobuf/trade.proto

syntax = "proto3";
package trade;
option go_package = "./trade";

// ========== 基本回應 ===========
message OKResp {}

// 空的請求
message NoneReq {}

// 分頁信息
message Pager {
  int64 total = 1;  // 總數量
  int64 size = 2;   // 每頁數量
  int64 index = 3;  // 當前頁碼
}

// ========== 訂單服務 ===========
message CreateOrderReq {
  string business_id = 1;   // 訂單業務流水號
  int32 order_type = 2;     // 訂單類型
  int32 order_status = 3;   // 訂單狀態
  string brand = 4;         // 下單平台
  string order_uid = 5;     // 下單用戶 UID
  string reference_id = 6;  // 訂單來源
  string count = 7;         // 訂單數量 (decimal to string)
  string order_fee = 8;     // 訂單手續費 (decimal to string)
  string amount = 9;        // 單價 (decimal to string)

  // 以下是可選字段（擴充用）
  optional string reference_brand = 10;           // 訂單來源平台
  optional string reference_uid = 11;             // 訂單來源用戶 UID
  optional int64 wallet_status = 12;              // 交易金額狀態
  optional int64 three_party_status = 13;         // 三方請求狀態
  optional int64 direction_type = 14;             // 交易方向
  optional string crypto_type = 15;               // 交易幣種
  optional string third_party_fee = 16;           // 第三方手續費 (decimal to string)
  optional string crypto_to_usdt_rate = 17;       // 交易幣種對 USDT 匯率 (decimal to string)
  optional string fiat_to_usd_rate = 18;          // 法幣對 USD 匯率 (decimal to string)
  optional string fee_crypto_to_usdt_rate = 19;   // 手續費幣種對 USDT 匯率 (decimal to string)
  optional string usdt_to_crypto_type_rate = 20;  // USDT 對交易幣種匯率 (decimal to string)
  optional string payment_fiat = 21;              // 支付法幣
  optional string payment_unit_price = 22;        // crypto 單價 (decimal to string)
  optional string payment_template_id = 23;       // 支付方式配置 ID
  optional int64 order_arrival_time = 24;         // 訂單到帳時間
  optional int64 order_payment_time = 25;         // 訂單付款時間
  optional int64 unpaid_timeout_second = 26;      // 支付期限秒數
  optional string chain_type = 27;                // 主網類型
  optional string tx_hash = 28;                   // 交易哈希
  optional string from_address = 29;              // 來源地址
  optional string to_address = 30;                // 目標地址
  optional string chain_fee = 31;                 // 鏈上交易手續費 (decimal to string)
  optional string chain_fee_crypto = 32;          // 鏈上手續費使用幣別
  optional string memo = 33;                      // 鏈上備註
  optional string order_note = 34;                // 訂單交易備註
}

message CancelOrderReq {
  string business_id = 1;
  int64 status = 2;
}

message ModifyOrderStatusReq {
  string business_id = 1;
  int64 status = 2;
}

message DeleteOrderReq {
  string business_id = 1;
}

message OrderStatusTimeoutReq {}

message GetOrderReq {
  string business_id = 1;  // 訂單業務流水號
}

message GetOrderResp {
  string business_id = 1;   // 訂單業務流水號
  int32 order_type = 2;     // 訂單類型
  int32 order_status = 3;   // 訂單狀態
  string brand = 4;         // 下單平台
  string order_uid = 5;     // 下單用戶 UID
  string reference_id = 6;  // 訂單來源
  string count = 7;         // 訂單數量 (decimal to string)
  string order_fee = 8;     // 訂單手續費 (decimal to string)
  string amount = 9;        // 單價 (decimal to string)

  // 以下是可選字段（擴充用）
  optional string reference_brand = 10;           // 訂單來源平台
  optional string reference_uid = 11;             // 訂單來源用戶 UID
  optional int64 wallet_status = 12;              // 交易金額狀態
  optional int64 three_party_status = 13;         // 三方請求狀態
  optional int64 direction_type = 14;             // 交易方向
  optional string crypto_type = 15;               // 交易幣種
  optional string third_party_fee = 16;           // 第三方手續費 (decimal to string)
  optional string crypto_to_usdt_rate = 17;       // 交易幣種對 USDT 匯率 (decimal to string)
  optional string fiat_to_usd_rate = 18;          // 法幣對 USD 匯率 (decimal to string)
  optional string fee_crypto_to_usdt_rate = 19;   // 手續費幣種對 USDT 匯率 (decimal to string)
  optional string usdt_to_crypto_type_rate = 20;  // USDT 對交易幣種匯率 (decimal to string)
  optional string payment_fiat = 21;              // 支付法幣
  optional string payment_unit_price = 22;        // crypto 單價 (decimal to string)
  optional string payment_template_id = 23;       // 支付方式配置 ID
  optional int64 order_arrival_time = 24;         // 訂單到帳時間
  optional int64 order_payment_time = 25;         // 訂單付款時間
  optional int64 unpaid_timeout_second = 26;      // 支付期限秒數
  optional string chain_type = 27;                // 主網類型
  optional string tx_hash = 28;                   // 交易哈希
  optional string from_address = 29;              // 來源地址
  optional string to_address = 30;                // 目標地址
  optional string chain_fee = 31;                 // 鏈上交易手續費 (decimal to string)
  optional string chain_fee_crypto = 32;          // 鏈上手續費使用幣別
  optional string memo = 33;                      // 鏈上備註
  optional string order_note = 34;                // 訂單交易備註
  int64 create_time = 35;                         // 建立時間
  int64 update_time = 36;                         // 更新時間
}

message ListOrderReq {
  int64 page_index = 1;  // required
  int64 page_size = 2;   // required

  string reference_id = 3;
  string reference_uid = 4;
  string business_id = 5;
  string uid = 6;
  int32 order_type = 7;
  repeated int32 direction_type = 8;
  repeated int32 order_status = 9;

  int64 start_create_time = 10;
  int64 end_create_time = 11;
  int64 start_update_time = 12;
  int64 end_update_time = 13;
  int64 start_order_arrival_time = 14;
  int64 end_order_arrival_time = 15;
  int64 start_order_payment_time = 16;
  int64 end_order_payment_time = 17;

  string crypto_type = 18;
  string tx_hash = 19;
}

message ListOrderResp {
  repeated GetOrderResp data = 1;  // 訂單列表
  Pager page = 2;
}

// OrderService 訂單服務（業務邏輯在外面組合）
service OrderService {
  // CreateOrder 建立訂單
  rpc CreateOrder(CreateOrderReq) returns (OKResp);
  // CancelOrder 取消訂單
  rpc CancelOrder(CancelOrderReq) returns (OKResp);
  // ModifyOrderStatus 修改訂單狀態
  rpc ModifyOrderStatus(ModifyOrderStatusReq) returns (OKResp);
  // DeleteOrder 刪除訂單（軟刪除）
  rpc DeleteOrder(DeleteOrderReq) returns (OKResp);
  // GetOrder 取得訂單詳情
  rpc GetOrder(GetOrderReq) returns (GetOrderResp);
  // ListOrder 取得訂單列表
  rpc ListOrder(ListOrderReq) returns (ListOrderResp);
  // OrderStatusTimeout 訂單超時任務/cron/order-status/timeout
  rpc OrderStatusTimeout(OrderStatusTimeoutReq) returns (OKResp);
}

// ========== 錢包服務 ===========
message CreateWalletReq {
  repeated WalletItem item = 1;
}

message WalletItem {
  string source = 1;           // 錢包來源
  string uid = 2;              // 錢包擁有者的 UID
  string currency_type = 3;    // 幣別
  string current_balance = 4;  // 當前餘額
  int64 wallet_type = 5;       // 錢包金額種類 1. 可用餘額 2. 凍結餘額 3. 限制餘額
}

message WalletTransactionReq {
  string uid = 1;                     // 錢包擁有者的 UID
  optional string order_id = 2;       // 訂單編號
  optional string business_type = 3;  // 業務種類
  optional string currency_type = 4;  // 幣別
  optional string amount = 5;         // 轉帳金額
  optional int64 wallet_type = 6;     // 操作金額種類
}

message QueryBalanceByDateReq {
  string uid = 1;            // 錢包擁有者的 UID
  string currency_type = 2;  // 幣別
}

message QueryBalanceByDateResp {
  string currency_type = 1;            // 幣別
  string available = 2;                // 可用餘額
  UnavailableBalance unavailable = 3;  // 不可用餘額
  int64 update_time = 4;
}

message UnavailableBalance {
  string freeze = 1;       // 凍結餘額
  string unconfirmed = 2;  // 限制餘額
}

// TODO 未來會新增查詢以及同步的功能

service WalletService {
  // CreateWallet 建立錢包
  rpc CreateWallet(CreateWalletReq) returns (OKResp);
  // DepositFunds 充值 - 增加 [可用餘額] 或 [限制餘額]
  rpc DepositFunds(WalletTransactionReq) returns (OKResp);
  // WithdrawFunds 提現 - 減少 [可用餘額]
  rpc WithdrawFunds(WalletTransactionReq) returns (OKResp);
  // FreezeFunds 凍結 - 將 [可用餘額] 減少，加到 [凍結餘額]
  rpc FreezeFunds(WalletTransactionReq) returns (OKResp);
  // UnfreezeFunds 解凍 - 減少 [凍結餘額]
  rpc UnfreezeFunds(WalletTransactionReq) returns (OKResp);
  // AppendToFreeze 追加凍結 - 減少可用餘額，追加到現有的 [凍結餘額] (基於原order_id)
  rpc AppendToFreeze(WalletTransactionReq) returns (OKResp);
  // RollbackFreeze 凍結回滾 - 減少 [凍結餘額]，加回 [可用餘額]，不可指定金額，整筆訂單的凍結金額加回 [可用餘額]
  rpc RollbackFreeze(WalletTransactionReq) returns (OKResp);
  // CancelFreeze 取消凍結 - 減少 [凍結餘額]，加回 [可用餘額]，可指定金額
  rpc CancelFreeze(WalletTransactionReq) returns (OKResp);
  // TransferToRestrictedFunds 限制 - 減少 [凍結餘額]，轉移到另一個使用者的 [限制餘額]
  rpc TransferToRestrictedFunds(WalletTransactionReq) returns (OKResp);
  // SettleRestrictedFunds 結算限制餘額 - 限制餘額在 T+N 天後自動失效，每日只能執行一次
  rpc SettleRestrictedFunds(NoneReq) returns (OKResp);
  // QueryBalance 餘額查詢 -> 依照日期查詢
  rpc QueryBalance(QueryBalanceByDateReq) returns (QueryBalanceByDateResp);
}

// ========== 庫存服務 ===========

message StockAdjustmentReq {
  string product_id = 1;  // 商品ID
  int64 quantity = 2;     // 調整的數量 (正數表示增加，負數表示減少)
}

message StockQueryReq {
  string product_id = 1;  // 商品ID
}

message StockResp {
  string product_id = 1;         // 商品ID
  int64 available_quantity = 2;  // 可用庫存
  int64 reserved_quantity = 3;   // 預留庫存
}

message StockListReq {
  int64 page_index = 1;            // required
  int64 page_size = 2;             // required
  repeated string product_id = 3;  // 一次查多筆
}

message StockListResp {
  repeated StockResp stock_items = 1;  // 所有商品的庫存清單
  Pager page = 2;
}

message StockReservationReq {
  string product_id = 1;  // 商品ID
  int64 quantity = 2;     // 預留的數量
}

message BatchStockAdjustmentReq {
  repeated StockAdjustmentReq adjustments = 1;  // 批次調整庫存
}

service InventoryService {
  // CreateStock 建立庫存品項
  rpc CreateStock(StockAdjustmentReq) returns (OKResp);
  // AddStock 增加庫存
  rpc AddStock(StockAdjustmentReq) returns (OKResp);
  // ReduceStock 減少庫存
  rpc ReduceStock(StockAdjustmentReq) returns (OKResp);
  // QueryStock 查詢單一商品的庫存
  rpc QueryStock(StockQueryReq) returns (StockResp);
  // ListAllStock 查詢所有商品的庫存狀況
  rpc ListAllStock(StockListReq) returns (StockListResp);
  // ReserveStock 預留庫存 (用於未完成的訂單)
  rpc ReserveStock(StockReservationReq) returns (OKResp);
  // ReleaseReservedStock 釋放預留庫存 (取消或失效的訂單)
  rpc ReleaseReservedStock(StockReservationReq) returns (OKResp);
  // AdjustStock 調整庫存 (批量修改庫存，用於大批商品更新)
  rpc AdjustStock(BatchStockAdjustmentReq) returns (OKResp);
}

// ========== 商品服務 ===========

// 商品請求和回應訊息
message ProductCreateReq {
  string name = 1;                 // 商品名稱
  string description = 2;          // 商品簡述
  string content = 3;              // 詳細商品內容
  double price = 4;                // 商品價格
  int64 amount_type = 5;           // 1 有限數量 2 無限數量
  string currency = 6;             // 貨幣類型 (如 USD, TWD)
  repeated string brand = 7;       // 產品品牌，可以看成channel_id or uid 就是誰得商品，用品牌比較通用
  repeated string category = 8;    // 商品分類
  repeated string tags = 9;        // 產品標籤（方便篩選）
  string sku = 10;                 // 庫存單位（Stock Keeping Unit）
  repeated string images = 11;     // 商品照片網址
  repeated string coupon_id = 12;  // 本商品專屬折扣碼 id
}

message ProductUpdateReq {
  string product_id = 1;            // 商品ID
  optional string name = 2;         // 商品名稱
  optional string description = 3;  // 商品簡述
  optional string content = 4;      // 詳細商品內容
  optional double price = 5;        // 商品價格
  optional int64 amount_type = 6;   // 1 有限數量 2 無限數量
  optional string currency = 7;     // 貨幣類型 (如 USD, TWD)
  repeated string brand = 8;        // 產品品牌，可以看成channel_id or uid 就是誰得商品，用品牌比較通用
  repeated string category = 9;     // 商品分類
  repeated string tags = 10;        // 產品標籤（方便篩選）
  optional string sku = 11;         // 庫存單位（Stock Keeping Unit）
  repeated string images = 12;      // 商品照片網址
  repeated string coupon_id = 13;   // 本商品專屬折扣碼 id
  optional bool is_available = 14;  // 是否上架
}

message ProductDeleteReq {
  string product_id = 1;  // 商品ID
}

message ProductQueryReq {
  string product_id = 1;  // 商品ID
}

message ProductResp {
  string product_id = 1;           // 商品ID
  string name = 2;                 // 商品名稱
  string description = 3;          // 商品簡述
  string content = 4;              // 詳細商品內容
  double price = 5;                // 商品價格
  int64 amount_type = 6;           // 1 有限數量 2 無限數量
  string currency = 7;             // 貨幣類型 (如 USD, TWD)
  repeated string brand = 8;       // 產品品牌，可以看成channel_id or uid 就是誰得商品，用品牌比較通用
  repeated string category = 9;    // 商品分類
  repeated string tags = 10;       // 產品標籤（方便篩選）
  string sku = 11;                 // 庫存單位（Stock Keeping Unit）
  repeated string images = 12;     // 商品照片網址
  repeated string coupon_id = 13;  // 本商品專屬折扣碼 id
  bool is_available = 14;          // 是否上架
}

message ProductListReq {
  int64 page_index = 1;
  int64 page_size = 2;

  repeated string product_id = 3;  // 商品ID
  optional bool is_available = 4;  // 是否上架
  repeated string tags = 5;        // 產品標籤（方便篩選）
  optional int64 amount_type = 6;  // 1 有限數量 2 無限數量
  repeated string currency = 7;    // 貨幣類型 (如 USD, TWD)
  repeated string brand = 8;       // 產品品牌，可以看成channel_id or uid 就是誰得商品，用品牌比較通用
  repeated string category = 9;    // 商品分類
}

message ProductListResp {
  repeated ProductResp products = 1;  // 所有商品清單
  Pager page = 2;
}

service ProductService {
  // CreateProduct 新增商品
  rpc CreateProduct(ProductCreateReq) returns (ProductResp);
  // UpdateProduct 更新商品資訊
  rpc UpdateProduct(ProductUpdateReq) returns (ProductResp);
  // DeleteProduct 刪除商品
  rpc DeleteProduct(ProductDeleteReq) returns (OKResp);
  // QueryProduct 查詢單一商品資訊
  rpc QueryProduct(ProductQueryReq) returns (ProductResp);
  // ListAllProducts 查詢所有商品資訊
  rpc ListAllProducts(ProductListReq) returns (ProductListResp);
}

// ========== 訂閱服務 ===========

// 訂閱請求和回應訊息 (訂閱的話，在結束時間結束前，不能再次訂閱，但取消之後可以再次訂閱)
message SubscriptionCreateReq {
  string uid = 1;                     // 使用者ID
  string plan_id = 2;                 // 訂閱方案ID
  bool auto_renew = 3;                // 是否自動續訂
  optional int64 auto_renew_day = 4;  // 自動續訂多久
  int64 start_date = 5;               // 訂閱開始日期
  int64 end_date = 6;                 // 訂閱結束時間
}

message SubscriptionUpdateReq {
  string subscription_id = 1;         // 訂閱ID
  optional int64 end_date = 2;        // 訂閱結束時間（延長要訂閱的時間）
  optional bool cancel = 3;           // 是否取消訂閱
  optional bool auto_renew = 4;       // 是否自動續訂
  optional int64 auto_renew_day = 5;  // 自動續訂多久
}

message SubscriptionCancelReq {
  string subscription_id = 1;  // 訂閱ID
}

message SubscriptionQueryReq {
  string subscription_id = 1;  // 訂閱ID
}

message SubscriptionResp {
  string subscription_id = 1;  // 訂閱ID
  string uid = 2;              // 使用者ID
  string plan_id = 3;          // 訂閱方案ID
  int64 start_date = 4;        // 訂閱開始日期
  int64 end_date = 5;          // 訂閱結束日期
  int64 status = 6;            // 訂閱狀態 (例如: 1"active", 2"expired", 3"canceled")
  bool auto_renew = 7;         // 是否自動續訂
  int64 auto_renew_day = 8;    // 自動續訂多久
}

message ListSubscriptionsReq {
  int64 page_index = 1;
  int64 page_size = 2;
  optional string uid = 3;
  repeated string subscription_id = 4;
  repeated string plan_id = 5;
  int64 status = 6;  // 訂閱狀態 (例如: 1"active", 2"expired", 3"canceled")
}

message SubscriptionListResp {
  repeated SubscriptionResp subscriptions = 1;  // 訂閱清單
  Pager page = 2;
}

message SubscriptionRenewReq {
  string subscription_id = 1;  // 訂閱ID
  int64 renewal_date = 2;      // 續訂日期
}

message SubscriptionStatusQueryReq {
  string subscription_id = 1;  // 訂閱ID
}

message SubscriptionStatusResp {
  string subscription_id = 1;  // 訂閱ID
  int64 status = 2;            // 訂閱狀態 (例如: 1"active", 2"expired", 3"canceled")
}

service SubscriptionService {
  // CreateSubscription 建立訂閱
  rpc CreateSubscription(SubscriptionCreateReq) returns (SubscriptionResp);
  // UpdateSubscription 更新訂閱設定
  rpc UpdateSubscription(SubscriptionUpdateReq) returns (SubscriptionResp);
  // CancelSubscription 取消訂閱
  rpc CancelSubscription(SubscriptionCancelReq) returns (OKResp);
  // QuerySubscription 查詢單一訂閱資訊
  rpc QuerySubscription(SubscriptionQueryReq) returns (SubscriptionResp);
  // ListSubscriptions 查詢所有訂閱 (用於管理和監控)
  rpc ListSubscriptions(ListSubscriptionsReq) returns (SubscriptionListResp);
  // RenewSubscription 續訂訂閱
  rpc RenewSubscription(SubscriptionRenewReq) returns (SubscriptionResp);
  // CheckSubscriptionStatus 查詢訂閱狀態 (啟用/過期/取消)
  rpc CheckSubscriptionStatus(SubscriptionStatusQueryReq) returns (SubscriptionStatusResp);
  // RefreshSubscriptionStatus cron 改變訂閱的狀態（時間到了要過期，需要續約自動續約），每 5 分鐘執行一次
  rpc RefreshSubscriptionStatus(NoneReq) returns (OKResp);
}

// ========== 優惠券服務 ===========

message Coupon {
  string coupon_id = 1;                         // 優惠券唯一識別碼
  string code = 2;                              // 優惠碼
  double discount = 3;                          // 折扣 (可以是百分比或固定金額)
  string discount_type = 4;                     // 折扣類型 ("percent" 或 "fixed")
  string start_date = 5;                        // 優惠券生效日期 (格式: YYYY-MM-DD)
  string end_date = 6;                          // 優惠券結束日期 (格式: YYYY-MM-DD)
  int32 usage_limit = 7;                        // 使用次數限制
  int32 used_count = 8;                         // 已使用次數
  string status = 9;                            // 優惠券狀態 ("active", "expired", "inactive")
  repeated string applicable_product_ids = 10;  // 可以使用此優惠券的產品ID列表
  bool is_common = 11;                          // 是否通用
}

message CreateCouponReq {
  string code = 1;                             // 優惠碼
  double discount = 2;                         // 折扣金額或百分比
  string discount_type = 3;                    // 折扣類型 ("percent" 或 "fixed")
  int64 start_date = 4;                        // 生效日期 (格式: YYYY-MM-DD)
  int64 end_date = 5;                          // 結束日期 (格式: YYYY-MM-DD)
  int64 usage_limit = 6;                       // 使用次數限制
  bool is_common = 7;                          // 是否通用
  repeated string applicable_product_ids = 8;  // 適用的產品ID列表
}

message UpdateCouponReq {
  string coupon_id = 1;                        // 優惠券ID
  string code = 2;                             // 優惠碼
  double discount = 3;                         // 折扣金額或百分比
  string discount_type = 4;                    // 折扣類型 ("percent" 或 "fixed")
  int64 start_date = 5;                        // 生效日期
  int64 end_date = 6;                          // 結束日期
  int64 usage_limit = 7;                       // 使用次數限制
  repeated string applicable_product_ids = 8;  // 適用的產品ID列表
  optional bool is_common = 9;                 // 是否通用
}

message CouponQueryReq {
  string coupon_id = 1;  // 優惠券ID
}

message CouponResp {
  Coupon coupon = 1;  // 優惠券詳情
}

message CouponListReq {
  int64 page_index = 1;
  int64 page_size = 2;
  repeated string coupon_id = 3;
  repeated string code = 4;
  int64 start_date = 5;                        // 生效日期
  int64 end_date = 6;                          // 結束日期
  repeated string applicable_product_ids = 7;  // 適用的產品ID列表
  bool is_use_able = 8;                        // 是否是還可用的
}

message CouponListResp {
  repeated Coupon coupons = 1;  // 優惠券列表
  Pager page = 2;
}

message ValidateCouponReq {
  string product_id = 1;     // 使用優惠券的產品ID
  double order_amount = 2;   // 訂單金額
  optional string code = 3;  // 優惠碼
  optional string coupon_id = 4;
}

message CouponValidationResp {
  bool is_valid = 1;            // 是否有效
  string message = 2;           // 驗證結果訊息 (如無效的原因或有效的提示)
  double discount_applied = 3;  // 允許的折扣金額
  string coupon_id = 4;         // 驗證成功的優惠券ID
}

service CouponService {
  // CreateCoupon 創建優惠券
  rpc CreateCoupon(CreateCouponReq) returns (CouponResp);
  // UpdateCoupon更新優惠券
  rpc UpdateCoupon(UpdateCouponReq) returns (CouponResp);
  // QueryCoupon查詢優惠券
  rpc QueryCoupon(CouponQueryReq) returns (CouponResp);
  // DeleteCoupon 刪除優惠券
  rpc DeleteCoupon(CouponQueryReq) returns (OKResp);
  // ListCoupons列出所有優惠券
  rpc ListCoupons(CouponListReq) returns (CouponListResp);
  // ValidateCoupon 驗證優惠券 (在下單或支付時使用)
  rpc ValidateCoupon(ValidateCouponReq) returns (CouponValidationResp);
}