Version: 0.9.69.dev.260504

后端： 1. 阶段 4 active-scheduler 服务边界落地，新增 `cmd/active-scheduler`、`services/active_scheduler`、`shared/contracts/activescheduler` 和 active-scheduler port，迁移 dry-run、trigger、preview、confirm zrpc 能力 2. active-scheduler outbox consumer、relay、retry loop 和 due job scanner 迁入独立服务入口，gateway `/active-schedule/*` 改为通过 zrpc client 调用 3. gateway 目录收口为 `gateway/api` + `gateway/client`，统一归档 userauth、notification、active-scheduler 的 HTTP 门面和 zrpc client 4. 将旧 `backend/active_scheduler` 领域核心下沉到 `services/active_scheduler/core`，清退旧根目录活跃实现，并补充 active-scheduler 启动期跨域依赖表检查 5. 调整单体启动与 outbox 归属，`cmd/all` 不再启动 active-scheduler workflow、scanner 或 handler 文档： 1. 更新微服务迁移计划，将阶段 4 active-scheduler 标记为首轮收口完成，并明确下一阶段进入 schedule / task / course / task-class
2026-05-04 21:01:00 +08:00
parent abe3b4960e
commit 4d9a5c4d30
66 changed files with 2048 additions and 466 deletions
--- a/backend/gateway/client/activescheduler/client.go
+++ b/backend/gateway/client/activescheduler/client.go
@@ -0,0 +1,195 @@
+package activescheduler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	activepb "github.com/LoveLosita/smartflow/backend/services/active_scheduler/rpc/pb"
+	contracts "github.com/LoveLosita/smartflow/backend/shared/contracts/activescheduler"
+	"github.com/zeromicro/go-zero/zrpc"
+)
+
+const (
+	defaultEndpoint = "127.0.0.1:9083"
+	defaultTimeout  = 8 * time.Second
+)
+
+type ClientConfig struct {
+	Endpoints []string
+	Target    string
+	Timeout   time.Duration
+}
+
+// Client 是 gateway 侧 active-scheduler zrpc 的最小适配层。
+//
+// 职责边界：
+// 1. 只负责跨进程 gRPC 调用和响应 JSON 透传，不碰 DAO、graph、outbox 或 job scanner；
+// 2. confirm/apply 业务拒绝从 gRPC status 反解成共享 ApplyError，便于 API 层维持既有响应形状；
+// 3. 复杂响应不在 gateway 重新建模，避免主动调度 DTO 复制扩散。
+type Client struct {
+	rpc activepb.ActiveSchedulerClient
+}
+
+func NewClient(cfg ClientConfig) (*Client, error) {
+	timeout := cfg.Timeout
+	if timeout <= 0 {
+		timeout = defaultTimeout
+	}
+	endpoints := normalizeEndpoints(cfg.Endpoints)
+	target := strings.TrimSpace(cfg.Target)
+	if len(endpoints) == 0 && target == "" {
+		endpoints = []string{defaultEndpoint}
+	}
+
+	zclient, err := zrpc.NewClient(zrpc.RpcClientConf{
+		Endpoints: endpoints,
+		Target:    target,
+		NonBlock:  true,
+		Timeout:   int64(timeout / time.Millisecond),
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &Client{rpc: activepb.NewActiveSchedulerClient(zclient.Conn())}, nil
+}
+
+func (c *Client) DryRun(ctx context.Context, req contracts.ActiveScheduleRequest) (json.RawMessage, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.DryRun(ctx, requestToPB(req))
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return jsonFromResponse(resp)
+}
+
+func (c *Client) Trigger(ctx context.Context, req contracts.ActiveScheduleRequest) (*contracts.TriggerResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.Trigger(ctx, requestToPB(req))
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return triggerFromPB(resp), nil
+}
+
+func (c *Client) CreatePreview(ctx context.Context, req contracts.ActiveScheduleRequest) (json.RawMessage, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.CreatePreview(ctx, requestToPB(req))
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return jsonFromResponse(resp)
+}
+
+func (c *Client) GetPreview(ctx context.Context, req contracts.GetPreviewRequest) (json.RawMessage, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.GetPreview(ctx, &activepb.GetPreviewRequest{
+		UserId:    int64(req.UserID),
+		PreviewId: req.PreviewID,
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return jsonFromResponse(resp)
+}
+
+func (c *Client) ConfirmPreview(ctx context.Context, req contracts.ConfirmPreviewRequest) (json.RawMessage, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.ConfirmPreview(ctx, confirmToPB(req))
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return jsonFromResponse(resp)
+}
+
+func (c *Client) ensureReady() error {
+	if c == nil || c.rpc == nil {
+		return errors.New("active-scheduler zrpc client is not initialized")
+	}
+	return nil
+}
+
+func requestToPB(req contracts.ActiveScheduleRequest) *activepb.ActiveScheduleRequest {
+	mockNowUnixNano := int64(0)
+	if req.MockNow != nil && !req.MockNow.IsZero() {
+		mockNowUnixNano = req.MockNow.UnixNano()
+	}
+	return &activepb.ActiveScheduleRequest{
+		UserId:          int64(req.UserID),
+		TriggerType:     req.TriggerType,
+		TargetType:      req.TargetType,
+		TargetId:        int64(req.TargetID),
+		FeedbackId:      req.FeedbackID,
+		IdempotencyKey:  req.IdempotencyKey,
+		MockNowUnixNano: mockNowUnixNano,
+		PayloadJson:     []byte(req.Payload),
+	}
+}
+
+func confirmToPB(req contracts.ConfirmPreviewRequest) *activepb.ConfirmPreviewRequest {
+	requestedAtUnixNano := int64(0)
+	if !req.RequestedAt.IsZero() {
+		requestedAtUnixNano = req.RequestedAt.UnixNano()
+	}
+	return &activepb.ConfirmPreviewRequest{
+		UserId:              int64(req.UserID),
+		PreviewId:           req.PreviewID,
+		CandidateId:         req.CandidateID,
+		Action:              req.Action,
+		EditedChangesJson:   []byte(req.EditedChanges),
+		IdempotencyKey:      req.IdempotencyKey,
+		RequestedAtUnixNano: requestedAtUnixNano,
+		TraceId:             req.TraceID,
+	}
+}
+
+func triggerFromPB(resp *activepb.TriggerResponse) *contracts.TriggerResponse {
+	if resp == nil {
+		return &contracts.TriggerResponse{}
+	}
+	var previewID *string
+	if resp.HasPreviewId {
+		value := resp.PreviewId
+		previewID = &value
+	}
+	return &contracts.TriggerResponse{
+		TriggerID: resp.TriggerId,
+		Status:    resp.Status,
+		PreviewID: previewID,
+		DedupeHit: resp.DedupeHit,
+		TraceID:   resp.TraceId,
+	}
+}
+
+func jsonFromResponse(resp *activepb.JSONResponse) (json.RawMessage, error) {
+	if resp == nil {
+		return nil, errors.New("active-scheduler zrpc service returned empty JSON response")
+	}
+	if len(resp.DataJson) == 0 {
+		return json.RawMessage("null"), nil
+	}
+	return json.RawMessage(resp.DataJson), nil
+}
+
+func normalizeEndpoints(values []string) []string {
+	endpoints := make([]string, 0, len(values))
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			endpoints = append(endpoints, trimmed)
+		}
+	}
+	return endpoints
+}
--- a/backend/gateway/client/activescheduler/errors.go
+++ b/backend/gateway/client/activescheduler/errors.go
@@ -0,0 +1,116 @@
+package activescheduler
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/respond"
+	contracts "github.com/LoveLosita/smartflow/backend/shared/contracts/activescheduler"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+const activeSchedulerApplyErrorDomain = "smartflow.active_scheduler.apply"
+
+// responseFromRPCError 负责把 active-scheduler 的 gRPC 错误反解回项目内错误。
+//
+// 职责边界：
+// 1. confirm/apply 业务错误恢复为 shared/contracts/activescheduler.ApplyError；
+// 2. 普通业务错误恢复为 respond.Response，供 API 层复用 DealWithError；
+// 3. 服务不可用或未知内部错误包装成普通 error，避免误报成用户可修正的参数问题。
+func responseFromRPCError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	st, ok := status.FromError(err)
+	if !ok {
+		return wrapRPCError(err)
+	}
+	if applyErr, ok := applyErrorFromStatus(st); ok {
+		return applyErr
+	}
+	if resp, ok := responseFromStatus(st); ok {
+		return resp
+	}
+
+	switch st.Code() {
+	case codes.Internal, codes.Unknown, codes.Unavailable, codes.DeadlineExceeded, codes.DataLoss, codes.Unimplemented:
+		msg := strings.TrimSpace(st.Message())
+		if msg == "" {
+			msg = "active-scheduler zrpc service internal error"
+		}
+		return wrapRPCError(errors.New(msg))
+	}
+
+	msg := strings.TrimSpace(st.Message())
+	if msg == "" {
+		msg = "active-scheduler zrpc service rejected request"
+	}
+	return respond.Response{Status: grpcCodeToRespondStatus(st.Code()), Info: msg}
+}
+
+func applyErrorFromStatus(st *status.Status) (*contracts.ApplyError, bool) {
+	for _, detail := range st.Details() {
+		info, ok := detail.(*errdetails.ErrorInfo)
+		if !ok || info.Domain != activeSchedulerApplyErrorDomain {
+			continue
+		}
+		message := strings.TrimSpace(st.Message())
+		if message == "" && info.Metadata != nil {
+			message = strings.TrimSpace(info.Metadata["info"])
+		}
+		return &contracts.ApplyError{
+			Code:    contracts.ApplyErrorCode(strings.TrimSpace(info.Reason)),
+			Message: message,
+		}, true
+	}
+	return nil, false
+}
+
+func responseFromStatus(st *status.Status) (respond.Response, bool) {
+	if st == nil {
+		return respond.Response{}, false
+	}
+	for _, detail := range st.Details() {
+		info, ok := detail.(*errdetails.ErrorInfo)
+		if !ok {
+			continue
+		}
+		statusValue := strings.TrimSpace(info.Reason)
+		if statusValue == "" {
+			statusValue = grpcCodeToRespondStatus(st.Code())
+		}
+		message := strings.TrimSpace(st.Message())
+		if message == "" && info.Metadata != nil {
+			message = strings.TrimSpace(info.Metadata["info"])
+		}
+		if message == "" {
+			message = statusValue
+		}
+		return respond.Response{Status: statusValue, Info: message}, true
+	}
+	return respond.Response{}, false
+}
+
+func grpcCodeToRespondStatus(code codes.Code) string {
+	switch code {
+	case codes.Unauthenticated:
+		return respond.ErrUnauthorized.Status
+	case codes.InvalidArgument:
+		return respond.MissingParam.Status
+	case codes.Internal, codes.Unknown, codes.DataLoss:
+		return "500"
+	default:
+		return "400"
+	}
+}
+
+func wrapRPCError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("调用 active-scheduler zrpc 服务失败: %w", err)
+}
--- a/backend/gateway/client/notification/client.go
+++ b/backend/gateway/client/notification/client.go
@@ -0,0 +1,181 @@
+package notification
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	notificationpb "github.com/LoveLosita/smartflow/backend/services/notification/rpc/pb"
+	contracts "github.com/LoveLosita/smartflow/backend/shared/contracts/notification"
+	"github.com/zeromicro/go-zero/zrpc"
+)
+
+const (
+	defaultEndpoint = "127.0.0.1:9082"
+	defaultTimeout  = 6 * time.Second
+)
+
+type ClientConfig struct {
+	Endpoints []string
+	Target    string
+	Timeout   time.Duration
+}
+
+// Client 是 gateway 侧 notification zrpc 的最小适配层。
+//
+// 职责边界：
+// 1. 只负责跨进程 gRPC 调用和响应转译，不碰 DB / provider / outbox 细节；
+// 2. 服务端业务错误先通过 gRPC status 传输，再在这里反解回 respond.Response 风格；
+// 3. 上层调用方仍然可以保持 `res, err :=` 的统一用法。
+type Client struct {
+	rpc notificationpb.NotificationClient
+}
+
+func NewClient(cfg ClientConfig) (*Client, error) {
+	timeout := cfg.Timeout
+	if timeout <= 0 {
+		timeout = defaultTimeout
+	}
+	endpoints := normalizeEndpoints(cfg.Endpoints)
+	target := strings.TrimSpace(cfg.Target)
+	if len(endpoints) == 0 && target == "" {
+		endpoints = []string{defaultEndpoint}
+	}
+
+	zclient, err := zrpc.NewClient(zrpc.RpcClientConf{
+		Endpoints: endpoints,
+		Target:    target,
+		NonBlock:  true,
+		Timeout:   int64(timeout / time.Millisecond),
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &Client{rpc: notificationpb.NewNotificationClient(zclient.Conn())}, nil
+}
+
+func (c *Client) GetFeishuWebhook(ctx context.Context, req contracts.GetFeishuWebhookRequest) (*contracts.ChannelResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.GetFeishuWebhook(ctx, &notificationpb.GetFeishuWebhookRequest{
+		UserId: int64(req.UserID),
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return channelFromResponse(resp)
+}
+
+func (c *Client) SaveFeishuWebhook(ctx context.Context, req contracts.SaveFeishuWebhookRequest) (*contracts.ChannelResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.SaveFeishuWebhook(ctx, &notificationpb.SaveFeishuWebhookRequest{
+		UserId:      int64(req.UserID),
+		Enabled:     req.Enabled,
+		WebhookUrl:  req.WebhookURL,
+		AuthType:    req.AuthType,
+		BearerToken: req.BearerToken,
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return channelFromResponse(resp)
+}
+
+func (c *Client) DeleteFeishuWebhook(ctx context.Context, req contracts.DeleteFeishuWebhookRequest) error {
+	if err := c.ensureReady(); err != nil {
+		return err
+	}
+	resp, err := c.rpc.DeleteFeishuWebhook(ctx, &notificationpb.DeleteFeishuWebhookRequest{
+		UserId: int64(req.UserID),
+	})
+	if err != nil {
+		return responseFromRPCError(err)
+	}
+	if resp == nil {
+		return errors.New("notification zrpc service returned empty delete response")
+	}
+	return nil
+}
+
+func (c *Client) TestFeishuWebhook(ctx context.Context, req contracts.TestFeishuWebhookRequest) (*contracts.TestResult, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.TestFeishuWebhook(ctx, &notificationpb.TestFeishuWebhookRequest{
+		UserId: int64(req.UserID),
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return testResultFromResponse(resp)
+}
+
+func (c *Client) ensureReady() error {
+	if c == nil || c.rpc == nil {
+		return errors.New("notification zrpc client is not initialized")
+	}
+	return nil
+}
+
+func channelFromResponse(resp *notificationpb.ChannelResponse) (*contracts.ChannelResponse, error) {
+	if resp == nil {
+		return nil, errors.New("notification zrpc service returned empty channel response")
+	}
+	var lastTestAt *time.Time
+	if value := timeFromUnixNano(resp.LastTestAtUnixNano); !value.IsZero() {
+		lastTestAt = &value
+	}
+	return &contracts.ChannelResponse{
+		Channel:        resp.Channel,
+		Enabled:        resp.Enabled,
+		Configured:     resp.Configured,
+		WebhookURLMask: resp.WebhookUrlMask,
+		AuthType:       resp.AuthType,
+		HasBearerToken: resp.HasBearerToken,
+		LastTestStatus: resp.LastTestStatus,
+		LastTestError:  resp.LastTestError,
+		LastTestAt:     lastTestAt,
+	}, nil
+}
+
+func testResultFromResponse(resp *notificationpb.TestResult) (*contracts.TestResult, error) {
+	if resp == nil {
+		return nil, errors.New("notification zrpc service returned empty test response")
+	}
+	channel, err := channelFromResponse(resp.Channel)
+	if err != nil {
+		return nil, err
+	}
+	return &contracts.TestResult{
+		Channel:  *channel,
+		Status:   resp.Status,
+		Outcome:  resp.Outcome,
+		Message:  resp.Message,
+		TraceID:  resp.TraceId,
+		SentAt:   timeFromUnixNano(resp.SentAtUnixNano),
+		Skipped:  resp.Skipped,
+		Provider: resp.Provider,
+	}, nil
+}
+
+func normalizeEndpoints(values []string) []string {
+	endpoints := make([]string, 0, len(values))
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			endpoints = append(endpoints, trimmed)
+		}
+	}
+	return endpoints
+}
+
+func timeFromUnixNano(value int64) time.Time {
+	if value <= 0 {
+		return time.Time{}
+	}
+	return time.Unix(0, value)
+}
--- a/backend/gateway/client/notification/errors.go
+++ b/backend/gateway/client/notification/errors.go
@@ -0,0 +1,151 @@
+package notification
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/respond"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// responseFromRPCError 负责把 notification 的 gRPC 错误反解回项目内的 respond.Response。
+//
+// 职责边界：
+// 1. 只在 gateway 边缘层使用，不下沉到服务实现里；
+// 2. 业务错误尽量恢复成 respond.Response，方便 API 层继续复用现有 DealWithError；
+// 3. 只要拿不到业务语义，就退化成普通 error，让上层按 500 处理。
+func responseFromRPCError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	st, ok := status.FromError(err)
+	if !ok {
+		return wrapRPCError(err)
+	}
+
+	if resp, ok := responseFromStatus(st); ok {
+		return resp
+	}
+
+	switch st.Code() {
+	case codes.Internal, codes.Unknown, codes.Unavailable, codes.DeadlineExceeded, codes.DataLoss, codes.Unimplemented:
+		msg := strings.TrimSpace(st.Message())
+		if msg == "" {
+			msg = "notification zrpc service internal error"
+		}
+		return wrapRPCError(errors.New(msg))
+	}
+
+	msg := strings.TrimSpace(st.Message())
+	if msg == "" {
+		msg = "notification zrpc service rejected request"
+	}
+	return respond.Response{
+		Status: grpcCodeToRespondStatus(st.Code()),
+		Info:   msg,
+	}
+}
+
+func responseFromStatus(st *status.Status) (respond.Response, bool) {
+	if st == nil {
+		return respond.Response{}, false
+	}
+
+	if resp, ok := responseFromStatusDetails(st); ok {
+		return resp, true
+	}
+	if resp, ok := responseFromLegacyStatus(st.Code(), st.Message()); ok {
+		return resp, true
+	}
+	return respond.Response{}, false
+}
+
+func responseFromStatusDetails(st *status.Status) (respond.Response, bool) {
+	for _, detail := range st.Details() {
+		info, ok := detail.(*errdetails.ErrorInfo)
+		if !ok {
+			continue
+		}
+
+		statusValue := strings.TrimSpace(info.Reason)
+		if statusValue == "" {
+			statusValue = grpcCodeToRespondStatus(st.Code())
+		}
+		if statusValue == "" {
+			return respond.Response{}, false
+		}
+
+		message := strings.TrimSpace(st.Message())
+		if message == "" && info.Metadata != nil {
+			message = strings.TrimSpace(info.Metadata["info"])
+		}
+		if message == "" {
+			message = statusValue
+		}
+		return respond.Response{Status: statusValue, Info: message}, true
+	}
+	return respond.Response{}, false
+}
+
+func responseFromLegacyStatus(code codes.Code, message string) (respond.Response, bool) {
+	trimmed := strings.TrimSpace(message)
+	if resp, ok := respondResponseByMessage(trimmed); ok {
+		return resp, true
+	}
+
+	switch code {
+	case codes.Unauthenticated:
+		if trimmed == "" {
+			trimmed = "unauthorized"
+		}
+		return respond.Response{Status: respond.ErrUnauthorized.Status, Info: trimmed}, true
+	case codes.InvalidArgument:
+		if trimmed == "" {
+			trimmed = "invalid argument"
+		}
+		return respond.Response{Status: respond.MissingParam.Status, Info: trimmed}, true
+	case codes.Internal, codes.Unknown, codes.DataLoss:
+		if trimmed == "" {
+			trimmed = "notification service internal error"
+		}
+		return respond.InternalError(errors.New(trimmed)), true
+	}
+
+	return respond.Response{}, false
+}
+
+func respondResponseByMessage(message string) (respond.Response, bool) {
+	switch strings.TrimSpace(message) {
+	case respond.MissingParam.Info:
+		return respond.MissingParam, true
+	case respond.WrongParamType.Info:
+		return respond.WrongParamType, true
+	case respond.ErrUnauthorized.Info:
+		return respond.ErrUnauthorized, true
+	}
+	return respond.Response{}, false
+}
+
+func grpcCodeToRespondStatus(code codes.Code) string {
+	switch code {
+	case codes.Unauthenticated:
+		return respond.ErrUnauthorized.Status
+	case codes.InvalidArgument:
+		return respond.MissingParam.Status
+	case codes.Internal, codes.Unknown, codes.DataLoss:
+		return "500"
+	default:
+		return "400"
+	}
+}
+
+func wrapRPCError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("调用 notification zrpc 服务失败: %w", err)
+}
--- a/backend/gateway/client/userauth/client.go
+++ b/backend/gateway/client/userauth/client.go
@@ -0,0 +1,218 @@
+package userauth
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/services/userauth/rpc/pb"
+	contracts "github.com/LoveLosita/smartflow/backend/shared/contracts/userauth"
+	"github.com/zeromicro/go-zero/zrpc"
+)
+
+const (
+	defaultEndpoint = "127.0.0.1:9081"
+	defaultTimeout  = 2 * time.Second
+)
+
+type ClientConfig struct {
+	Endpoints []string
+	Target    string
+	Timeout   time.Duration
+}
+
+// Client 是 gateway 侧 user/auth zrpc 的最小适配层。
+//
+// 职责边界：
+// 1. 只负责跨进程 gRPC 调用和响应转译，不碰 DB / Redis / JWT 细节；
+// 2. 服务端业务错误先通过 gRPC status 传输，再在这里反解回 respond.Response 风格；
+// 3. 上层调用方仍然可以保持 `res, err :=` 的统一用法。
+type Client struct {
+	rpc pb.UserAuthClient
+}
+
+func NewClient(cfg ClientConfig) (*Client, error) {
+	timeout := cfg.Timeout
+	if timeout <= 0 {
+		timeout = defaultTimeout
+	}
+	endpoints := normalizeEndpoints(cfg.Endpoints)
+	target := strings.TrimSpace(cfg.Target)
+	if len(endpoints) == 0 && target == "" {
+		endpoints = []string{defaultEndpoint}
+	}
+
+	zclient, err := zrpc.NewClient(zrpc.RpcClientConf{
+		Endpoints: endpoints,
+		Target:    target,
+		NonBlock:  true,
+		Timeout:   int64(timeout / time.Millisecond),
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &Client{rpc: pb.NewUserAuthClient(zclient.Conn())}, nil
+}
+
+func (c *Client) Register(ctx context.Context, req contracts.RegisterRequest) (*contracts.RegisterResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.Register(ctx, &pb.RegisterRequest{
+		Username:    req.Username,
+		Password:    req.Password,
+		PhoneNumber: req.PhoneNumber,
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	if resp == nil {
+		return nil, errors.New("userauth zrpc service returned empty register response")
+	}
+	return &contracts.RegisterResponse{ID: uint(resp.Id)}, nil
+}
+
+func (c *Client) Login(ctx context.Context, req contracts.LoginRequest) (*contracts.Tokens, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.Login(ctx, &pb.LoginRequest{
+		Username: req.Username,
+		Password: req.Password,
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return tokensFromResponse(resp)
+}
+
+func (c *Client) RefreshToken(ctx context.Context, req contracts.RefreshTokenRequest) (*contracts.Tokens, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.RefreshToken(ctx, &pb.RefreshTokenRequest{
+		RefreshToken: req.RefreshToken,
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	return tokensFromResponse(resp)
+}
+
+func (c *Client) Logout(ctx context.Context, accessToken string) error {
+	if err := c.ensureReady(); err != nil {
+		return err
+	}
+	resp, err := c.rpc.Logout(ctx, &pb.LogoutRequest{
+		AccessToken: accessToken,
+	})
+	if err != nil {
+		return responseFromRPCError(err)
+	}
+	if resp == nil {
+		return errors.New("userauth zrpc service returned empty logout response")
+	}
+	return nil
+}
+
+func (c *Client) ValidateAccessToken(ctx context.Context, accessToken string) (*contracts.ValidateAccessTokenResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.ValidateAccessToken(ctx, &pb.ValidateAccessTokenRequest{
+		AccessToken: accessToken,
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	if resp == nil {
+		return nil, errors.New("userauth zrpc service returned empty validate response")
+	}
+	return &contracts.ValidateAccessTokenResponse{
+		Valid:     resp.Valid,
+		UserID:    int(resp.UserId),
+		TokenType: resp.TokenType,
+		JTI:       resp.Jti,
+		ExpiresAt: timeFromUnixNano(resp.ExpiresAtUnixNano),
+	}, nil
+}
+
+func (c *Client) CheckTokenQuota(ctx context.Context, userID int) (*contracts.CheckTokenQuotaResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.CheckTokenQuota(ctx, &pb.CheckTokenQuotaRequest{
+		UserId: int64(userID),
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	if resp == nil {
+		return nil, errors.New("userauth zrpc service returned empty quota response")
+	}
+	return &contracts.CheckTokenQuotaResponse{
+		Allowed:     resp.Allowed,
+		TokenLimit:  int(resp.TokenLimit),
+		TokenUsage:  int(resp.TokenUsage),
+		LastResetAt: timeFromUnixNano(resp.LastResetAtUnixNano),
+	}, nil
+}
+
+func (c *Client) AdjustTokenUsage(ctx context.Context, req contracts.AdjustTokenUsageRequest) (*contracts.CheckTokenQuotaResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	resp, err := c.rpc.AdjustTokenUsage(ctx, &pb.AdjustTokenUsageRequest{
+		EventId:    req.EventID,
+		UserId:     int64(req.UserID),
+		TokenDelta: int64(req.TokenDelta),
+	})
+	if err != nil {
+		return nil, responseFromRPCError(err)
+	}
+	if resp == nil {
+		return nil, errors.New("userauth zrpc service returned empty adjust response")
+	}
+	return &contracts.CheckTokenQuotaResponse{
+		Allowed:     resp.Allowed,
+		TokenLimit:  int(resp.TokenLimit),
+		TokenUsage:  int(resp.TokenUsage),
+		LastResetAt: timeFromUnixNano(resp.LastResetAtUnixNano),
+	}, nil
+}
+
+func (c *Client) ensureReady() error {
+	if c == nil || c.rpc == nil {
+		return errors.New("userauth zrpc client is not initialized")
+	}
+	return nil
+}
+
+func tokensFromResponse(resp *pb.TokensResponse) (*contracts.Tokens, error) {
+	if resp == nil {
+		return nil, errors.New("userauth zrpc service returned empty token response")
+	}
+	return &contracts.Tokens{
+		AccessToken:  resp.AccessToken,
+		RefreshToken: resp.RefreshToken,
+	}, nil
+}
+
+func normalizeEndpoints(values []string) []string {
+	endpoints := make([]string, 0, len(values))
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			endpoints = append(endpoints, trimmed)
+		}
+	}
+	return endpoints
+}
+
+func timeFromUnixNano(value int64) time.Time {
+	if value <= 0 {
+		return time.Time{}
+	}
+	return time.Unix(0, value)
+}
--- a/backend/gateway/client/userauth/errors.go
+++ b/backend/gateway/client/userauth/errors.go
@@ -0,0 +1,198 @@
+package userauth
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/respond"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// responseFromRPCError 负责把 user/auth 的 gRPC 错误反解回项目内的 respond.Response。
+//
+// 职责边界：
+// 1. 只在 gateway 边缘层使用，不下沉到服务实现里；
+// 2. 业务错误尽量恢复成 respond.Response，方便 API 层继续复用现有 DealWithError；
+// 3. 只要拿不到业务语义，就退化成普通 error，让上层按 500 处理。
+func responseFromRPCError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	st, ok := status.FromError(err)
+	if !ok {
+		return wrapRPCError(err)
+	}
+
+	if resp, ok := responseFromStatus(st); ok {
+		return resp
+	}
+
+	switch st.Code() {
+	case codes.Internal, codes.Unknown, codes.Unavailable, codes.DeadlineExceeded, codes.DataLoss, codes.Unimplemented:
+		msg := strings.TrimSpace(st.Message())
+		if msg == "" {
+			msg = "userauth zrpc service internal error"
+		}
+		return wrapRPCError(errors.New(msg))
+	}
+
+	msg := strings.TrimSpace(st.Message())
+	if msg == "" {
+		msg = "userauth zrpc service rejected request"
+	}
+	return respond.Response{
+		Status: grpcCodeToRespondStatus(st.Code()),
+		Info:   msg,
+	}
+}
+
+func responseFromStatus(st *status.Status) (respond.Response, bool) {
+	if st == nil {
+		return respond.Response{}, false
+	}
+
+	if resp, ok := responseFromStatusDetails(st); ok {
+		return resp, true
+	}
+	if resp, ok := responseFromLegacyStatus(st.Code(), st.Message()); ok {
+		return resp, true
+	}
+	return respond.Response{}, false
+}
+
+func responseFromStatusDetails(st *status.Status) (respond.Response, bool) {
+	for _, detail := range st.Details() {
+		info, ok := detail.(*errdetails.ErrorInfo)
+		if !ok {
+			continue
+		}
+
+		statusValue := strings.TrimSpace(info.Reason)
+		if statusValue == "" {
+			statusValue = grpcCodeToRespondStatus(st.Code())
+		}
+		if statusValue == "" {
+			return respond.Response{}, false
+		}
+
+		message := strings.TrimSpace(st.Message())
+		if message == "" && info.Metadata != nil {
+			message = strings.TrimSpace(info.Metadata["info"])
+		}
+		if message == "" {
+			message = statusValue
+		}
+		return respond.Response{Status: statusValue, Info: message}, true
+	}
+	return respond.Response{}, false
+}
+
+func responseFromLegacyStatus(code codes.Code, message string) (respond.Response, bool) {
+	trimmed := strings.TrimSpace(message)
+	if resp, ok := respondResponseByMessage(trimmed); ok {
+		return resp, true
+	}
+
+	switch code {
+	case codes.Unauthenticated:
+		if trimmed == "" {
+			trimmed = "unauthorized"
+		}
+		return respond.Response{Status: respond.ErrUnauthorized.Status, Info: trimmed}, true
+	case codes.AlreadyExists:
+		if trimmed == "" {
+			trimmed = "already exists"
+		}
+		return respond.Response{Status: respond.InvalidName.Status, Info: trimmed}, true
+	case codes.NotFound:
+		if trimmed == "" {
+			trimmed = "not found"
+		}
+		return respond.Response{Status: respond.WrongName.Status, Info: trimmed}, true
+	case codes.ResourceExhausted:
+		if trimmed == "" {
+			trimmed = respond.TokenUsageExceedsLimit.Info
+		}
+		return respond.Response{Status: respond.TokenUsageExceedsLimit.Status, Info: trimmed}, true
+	case codes.InvalidArgument:
+		if trimmed == "" {
+			trimmed = "invalid argument"
+		}
+		return respond.Response{Status: respond.MissingParam.Status, Info: trimmed}, true
+	case codes.Internal, codes.Unknown, codes.DataLoss:
+		if trimmed == "" {
+			trimmed = "userauth service internal error"
+		}
+		return respond.InternalError(errors.New(trimmed)), true
+	}
+
+	return respond.Response{}, false
+}
+
+func respondResponseByMessage(message string) (respond.Response, bool) {
+	switch strings.TrimSpace(message) {
+	case respond.MissingParam.Info:
+		return respond.MissingParam, true
+	case respond.WrongParamType.Info:
+		return respond.WrongParamType, true
+	case respond.ParamTooLong.Info:
+		return respond.ParamTooLong, true
+	case respond.InvalidName.Info:
+		return respond.InvalidName, true
+	case respond.WrongName.Info:
+		return respond.WrongName, true
+	case respond.WrongPwd.Info:
+		return respond.WrongPwd, true
+	case respond.WrongUsernameOrPwd.Info:
+		return respond.WrongUsernameOrPwd, true
+	case respond.MissingToken.Info:
+		return respond.MissingToken, true
+	case respond.InvalidTokenSingingMethod.Info:
+		return respond.InvalidTokenSingingMethod, true
+	case respond.InvalidToken.Info:
+		return respond.InvalidToken, true
+	case respond.InvalidClaims.Info:
+		return respond.InvalidClaims, true
+	case respond.ErrUnauthorized.Info:
+		return respond.ErrUnauthorized, true
+	case respond.InvalidRefreshToken.Info:
+		return respond.InvalidRefreshToken, true
+	case respond.WrongTokenType.Info:
+		return respond.WrongTokenType, true
+	case respond.UserLoggedOut.Info:
+		return respond.UserLoggedOut, true
+	case respond.WrongUserID.Info:
+		return respond.WrongUserID, true
+	case respond.TokenUsageExceedsLimit.Info:
+		return respond.TokenUsageExceedsLimit, true
+	}
+	return respond.Response{}, false
+}
+
+func grpcCodeToRespondStatus(code codes.Code) string {
+	switch code {
+	case codes.Unauthenticated:
+		return respond.ErrUnauthorized.Status
+	case codes.AlreadyExists:
+		return respond.InvalidName.Status
+	case codes.NotFound:
+		return respond.WrongName.Status
+	case codes.ResourceExhausted:
+		return respond.TokenUsageExceedsLimit.Status
+	case codes.Internal, codes.Unknown, codes.DataLoss:
+		return "500"
+	default:
+		return "400"
+	}
+}
+
+func wrapRPCError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("调用 userauth zrpc 服务失败: %w", err)
+}