CustomerService

客户管理服务，负责客户的 CRUD 操作。Customer 用户登录后自动限定数据范围为自身的 customer_id。

RPC 列表

RPC	描述	权限
CreateCustomer	创建客户	admin
ListCustomers	客户列表（分页+筛选）	admin
GetCustomer	获取客户详情	admin
UpdateCustomer	更新客户信息	admin
DeleteCustomer	删除客户	admin

CreateCustomer

描述

创建新客户。

Request — `CreateCustomerRequest`

字段	类型	编号	必填	描述
name	string	1	是	客户名称
contact_person	string	2	是	联系人
email	string	3	是	联系邮箱
phone	string	4	是	联系电话
company	string	5	是	公司名称
notes	string	6	是	备注
credit_limit	string	7	是	信用额度（字符串金额）

Response — `CreateCustomerResponse`

字段	类型	编号	描述
customer	CustomerInfo	1	创建的客户信息

错误码

错误	说明
InvalidArgument	参数校验失败
AlreadyExists	同名称客户已存在
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"name":"ACME Corp","contact_person":"John Doe","email":"[email protected]","phone":"1234567890","company":"ACME Inc.","notes":"VIP客户","credit_limit":"10000.00"}' \
  localhost:50051 rustbill.customer.CustomerService/CreateCustomer

const resp = await api.createCustomer({
  name: "ACME Corp",
  contact_person: "John Doe",
  email: "[email protected]",
  phone: "1234567890",
  company: "ACME Inc.",
  notes: "VIP客户",
  credit_limit: "10000.00"
});

ListCustomers

描述

分页查询客户列表，支持按状态和关键词筛选。

Request — `ListCustomersRequest`

字段	类型	编号	必填	描述
pagination	PageRequest	1	是	分页参数
is_active	bool?	2	否	按启用状态过滤
search	string?	3	否	名称/邮箱关键词搜索

Response — `ListCustomersResponse`

字段	类型	编号	描述
customers	repeated CustomerInfo	1	客户列表
meta	PageMeta	2	分页元数据

错误码

错误	说明
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"pagination":{"page":1,"page_size":20},"is_active":true,"search":"ACME"}' \
  localhost:50051 rustbill.customer.CustomerService/ListCustomers

GetCustomer

描述

获取单个客户详情。

Request — `GetCustomerRequest`

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

Response — `GetCustomerResponse`

字段	类型	编号	描述
customer	CustomerInfo	1	客户信息

错误码

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

示例

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

UpdateCustomer

描述

更新客户信息。所有字段均可选，仅更新传入的字段。

Request — `UpdateCustomerRequest`

字段	类型	编号	必填	描述
id	string	1	是	客户 ID
name	string?	2	否	客户名称
contact_person	string?	3	否	联系人
email	string?	4	否	联系邮箱
phone	string?	5	否	联系电话
company	string?	6	否	公司名称
notes	string?	7	否	备注
credit_limit	string?	8	否	信用额度
is_active	bool?	9	否	启用状态
can_create_api_keys	bool?	10	否	是否允许创建 API Key

Response — `UpdateCustomerResponse`

字段	类型	编号	描述
customer	CustomerInfo	1	更新后的客户信息

错误码

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

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192a123-...","credit_limit":"20000.00","can_create_api_keys":true}' \
  localhost:50051 rustbill.customer.CustomerService/UpdateCustomer

DeleteCustomer

描述

删除指定客户。

Request — `DeleteCustomerRequest`

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

Response — `DeleteCustomerResponse`

无字段。

错误码

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

示例

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

公共类型

CustomerInfo

字段	类型	编号	描述
id	string	1	客户 UUID
name	string	2	客户名称
contact_person	string	3	联系人姓名
email	string	4	联系邮箱
phone	string	5	联系电话
company	string	6	公司名称
notes	string	7	备注
balance	string	8	账户余额（字符串金额）
credit_limit	string	9	信用额度（字符串金额）
is_active	bool	10	是否启用
created_at	string	11	创建时间（RFC3339）
updated_at	string	12	更新时间（RFC3339）
can_create_api_keys	bool	13	是否允许创建 API Key

Keyboard shortcuts

RustBill 文档