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/dao/connect.go

@@ -0,0 +1,52 @@
+package dao
+
+import (
+	"fmt"
+
+	"github.com/spf13/viper"
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+)
+
+// OpenDBFromConfig 创建 course 服务自己的数据库句柄。
+//
+// 职责边界：
+// 1. course 当前没有独立课程写模型表，导入链路迁移期仍写 schedule_events / schedules；
+// 2. 本函数不 AutoMigrate schedule 表，避免 course 进程越权管理 schedule schema；
+// 3. 启动期只检查运行时依赖表是否存在，缺表时尽早失败。
+func OpenDBFromConfig() (*gorm.DB, error) {
+	host := viper.GetString("database.host")
+	port := viper.GetString("database.port")
+	user := viper.GetString("database.user")
+	password := viper.GetString("database.password")
+	dbname := viper.GetString("database.dbname")
+
+	dsn := fmt.Sprintf(
+		"%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
+		user, password, host, port, dbname,
+	)
+
+	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
+	if err != nil {
+		return nil, err
+	}
+	if err = ensureRuntimeDependencyTables(db); err != nil {
+		return nil, err
+	}
+	return db, nil
+}
+
+// ensureRuntimeDependencyTables 显式检查 course 导入链路迁移期仍直写的 schedule 表。
+//
+// 说明：
+// 1. schedule_events / schedules 属于 schedule 服务正式日程域；
+// 2. 本轮保留 course 直写权限，用来维持课程导入两个表同事务写入；
+// 3. 后续若改为 schedule RPC bridge，应先补课程导入幂等与冲突返回契约，再移除这里的依赖检查。
+func ensureRuntimeDependencyTables(db *gorm.DB) error {
+	for _, table := range []string{"schedule_events", "schedules"} {
+		if !db.Migrator().HasTable(table) {
+			return fmt.Errorf("course runtime dependency table missing: %s", table)
+		}
+	}
+	return nil
+}

backend/services/course/dao/course.go

@@ -0,0 +1,50 @@
+package dao
+
+import (
+	"context"
+
+	"github.com/LoveLosita/smartflow/backend/model"
+	"gorm.io/gorm"
+)
+
+type CourseDAO struct {
+	db *gorm.DB
+}
+
+// NewCourseDAO 创建ScheduleDAO实例
+func NewCourseDAO(db *gorm.DB) *CourseDAO {
+	return &CourseDAO{
+		db: db,
+	}
+}
+
+func (r *CourseDAO) WithTx(tx *gorm.DB) *CourseDAO {
+	return &CourseDAO{db: tx}
+}
+
+func (r *CourseDAO) AddUserCoursesIntoSchedule(ctx context.Context, courses []model.Schedule) error {
+	if err := r.db.WithContext(ctx).Create(&courses).Error; err != nil {
+		return err
+	}
+	return nil
+}
+
+func (r *CourseDAO) AddUserCoursesIntoScheduleEvents(ctx context.Context, events []model.ScheduleEvent) ([]int, error) {
+	if err := r.db.WithContext(ctx).Create(&events).Error; err != nil {
+		return nil, err
+	}
+	ids := make([]int, 0, len(events))
+	for i := range events {
+		ids = append(ids, events[i].ID)
+	}
+	return ids, nil
+}
+
+// Transaction 在同一个数据库事务中执行传入的函数，供 service 层复用（自动提交/回滚）
+// 规则：fn 返回 nil \-\> 提交；fn 返回 error 或发生 panic \-\> 回滚
+// 说明：gorm\.\(\\\*DB\)\.Transaction 会在 fn 返回 error 时回滚，并在发生 panic 时自动回滚后继续向上抛出 panic
+func (r *CourseDAO) Transaction(fn func(txDAO *CourseDAO) error) error {
+	return r.db.Transaction(func(tx *gorm.DB) error {
+		return fn(NewCourseDAO(tx))
+	})
+}

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)
+}

backend/services/course/sv/course.go

