OrderService

订单全生命周期管理服务，涵盖下单、支付、查询和状态管理。订单状态从 pending 开始流转，支付成功后异步触发资源开通。

RPC 列表

RPC	描述	权限
CreateOrder	创建订单（可选同步返回支付信息）	已认证（customer）
ListOrders	订单列表（分页+筛选）	admin 全量 / customer 自身
GetOrder	获取订单详情	admin 全量 / customer 自身
UpdateOrder	更新订单状态/备注	admin
DeleteOrder	删除订单	admin
PayOrder	发起支付	已认证（customer）

CreateOrder

描述

创建新订单，可选择是否在创建时同时发起支付。

Request — `CreateOrderRequest`

字段	类型	编号	必填	描述
customer_id	string	1	是	客户 ID（UUID）
product_id	string	2	是	商品 ID（UUID）
provider_interface_id	string	3	是	Provider 接口 ID（UUID）
server_spec	ServerSpec	4	是	服务器规格配置
currency	string	5	是	货币代码（如 `"CNY"`）
gateway_interface_id	string	6	是	支付网关接口 ID（UUID）
notes	string	7	是	备注
billing_cycle	string	8	是	计费周期：`"monthly"` / `"quarterly"` / `"yearly"`

Response — `CreateOrderResponse`

字段	类型	编号	描述
order	OrderInfo	1	创建的订单信息
payment	PaymentInfo?	2	支付信息（如果创建时请求支付）

错误码

错误	说明
InvalidArgument	参数校验失败（商品不存在、接口无效等）
NotFound	商品、接口或客户不存在
Unauthenticated	未登录

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"customer_id":"0192a123-...","product_id":"0192b456-...","provider_interface_id":"0192c789-...","server_spec":{"cpu_cores":2,"memory_gb":4,"disk_gb":50,"bandwidth_mbps":100,"region":"us-west","os":"ubuntu-22.04"},"currency":"CNY","gateway_interface_id":"0192d012-...","notes":"","billing_cycle":"monthly"}' \
  localhost:50051 rustbill.order.OrderService/CreateOrder

const resp = await api.createOrder({
  customer_id: "0192a123-...",
  product_id: "0192b456-...",
  provider_interface_id: "0192c789-...",
  server_spec: {
    cpu_cores: 2,
    memory_gb: 4,
    disk_gb: 50,
    bandwidth_mbps: 100,
    region: "us-west",
    os: "ubuntu-22.04"
  },
  currency: "CNY",
  gateway_interface_id: "0192d012-...",
  notes: "",
  billing_cycle: "monthly"
});

ListOrders

描述

分页查询订单列表。Admin 用户可查看所有订单，Customer 用户自动限定为自身订单。

Request — `ListOrdersRequest`

字段	类型	编号	必填	描述
pagination	PageRequest	1	是	分页参数
customer_id	string?	2	否	按客户过滤（admin 可用）
status	string?	3	否	按状态过滤
provider_interface_id	string?	4	否	按 Provider 接口过滤
search	string?	5	否	关键词搜索

Response — `ListOrdersResponse`

字段	类型	编号	描述
orders	repeated OrderInfo	1	订单列表
meta	PageMeta	2	分页元数据

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"pagination":{"page":1,"page_size":20},"status":"active"}' \
  localhost:50051 rustbill.order.OrderService/ListOrders

GetOrder

描述

获取单个订单详情。

Request — `GetOrderRequest`

字段	类型	编号	必填	描述
id	string	1	是	订单 ID（UUID）

Response — `GetOrderResponse`

字段	类型	编号	描述
order	OrderInfo	1	订单信息

错误码

错误	说明
NotFound	订单不存在
PermissionDenied	customer 用户无权查看他人订单

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192a123-4567-7890-abcd-ef0123456789"}' \
  localhost:50051 rustbill.order.OrderService/GetOrder

UpdateOrder

描述

