Version: 0.9.73.dev.260505

后端：
1.阶段 5 course 服务边界落地
- 新增 cmd/course 独立进程入口，落地 services/course dao/rpc/sv
- 新增 gateway/client/course、shared/contracts/course 和 shared/ports course port
- 将 /api/v1/course/* HTTP 门面切到 course zrpc，gateway 只保留鉴权、限流、幂等、文件读取和响应透传
- 保留 course 迁移期直写 schedule_events / schedules 权限，维持课程导入两个表同事务写入语义
- 为 course parse-image 补 bytes RPC 契约和 gRPC 消息大小配置，兼容课表图片上传
- 补充 course.rpc 示例配置与阶段 5 文档基线、切流点、残留依赖和 smoke 记录

backend/gateway/api/course.go

@@ -2,57 +2,65 @@ package api
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"io"
 	"log"
 	"net/http"
 	"time"
 
-	"github.com/LoveLosita/smartflow/backend/model"
 	"github.com/LoveLosita/smartflow/backend/respond"
-	"github.com/LoveLosita/smartflow/backend/service"
+	coursecontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/course"
+	"github.com/LoveLosita/smartflow/backend/shared/ports"
 	"github.com/gin-gonic/gin"
 )
 
+const courseRequestTimeout = 10 * time.Second
+
 type CourseHandler struct {
-	service *service.CourseService
+	client ports.CourseCommandClient
 }
 
-func NewCourseHandler(service *service.CourseService) *CourseHandler {
-	return &CourseHandler{
-		service: service,
-	}
+func NewCourseHandler(client ports.CourseCommandClient) *CourseHandler {
+	return &CourseHandler{client: client}
+}
+
+type courseImportConflict interface {
+	ConflictsJSON() json.RawMessage
 }
 
 func (sa *CourseHandler) CheckUserCourse(c *gin.Context) {
-	var req model.UserCheckCourseRequest
+	var req coursecontracts.UserCheckCourseRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
 
-	if service.CheckSingleCourse(req) {
-		c.JSON(http.StatusOK, respond.Ok)
+	ctx, cancel := context.WithTimeout(c.Request.Context(), courseRequestTimeout)
+	defer cancel()
+	if err := sa.client.ValidateCourse(ctx, req); err != nil {
+		respond.DealWithError(c, err)
 		return
 	}
-	c.JSON(http.StatusBadRequest, respond.WrongCourseInfo)
+	c.JSON(http.StatusOK, respond.Ok)
 }
 
 func (sa *CourseHandler) AddUserCourses(c *gin.Context) {
-	var req model.UserImportCoursesRequest
+	var req coursecontracts.UserImportCoursesRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}
 
-	userID := c.GetInt("user_id")
-	ctx, cancel := context.WithTimeout(c.Request.Context(), 10*time.Second)
+	req.UserID = c.GetInt("user_id")
+	ctx, cancel := context.WithTimeout(c.Request.Context(), courseRequestTimeout)
 	defer cancel()
 
-	conflicts, err := sa.service.AddUserCourses(ctx, req, userID)
+	_, err := sa.client.ImportCourses(ctx, req)
 	if err != nil {
-		if errors.Is(err, respond.ScheduleConflict) {
-			c.JSON(http.StatusConflict, respond.RespWithData(respond.ScheduleConflict, conflicts))
+		var conflict courseImportConflict
+		if errors.As(err, &conflict) {
+			c.JSON(http.StatusConflict, respond.RespWithData(respond.ScheduleConflict, conflict.ConflictsJSON()))
 			return
 		}
 		respond.DealWithError(c, err)
@@ -107,33 +115,34 @@ func (sa *CourseHandler) ParseCourseTableImage(c *gin.Context) {
 	ctx, cancel := context.WithCancel(c.Request.Context())
 	defer cancel()
 
-	draft, err := sa.service.ParseCourseTableImage(ctx, model.CourseImageParseRequest{
+	rawDraft, err := sa.client.ParseCourseTableImage(ctx, coursecontracts.CourseImageParseRequest{
 		Filename:   fileHeader.Filename,
 		MIMEType:   fileHeader.Header.Get("Content-Type"),
 		ImageBytes: imageBytes,
 	})
 	if err != nil {
+		var resp respond.Response
 		switch {
-		case errors.Is(err, service.ErrCourseImageParserUnavailable):
+		case errors.As(err, &resp) && resp.Status == "50003":
 			log.Printf("[COURSE_PARSE][API] parser unavailable user=%d filename=%q", userID, fileHeader.Filename)
-			c.JSON(http.StatusServiceUnavailable, respond.Response{Status: "50003", Info: "course image parser is not configured"})
+			c.JSON(http.StatusServiceUnavailable, resp)
 			return
-		case errors.Is(err, service.ErrCourseImageTooLarge):
+		case errors.As(err, &resp) && resp.Status == "40064":
 			log.Printf("[COURSE_PARSE][API] file too large user=%d filename=%q bytes=%d", userID, fileHeader.Filename, len(imageBytes))
-			c.JSON(http.StatusBadRequest, respond.Response{Status: "40064", Info: "course image too large"})
+			c.JSON(http.StatusBadRequest, resp)
 			return
-		case errors.Is(err, service.ErrCourseImageUnsupportedMIME):
+		case errors.As(err, &resp) && resp.Status == "40065":
 			log.Printf(
 				"[COURSE_PARSE][API] unsupported mime user=%d filename=%q header_content_type=%q",
 				userID,
 				fileHeader.Filename,
 				fileHeader.Header.Get("Content-Type"),
 			)
-			c.JSON(http.StatusBadRequest, respond.Response{Status: "40065", Info: "unsupported course image format"})
+			c.JSON(http.StatusBadRequest, resp)
 			return
-		case errors.Is(err, service.ErrCourseImageEmpty):
+		case errors.As(err, &resp) && resp.Status == "40066":
 			log.Printf("[COURSE_PARSE][API] empty file user=%d filename=%q", userID, fileHeader.Filename)
-			c.JSON(http.StatusBadRequest, respond.Response{Status: "40066", Info: "course image is empty"})
+			c.JSON(http.StatusBadRequest, resp)
 			return
 		default:
 			log.Printf("[COURSE_PARSE][API] unexpected failure user=%d filename=%q err=%v", userID, fileHeader.Filename, err)
@@ -142,6 +151,13 @@ func (sa *CourseHandler) ParseCourseTableImage(c *gin.Context) {
 		}
 	}
 
+	var draft coursecontracts.CourseImageParseResponse
+	if err := json.Unmarshal(rawDraft, &draft); err != nil {
+		log.Printf("[COURSE_PARSE][API] decode response failed user=%d filename=%q err=%v", userID, fileHeader.Filename, err)
+		respond.DealWithError(c, err)
+		return
+	}
+
 	log.Printf(
 		"[COURSE_PARSE][API] request success user=%d filename=%q draft_status=%s rows=%d warnings=%d",
 		userID,

backend/gateway/client/course/client.go

@@ -0,0 +1,162 @@
+package course
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	coursepb "github.com/LoveLosita/smartflow/backend/services/course/rpc/pb"
+	coursecontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/course"
+	"github.com/zeromicro/go-zero/zrpc"
+	"google.golang.org/grpc"
+)
+
+const (
+	defaultEndpoint          = "127.0.0.1:9087"
+	defaultTimeout           = 10 * time.Second
+	defaultMaxRPCMessageSize = 8 * 1024 * 1024
+	rpcMessageSizePadding    = 1024 * 1024
+)
+
+type ClientConfig struct {
+	Endpoints     []string
+	Target        string
+	Timeout       time.Duration
+	MaxImageBytes int64
+}
+
+// Client 是 gateway 访问 course zrpc 的最小适配层。
+//
+// 职责边界：
+// 1. 只负责跨进程 gRPC 调用和 JSON/bytes 透传，不触碰 DAO；
+// 2. HTTP 入参仍由 gateway/api 做基础绑定，业务校验交给 course 服务；
+// 3. import 冲突通过 CourseImportConflictError 返回，让 HTTP 层保留 409 + conflicts 数据。
+type Client struct {
+	rpc coursepb.CourseClient
+}
+
+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}
+	}
+
+	maxMessageSize := normalizeMaxRPCMessageSize(cfg.MaxImageBytes)
+	zclient, err := zrpc.NewClient(zrpc.RpcClientConf{
+		Endpoints: endpoints,
+		Target:    target,
+		NonBlock:  true,
+		Timeout:   int64(timeout / time.Millisecond),
+	}, zrpc.WithDialOption(grpc.WithDefaultCallOptions(
+		grpc.MaxCallRecvMsgSize(maxMessageSize),
+		grpc.MaxCallSendMsgSize(maxMessageSize),
+	)))
+	if err != nil {
+		return nil, err
+	}
+	client := &Client{rpc: coursepb.NewCourseClient(zclient.Conn())}
+	if err := client.ping(timeout); err != nil {
+		return nil, err
+	}
+	return client, nil
+}
+
+func (c *Client) ValidateCourse(ctx context.Context, req coursecontracts.UserCheckCourseRequest) error {
+	_, err := c.callJSON(ctx, c.rpc.ValidateCourse, req)
+	return responseFromRPCError(err)
+}
+
+func (c *Client) ImportCourses(ctx context.Context, req coursecontracts.UserImportCoursesRequest) (json.RawMessage, error) {
+	resp, err := c.callJSON(ctx, c.rpc.ImportCourses, req)
+	raw, err := jsonFromResponse(resp, err)
+	if err != nil {
+		return nil, err
+	}
+	var result coursecontracts.ImportCoursesResult
+	if err := json.Unmarshal(raw, &result); err != nil {
+		return nil, err
+	}
+	if result.Conflict {
+		return nil, CourseImportConflictError{conflicts: result.Conflicts}
+	}
+	return raw, nil
+}
+
+func (c *Client) ParseCourseTableImage(ctx context.Context, req coursecontracts.CourseImageParseRequest) (json.RawMessage, error) {
+	resp, err := c.rpc.ParseCourseImage(ctx, &coursepb.CourseImageRequest{
+		Filename:   req.Filename,
+		MimeType:   req.MIMEType,
+		ImageBytes: req.ImageBytes,
+	})
+	return jsonFromResponse(resp, err)
+}
+
+func (c *Client) ensureReady() error {
+	if c == nil || c.rpc == nil {
+		return errors.New("course 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, &coursepb.StatusResponse{})
+	return responseFromRPCError(err)
+}
+
+func (c *Client) callJSON(ctx context.Context, fn func(context.Context, *coursepb.JSONRequest, ...grpc.CallOption) (*coursepb.JSONResponse, error), payload any) (*coursepb.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, &coursepb.JSONRequest{PayloadJson: raw})
+}
+
+func jsonFromResponse(resp *coursepb.JSONResponse, rpcErr error) (json.RawMessage, error) {
+	if rpcErr != nil {
+		return nil, responseFromRPCError(rpcErr)
+	}
+	if resp == nil {
+		return nil, errors.New("course 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
+}
+
+func normalizeMaxRPCMessageSize(maxImageBytes int64) int {
+	if maxImageBytes <= 0 {
+		return defaultMaxRPCMessageSize
+	}
+	size := maxImageBytes + rpcMessageSizePadding
+	if size < defaultMaxRPCMessageSize {
+		return defaultMaxRPCMessageSize
+	}
+	return int(size)
+}

backend/gateway/client/course/errors.go

@@ -0,0 +1,111 @@
+package course
+
+import (
+	"encoding/json"
+	"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"
+)
+
+// CourseImportConflictError 表示课程导入和已有非课程日程冲突。
+//
+// 职责边界：
+// 1. 只在 gateway 边缘层用于恢复旧 HTTP 409 + conflicts 响应；
+// 2. 不承载冲突计算逻辑，冲突详情由 course 服务生成；
+// 3. ConflictsJSON 返回原始 JSON，避免 gateway 复制 schedule 冲突 DTO。
+type CourseImportConflictError struct {
+	conflicts json.RawMessage
+}
+
+func (e CourseImportConflictError) Error() string {
+	return respond.ScheduleConflict.Info
+}
+
+func (e CourseImportConflictError) ConflictsJSON() json.RawMessage {
+	if len(e.conflicts) == 0 {
+		return json.RawMessage("[]")
+	}
+	return e.conflicts
+}
+
+// responseFromRPCError 负责把 course 的 gRPC 错误反解回项目内错误。
+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 = "course zrpc service internal error"
+		}
+		return wrapRPCError(errors.New(msg))
+	}
+
+	msg := strings.TrimSpace(st.Message())
+	if msg == "" {
+		msg = "course 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.WrongParamType.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("调用 course zrpc 服务失败: %w", err)
+}