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 记录
2026-05-05 12:07:31 +08:00
parent 7ed8adf8d1
commit fd327f845b
21 changed files with 1882 additions and 42 deletions
--- a/backend/services/course/sv/course.go
+++ b/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
+}
--- a/backend/services/course/sv/course_parse.go
+++ b/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 "课程表图片识别已完成，请人工核对后再导入。"
+	}
+}
--- a/backend/services/course/sv/course_parse_ark.go
+++ b/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 == ""
+}
--- a/backend/services/course/sv/course_parse_prompt.go
+++ b/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，方便前端逐行回显核对。
+`