Version: 0.9.72.dev.260505

后端：
1.task-class 服务边界落地
- 新增 cmd/task-class 独立进程入口，落地 services/task_class dao/rpc/sv
- 新增 gateway/client/taskclass、shared/contracts/taskclass 和 shared/ports task-class port
- 将 /api/v1/task-class/* HTTP 门面切到 task-class zrpc，gateway 只保留鉴权、幂等、参数绑定和响应透传
- 保留 task-class 迁移期直写 schedule_events / schedules 权限，维持 insert/apply 与 item 状态更新的本地事务语义
- 修复 task-class 删除已排入日程任务块时 schedules / schedule_events 的外键删除顺序
- 补充 taskClass.rpc 示例配置与阶段 5 文档基线、切流点、残留依赖和 smoke 记录
- 忽略根目录 .tmp 临时烟测产物

backend/gateway/api/task-class.go

@@ -6,41 +6,34 @@ import (
 	"strconv"
 	"time"
 
-	"github.com/LoveLosita/smartflow/backend/model"
 	"github.com/LoveLosita/smartflow/backend/respond"
-	"github.com/LoveLosita/smartflow/backend/service"
+	taskclasscontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclass"
+	"github.com/LoveLosita/smartflow/backend/shared/ports"
 	"github.com/gin-gonic/gin"
 )
 
+const taskClassRequestTimeout = 6 * time.Second
+
 type TaskClassHandler struct {
-	svc *service.TaskClassService
+	client ports.TaskClassCommandClient
 }
 
-// NewTaskClassHandler 组装 Handler 的“工厂”
-func NewTaskClassHandler(svc *service.TaskClassService) *TaskClassHandler {
-	return &TaskClassHandler{
-		svc: svc, // 把传进来的 Service 揣进口袋里
-	}
+// NewTaskClassHandler 创建 task-class HTTP 门面。
+func NewTaskClassHandler(client ports.TaskClassCommandClient) *TaskClassHandler {
+	return &TaskClassHandler{client: client}
 }
 
-const (
-	create = 0
-	update = 1
-)
-
 func (api *TaskClassHandler) UserAddTaskClass(c *gin.Context) {
-	var req model.UserAddTaskClassRequest
-	err := c.ShouldBindJSON(&req)
-	if err != nil {
+	var req taskclasscontracts.UpsertTaskClassRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
-	userIDInterface := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	err = api.svc.AddOrUpdateTaskClass(ctx, &req, userIDInterface, create, 0)
-	if err != nil {
+	req.UserID = c.GetInt("user_id")
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	if _, err := api.client.AddTaskClass(ctx, req); err != nil {
 		respond.DealWithError(c, err)
 		return
 	}
@@ -48,11 +41,11 @@ func (api *TaskClassHandler) UserAddTaskClass(c *gin.Context) {
 }
 
 func (api *TaskClassHandler) UserGetTaskClassInfos(c *gin.Context) {
-	userIDInterface := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	resp, err := api.svc.GetUserTaskClassInfos(ctx, userIDInterface)
+	userID := c.GetInt("user_id")
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	resp, err := api.client.ListTaskClasses(ctx, userID)
 	if err != nil {
 		respond.DealWithError(c, err)
 		return
@@ -62,7 +55,6 @@ func (api *TaskClassHandler) UserGetTaskClassInfos(c *gin.Context) {
 
 func (api *TaskClassHandler) UserGetCompleteTaskClass(c *gin.Context) {
 	taskClassID := c.Query("task_class_id")
-	//将taskClassID转换为int
 	intTaskClassID, err := strconv.Atoi(taskClassID)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
@@ -72,11 +64,14 @@ func (api *TaskClassHandler) UserGetCompleteTaskClass(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, respond.MissingParam)
 		return
 	}
-	userIDInterface := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	resp, err := api.svc.GetUserCompleteTaskClass(ctx, userIDInterface, intTaskClassID)
+	userID := c.GetInt("user_id")
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	resp, err := api.client.GetTaskClass(ctx, taskclasscontracts.GetTaskClassRequest{
+		UserID:      userID,
+		TaskClassID: intTaskClassID,
+	})
 	if err != nil {
 		respond.DealWithError(c, err)
 		return
@@ -85,21 +80,23 @@ func (api *TaskClassHandler) UserGetCompleteTaskClass(c *gin.Context) {
 }
 
 func (api *TaskClassHandler) UserUpdateTaskClass(c *gin.Context) {
-	var req model.UserAddTaskClassRequest
-	err := c.ShouldBindJSON(&req)
-	if err != nil {
+	var req taskclasscontracts.UpsertTaskClassRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
 	taskClassID := c.Query("task_class_id")
-	//将taskClassID转换为int
 	intTaskClassID, err := strconv.Atoi(taskClassID)
-	userIDInterface := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	err = api.svc.AddOrUpdateTaskClass(ctx, &req, userIDInterface, update, intTaskClassID)
 	if err != nil {
+		c.JSON(http.StatusBadRequest, respond.WrongParamType)
+		return
+	}
+	req.UserID = c.GetInt("user_id")
+	req.TaskClassID = intTaskClassID
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	if _, err := api.client.UpdateTaskClass(ctx, req); err != nil {
 		respond.DealWithError(c, err)
 		return
 	}
@@ -107,25 +104,23 @@ func (api *TaskClassHandler) UserUpdateTaskClass(c *gin.Context) {
 }
 
 func (api *TaskClassHandler) UserAddTaskClassItemIntoSchedule(c *gin.Context) {
-	var req model.UserInsertTaskClassItemToScheduleRequest
-	err := c.ShouldBindJSON(&req)
-	if err != nil {
+	var req taskclasscontracts.InsertTaskClassItemIntoScheduleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
 	taskID := c.Query("task_item_id")
-	//将taskID转换为int
 	intTaskID, err := strconv.Atoi(taskID)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
-	userIDInterface := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	err = api.svc.AddTaskClassItemIntoSchedule(ctx, &req, userIDInterface, intTaskID)
-	if err != nil {
+	req.UserID = c.GetInt("user_id")
+	req.TaskItemID = intTaskID
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	if _, err := api.client.InsertTaskClassItemIntoSchedule(ctx, req); err != nil {
 		respond.DealWithError(c, err)
 		return
 	}
@@ -134,18 +129,19 @@ func (api *TaskClassHandler) UserAddTaskClassItemIntoSchedule(c *gin.Context) {
 
 func (api *TaskClassHandler) DeleteTaskClassItem(c *gin.Context) {
 	taskID := c.Query("task_item_id")
-	//将taskID转换为int
 	intTaskID, err := strconv.Atoi(taskID)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
 	userID := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	err = api.svc.DeleteTaskClassItem(ctx, userID, intTaskID)
-	if err != nil {
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	if _, err := api.client.DeleteTaskClassItem(ctx, taskclasscontracts.DeleteTaskClassItemRequest{
+		UserID:     userID,
+		TaskItemID: intTaskID,
+	}); err != nil {
 		respond.DealWithError(c, err)
 		return
 	}
@@ -154,18 +150,19 @@ func (api *TaskClassHandler) DeleteTaskClassItem(c *gin.Context) {
 
 func (api *TaskClassHandler) DeleteTaskClass(c *gin.Context) {
 	taskClassID := c.Query("task_class_id")
-	//将taskClassID转换为int
 	intTaskClassID, err := strconv.Atoi(taskClassID)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
 	userID := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	err = api.svc.DeleteTaskClass(ctx, userID, intTaskClassID)
-	if err != nil {
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	if _, err := api.client.DeleteTaskClass(ctx, taskclasscontracts.DeleteTaskClassRequest{
+		UserID:      userID,
+		TaskClassID: intTaskClassID,
+	}); err != nil {
 		respond.DealWithError(c, err)
 		return
 	}
@@ -173,18 +170,16 @@ func (api *TaskClassHandler) DeleteTaskClass(c *gin.Context) {
 }
 
 func (api *TaskClassHandler) UserInsertBatchTaskClassItemsIntoSchedule(c *gin.Context) {
-	var req model.UserInsertTaskClassItemToScheduleRequestBatch
-	err := c.ShouldBindJSON(&req)
-	if err != nil {
+	var req taskclasscontracts.ApplyBatchIntoScheduleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
-	userID := c.GetInt("user_id")
-	// 创建一个带 1 秒超时的上下文
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 1*time.Second)
-	defer cancel() // 记得释放资源
-	err = api.svc.BatchApplyPlans(ctx, req.TaskClassID, userID, &req)
-	if err != nil {
+	req.UserID = c.GetInt("user_id")
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), taskClassRequestTimeout)
+	defer cancel()
+	if _, err := api.client.ApplyBatchIntoSchedule(ctx, req); err != nil {
 		respond.DealWithError(c, err)
 		return
 	}

backend/gateway/client/taskclass/client.go

@@ -0,0 +1,154 @@
+package taskclass
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	taskclasspb "github.com/LoveLosita/smartflow/backend/services/task_class/rpc/pb"
+	taskclasscontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclass"
+	"github.com/zeromicro/go-zero/zrpc"
+	"google.golang.org/grpc"
+)
+
+const (
+	defaultEndpoint = "127.0.0.1:9086"
+	defaultTimeout  = 6 * time.Second
+)
+
+type ClientConfig struct {
+	Endpoints []string
+	Target    string
+	Timeout   time.Duration
+}
+
+// Client 是 gateway 访问 task-class zrpc 的最小适配层。
+//
+// 职责边界：
+// 1. 只负责跨进程 gRPC 调用和 JSON 透传，不触碰 DAO 或迁移期 schedule 直写细节；
+// 2. HTTP 入参仍由 gateway/api 做基础绑定，业务校验交给 task-class 服务；
+// 3. 复杂响应不在 gateway 重建模型，避免 DTO 复制扩散。
+type Client struct {
+	rpc taskclasspb.TaskClassClient
+}
+
+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
+	}
+	client := &Client{rpc: taskclasspb.NewTaskClassClient(zclient.Conn())}
+	if err := client.ping(timeout); err != nil {
+		return nil, err
+	}
+	return client, nil
+}
+
+func (c *Client) AddTaskClass(ctx context.Context, req taskclasscontracts.UpsertTaskClassRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.AddTaskClass, req)
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) ListTaskClasses(ctx context.Context, userID int) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.ListTaskClasses, taskclasscontracts.UserRequest{UserID: userID})
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) GetTaskClass(ctx context.Context, req taskclasscontracts.GetTaskClassRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.GetTaskClass, req)
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) UpdateTaskClass(ctx context.Context, req taskclasscontracts.UpsertTaskClassRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.UpdateTaskClass, req)
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) InsertTaskClassItemIntoSchedule(ctx context.Context, req taskclasscontracts.InsertTaskClassItemIntoScheduleRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.InsertTaskClassItemIntoSchedule, req)
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) DeleteTaskClassItem(ctx context.Context, req taskclasscontracts.DeleteTaskClassItemRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.DeleteTaskClassItem, req)
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) DeleteTaskClass(ctx context.Context, req taskclasscontracts.DeleteTaskClassRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.DeleteTaskClass, req)
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) ApplyBatchIntoSchedule(ctx context.Context, req taskclasscontracts.ApplyBatchIntoScheduleRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.ApplyBatchIntoSchedule, req)
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) ensureReady() error {
+	if c == nil || c.rpc == nil {
+		return errors.New("task-class zrpc client is not initialized")
+	}
+	return nil
+}
+
+func (c *Client) ping(timeout time.Duration) error {
+	if err := c.ensureReady(); err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+	_, err := c.rpc.Ping(ctx, &taskclasspb.StatusResponse{})
+	return responseFromRPCError(err)
+}
+
+func (c *Client) callJSON(ctx context.Context, fn func(context.Context, *taskclasspb.JSONRequest, ...grpc.CallOption) (*taskclasspb.JSONResponse, error), payload any) (*taskclasspb.JSONResponse, error) {
+	if err := c.ensureReady(); err != nil {
+		return nil, err
+	}
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return nil, err
+	}
+	return fn(ctx, &taskclasspb.JSONRequest{PayloadJson: raw})
+}
+
+func jsonFromResponse(resp *taskclasspb.JSONResponse, rpcErr error) (json.RawMessage, error) {
+	if rpcErr != nil {
+		return nil, responseFromRPCError(rpcErr)
+	}
+	if resp == nil {
+		return nil, errors.New("task-class 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
+}

backend/gateway/client/taskclass/errors.go

@@ -0,0 +1,96 @@
+package taskclass
+
+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 负责把 task-class 的 gRPC 错误反解回项目内错误。
+//
+// 职责边界：
+// 1. 只在 gateway 边缘层使用；
+// 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 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 = "task-class zrpc service internal error"
+		}
+		return wrapRPCError(errors.New(msg))
+	}
+
+	msg := strings.TrimSpace(st.Message())
+	if msg == "" {
+		msg = "task-class 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
+	}
+	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.PermissionDenied:
+		return respond.ErrUnauthorized.Status
+	case codes.InvalidArgument:
+		return respond.MissingParam.Status
+	case codes.NotFound:
+		return respond.UserTaskClassNotFound.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("调用 task-class zrpc 服务失败: %w", err)
+}