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/services/course/rpc/course.proto

@@ -0,0 +1,29 @@
+syntax = "proto3";
+
+package smartflow.course;
+
+option go_package = "github.com/LoveLosita/smartflow/backend/services/course/rpc/pb";
+
+service Course {
+  rpc Ping(StatusResponse) returns (StatusResponse);
+  rpc ValidateCourse(JSONRequest) returns (JSONResponse);
+  rpc ImportCourses(JSONRequest) returns (JSONResponse);
+  rpc ParseCourseImage(CourseImageRequest) returns (JSONResponse);
+}
+
+message JSONRequest {
+  bytes payload_json = 1;
+}
+
+message JSONResponse {
+  bytes data_json = 1;
+}
+
+message CourseImageRequest {
+  string filename = 1;
+  string mime_type = 2;
+  bytes image_bytes = 3;
+}
+
+message StatusResponse {
+}

backend/services/course/rpc/errors.go

@@ -0,0 +1,84 @@
+package rpc
+
+import (
+	"errors"
+	"log"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/respond"
+	coursesv "github.com/LoveLosita/smartflow/backend/services/course/sv"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+const courseErrorDomain = "smartflow.course"
+
+// grpcErrorFromServiceError 负责把 course 内部错误转换为 gRPC status。
+//
+// 职责边界：
+// 1. respond.Response 保留项目内部 status/info，供 gateway 反解；
+// 2. 图片解析哨兵错误转换为历史 HTTP 兼容错误码；
+// 3. 未分类错误只暴露通用内部错误，详细信息留在服务日志。
+func grpcErrorFromServiceError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var resp respond.Response
+	if errors.As(err, &resp) {
+		return grpcErrorFromResponse(resp)
+	}
+	switch {
+	case errors.Is(err, coursesv.ErrCourseImageParserUnavailable):
+		return grpcErrorFromResponse(respond.Response{Status: "50003", Info: "course image parser is not configured"})
+	case errors.Is(err, coursesv.ErrCourseImageTooLarge):
+		return grpcErrorFromResponse(respond.Response{Status: "40064", Info: "course image too large"})
+	case errors.Is(err, coursesv.ErrCourseImageUnsupportedMIME):
+		return grpcErrorFromResponse(respond.Response{Status: "40065", Info: "unsupported course image format"})
+	case errors.Is(err, coursesv.ErrCourseImageEmpty):
+		return grpcErrorFromResponse(respond.Response{Status: "40066", Info: "course image is empty"})
+	}
+	log.Printf("course rpc internal error: %v", err)
+	return status.Error(codes.Internal, "course service internal error")
+}
+
+func grpcErrorFromResponse(resp respond.Response) error {
+	code := grpcCodeFromRespondStatus(resp.Status)
+	message := strings.TrimSpace(resp.Info)
+	if message == "" {
+		message = strings.TrimSpace(resp.Status)
+	}
+	st := status.New(code, message)
+	detail := &errdetails.ErrorInfo{
+		Domain: courseErrorDomain,
+		Reason: resp.Status,
+		Metadata: map[string]string{
+			"info": resp.Info,
+		},
+	}
+	withDetails, err := st.WithDetails(detail)
+	if err != nil {
+		return st.Err()
+	}
+	return withDetails.Err()
+}
+
+func grpcCodeFromRespondStatus(statusValue string) codes.Code {
+	switch strings.TrimSpace(statusValue) {
+	case respond.MissingToken.Status, respond.InvalidToken.Status, respond.InvalidClaims.Status,
+		respond.ErrUnauthorized.Status, respond.WrongTokenType.Status, respond.UserLoggedOut.Status:
+		return codes.Unauthenticated
+	case respond.CourseNotBelongToUser.Status:
+		return codes.PermissionDenied
+	case respond.MissingParam.Status, respond.WrongParamType.Status, respond.ParamTooLong.Status,
+		respond.WrongUserID.Status, respond.WrongCourseID.Status, respond.WrongCourseInfo.Status,
+		respond.InsertCourseTwice.Status, respond.ScheduleConflict.Status, respond.InvalidSectionNumber.Status,
+		respond.InvalidWeekOrDayOfWeek.Status, respond.InvalidSectionRange.Status,
+		respond.TimeOutOfRangeOfThisSemester.Status:
+		return codes.InvalidArgument
+	}
+	if strings.HasPrefix(strings.TrimSpace(statusValue), "5") {
+		return codes.Internal
+	}
+	return codes.InvalidArgument
+}

backend/services/course/rpc/handler.go

