// DownstreamClient 抽象层共享类型（B8 裁决：3 个 BFF 统一使用）
// 所有下游 gRPC 调用通过此抽象层，统一 trace 上下文注入 + 错误映射 + metrics

/** 下游调用上下文（per-request，由 GraphQL Resolver 注入） */
export interface CallContext {
  /** 当前用户 ID（从 JWT 或 x-user-id header 提取） */
  userId: string;
  /** 请求追踪 ID（X-Request-Id，用于日志关联） */
  traceId?: string;
  /** 用户角色（可选，用于下游权限校验） */
  roles?: readonly string[];
}

/** 下游调用结果（降级模式 B 支持：success + degraded 标记） */
export type DownstreamResult<T> =
  | { success: true; data: T; degraded?: false }
  | { success: true; data: T | null; degraded: true; warning: string }
  | { success: false; error: DownstreamError };

export interface DownstreamError {
  code: string;
  message: string;
  service: string;
  rpc?: string;
  details?: Record<string, unknown>;
}

/** 下游服务名（用于 metrics 标签 + 日志字段） */
export type DownstreamServiceName =
  "iam" | "core-edu" | "content" | "data-ana" | "msg" | "ai";

/** gRPC 健康检查结果（/readyz 探针用） */
export interface GrpcHealthStatus {
  service: DownstreamServiceName;
  target: string;
  status: "SERVING" | "NOT_SERVING" | "UNKNOWN" | "UNREACHABLE";
  latencyMs?: number;
  error?: string;
}

/** 下游 gRPC 调用 metadata（注入 trace context + x-user-id） */
export interface GrpcMetadata {
  "x-user-id": string;
  "x-request-id"?: string;
  traceparent?: string;
}
