gRPC 接口设计

逐条规则在 .claude/rules/rpc/proto.md 与 .claude/rules/rpc/grpc-go.md，编辑对应文件时自动加载。兼容性实测见 references/proto.md，服务端／客户端／测试模板与实测依据见 references/grpc-go.md。

1. 确认用不用 gRPC

项目已有 RPC 方案时沿用；引入 gRPC 或网关属于选型，写 ADR。

2. 选调用模式

默认 unary。只有以下情况考虑流，并在设计中写明代价：

流的代价：一条流固定在一个后端实例（扩容后不会自动分流）；中断后要重建并处理已消费部分，不能像 unary 一样直接重试；每条活跃流占用服务端 goroutine 与缓冲；GracefulStop 会一直等流结束。分页能解决的大结果集优先用分页 unary。

3. 写契约

逐项写进设计文档（docs/design/<模块>-rpc.md）或 proto 注释：

4. 兼容性检查

改已有 proto 前对照 references/proto.md 的兼容性表；项目有 buf.yaml 时运行 buf lint 与 buf breaking。新项目 buf.yaml 的 breaking 用 FILE（buf 默认）：淘汰字段标 [deprecated = true] 保留，不删除；破坏性变更走新版本 package，与旧版本并存到调用方全部迁移。

5. 实现

1. 生成代码（项目的 buf generate / make proto）。
2. 传输层 handler：pb ↔ dto 转换、调用 service、按错误映射表返回 status（模板见 references/grpc-go.md）。
3. service、repository 按 rules/go/layering.md 实现，不感知 gRPC。
4. 服务端装配：recovery 拦截器在最前、健康检查、keepalive 策略、优雅关闭。
5. 调用方：复用 ClientConn、service config（负载均衡、超时、重试）、转发需要的 metadata。

6. 测试

• 用 bufconn 起进程内服务端，覆盖：正常返回、每种业务错误的 code、参数缺失、deadline 到期。
• 流式方法覆盖：正常结束（io.EOF）、中途出错、客户端取消。

7. 自查清单

• 每个出站调用都有 deadline，handler 把收到的 ctx 传给下游
• handler 只返回 status 错误，Internal 不泄露内部错误文本
• 非幂等写方法没有配置自动重试，或有幂等键去重
• 删除的字段已 reserved 号与名，没有改已有字段的类型、名字或 oneof 归属
• 需要转发的 metadata（request id 等）已显式写入出站 context
• 长耗时处理与流的发送循环检查 ctx.Done()
• 新服务已注册健康检查，关闭流程有超时兜底
• 依赖 round_robin 的调用方使用 headless Service 或 L7 代理（运维面见 dev-ops 的 middleware-ops）