@@ -0,0 +1,165 @@
+package sv
+
+import (
+	"context"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/conv"
+	rootdao "github.com/LoveLosita/smartflow/backend/dao"
+	"github.com/LoveLosita/smartflow/backend/model"
+	"github.com/LoveLosita/smartflow/backend/respond"
+	coursedao "github.com/LoveLosita/smartflow/backend/services/course/dao"
+	llmservice "github.com/LoveLosita/smartflow/backend/services/llm"
+)
+
+type CourseService struct {
+	// 伸出手：准备接住 DAO
+	courseDAO                  *coursedao.CourseDAO
+	scheduleDAO                *rootdao.ScheduleDAO
+	courseImageResponsesClient *llmservice.ArkResponsesClient
+	courseImageConfig          CourseImageParseConfig
+	courseImageModel           string
+}
+
+// NewCourseService 创建 CourseService 实例
+func NewCourseService(
+	courseDAO *coursedao.CourseDAO,
+	scheduleDAO *rootdao.ScheduleDAO,
+	courseImageResponsesClient *llmservice.ArkResponsesClient,
+	courseImageConfig CourseImageParseConfig,
+	courseImageModel string,
+) *CourseService {
+	return &CourseService{
+		courseDAO:                  courseDAO,
+		scheduleDAO:                scheduleDAO,
+		courseImageResponsesClient: courseImageResponsesClient,
+		courseImageConfig:          courseImageConfig,
+		courseImageModel:           strings.TrimSpace(courseImageModel),
+	}
+}
+
+func isUniqueViolation(err error) bool {
+	if err == nil {
+		return false
+	}
+	// 兼容常见 MySQL / PostgreSQL / SQLite 的报错关键字
+	// 也可以进一步精确到你的索引名 idx_user_slot_atomic
+	msg := strings.ToLower(err.Error())
+	if strings.Contains(msg, "duplicate entry") ||
+		strings.Contains(msg, "unique constraint") ||
+		strings.Contains(msg, "unique violation") ||
+		strings.Contains(msg, "duplicate key") {
+		return true
+	}
+	return false
+}
+
+func CheckSingleCourse(req model.UserCheckCourseRequest) bool {
+	for _, arrangement := range req.Arrangements {
+		if arrangement.StartWeek > arrangement.EndWeek ||
+			arrangement.DayOfWeek < 1 || arrangement.DayOfWeek > 7 ||
+			arrangement.StartSection < 1 || arrangement.EndSection < arrangement.StartSection ||
+			arrangement.EndSection > 12 || arrangement.StartWeek < 1 || arrangement.EndWeek > 24 {
+			return false
+		}
+	}
+	return true
+}
+
+// AddUserCourses 添加用户课程表
+func (ss *CourseService) AddUserCourses(ctx context.Context, req model.UserImportCoursesRequest, userID int) ([]model.ScheduleConflictDetail, error) {
+	//1.先校验参数是否正确
+	for _, course := range req.Courses {
+		result := CheckSingleCourse(course)
+		if !result {
+			return nil, respond.WrongCourseInfo
+		}
+	}
+	//2.将前端传来的课程信息转换为 Schedule 和 ScheduleEvent 切片
+	var finalSchedules []model.Schedule
+	var finalScheduleEvents []model.ScheduleEvent
+	var pos []int
+	for _, course := range req.Courses {
+		// 避免取 range 迭代变量字段地址导致指针复用问题
+		location := course.Location
+		for _, arrangement := range course.Arrangements {
+			weekType := arrangement.WeekType
+			for week := arrangement.StartWeek; week <= arrangement.EndWeek; week++ {
+				if weekType == "odd" && week%2 == 0 {
+					continue
+				}
+				if weekType == "even" && week%2 != 0 {
+					continue
+				}
+				//2.转换为 Schedule_event 切片
+				st, ed, err := conv.RelativeTimeToRealTime(week, arrangement.DayOfWeek, arrangement.StartSection, arrangement.EndSection)
+				if err != nil {
+					return nil, err
+				}
+				scheduleEvent := model.ScheduleEvent{
+					UserID:        userID,
+					Name:          course.CourseName,
+					Location:      &location,
+					Type:          "course",
+					RelID:         nil,
+					CanBeEmbedded: course.IsAllowTasks,
+					StartTime:     st,
+					EndTime:       ed,
+				}
+				finalScheduleEvents = append(finalScheduleEvents, scheduleEvent)
+				//3.转换为 Schedule 切片
+				for section := arrangement.StartSection; section <= arrangement.EndSection; section++ {
+					schedule := model.Schedule{
+						Week:      week,
+						DayOfWeek: arrangement.DayOfWeek,
+						Section:   section,
+						Status:    "normal",
+						UserID:    userID,
+						EventID:   0,
+					}
+					finalSchedules = append(finalSchedules, schedule)
+					pos = append(pos, len(finalScheduleEvents)-1)
+				}
+			}
+		}
+	}
+	//3.先检测是否重复插入了课程（同一周、同一天、同一节已有课程）
+	exists, err := ss.scheduleDAO.CheckScheduleConflict(ctx, finalSchedules)
+	if err != nil {
+		return nil, err
+	}
+	if exists {
+		return nil, respond.InsertCourseTwice
+	}
+	//4.再检查是否和某些非课程的日程冲突（同一周、同一天、同一节已有非课程日程），并给出具体的冲突信息
+	conflicts, err := ss.scheduleDAO.GetNonCourseScheduleConflicts(ctx, finalSchedules)
+	if err != nil {
+		return nil, err
+	}
+	if len(conflicts) > 0 {
+		ret := conv.SchedulesToScheduleConflictDetail(conflicts)
+		return ret, respond.ScheduleConflict
+	}
+	//5.事务：插入两个表要么都成功，要么都回滚
+	err = ss.courseDAO.Transaction(func(txDAO *coursedao.CourseDAO) error {
+		ids, err := txDAO.AddUserCoursesIntoScheduleEvents(ctx, finalScheduleEvents)
+		if err != nil {
+			return err
+		}
+		// 将生成的 ScheduleEvent ID 赋值给对应的 Schedule 的 EventID 字段
+		for i := range finalSchedules {
+			finalSchedules[i].EventID = ids[pos[i]]
+		}
+		if err := txDAO.AddUserCoursesIntoSchedule(ctx, finalSchedules); err != nil {
+			return err
+		}
+		return nil
+	})
+	if err != nil {
+		if isUniqueViolation(err) {
+			return nil, respond.InsertCourseTwice
+		}
+		return nil, err
+	}
+	return nil, nil
+}