更新订单状态、Provider 实例 ID 或备注。

Request — `UpdateOrderRequest`

字段	类型	编号	必填	描述
id	string	1	是	订单 ID
status	string?	2	否	新状态
provider_instance_id	string?	3	否	上游实例 ID
notes	string?	4	否	备注

Response — `UpdateOrderResponse`

字段	类型	编号	描述
order	OrderInfo	1	更新后的订单信息

错误码

错误	说明
NotFound	订单不存在
InvalidArgument	状态流转不合法
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192a123-...","status":"active","notes":"已开通"}' \
  localhost:50051 rustbill.order.OrderService/UpdateOrder

DeleteOrder

描述

删除指定订单。

Request — `DeleteOrderRequest`

字段	类型	编号	必填	描述
id	string	1	是	订单 ID（UUID）

Response — `DeleteOrderResponse`

无字段。

错误码

错误	说明
NotFound	订单不存在
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192a123-4567-7890-abcd-ef0123456789"}' \
  localhost:50051 rustbill.order.OrderService/DeleteOrder

PayOrder

描述

对指定订单发起支付。调用 PaymentGateway 插件生成支付链接或二维码。支付成功后 event_worker 异步触发资源开通。

Request — `PayOrderRequest`

字段	类型	编号	必填	描述
order_id	string	1	是	订单 ID（UUID）
gateway_interface_id	string	2	是	支付网关接口 ID（UUID）

Response — `PayOrderResponse`

字段	类型	编号	描述
payment	PaymentInfo	1	支付信息

PaymentInfo

字段	类型	编号	描述
payment_id	string	1	支付记录 ID
gateway_interface_id	string	2	网关接口 ID
payment_url	string	3	支付页面 URL
qr_code	string	4	二维码内容（Base64 或 URL）
instructions	string	5	支付说明

错误码

错误	说明
NotFound	订单不存在
InvalidArgument	订单状态不允许支付（如已支付或已取消）
Internal	网关插件执行失败
Unauthenticated	未登录

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"order_id":"0192a123-...","gateway_interface_id":"0192d012-..."}' \
  localhost:50051 rustbill.order.OrderService/PayOrder

const resp = await api.payOrder({
  order_id: "0192a123-...",
  gateway_interface_id: "0192d012-..."
});
// resp.payment.payment_url → 跳转到支付页面

公共类型

OrderInfo

字段	类型	编号	描述
id	string	1	订单 UUID
customer_id	string	2	客户 ID
product_id	string	3	商品 ID
provider_interface_id	string	4	Provider 接口 ID
provider_instance_id	string	5	上游实例 ID（开通后填充）
server_spec	ServerSpec	6	服务器规格
status	string	7	订单状态
amount	string	8	订单金额（字符串）
currency	string	9	货币代码
gateway_interface_id	string	10	支付网关接口 ID
gateway_payment_id	string	11	网关支付 ID（支付后填充）
notes	string	12	备注
created_at	string	13	创建时间（RFC3339）
updated_at	string	14	更新时间（RFC3339）
product_name	string	15	商品名称（冗余）
billing_cycle	string	16	计费周期：`"monthly"` / `"quarterly"` / `"yearly"`

ServerSpec

字段	类型	编号	描述
cpu_cores	uint32	1	CPU 核心数
memory_gb	uint32	2	内存（GB）
disk_gb	uint32	3	磁盘（GB）
bandwidth_mbps	uint32	4	带宽（Mbps）
region	string	5	地域
os	string	6	操作系统
extra_specs	map<string,string>	7	扩展规格键值对

订单状态流转

pending → paid → provisioning → active / suspended / cancelled / refunded / completed
                                      ↓
                                  terminated

状态	说明
pending	待支付
paid	已支付（等待开通）
provisioning	开通中
active	运行中
suspended	已暂停
cancelled	已取消
refunded	已退款
completed	已完成

Keyboard shortcuts

RustBill 文档