@@ -0,0 +1,141 @@
+package rpc
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+
+	"github.com/LoveLosita/smartflow/backend/model"
+	"github.com/LoveLosita/smartflow/backend/respond"
+	"github.com/LoveLosita/smartflow/backend/services/course/rpc/pb"
+	coursesv "github.com/LoveLosita/smartflow/backend/services/course/sv"
+	coursecontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/course"
+)
+
+type Handler struct {
+	pb.UnimplementedCourseServer
+	svc *coursesv.CourseService
+}
+
+func NewHandler(svc *coursesv.CourseService) *Handler {
+	return &Handler{svc: svc}
+}
+
+// Ping 供调用方在启动期确认 course zrpc 已可用。
+func (h *Handler) Ping(ctx context.Context, req *pb.StatusResponse) (*pb.StatusResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	return &pb.StatusResponse{}, nil
+}
+
+func (h *Handler) ValidateCourse(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq coursecontracts.UserCheckCourseRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	if !coursesv.CheckSingleCourse(toModelCheckCourseRequest(contractReq)) {
+		return nil, grpcErrorFromServiceError(respond.WrongCourseInfo)
+	}
+	return jsonResponse(nil, nil)
+}
+
+func (h *Handler) ImportCourses(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq coursecontracts.UserImportCoursesRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	conflicts, err := h.svc.AddUserCourses(ctx, toModelImportCoursesRequest(contractReq), contractReq.UserID)
+	if errors.Is(err, respond.ScheduleConflict) {
+		rawConflicts, marshalErr := json.Marshal(conflicts)
+		if marshalErr != nil {
+			return nil, grpcErrorFromServiceError(marshalErr)
+		}
+		return jsonResponse(coursecontracts.ImportCoursesResult{
+			Conflict:  true,
+			Conflicts: rawConflicts,
+		}, nil)
+	}
+	return jsonResponse(coursecontracts.ImportCoursesResult{Conflict: false}, err)
+}
+
+func (h *Handler) ParseCourseImage(ctx context.Context, req *pb.CourseImageRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	draft, err := h.svc.ParseCourseTableImage(ctx, model.CourseImageParseRequest{
+		Filename:   req.Filename,
+		MIMEType:   req.MimeType,
+		ImageBytes: req.ImageBytes,
+	})
+	return jsonResponse(draft, err)
+}
+
+func (h *Handler) ensureReady(req any) error {
+	if h == nil || h.svc == nil {
+		return grpcErrorFromServiceError(errors.New("course service dependency not initialized"))
+	}
+	if req == nil {
+		return grpcErrorFromServiceError(respond.MissingParam)
+	}
+	return nil
+}
+
+func jsonResponse(value any, err error) (*pb.JSONResponse, error) {
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.JSONResponse{DataJson: raw}, nil
+}
+
+func toModelImportCoursesRequest(req coursecontracts.UserImportCoursesRequest) model.UserImportCoursesRequest {
+	courses := make([]model.UserCheckCourseRequest, 0, len(req.Courses))
+	for _, course := range req.Courses {
+		courses = append(courses, toModelCheckCourseRequest(course))
+	}
+	return model.UserImportCoursesRequest{Courses: courses}
+}
+
+func toModelCheckCourseRequest(req coursecontracts.UserCheckCourseRequest) model.UserCheckCourseRequest {
+	arrangements := make([]struct {
+		StartWeek    int    `json:"start_week"`
+		EndWeek      int    `json:"end_week"`
+		DayOfWeek    int    `json:"day_of_week"`
+		StartSection int    `json:"start_section"`
+		EndSection   int    `json:"end_section"`
+		WeekType     string `json:"week_type"`
+	}, 0, len(req.Arrangements))
+	for _, arrangement := range req.Arrangements {
+		arrangements = append(arrangements, struct {
+			StartWeek    int    `json:"start_week"`
+			EndWeek      int    `json:"end_week"`
+			DayOfWeek    int    `json:"day_of_week"`
+			StartSection int    `json:"start_section"`
+			EndSection   int    `json:"end_section"`
+			WeekType     string `json:"week_type"`
+		}{
+			StartWeek:    arrangement.StartWeek,
+			EndWeek:      arrangement.EndWeek,
+			DayOfWeek:    arrangement.DayOfWeek,
+			StartSection: arrangement.StartSection,
+			EndSection:   arrangement.EndSection,
+			WeekType:     arrangement.WeekType,
+		})
+	}
+	return model.UserCheckCourseRequest{
+		CourseName:   req.CourseName,
+		Location:     req.Location,
+		IsAllowTasks: req.IsAllowTasks,
+		Arrangements: arrangements,
+	}
+}

