gRPC API 参考

RustBill 使用 gRPC 作为后端 API 协议，同时支持 gRPC-Web（浏览器端）。共 10 个 gRPC 服务，分布在 6 个 proto package 中。

通用约定

约定	说明
金额	所有金额字段使用字符串类型（如 `"50.00"`），不使用浮点数
ID	所有 ID 均为 UUID v7 字符串
时间戳	RFC3339 格式字符串（如 `"2024-01-15T10:30:00Z"`）
分页	`PageRequest { page: uint32, page_size: uint32 }`，响应含 `PageMeta`
可选字段	proto3 `optional` 关键字标记的字段，未设置时不出现在 JSON payload 中

RustBill 使用三种认证方式，分别对应不同的用户类型和中间件：

认证方式	用户类型	Token 格式	中间件
Session Cookie	Admin	httpOnly Cookie	`SessionAuthLayer`
JWT Bearer	Customer	`Authorization: Bearer <token>`	`JwtAuthLayer`
API Key Bearer	Downstream	`Authorization: Bearer <api_key>`	`ApiKeyAuthLayer`

Admin 认证流程：登录 → 服务端返回 Set-Cookie → 浏览器自动携带 cookie。Admin SPA 使用 credentials: 'include' 发送同源请求。

Customer 认证流程：登录 → 返回 access_token + refresh_token → 前端存储到 localStorage → 每次请求在 Authorization 头携带。

API Key 认证流程：在 ApiKeyService 创建 → 在 Authorization 头中作为 Bearer token 携带 → 注入 DownstreamUser。

所有 gRPC 方法遵循路径格式：

/rustbill.{package}.{Service}/{Method}

例如：

浏览器端使用 gRPC-Web 协议。请求需携带 grpc-web 头，响应可能为 trailers-only（状态码 200 + grpc-status header）。CORS 需服务端配置允许的 origin。

服务	Package	文件	职责
IdentityService	rustbill.identity	identity.md	认证、用户管理、密码管理
ProductService	rustbill.product	product.md	商品 CRUD、批量操作、上游导入
CustomerService	rustbill.customer	customer.md	客户 CRUD
OrderService	rustbill.order	order.md	订单全生命周期、支付
BillingService	rustbill.billing	billing.md	发票管理、周期账单生成
PaymentService	rustbill.payment	payment.md	支付创建、回调、退款
IntegrationService	rustbill.integration	integration.md	插件管理、供应商操作、上游实例
NotificationService	rustbill.notification	notification.md	通知渠道、手动发送
TicketService	rustbill.ticket	ticket.md	工单全生命周期管理
ApiKeyService	rustbill.downstream	apikey.md	API Key 创建与管理

定义在 rustbill.common package（common.proto）。

字段	类型	编号	描述
page	uint32	1	页码（从 1 开始）
page_size	uint32	2	每页条数

无字段的空消息。

字段	类型	编号	描述
id	string	1	UUID v7 格式 ID

所有 gRPC 错误通过标准 grpc-status header 返回：