backend/services/course/sv/course_parse.go

@@ -0,0 +1,295 @@
+package sv
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/model"
+)
+
+const (
+	defaultCourseImageMaxBytes  = 5 * 1024 * 1024
+	defaultCourseImageMaxTokens = 16384
+	maxCourseImageDraftRows     = 256
+	courseImageParseTemperature = 0.1
+)
+
+var (
+	ErrCourseImageParserUnavailable = errors.New("course image parser is not configured")
+	ErrCourseImageTooLarge          = errors.New("course image is too large")
+	ErrCourseImageUnsupportedMIME   = errors.New("course image mime type is not supported")
+	ErrCourseImageEmpty             = errors.New("course image is empty")
+)
+
+type CourseImageParseConfig struct {
+	MaxImageBytes int64
+	MaxTokens     int
+}
+
+func NewCourseImageParseConfig(maxImageBytes int64, maxTokens int) CourseImageParseConfig {
+	if maxImageBytes <= 0 {
+		maxImageBytes = defaultCourseImageMaxBytes
+	}
+	if maxTokens <= 0 {
+		maxTokens = defaultCourseImageMaxTokens
+	}
+	return CourseImageParseConfig{
+		MaxImageBytes: maxImageBytes,
+		MaxTokens:     maxTokens,
+	}
+}
+
+func normalizeCourseImageParseRequest(req model.CourseImageParseRequest, cfg CourseImageParseConfig) (*model.CourseImageParseRequest, error) {
+	req.Filename = strings.TrimSpace(req.Filename)
+	req.MIMEType = strings.TrimSpace(strings.ToLower(req.MIMEType))
+	if len(req.ImageBytes) == 0 {
+		return nil, ErrCourseImageEmpty
+	}
+	if int64(len(req.ImageBytes)) > cfg.MaxImageBytes {
+		return nil, ErrCourseImageTooLarge
+	}
+
+	detected := strings.ToLower(strings.TrimSpace(http.DetectContentType(req.ImageBytes)))
+	if req.MIMEType == "" || req.MIMEType == "application/octet-stream" {
+		req.MIMEType = detected
+	}
+	if !isSupportedCourseImageMIME(req.MIMEType) {
+		if isSupportedCourseImageMIME(detected) {
+			req.MIMEType = detected
+		} else {
+			return nil, ErrCourseImageUnsupportedMIME
+		}
+	}
+
+	if req.Filename == "" {
+		req.Filename = "course-table"
+	}
+	return &req, nil
+}
+
+func isSupportedCourseImageMIME(mimeType string) bool {
+	switch strings.TrimSpace(strings.ToLower(mimeType)) {
+	case "image/jpeg", "image/png", "image/webp":
+		return true
+	default:
+		return false
+	}
+}
+
+func normalizeCourseImageParseResponse(resp *model.CourseImageParseResponse) (*model.CourseImageParseResponse, error) {
+	if resp == nil {
+		return nil, errors.New("course image parse response is nil")
+	}
+
+	resp.DraftStatus = model.CourseImageParseDraftStatus(strings.ToLower(strings.TrimSpace(string(resp.DraftStatus))))
+	resp.Message = strings.TrimSpace(resp.Message)
+	resp.Warnings = normalizeWarningList(resp.Warnings)
+	resp.Rows = normalizeCourseImageParseRows(resp.Rows, &resp.Warnings)
+
+	switch resp.DraftStatus {
+	case model.CourseImageParseDraftStatusSuccess:
+		if len(resp.Rows) == 0 {
+			return nil, errors.New("course image parse response has no rows in success status")
+		}
+		for idx := range resp.Rows {
+			if err := validateCourseImageParseRow(&resp.Rows[idx], true); err != nil {
+				return nil, fmt.Errorf("course image parse success row %d invalid: %w", idx+1, err)
+			}
+		}
+	case model.CourseImageParseDraftStatusPartial:
+		if len(resp.Rows) == 0 {
+			return nil, errors.New("course image parse response has no rows in partial status")
+		}
+		for idx := range resp.Rows {
+			if err := validateCourseImageParseRow(&resp.Rows[idx], false); err != nil {
+				return nil, fmt.Errorf("course image parse partial row %d invalid: %w", idx+1, err)
+			}
+		}
+	case model.CourseImageParseDraftStatusReject:
+		resp.Rows = make([]model.CourseImageParseRow, 0)
+	default:
+		return nil, fmt.Errorf("unsupported draft_status: %s", resp.DraftStatus)
+	}
+
+	if resp.Message == "" {
+		resp.Message = defaultCourseImageParseMessage(resp.DraftStatus, len(resp.Rows))
+	}
+	return resp, nil
+}
+
+func normalizeCourseImageParseRows(rows []model.CourseImageParseRow, warnings *[]string) []model.CourseImageParseRow {
+	if len(rows) == 0 {
+		return make([]model.CourseImageParseRow, 0)
+	}
+	if len(rows) > maxCourseImageDraftRows {
+		rows = rows[:maxCourseImageDraftRows]
+		appendUniqueWarning(warnings, "识别结果行数超过上限，后端已截断为 256 行，请重点核对。")
+	}
+
+	normalized := make([]model.CourseImageParseRow, 0, len(rows))
+	for idx := range rows {
+		row := rows[idx]
+		row.RowID = strings.TrimSpace(row.RowID)
+		if row.RowID == "" {
+			row.RowID = fmt.Sprintf("row_%03d", idx+1)
+		}
+		row.CourseName = strings.TrimSpace(row.CourseName)
+		row.Location = strings.TrimSpace(row.Location)
+		row.WeekType = normalizeCourseImageWeekType(row.WeekType)
+		row.RawText = strings.TrimSpace(row.RawText)
+		row.RowWarnings = normalizeWarningList(row.RowWarnings)
+		normalizeOptionalPositiveInt(&row.StartWeek)
+		normalizeOptionalPositiveInt(&row.EndWeek)
+		normalizeOptionalPositiveInt(&row.DayOfWeek)
+		normalizeOptionalPositiveInt(&row.StartSection)
+		normalizeOptionalPositiveInt(&row.EndSection)
+		if row.Confidence < 0 {
+			row.Confidence = 0
+		}
+		if row.Confidence > 1 {
+			row.Confidence = 1
+		}
+		if row.CourseName == "" &&
+			row.StartWeek == nil &&
+			row.EndWeek == nil &&
+			row.DayOfWeek == nil &&
+			row.StartSection == nil &&
+			row.EndSection == nil &&
+			row.RawText == "" {
+			appendUniqueWarning(warnings, fmt.Sprintf("存在空白草稿行，后端已自动忽略：%s", row.RowID))
+			continue
+		}
+		normalized = append(normalized, row)
+	}
+
+	return normalized
+}
+
+func validateCourseImageParseRow(row *model.CourseImageParseRow, strict bool) error {
+	if row == nil {
+		return errors.New("row is nil")
+	}
+	if strict && row.CourseName == "" {
+		return errors.New("course_name is empty")
+	}
+	if strict && row.WeekType == "" {
+		return errors.New("week_type is empty")
+	}
+	if row.WeekType != "" && row.WeekType != "all" && row.WeekType != "odd" && row.WeekType != "even" {
+		return fmt.Errorf("week_type is invalid: %s", row.WeekType)
+	}
+
+	if err := validateOptionalCourseIntPair(row.StartWeek, row.EndWeek, 1, 24, "week", strict); err != nil {
+		return err
+	}
+	if err := validateOptionalCourseIntPair(row.StartSection, row.EndSection, 1, 12, "section", strict); err != nil {
+		return err
+	}
+	if strict && row.DayOfWeek == nil {
+		return errors.New("day_of_week is empty")
+	}
+	if row.DayOfWeek != nil && (*row.DayOfWeek < 1 || *row.DayOfWeek > 7) {
+		return fmt.Errorf("day_of_week out of range: %d", *row.DayOfWeek)
+	}
+	return nil
+}
+
+func validateOptionalCourseIntPair(start *int, end *int, min int, max int, field string, strict bool) error {
+	if strict {
+		if start == nil || end == nil {
+			return fmt.Errorf("%s range is incomplete", field)
+		}
+	}
+	if start == nil && end == nil {
+		return nil
+	}
+	if start == nil || end == nil {
+		return fmt.Errorf("%s range is incomplete", field)
+	}
+	if *start < min || *start > max {
+		return fmt.Errorf("%s start out of range: %d", field, *start)
+	}
+	if *end < min || *end > max {
+		return fmt.Errorf("%s end out of range: %d", field, *end)
+	}
+	if *start > *end {
+		return fmt.Errorf("%s start is greater than end: %d > %d", field, *start, *end)
+	}
+	return nil
+}
+
+func normalizeOptionalPositiveInt(target **int) {
+	if target == nil || *target == nil {
+		return
+	}
+	if **target <= 0 {
+		*target = nil
+	}
+}
+
+func normalizeCourseImageWeekType(raw string) string {
+	normalized := strings.ToLower(strings.TrimSpace(raw))
+	switch normalized {
+	case "", "unknown", "null":
+		return ""
+	case "all", "every", "weekly", "each week", "每周", "全周", "全部":
+		return "all"
+	case "odd", "single", "单", "单周":
+		return "odd"
+	case "even", "double", "双", "双周":
+		return "even"
+	default:
+		return normalized
+	}
+}
+
+func normalizeWarningList(items []string) []string {
+	if len(items) == 0 {
+		return make([]string, 0)
+	}
+	seen := make(map[string]struct{}, len(items))
+	result := make([]string, 0, len(items))
+	for _, item := range items {
+		trimmed := strings.TrimSpace(item)
+		if trimmed == "" {
+			continue
+		}
+		if _, ok := seen[trimmed]; ok {
+			continue
+		}
+		seen[trimmed] = struct{}{}
+		result = append(result, trimmed)
+	}
+	return result
+}
+
+func appendUniqueWarning(target *[]string, warningText string) {
+	if target == nil {
+		return
+	}
+	trimmed := strings.TrimSpace(warningText)
+	if trimmed == "" {
+		return
+	}
+	for _, existing := range *target {
+		if strings.TrimSpace(existing) == trimmed {
+			return
+		}
+	}
+	*target = append(*target, trimmed)
+}
+
+func defaultCourseImageParseMessage(status model.CourseImageParseDraftStatus, rowCount int) string {
+	switch status {
+	case model.CourseImageParseDraftStatusSuccess:
+		return fmt.Sprintf("已识别 %d 条课程安排，请重点核对周次、星期和节次。", rowCount)
+	case model.CourseImageParseDraftStatusPartial:
+		return fmt.Sprintf("已识别 %d 条课程安排，但仍存在不确定字段，请结合 warning 逐项核对。", rowCount)
+	case model.CourseImageParseDraftStatusReject:
+		return "图片信息不足，建议重新上传完整、清晰、包含表头和节次栏的总课表截图。"
+	default:
+		return "课程表图片识别已完成，请人工核对后再导入。"
+	}
+}

