BillingService

账单管理服务，负责发票的 CRUD 操作和周期性账单生成。支持按计费周期自动汇总订单生成客户账单。

RPC 列表

RPC	描述	权限
CreateInvoice	手动创建发票	admin
ListInvoices	发票列表（分页+筛选）	admin 全量 / customer 自身
GetInvoice	获取发票详情	admin 全量 / customer 自身
UpdateInvoice	更新发票状态/备注	admin
DeleteInvoice	删除发票	admin
GenerateInvoices	批量生成周期账单	admin

CreateInvoice

描述

手动创建一张发票（含发票行项目）。

Request — `CreateInvoiceRequest`

字段	类型	编号	必填	描述
customer_id	string	1	是	客户 ID（UUID）
billing_period_start	string	2	是	计费周期开始（日期字符串）
billing_period_end	string	3	是	计费周期结束（日期字符串）
amount	string	4	是	小计金额（字符串）
tax_amount	string	5	是	税额（字符串）
total_amount	string	6	是	总金额（含税）
due_date	string	7	是	到期日期
notes	string	8	是	备注
items	repeated InvoiceItemInput	9	是	发票行项目列表

InvoiceItemInput

字段	类型	编号	描述
description	string	1	项目描述
quantity	uint32	2	数量
unit_price	string	3	单价（字符串金额）
amount	string	4	金额（quantity × unit_price）

Response — `CreateInvoiceResponse`

字段	类型	编号	描述
invoice	InvoiceInfo	1	创建的发票信息

错误码

错误	说明
InvalidArgument	参数校验失败
NotFound	客户不存在
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"customer_id":"0192a123-...","billing_period_start":"2024-01-01","billing_period_end":"2024-01-31","amount":"100.00","tax_amount":"13.00","total_amount":"113.00","due_date":"2024-02-15","notes":"1月账单","items":[{"description":"VPS-1C2G 月费","quantity":1,"unit_price":"100.00","amount":"100.00"}]}' \
  localhost:50051 rustbill.billing.BillingService/CreateInvoice

const resp = await api.createInvoice({
  customer_id: "0192a123-...",
  billing_period_start: "2024-01-01",
  billing_period_end: "2024-01-31",
  amount: "100.00",
  tax_amount: "13.00",
  total_amount: "113.00",
  due_date: "2024-02-15",
  notes: "1月账单",
  items: [{ description: "VPS-1C2G 月费", quantity: 1, unit_price: "100.00", amount: "100.00" }]
});

ListInvoices

描述

分页查询发票列表。Admin 可查看所有发票，Customer 自动限定为自身发票。

Request — `ListInvoicesRequest`

字段	类型	编号	必填	描述
pagination	PageRequest	1	是	分页参数
customer_id	string?	2	否	按客户过滤（admin 可用）
status	string?	3	否	按状态过滤

Response — `ListInvoicesResponse`

字段	类型	编号	描述
invoices	repeated InvoiceInfo	1	发票列表
meta	PageMeta	2	分页元数据

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"pagination":{"page":1,"page_size":20},"status":"issued"}' \
  localhost:50051 rustbill.billing.BillingService/ListInvoices

GetInvoice

描述

获取单张发票详情，含发票行项目。

Request — `GetInvoiceRequest`

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

Response — `GetInvoiceResponse`

字段	类型	编号	描述
invoice	InvoiceInfo	1	发票信息

错误码

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

示例

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

UpdateInvoice

描述

更新发票状态或备注。

Request — `UpdateInvoiceRequest`

字段	类型	编号	必填	描述
id	string	1	是	发票 ID
status	string?	2	否	新状态
notes	string?	3	否	备注

Response — `UpdateInvoiceResponse`

字段	类型	编号	描述
invoice	InvoiceInfo	1	更新后的发票信息

错误码

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

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192a123-...","status":"paid"}' \
  localhost:50051 rustbill.billing.BillingService/UpdateInvoice

DeleteInvoice

描述

删除指定发票。

Request — `DeleteInvoiceRequest`

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

Response — `DeleteInvoiceResponse`

无字段。

错误码

错误	说明
NotFound	发票不存在
PermissionDenied	非 admin 用户

示例

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

GenerateInvoices

描述

按指定计费周期批量生成客户发票。系统遍历周期内所有已完成或活跃的订单，按客户汇总生成发票。

Request — `GenerateInvoicesRequest`

字段	类型	编号	必填	描述
billing_period_start	string	1	是	计费周期开始（日期字符串）
billing_period_end	string	2	是	计费周期结束（日期字符串）

Response — `GenerateInvoicesResponse`

字段	类型	编号	描述
generated_count	uint32	1	生成的发票数量

错误码

错误	说明
InvalidArgument	日期格式无效或周期非法
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"billing_period_start":"2024-01-01","billing_period_end":"2024-01-31"}' \
  localhost:50051 rustbill.billing.BillingService/GenerateInvoices

公共类型

InvoiceInfo

字段	类型	编号	描述
id	string	1	发票 UUID
invoice_number	string	2	发票编号
customer_id	string	3	客户 ID
billing_period_start	string	4	计费周期开始
billing_period_end	string	5	计费周期结束
amount	string	6	小计金额（字符串）
tax_amount	string	7	税额（字符串）
total_amount	string	8	总金额（含税，字符串）
status	string	9	发票状态
issued_at	string	10	签发时间（RFC3339）
paid_at	string	11	支付时间（RFC3339）
due_date	string	12	到期日期
notes	string	13	备注
created_at	string	14	创建时间（RFC3339）
updated_at	string	15	更新时间（RFC3339）
items	repeated InvoiceItemInfo	16	发票行项目

InvoiceItemInfo

字段	类型	编号	描述
id	string	1	行项目 UUID
description	string	2	项目描述
quantity	uint32	3	数量
unit_price	string	4	单价（字符串金额）
amount	string	5	金额（quantity × unit_price）

发票状态流转

draft → issued → paid / overdue → cancelled

状态	说明
draft	草稿
issued	已签发（待支付）
paid	已支付
overdue	已逾期
cancelled	已取消

Keyboard shortcuts

RustBill 文档