backend/services/course/rpc/pb/course.pb.go

@@ -0,0 +1,52 @@
+package pb
+
+import proto "github.com/golang/protobuf/proto"
+
+var _ = proto.Marshal
+
+const _ = proto.ProtoPackageIsVersion3
+
+type JSONRequest struct {
+	PayloadJson          []byte   `protobuf:"bytes,1,opt,name=payload_json,json=payloadJson,proto3" json:"payload_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *JSONRequest) Reset()         { *m = JSONRequest{} }
+func (m *JSONRequest) String() string { return proto.CompactTextString(m) }
+func (*JSONRequest) ProtoMessage()    {}
+
+type JSONResponse struct {
+	DataJson             []byte   `protobuf:"bytes,1,opt,name=data_json,json=dataJson,proto3" json:"data_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *JSONResponse) Reset()         { *m = JSONResponse{} }
+func (m *JSONResponse) String() string { return proto.CompactTextString(m) }
+func (*JSONResponse) ProtoMessage()    {}
+
+type CourseImageRequest struct {
+	Filename             string   `protobuf:"bytes,1,opt,name=filename,proto3" json:"filename,omitempty"`
+	MimeType             string   `protobuf:"bytes,2,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"`
+	ImageBytes           []byte   `protobuf:"bytes,3,opt,name=image_bytes,json=imageBytes,proto3" json:"image_bytes,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *CourseImageRequest) Reset()         { *m = CourseImageRequest{} }
+func (m *CourseImageRequest) String() string { return proto.CompactTextString(m) }
+func (*CourseImageRequest) ProtoMessage()    {}
+
+type StatusResponse struct {
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *StatusResponse) Reset()         { *m = StatusResponse{} }
+func (m *StatusResponse) String() string { return proto.CompactTextString(m) }
+func (*StatusResponse) ProtoMessage()    {}

backend/services/course/rpc/pb/course_grpc.pb.go

@@ -0,0 +1,141 @@
+package pb
+
+import (
+	context "context"
+
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+const (
+	Course_Ping_FullMethodName             = "/smartflow.course.Course/Ping"
+	Course_ValidateCourse_FullMethodName   = "/smartflow.course.Course/ValidateCourse"
+	Course_ImportCourses_FullMethodName    = "/smartflow.course.Course/ImportCourses"
+	Course_ParseCourseImage_FullMethodName = "/smartflow.course.Course/ParseCourseImage"
+)
+
+type CourseClient interface {
+	Ping(ctx context.Context, in *StatusResponse, opts ...grpc.CallOption) (*StatusResponse, error)
+	ValidateCourse(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	ImportCourses(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	ParseCourseImage(ctx context.Context, in *CourseImageRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+}
+
+type courseClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewCourseClient(cc grpc.ClientConnInterface) CourseClient {
+	return &courseClient{cc}
+}
+
+func (c *courseClient) Ping(ctx context.Context, in *StatusResponse, opts ...grpc.CallOption) (*StatusResponse, error) {
+	out := new(StatusResponse)
+	err := c.cc.Invoke(ctx, Course_Ping_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *courseClient) ValidateCourse(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Course_ValidateCourse_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *courseClient) ImportCourses(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Course_ImportCourses_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *courseClient) ParseCourseImage(ctx context.Context, in *CourseImageRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Course_ParseCourseImage_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+type CourseServer interface {
+	Ping(context.Context, *StatusResponse) (*StatusResponse, error)
+	ValidateCourse(context.Context, *JSONRequest) (*JSONResponse, error)
+	ImportCourses(context.Context, *JSONRequest) (*JSONResponse, error)
+	ParseCourseImage(context.Context, *CourseImageRequest) (*JSONResponse, error)
+}
+
+type UnimplementedCourseServer struct{}
+
+func (UnimplementedCourseServer) Ping(context.Context, *StatusResponse) (*StatusResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Ping not implemented")
+}
+func (UnimplementedCourseServer) ValidateCourse(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ValidateCourse not implemented")
+}
+func (UnimplementedCourseServer) ImportCourses(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ImportCourses not implemented")
+}
+func (UnimplementedCourseServer) ParseCourseImage(context.Context, *CourseImageRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ParseCourseImage not implemented")
+}
+
+func RegisterCourseServer(s grpc.ServiceRegistrar, srv CourseServer) {
+	s.RegisterService(&Course_ServiceDesc, srv)
+}
+
+func _Course_Ping_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(StatusResponse)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(CourseServer).Ping(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Course_Ping_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(CourseServer).Ping(ctx, req.(*StatusResponse))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Course_JSON_Handler(fullMethod string, invoke func(CourseServer, context.Context, *JSONRequest) (*JSONResponse, error)) grpc.MethodHandler {
+	return func(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+		in := new(JSONRequest)
+		if err := dec(in); err != nil {
+			return nil, err
+		}
+		if interceptor == nil {
+			return invoke(srv.(CourseServer), ctx, in)
+		}
+		info := &grpc.UnaryServerInfo{Server: srv, FullMethod: fullMethod}
+		handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+			return invoke(srv.(CourseServer), ctx, req.(*JSONRequest))
+		}
+		return interceptor(ctx, in, info, handler)
+	}
+}
+
+func _Course_ParseCourseImage_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(CourseImageRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(CourseServer).ParseCourseImage(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Course_ParseCourseImage_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(CourseServer).ParseCourseImage(ctx, req.(*CourseImageRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+var Course_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "smartflow.course.Course",
+	HandlerType: (*CourseServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{MethodName: "Ping", Handler: _Course_Ping_Handler},
+		{MethodName: "ValidateCourse", Handler: _Course_JSON_Handler(Course_ValidateCourse_FullMethodName, CourseServer.ValidateCourse)},
+		{MethodName: "ImportCourses", Handler: _Course_JSON_Handler(Course_ImportCourses_FullMethodName, CourseServer.ImportCourses)},
+		{MethodName: "ParseCourseImage", Handler: _Course_ParseCourseImage_Handler},
+	},
+	Streams:  []grpc.StreamDesc{},
+	Metadata: "course.proto",
+}

backend/services/course/rpc/server.go

@@ -0,0 +1,77 @@
+package rpc
+
+import (
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/services/course/rpc/pb"
+	coursesv "github.com/LoveLosita/smartflow/backend/services/course/sv"
+	"github.com/zeromicro/go-zero/core/service"
+	"github.com/zeromicro/go-zero/zrpc"
+	"google.golang.org/grpc"
+)
+
+const (
+	defaultListenOn          = "0.0.0.0:9087"
+	defaultTimeout           = 10 * time.Second
+	defaultMaxRPCMessageSize = 8 * 1024 * 1024
+	rpcMessageSizePadding    = 1024 * 1024
+)
+
+type ServerOptions struct {
+	ListenOn      string
+	Timeout       time.Duration
+	MaxImageBytes int64
+	Service       *coursesv.CourseService
+}
+
+// NewServer 创建 course zrpc 服务端。
+//
+// 职责边界：
+// 1. 只负责 zrpc server 配置与 gRPC handler 注册；
+// 2. 不创建数据库、模型客户端或业务服务，它们由 cmd/course 管理；
+// 3. 图片解析走 bytes 请求，需按 maxImageBytes 抬高 gRPC 消息上限。
+func NewServer(opts ServerOptions) (*zrpc.RpcServer, string, error) {
+	if opts.Service == nil {
+		return nil, "", errors.New("course service dependency not initialized")
+	}
+
+	listenOn := strings.TrimSpace(opts.ListenOn)
+	if listenOn == "" {
+		listenOn = defaultListenOn
+	}
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = defaultTimeout
+	}
+
+	server, err := zrpc.NewServer(zrpc.RpcServerConf{
+		ServiceConf: service.ServiceConf{
+			Name: "course.rpc",
+			Mode: service.DevMode,
+		},
+		ListenOn: listenOn,
+		Timeout:  int64(timeout / time.Millisecond),
+	}, func(grpcServer *grpc.Server) {
+		pb.RegisterCourseServer(grpcServer, NewHandler(opts.Service))
+	})
+	if err != nil {
+		return nil, "", err
+	}
+
+	maxMessageSize := normalizeMaxRPCMessageSize(opts.MaxImageBytes)
+	server.AddOptions(grpc.MaxRecvMsgSize(maxMessageSize), grpc.MaxSendMsgSize(maxMessageSize))
+	return server, listenOn, nil
+}
+
+func normalizeMaxRPCMessageSize(maxImageBytes int64) int {
+	if maxImageBytes <= 0 {
+		return defaultMaxRPCMessageSize
+	}
+	size := maxImageBytes + rpcMessageSizePadding
+	if size < defaultMaxRPCMessageSize {
+		return defaultMaxRPCMessageSize
+	}
+	return int(size)
+}