backend/services/course/sv/course_parse_ark.go

@@ -0,0 +1,228 @@
+package sv
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"log"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/model"
+	llmservice "github.com/LoveLosita/smartflow/backend/services/llm"
+)
+
+// ParseCourseTableImage 使用 Ark SDK Responses 解析课程表图片。
+func (ss *CourseService) ParseCourseTableImage(ctx context.Context, req model.CourseImageParseRequest) (*model.CourseImageParseResponse, error) {
+	if ss == nil || ss.courseImageResponsesClient == nil {
+		modelName := ""
+		if ss != nil {
+			modelName = ss.courseImageModel
+		}
+		log.Printf(
+			"[COURSE_PARSE][SERVICE] parser unavailable model_name=%q filename=%q mime=%q bytes=%d",
+			modelName,
+			req.Filename,
+			req.MIMEType,
+			len(req.ImageBytes),
+		)
+		return nil, ErrCourseImageParserUnavailable
+	}
+
+	normalizedReq, err := normalizeCourseImageParseRequest(req, ss.courseImageConfig)
+	if err != nil {
+		log.Printf(
+			"[COURSE_PARSE][SERVICE] request normalization failed filename=%q mime=%q bytes=%d err=%v",
+			req.Filename,
+			req.MIMEType,
+			len(req.ImageBytes),
+			err,
+		)
+		return nil, err
+	}
+
+	log.Printf(
+		"[COURSE_PARSE][SERVICE] normalized request model_name=%q filename=%q mime=%q bytes=%d max_bytes=%d",
+		ss.courseImageModel,
+		normalizedReq.Filename,
+		normalizedReq.MIMEType,
+		len(normalizedReq.ImageBytes),
+		ss.courseImageConfig.MaxImageBytes,
+	)
+
+	messages, base64Chars, promptChars := buildCourseImageParseResponsesMessages(normalizedReq)
+	startAt := time.Now()
+	log.Printf(
+		"[COURSE_PARSE][SERVICE] model invoke start model_name=%q filename=%q mime=%q message_count=%d base64_chars=%d prompt_chars=%d payload_chars_estimate=%d thinking=%s temperature=%.2f max_output_tokens=%d text_format=%s",
+		ss.courseImageModel,
+		normalizedReq.Filename,
+		normalizedReq.MIMEType,
+		len(messages),
+		base64Chars,
+		promptChars,
+		base64Chars+promptChars+len(strings.TrimSpace(courseImageParseSystemPrompt)),
+		llmservice.ThinkingModeDisabled,
+		courseImageParseTemperature,
+		ss.courseImageConfig.MaxTokens,
+		"json_object",
+	)
+
+	// 1. 课程表图片识别输出体量大，显式透传 max_output_tokens，避免被默认值截断。
+	// 2. text_format 固定为 json_object，降低输出混入解释文本导致解析失败的概率。
+	// 3. thinking 显式关闭，优先保证课程导入链路稳定性。
+	draft, rawResult, err := llmservice.GenerateArkResponsesJSON[model.CourseImageParseResponse](ctx, ss.courseImageResponsesClient, messages, llmservice.ArkResponsesOptions{
+		Temperature:     courseImageParseTemperature,
+		MaxOutputTokens: ss.courseImageConfig.MaxTokens,
+		Thinking:        llmservice.ThinkingModeDisabled,
+		TextFormat:      "json_object",
+	})
+	if err != nil {
+		rawText := ""
+		rawChars := 0
+		status := ""
+		incompleteReason := ""
+		errorCode := ""
+		errorMessage := ""
+		inputTokens := int64(0)
+		outputTokens := int64(0)
+		totalTokens := int64(0)
+		if rawResult != nil {
+			rawText = strings.TrimSpace(rawResult.Text)
+			rawChars = len(rawText)
+			status = strings.TrimSpace(rawResult.Status)
+			incompleteReason = strings.TrimSpace(rawResult.IncompleteReason)
+			errorCode = strings.TrimSpace(rawResult.ErrorCode)
+			errorMessage = strings.TrimSpace(rawResult.ErrorMessage)
+			if rawResult.Usage != nil {
+				inputTokens = rawResult.Usage.InputTokens
+				outputTokens = rawResult.Usage.OutputTokens
+				totalTokens = rawResult.Usage.TotalTokens
+			}
+		}
+		log.Printf(
+			"[COURSE_PARSE][SERVICE] model invoke failed model_name=%q filename=%q mime=%q cost_ms=%d err=%v status=%q incomplete_reason=%q error_code=%q error_message=%q input_tokens=%d output_tokens=%d total_tokens=%d raw_chars=%d raw_full=\n%s",
+			ss.courseImageModel,
+			normalizedReq.Filename,
+			normalizedReq.MIMEType,
+			time.Since(startAt).Milliseconds(),
+			err,
+			status,
+			incompleteReason,
+			errorCode,
+			errorMessage,
+			inputTokens,
+			outputTokens,
+			totalTokens,
+			rawChars,
+			rawText,
+		)
+		if isCourseImageOutputTruncated(rawResult) {
+			return nil, fmt.Errorf(
+				"课程表识别输出疑似被 max_output_tokens 截断：status=%s incomplete_reason=%s output_tokens=%d max_output_tokens=%d",
+				status,
+				incompleteReason,
+				outputTokens,
+				ss.courseImageConfig.MaxTokens,
+			)
+		}
+		return nil, err
+	}
+
+	rawText := ""
+	rawChars := 0
+	status := ""
+	incompleteReason := ""
+	errorCode := ""
+	errorMessage := ""
+	inputTokens := int64(0)
+	outputTokens := int64(0)
+	totalTokens := int64(0)
+	if rawResult != nil {
+		rawText = strings.TrimSpace(rawResult.Text)
+		rawChars = len(rawText)
+		status = strings.TrimSpace(rawResult.Status)
+		incompleteReason = strings.TrimSpace(rawResult.IncompleteReason)
+		errorCode = strings.TrimSpace(rawResult.ErrorCode)
+		errorMessage = strings.TrimSpace(rawResult.ErrorMessage)
+		if rawResult.Usage != nil {
+			inputTokens = rawResult.Usage.InputTokens
+			outputTokens = rawResult.Usage.OutputTokens
+			totalTokens = rawResult.Usage.TotalTokens
+		}
+	}
+	log.Printf(
+		"[COURSE_PARSE][SERVICE] model invoke success model_name=%q filename=%q mime=%q cost_ms=%d status=%q incomplete_reason=%q error_code=%q error_message=%q input_tokens=%d output_tokens=%d total_tokens=%d raw_chars=%d raw_full=\n%s",
+		ss.courseImageModel,
+		normalizedReq.Filename,
+		normalizedReq.MIMEType,
+		time.Since(startAt).Milliseconds(),
+		status,
+		incompleteReason,
+		errorCode,
+		errorMessage,
+		inputTokens,
+		outputTokens,
+		totalTokens,
+		rawChars,
+		rawText,
+	)
+
+	normalizedDraft, err := normalizeCourseImageParseResponse(draft)
+	if err != nil {
+		log.Printf(
+			"[COURSE_PARSE][SERVICE] draft normalization failed model_name=%q filename=%q err=%v draft_status=%v row_count=%d",
+			ss.courseImageModel,
+			normalizedReq.Filename,
+			err,
+			draft.DraftStatus,
+			len(draft.Rows),
+		)
+		return nil, err
+	}
+
+	log.Printf(
+		"[COURSE_PARSE][SERVICE] draft normalization success model_name=%q filename=%q draft_status=%s rows=%d warnings=%d",
+		ss.courseImageModel,
+		normalizedReq.Filename,
+		normalizedDraft.DraftStatus,
+		len(normalizedDraft.Rows),
+		len(normalizedDraft.Warnings),
+	)
+
+	return normalizedDraft, nil
+}
+
+func buildCourseImageParseResponsesMessages(req *model.CourseImageParseRequest) ([]llmservice.ArkResponsesMessage, int, int) {
+	userPrompt := fmt.Sprintf(courseImageParseUserPromptTemplate, req.Filename, req.MIMEType)
+	base64Data := base64.StdEncoding.EncodeToString(req.ImageBytes)
+	imageDataURL := fmt.Sprintf("data:%s;base64,%s", req.MIMEType, base64Data)
+
+	messages := []llmservice.ArkResponsesMessage{
+		{
+			Role: "system",
+			Text: strings.TrimSpace(courseImageParseSystemPrompt),
+		},
+		{
+			Role:        "user",
+			Text:        strings.TrimSpace(userPrompt),
+			ImageURL:    imageDataURL,
+			ImageDetail: "high",
+		},
+	}
+	return messages, len(base64Data), len(strings.TrimSpace(userPrompt))
+}
+
+func isCourseImageOutputTruncated(rawResult *llmservice.ArkResponsesResult) bool {
+	if rawResult == nil {
+		return false
+	}
+
+	reason := strings.ToLower(strings.TrimSpace(rawResult.IncompleteReason))
+	if strings.Contains(reason, "max_output_tokens") ||
+		strings.Contains(reason, "max_tokens") ||
+		strings.Contains(reason, "length") {
+		return true
+	}
+
+	return strings.EqualFold(strings.TrimSpace(rawResult.Status), "incomplete") && reason == ""
+}

backend/services/course/sv/course_parse_prompt.go

@@ -0,0 +1,59 @@
+package sv
+
+const courseImageParseSystemPrompt = `
+你是 SmartFlow 的“总课表图片识别器”。你的唯一任务是读取用户上传的总课表图片，输出结构化 JSON 草稿，供前端人工核对后再导入系统。
+
+必须遵守以下规则：
+1. 只能输出一个 JSON 对象，禁止输出 Markdown、代码块、解释文字或额外前后缀。
+2. 顶层 JSON 结构必须是：
+{
+  "draft_status": "success | partial | reject",
+  "message": "字符串",
+  "warnings": ["字符串"],
+  "rows": [
+    {
+      "row_id": "字符串，可为空",
+      "course_name": "字符串",
+      "location": "字符串",
+      "is_allow_tasks": false,
+      "start_week": 1,
+      "end_week": 16,
+      "day_of_week": 1,
+      "start_section": 1,
+      "end_section": 2,
+      "week_type": "all | odd | even",
+      "confidence": 0.92,
+      "raw_text": "原图中对应的近似文本",
+      "row_warnings": ["字符串"]
+    }
+  ]
+}
+3. rows 中一行只表达一个“课程安排片段”，不要把同一门课的多个时间段强行合并成一行。
+4. is_allow_tasks 无法从课表图片稳定识别时，一律返回 false，不要自行猜测。
+5. 若图片完整且大部分字段明确，可返回 success。
+6. 若图片可识别出部分行，但存在裁切、模糊、遮挡、单双周不清晰、节次/周次不确定等问题，返回 partial。
+7. 若图片严重不完整、分辨率过低、主体不是课表、无法可靠识别，返回 reject，同时 rows 置为空数组。
+8. 不要编造信息。看不清的数值字段请返回 null，并在 row_warnings 或 warnings 中明确说明原因。
+9. week_type 只能是：
+   - all：每周/未标注单双周
+   - odd：单周
+   - even：双周
+10. day_of_week 使用 1-7 表示周一到周日。
+11. start_section/end_section 使用原子节次编号，例如 1-2 节应输出 start_section=1, end_section=2。
+12. confidence 取 0 到 1 之间的小数；不确定时可以偏保守。
+13. 如果 rows 不为空，优先保证“周次、星期、节次”准确，地点可为空字符串。
+14. 当图片信息不足时，应明确拒绝或降级为 partial，而不是强行补全。
+15. 填写json中course_name时，严格按照截图的课程名称来。例如，有的课可能既有本体，又有实验课，这算是两门不同的课。
+16. 周信息是可能出现中断的，例如一节课可能是第1周和第6-12周，这是正常的课程安排，请不要擅自更改。
+`
+
+const courseImageParseUserPromptTemplate = `
+请识别这张总课表图片，并严格按照约定 JSON 输出草稿。
+
+补充约束：
+1. 文件名：%s
+2. MIME 类型：%s
+3. 这是一张供学生核对的“导入草稿”，不是最终真值；不确定就留空或写 warning。
+4. 如果图片右侧、底部、表头、周次栏、节次栏有缺失，请优先返回 partial 或 reject。
+5. rows 里尽量保留 raw_text，方便前端逐行回显核对。
+`