DEV-MERGE-LEGACY-BACKEND-2026/internal/academic/handler/course_handler_test.go

// 课程 / 排班 / 打卡端点单测（AC-13c：端点 44~57）。
//
// 断言纪律（与前几批一致）：
//   - 只断 body 契约（HTTP 恒 200 + body.code），不断 HTTP 状态码；
//   - **每个端点至少一条"写错会变红"的断言**，且尽量落在**数据库**上而不是只断响应体
//     （响应体可以"改一个字段名"骗过自己，库里的列不会）；
//   - 错误码只比对 `apperr` / `infraerrors` 的常量，**不硬编码数字**。
//
// 覆盖结构：
//
//	44 课程列表          teacherIds 来自 t_courses_class、recordCount 来自 t_courses_record；
//	                    跨机构课程**不出现**（Scoped）
//	45 新建/更新课程     新建恒 status=0（未发布）；PUT 是部分更新（未传字段不变）
//	46 排班规则          status=2（已结束）的规则**必须出现**（onlyActive 会漏）；week 原值
//	47 新建规则          同老师+同周+时段重叠 → **3122**；不同周 → 200
//	49 生成课表          幂等：第二次 generated=0 / changed=false
//	50 开始上课          actual_start_time 落库；重复开始 → **3121**
//	51 结束上课          跨 5 张表断言（record_student / expense / expense_school / divide_log / payroll）
//	                    + 分账失败整体回滚（变异）
//	52 打卡              已结束的课 → **3121**；未结束 → 写 cost 并回显 checked
//	53 报课学生          欠费字段取 remainder_receivable（造 unpaid=999 的陷阱行）
//	54 报名              快照恒等式 receivable = net_receipts + remainder_receivable；
//	                    confirm_discount_user_id 必须写（否则永远进不了核销候选）；重复 → 3140
//	55 欠费列表          **remainder_receivable > 0**（造 unpaid=999/remainder=0 的陷阱行必须不出现）
//	56 欠费核销          net_receipts 增、remainder_receivable 减（同一条 UPDATE）；跨机构 → 1004
//	57 学生课表          按学生过滤（另一个学生的课不出现）；跨用户查 → 1004
package handler

import (
	"encoding/json"
	"strings"
	"testing"
	"time"

	"github.com/gofiber/fiber/v2"
	"gorm.io/gorm"

	"yuansiwei/unified-backend/internal/academic/apperr"
	"yuansiwei/unified-backend/internal/academic/model"
	"yuansiwei/unified-backend/internal/academic/money"
	infraerrors "yuansiwei/unified-backend/internal/infra/errors"
	appscope "yuansiwei/unified-backend/internal/infra/scope"
)

// ---------------------------------------------------------------- 测试基础设施

// 测试用常量（ULID 形态的假 ID，长度 26 与真实约束一致）。
const (
	courseTestStudent     = "01HSTUDENT00000000000001"
	courseTestOther       = "01HSTUDENT00000000000002"
	courseTestTeacher     = "01HTEACHER00000000000001"
	courseTestTeacher2    = "01HTEACHER00000000000002"
	courseTestRecommender = "01HRECOMMENDER00000000001"
	courseTestUpline      = "01HUPLINE00000000000001"
	courseTestOperator    = "01HOPERATOR0000000000001"
)

// newCourseTestDB 课程域测试库：资金四表（复用）+ 课程 6 表 + 课酬 3 表 + 分账 2 表。
//
// 与 `newHandlerTestDB` 同构地逐表 AutoMigrate 并删除**非唯一索引**（SQLite 索引名库级唯一，
// 而 academic model 多表共用 `idx_inst_campus` 等名字）。
func newCourseTestDB(t *testing.T) *gorm.DB {
	t.Helper()
	base := newHandlerTestDB(t) // 资金 4 表 + 活动 6 表 + t_campus（机构 1 / 校区 10）
	extra := []any{
		&model.Courses{}, &model.CoursesClassify{}, &model.CoursesClass{},
		&model.CoursesStudent{}, &model.CoursesRecord{}, &model.CoursesRecordStudent{},
		&model.CoursePayment{}, &model.CoursePaymentDetail{}, &model.TeacherInformation{},
		&model.UserDivideInto{}, &model.UserDivideIntoLog{},
	}
	// 先把 `newHandlerTestDB` 留下的**唯一索引**清干净：`uk_biz_no` 在 t_user_balance_request
	// （资金域）与 3 张课程表上同名，SQLite 的索引名是库级唯一 ⇒ 不清会直接建表失败。
	// 测试库放弃唯一约束（生产 MySQL 表级隔离，不受影响）。
	var leftovers []string
	if err := base.Raw(
		"SELECT name FROM sqlite_master WHERE type='index' AND name NOT LIKE 'sqlite_%'").Scan(&leftovers).Error; err != nil {
		t.Fatalf("读取遗留索引失败: %v", err)
	}
	for _, name := range leftovers {
		if err := base.Exec("DROP INDEX IF EXISTS `" + name + "`").Error; err != nil {
			t.Fatalf("删除遗留索引(%s) 失败: %v", name, err)
		}
	}
	for _, tbl := range extra {
		if err := base.AutoMigrate(tbl); err != nil {
			t.Fatalf("AutoMigrate(%T) 失败: %v", tbl, err)
		}
		stmt := &gorm.Statement{DB: base}
		if err := stmt.Parse(tbl); err != nil {
			t.Fatalf("解析表名(%T) 失败: %v", tbl, err)
		}
		var idxRows []struct {
			Name string
			SQL  *string
		}
		if err := base.Raw(
			"SELECT name, sql FROM sqlite_master WHERE type='index' AND tbl_name=? AND name NOT LIKE 'sqlite_%'",
			stmt.Schema.Table).Scan(&idxRows).Error; err != nil {
			t.Fatalf("读索引清单(%s) 失败: %v", stmt.Schema.Table, err)
		}
		for _, row := range idxRows {
			// ⚠ **唯一索引也一并删除**（与 `newHandlerTestDB` 不同）：academic model 里
			// `uk_biz_no` 同时出现在 t_courses_student / t_courses_record / t_courses_record_student
			// 三张表上，而 SQLite 的索引名是**库级唯一**（MySQL 是表级）⇒ 第二张表建索引必报
			// "index uk_biz_no already exists"。测试库因此放弃唯一约束（生产是 MySQL，不受影响；
			// 服务层测试 `migrateLearningTables` 同款处理）。
			if err := base.Exec("DROP INDEX IF EXISTS `" + row.Name + "`").Error; err != nil {
				t.Fatalf("删索引(%s) 失败: %v", row.Name, err)
			}
		}
	}
	return base
}

// newCourseTestApp 挂 15 条课程域路由（**不做角色白名单**：那是 e2e 的职责，见 route_e2e_test.go）。
//
// 作用域由 `X-Test-Scope` 头选择：`none` = 不注入（1001）、`super` = 超管、`student` = 学生、
// `teacher` = 老师、缺省 = 财务（机构 1 / 校区 10）。
func newCourseTestApp(t *testing.T, db *gorm.DB) *fiber.App {
	t.Helper()
	h, err := New(Config{DB: db})
	if err != nil {
		t.Fatalf("handler.New 失败: %v", err)
	}
	app := fiber.New(fiber.Config{DisableStartupMessage: true})
	app.Use(func(c *fiber.Ctx) error {
		switch c.Get("X-Test-Scope") {
		case "none":
			// 不写作用域 → 未登录语义（1001）
		case "super":
			appscope.Set(c, testSuperScope())
		case "student":
			appscope.Set(c, &appscope.Scope{
				InstitutionID: 1, CampusID: 10,
				UserID: courseTestStudent, Role: RoleStudent,
			})
		case "teacher":
			appscope.Set(c, &appscope.Scope{
				InstitutionID: 1, CampusID: 10,
				UserID: courseTestTeacher, Role: RoleTeacher,
			})
		default:
			appscope.Set(c, testScope())
		}
		return c.Next()
	})
	// 注册顺序与 route.go 一致（静态段先于 `:id`）
	app.Get(PathCourses, h.ListCourses)
	app.Post(PathCourses, h.CreateCourse)
	app.Get(PathCourseArrears, h.ListCourseArrears)
	app.Post(PathCourseArrearsCounteract, h.CounteractCourseArrears)
	app.Post(PathCourseRecordStart, h.StartCourseRecord)
	app.Post(PathCourseRecordFinish, h.FinishCourseRecord)
	app.Post(PathCourseRecordAttendance, h.MarkCourseRecordAttendance)
	app.Put(PathCourseDetail, h.UpdateCourse)
	app.Get(PathCourseClasses, h.ListCourseClasses)
	app.Post(PathCourseClasses, h.CreateCourseClass)
	app.Get(PathCourseRecords, h.ListCourseRecords)
	app.Post(PathCourseRecordsGenerate, h.GenerateCourseRecords)
	app.Get(PathCourseStudents, h.ListCourseStudents)
	app.Post(PathCourseStudents, h.EnrollCourseStudent)
	app.Get(PathStudentSchedule, h.GetStudentSchedule)
	return app
}

// seedCourse 建一门课程（机构 1 / 指定校区；classify 默认 0）。
func seedCourse(t *testing.T, db *gorm.DB, name string, campusID int64) *model.Courses {
	t.Helper()
	row := &model.Courses{
		InstitutionID: 1, CampusID: campusID, Name: name,
		Status: model.CoursesStatusUnpublished, Number: 10, Duration: "1.0", Week: "-1",
		OriginalCost: "100.00", RealPrice: "100.00", DiscountCash: "0.00",
	}
	if err := db.Create(row).Error; err != nil {
		t.Fatalf("建课程失败: %v", err)
	}
	return row
}

// seedClassRule 建一条排班规则。
func seedClassRule(t *testing.T, db *gorm.DB, coursesID, classID int64, teacher, week string, status int32, startHM, endHM string) *model.CoursesClass {
	t.Helper()
	start := mustHM(t, startHM)
	var end *time.Time
	if endHM != "" {
		end = mustHM(t, endHM)
	}
	row := &model.CoursesClass{
		Status: status, CoursesID: coursesID, ClassID: classID,
		TeacherID: &teacher, InstitutionID: 1, CampusID: 10,
		StandardLessonCost: "100.00", Number: 10, LessonCost: "100.00",
		DiscountCash: "0.00", FinishedNumber: 0, Confirm: model.CoursesClassConfirmNo,
		Week: week, StartTime: start, EndTime: end,
	}
	if err := db.Create(row).Error; err != nil {
		t.Fatalf("建排班规则失败: %v", err)
	}
	return row
}

// mustHM 把 "HH:MM" 转成时分列（1970-01-01 + 时分，UTC），与服务层口径一致。
func mustHM(t *testing.T, hm string) *time.Time {
	t.Helper()
	parts := strings.Split(hm, ":")
	hour := mustAtoi(t, parts[0])
	minute := 0
	if len(parts) > 1 {
		minute = mustAtoi(t, parts[1])
	}
	at := time.Date(1970, 1, 1, hour, minute, 0, 0, time.UTC)
	return &at
}

// mustAtoi 测试用 Atoi（失败即 fatal）。
func mustAtoi(t *testing.T, raw string) int {
	t.Helper()
	value := 0
	for _, ch := range strings.TrimSpace(raw) {
		if ch < '0' || ch > '9' {
			t.Fatalf("非数字: %q", raw)
		}
		value = value*10 + int(ch-'0')
	}
	return value
}

// seedEnrollment 建报课行（**故意把 unpaid 写成垃圾值**，用于证明"欠费口径不用 unpaid"）。
func seedEnrollment(t *testing.T, db *gorm.DB, coursesID int64, studentID, bizNo string,
	lessonCost, receivable, netReceipts, remainderReceivable, unpaid string) *model.CoursesStudent {
	t.Helper()
	confirm := courseTestOperator
	row := &model.CoursesStudent{
		BizNo: bizNo, CoursesID: coursesID, InstitutionID: 1, CampusID: 10,
		StudentID: studentID, Type: model.CoursesStudentTypeNormal,
		Status:     model.CoursesStudentStatusNormal,
		Receivable: receivable, NetReceipts: netReceipts, Unpaid: unpaid,
		LessonCost: lessonCost, Number: 10, FinishedNumber: 0,
		DiscountCash: "0.00", GiveNumber: 0, GiveCost: "0.00",
		RemainderNumber: 10, RemainderCost: netReceipts,
		RemainderReceivable: remainderReceivable, BadDebt: "0.00",
		ConfirmDiscountUserID: &confirm,
	}
	if err := db.Create(row).Error; err != nil {
		t.Fatalf("建报课行失败: %v", err)
	}
	return row
}

// seedRecord 建排班实例。
func seedRecord(t *testing.T, db *gorm.DB, coursesID, classID int64, bizNo string, status int32, at time.Time) *model.CoursesRecord {
	t.Helper()
	teacher := courseTestTeacher
	end := at.Add(time.Hour)
	row := &model.CoursesRecord{
		BizNo: bizNo, CoursesID: coursesID, ClassID: classID,
		TeacherID: &teacher, InstitutionID: 1, CampusID: 10, Status: status,
		StartTime: &at, EndTime: &end,
	}
	if err := db.Create(row).Error; err != nil {
		t.Fatalf("建排班实例失败: %v", err)
	}
	return row
}

// requireMoney 比较"元字符串"金额（**不比较字面量**）。
//
// 为什么不直接比字符串：SQLite 没有 DECIMAL 类型，`"100.00"` 读回来是 `"100"`；
// 生产 MySQL 读回来是 `"100.00"`。断言要跨两种方言成立，就必须比**分值**而不是比字面量。
func requireMoney(t *testing.T, label, got, want string) {
	t.Helper()
	if strings.TrimSpace(got) == "" {
		t.Fatalf("%s 为空（读不到列），期望 %s", label, want)
	}
	g, gerr := money.Parse(got)
	if gerr != nil {
		t.Fatalf("%s = %q 不是合法金额: %v", label, got, gerr)
	}
	w, werr := money.Parse(want)
	if werr != nil {
		t.Fatalf("期望值 %q 不是合法金额: %v", want, werr)
	}
	if g.Cents() != w.Cents() {
		t.Fatalf("%s = %q（%d 分），期望 %q（%d 分）", label, got, g.Cents(), want, w.Cents())
	}
}

// jsonMap 把响应 data 解成 map（断言"某个键必须不存在"时用）。
func jsonMap(t *testing.T, raw json.RawMessage) map[string]any {
	t.Helper()
	out := map[string]any{}
	if len(raw) == 0 {
		return out
	}
	if err := json.Unmarshal(raw, &out); err != nil {
		t.Fatalf("响应 data 不是 JSON 对象: %v（原文 %s）", err, string(raw))
	}
	return out
}

// pageList 取分页响应的 list 字段（[]any）。
func pageList(t *testing.T, raw json.RawMessage) []any {
	t.Helper()
	got := jsonMap(t, raw)
	items, ok := got["list"].([]any)
	if !ok {
		t.Fatalf("响应缺少 list 数组：%s", string(raw))
	}
	return items
}

// ---------------------------------------------------------------- 端点 44：课程列表

// TestListCoursesAggregatesTeacherIDsAndRecordCount 端点 44 的两个派生列必须来自**另外两张表**。
//
// 变红条件：
//   - `teacherIds` 恒空（漏 join `t_courses_class`）→ 断言 1 红；
//   - `recordCount` 恒 0（漏 count `t_courses_record`）→ 断言 2 红；
//   - 机构过滤失效（把机构 2 的课程也返回）→ 断言 3 红。
func TestListCoursesAggregatesTeacherIDsAndRecordCount(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "数学A", 10)
	// 两条规则、三个不同老师（含一条重复老师）→ teacherIds 必须去重且升序
	seedClassRule(t, db, course.ID, 1001, courseTestTeacher2, "1", model.CoursesClassStatusOngoing, "09:00", "10:00")
	seedClassRule(t, db, course.ID, 1001, courseTestTeacher, "3", model.CoursesClassStatusEnded, "11:00", "12:00")
	seedClassRule(t, db, course.ID, 1002, courseTestTeacher2, "5", model.CoursesClassStatusOngoing, "13:00", "14:00")
	for i := 0; i < 3; i++ {
		seedRecord(t, db, course.ID, 1001, "REC"+string(rune('A'+i)), model.CoursesRecordStatusNotStarted,
			time.Date(2026, 11, 10+i, 9, 0, 0, 0, time.Local))
	}
	// 另一机构的课程（不得出现在机构 1 的列表里）
	other := &model.Courses{
		InstitutionID: 2, CampusID: 20, Name: "别家课程", Status: model.CoursesStatusPublished,
		Duration: "1.0", Week: "-1", OriginalCost: "0.00", RealPrice: "0.00", DiscountCash: "0.00",
	}
	if err := db.Create(other).Error; err != nil {
		t.Fatalf("建跨机构课程失败: %v", err)
	}

	app := newCourseTestApp(t, db)
	code, msg, data := doJSON(t, app, fiber.MethodGet, PathCourses, nil, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("GET %s = %d（%s），期望 200", PathCourses, code, msg)
	}
	payload := jsonMap(t, data)
	items, _ := payload["list"].([]any)
	if len(items) != 1 {
		t.Fatalf("列表行数 = %d，期望 1（跨机构课程必须被 Scoped 过滤）：%s", len(items), string(data))
	}
	row, _ := items[0].(map[string]any)

	// 断言 1：teacherIds 去重 + 升序，且**来自 t_courses_class**
	teacherIDs, _ := row["teacherIds"].([]any)
	if len(teacherIDs) != 2 {
		t.Fatalf("teacherIds = %v，期望 2 个（去重后 %s/%s）—— 空数组说明没查 t_courses_class",
			row["teacherIds"], courseTestTeacher, courseTestTeacher2)
	}
	if teacherIDs[0] != courseTestTeacher || teacherIDs[1] != courseTestTeacher2 {
		t.Fatalf("teacherIds = %v，期望升序 [%s %s]", teacherIDs, courseTestTeacher, courseTestTeacher2)
	}

	// 断言 2：recordCount 来自 t_courses_record 计数
	if got, _ := row["recordCount"].(float64); got != 3 {
		t.Fatalf("recordCount = %v，期望 3（t_courses_record 三行）；0 说明没做计数聚合", row["recordCount"])
	}

	// 断言 3：作用域键（机构/校区）必须下发
	if got, _ := row["institutionId"].(float64); got != 1 {
		t.Fatalf("institutionId = %v，期望 1", row["institutionId"])
	}
}

// ---------------------------------------------------------------- 端点 45：课程 CRUD

// TestCreateCourseIsUnpublished 端点 45 新建：恒落 status=0（未发布），作用域列取 token 而非 body。
//
// 变红条件：把 body 的 status/institutionId 透传进库（或忘写作用域列）→ 库里 status/institution_id 不符。
func TestCreateCourseIsUnpublished(t *testing.T) {
	db := newCourseTestDB(t)
	app := newCourseTestApp(t, db)
	code, msg, data := doJSON(t, app, fiber.MethodPost, PathCourses, map[string]any{
		"name": "英语B", "duration": "1.5", "number": 8, "realPrice": "200.00",
		"week": "1,3,5", "status": 3, "institutionId": 99, // status/institutionId 必须被忽略
	}, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("POST %s = %d（%s），期望 200", PathCourses, code, msg)
	}
	id, _ := jsonMap(t, data)["id"].(float64)
	if id <= 0 {
		t.Fatalf("响应 id = %v，期望 >0", jsonMap(t, data)["id"])
	}
	var row model.Courses
	if err := db.First(&row, int64(id)).Error; err != nil {
		t.Fatalf("回读课程失败: %v", err)
	}
	// status 断言拆到 TestCreateCourseStatusIsUnpublished（D11 的回归门禁，含缺陷成因与修法）。
	if row.InstitutionID != 1 {
		t.Fatalf("institution_id = %d，期望 1（取作用域，不信 body 的 99）", row.InstitutionID)
	}
	if row.CampusID != 10 {
		t.Fatalf("campus_id = %d，期望 10（作用域校区）", row.CampusID)
	}
	if row.Week != "1,3,5" {
		t.Fatalf("week = %q，期望原值 1,3,5", row.Week)
	}

	// 2001：缺 name
	if code, msg, _ := doJSON(t, app, fiber.MethodPost, PathCourses, map[string]any{
		"duration": "1.0",
	}, "X-Test-Token", "t"); code != infraerrors.ErrBadParam.Code {
		t.Fatalf("缺 name = %d（%s），期望 2001", code, msg)
	}
}

// TestCreateCourseStatusIsUnpublished **新建课程必须落 status=0（未发布）**——D11 的回归门禁。
//
// 缺陷原貌（2026-11-09 实测）：`CourseService.CreateCourse` 显式写 `Status=0`，但
// `model.Courses.Status` 的 gorm tag 带 `default:1` ⇒ GORM 对"有 default tag 且值为零"的列
// **跳过该列**、由 DB 默认值填充 ⇒ 落库 `status=1`（"新建即发布"：课程直接出现在可报名列表）。
// MySQL 与 SQLite 走同一段 GORM 回调，生产同样成立。
//
// 修复（team-lead 裁决）：**去掉 `model.Courses.Status` 的 `default:1`（DDL 不动）**，
// 而不是 `tx.Select("*").Create(row)` —— 后者会把 `created_at`/`updated_at` 等零值一并写入，
// 正是 `a1971b7`（审计时间零值落库）修过的反向坑。
//
// 本用例是**回归门禁**：把 `default:1` 加回 tag，本用例必红（实测见交付报告）。
func TestCreateCourseStatusIsUnpublished(t *testing.T) {
	db := newCourseTestDB(t)
	app := newCourseTestApp(t, db)
	code, msg, data := doJSON(t, app, fiber.MethodPost, PathCourses, map[string]any{
		"name": "状态测试课", "duration": "1.0",
	}, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("POST %s = %d（%s），期望 200", PathCourses, code, msg)
	}
	id, _ := jsonMap(t, data)["id"].(float64)
	var row model.Courses
	if err := db.First(&row, int64(id)).Error; err != nil {
		t.Fatalf("回读课程失败: %v", err)
	}
	if row.Status != model.CoursesStatusUnpublished {
		t.Fatalf("新建课程 status = %d，期望 0（未发布）—— status 只能走状态机入口", row.Status)
	}
}

// TestUpdateCourseIsPartial 端点 45 更新：只改传入列（未传的 name/number 必须保持原值）。
//
// 变红条件：写成"整体替换"（未传字段被清空/归零）→ name 或 number 变空/0。
func TestUpdateCourseIsPartial(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "物理C", 10)
	course.Number = 12
	if err := db.Save(course).Error; err != nil {
		t.Fatalf("更新种子课程失败: %v", err)
	}
	app := newCourseTestApp(t, db)
	code, msg, _ := doJSON(t, app, fiber.MethodPut, "/admin/courses/"+itoa(course.ID), map[string]any{
		"remark": "只改备注",
	}, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("PUT 课程 = %d（%s），期望 200", code, msg)
	}
	var row model.Courses
	if err := db.First(&row, course.ID).Error; err != nil {
		t.Fatalf("回读课程失败: %v", err)
	}
	if row.Name != "物理C" {
		t.Fatalf("name = %q，期望保持 物理C —— 部分更新被写成了整体替换", row.Name)
	}
	if row.Number != 12 {
		t.Fatalf("number = %d，期望保持 12 —— 未传字段被清零", row.Number)
	}
	if row.Remark == nil || *row.Remark != "只改备注" {
		t.Fatalf("remark = %v，期望 只改备注", row.Remark)
	}
}

// itoa 测试用整数转字符串（避免引入 strconv 之外的依赖）。
func itoa(v int64) string {
	if v == 0 {
		return "0"
	}
	digits := make([]byte, 0, 20)
	for v > 0 {
		digits = append([]byte{byte('0' + v%10)}, digits...)
		v /= 10
	}
	return string(digits)
}

// ---------------------------------------------------------------- 端点 46：排班规则

// TestListCourseClassesKeepsEndedRules 端点 46 必须列出**全部**规则（含 status=2 已结束）。
//
// 为什么这条重要：AC-11 的 `ListClasses(onlyActive=true)` 是"排班生成"专用过滤，
// 若 handler 顺手复用它，已结束的规则会静默消失（前端看到的是"这个班没排过课"）。
// 变红条件：把 onlyActive 传成 true → total 从 2 变 1。
func TestListCourseClassesKeepsEndedRules(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "化学D", 10)
	seedClassRule(t, db, course.ID, 2001, courseTestTeacher, "1,3,5", model.CoursesClassStatusOngoing, "09:00", "10:00")
	seedClassRule(t, db, course.ID, 2002, courseTestTeacher2, "2", model.CoursesClassStatusEnded, "14:00", "15:00")
	app := newCourseTestApp(t, db)
	code, msg, data := doJSON(t, app, fiber.MethodGet, "/admin/courses/"+itoa(course.ID)+"/classes", nil, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("GET classes = %d（%s），期望 200", code, msg)
	}
	total, _ := jsonMap(t, data)["total"].(float64)
	if total != 2 {
		t.Fatalf("total = %v，期望 2（含 status=2 的规则）—— 1 说明误用了 onlyActive 过滤", total)
	}
	items := pageList(t, data)
	first, _ := items[0].(map[string]any)
	// week 必须是**原值字符串**（契约写 number 1~7，但该列是多值字符串，见 classRowView 注释）
	if week, _ := first["week"].(string); week != "1,3,5" {
		t.Fatalf("week = %v（%T），期望原值字符串 \"1,3,5\"", first["week"], first["week"])
	}
	if _, hasRoom := first["room"]; hasRoom {
		t.Fatalf("响应出现了 room 字段（%s）：t_courses_class 没有 room 列，不得下发", string(data))
	}
}

// ---------------------------------------------------------------- 端点 47：新建排班规则

// TestCreateCourseClassConflictReturns3122 端点 47：同老师 + 同周 + 时段重叠 → 3122。
//
// 变红条件：去掉冲突判定 → 冲突请求返回 200（并且库里多出一条重叠规则）。
func TestCreateCourseClassConflictReturns3122(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "生物E", 10)
	seedClassRule(t, db, course.ID, 3001, courseTestTeacher, "1", model.CoursesClassStatusOngoing, "09:00", "10:00")
	app := newCourseTestApp(t, db)

	base := map[string]any{
		"teacherId": courseTestTeacher, "week": "1", "start": "09:30", "end": "10:30",
		"lessonCost": "100.00", "number": 10,
	}
	code, msg, _ := doJSON(t, app, fiber.MethodPost, "/admin/courses/"+itoa(course.ID)+"/classes", base, "X-Test-Token", "t")
	if code != apperr.CodeScheduleConflict {
		t.Fatalf("重叠排班 = %d（%s），期望 3122（排班冲突）", code, msg)
	}
	var count int64
	db.Model(&model.CoursesClass{}).Where("courses_id = ?", course.ID).Count(&count)
	if count != 1 {
		t.Fatalf("冲突被拒后规则数 = %d，期望仍为 1（不得先写后报错）", count)
	}

	// 对照：换一天（week=2）必须成功，否则说明冲突判定过宽
	okBody := map[string]any{
		"teacherId": courseTestTeacher, "week": "2", "start": "09:30", "end": "10:30",
		"lessonCost": "100.00", "number": 10,
	}
	code, msg, data := doJSON(t, app, fiber.MethodPost, "/admin/courses/"+itoa(course.ID)+"/classes", okBody, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("不同周的排班 = %d（%s），期望 200（冲突判定过宽）", code, msg)
	}
	if _, ok := jsonMap(t, data)["classId"]; !ok {
		t.Fatalf("响应缺 classId：%s", string(data))
	}
}

// ---------------------------------------------------------------- 端点 49：生成课表

// TestGenerateRecordsIdempotent 端点 49 幂等：同 courses+start_time 不重复插。
//
// 变红条件：去掉 `FindByCoursesStart` 幂等判据 → 第二次 generated>0、库里行数翻倍。
func TestGenerateRecordsIdempotent(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "地理F", 10)
	seedClassRule(t, db, course.ID, 4001, courseTestTeacher, "-1", model.CoursesClassStatusOngoing, "09:00", "10:00")
	app := newCourseTestApp(t, db)
	body := map[string]any{"days": 3, "from": "2026-11-10"}

	code, msg, data := doJSON(t, app, fiber.MethodPost, "/admin/courses/"+itoa(course.ID)+"/records/generate", body, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("生成课表 = %d（%s），期望 200", code, msg)
	}
	if got, _ := jsonMap(t, data)["generated"].(float64); got != 3 {
		t.Fatalf("首次 generated = %v，期望 3", jsonMap(t, data)["generated"])
	}
	code, msg, data = doJSON(t, app, fiber.MethodPost, "/admin/courses/"+itoa(course.ID)+"/records/generate", body, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("二次生成 = %d（%s），期望 200", code, msg)
	}
	payload := jsonMap(t, data)
	if got, _ := payload["generated"].(float64); got != 0 {
		t.Fatalf("二次 generated = %v，期望 0（幂等：同 courses+start_time 不重复插）", payload["generated"])
	}
	if changed, _ := payload["changed"].(bool); changed {
		t.Fatalf("二次 changed = true，期望 false（本次无新增）")
	}
	var count int64
	db.Model(&model.CoursesRecord{}).Where("courses_id = ?", course.ID).Count(&count)
	if count != 3 {
		t.Fatalf("库中实例数 = %d，期望 3（幂等失败会翻倍成 6）", count)
	}
}

// ---------------------------------------------------------------- 端点 50 / 52：开始上课 / 打卡

// TestStartRecordWritesActualStart 端点 50：status 0→1 且 `actual_start_time` 落库；重复开始 → 3121。
//
// 变红条件：只改 status 不写 actual_start_time → 断言 1 红；重复开始返回 200 → 断言 2 红。
func TestStartRecordWritesActualStart(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "历史G", 10)
	record := seedRecord(t, db, course.ID, 5001, "RECSTART", model.CoursesRecordStatusNotStarted,
		time.Now().Add(-time.Hour))
	app := newCourseTestApp(t, db)
	path := "/admin/courses/records/" + itoa(record.ID) + "/start"

	code, msg, data := doJSON(t, app, fiber.MethodPost, path, nil, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("开始上课 = %d（%s），期望 200", code, msg)
	}
	payload := jsonMap(t, data)
	if got, _ := payload["status"].(float64); got != float64(model.CoursesRecordStatusOngoing) {
		t.Fatalf("status = %v，期望 1", payload["status"])
	}
	if got, _ := payload["courseId"].(float64); got != float64(course.ID) {
		t.Fatalf("courseId = %v，期望 %d", payload["courseId"], course.ID)
	}
	var row struct {
		Status      int32      `gorm:"column:status"`
		ActualStart *time.Time `gorm:"column:actual_start_time"`
	}
	if err := db.Raw("SELECT status, actual_start_time FROM t_courses_record WHERE id = ?", record.ID).Scan(&row).Error; err != nil {
		t.Fatalf("回读实例失败: %v", err)
	}
	if row.Status != model.CoursesRecordStatusOngoing || row.ActualStart == nil {
		t.Fatalf("库里 status=%d actual_start_time=%v，期望 1 且非空（模型红线：开课时间必写）", row.Status, row.ActualStart)
	}

	// 重复开始 → 3121（不会写出第二个开课时间）
	if code, msg, _ := doJSON(t, app, fiber.MethodPost, path, nil, "X-Test-Token", "t"); code != apperr.CodeRecordStateInvalid {
		t.Fatalf("重复开始上课 = %d（%s），期望 3121", code, msg)
	}
}

// TestAttendanceRejectsFinishedRecord 端点 52：已结束的课不能补打卡（3121）；未结束则写 cost 并回显人数。
//
// 变红条件：去掉"已结束"判定 → 返回 200 且库中出现结课后追加的打卡行（income 对账缺口）。
func TestAttendanceRejectsFinishedRecord(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "政治H", 10)
	open := seedRecord(t, db, course.ID, 6001, "RECOPEN", model.CoursesRecordStatusOngoing,
		time.Now().Add(-time.Hour))
	closed := seedRecord(t, db, course.ID, 6001, "RECCLOSED", model.CoursesRecordStatusFinished,
		time.Now().Add(-24*time.Hour))
	app := newCourseTestApp(t, db)

	body := map[string]any{"list": []map[string]any{
		{"userId": courseTestStudent, "type": 1, "pay": 1, "cost": "100.00", "giveCost": "0.00"},
	}}
	code, msg, data := doJSON(t, app, fiber.MethodPost,
		"/admin/courses/records/"+itoa(open.ID)+"/attendance", body, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("未结束课打卡 = %d（%s），期望 200", code, msg)
	}
	if got, _ := jsonMap(t, data)["checked"].(float64); got != 1 {
		t.Fatalf("checked = %v，期望 1", jsonMap(t, data)["checked"])
	}
	var cost struct {
		Cost string `gorm:"column:cost"`
		Pay  int8   `gorm:"column:pay"`
		Typ  int32  `gorm:"column:type"`
	}
	if err := db.Raw("SELECT cost, pay, type FROM t_courses_record_student WHERE record_id = ? AND student_id = ?",
		open.ID, courseTestStudent).Scan(&cost).Error; err != nil {
		t.Fatalf("回读打卡行失败: %v", err)
	}
	requireMoney(t, "打卡行 cost", cost.Cost, "100.00")

	// 已结束的课 → 3121
	code, msg, _ = doJSON(t, app, fiber.MethodPost,
		"/admin/courses/records/"+itoa(closed.ID)+"/attendance", body, "X-Test-Token", "t")
	if code != apperr.CodeRecordStateInvalid {
		t.Fatalf("已结束课补打卡 = %d（%s），期望 3121", code, msg)
	}
}

// ---------------------------------------------------------------- 端点 53：报课学生

// TestListCourseStudentsUsesRemainderReceivable 端点 53 的欠费字段必须取 `remainder_receivable`。
//
// 陷阱行：`unpaid=999.00`（僵尸列的脏值）、`remainder_receivable=100.00`（真值）。
// 变红条件：字段取成 `unpaid` → 响应里 remainderReceivable 变成 999.00；
//
//	把 unpaid 一起下发 → 断言"响应不含 unpaid 键"红。
func TestListCourseStudentsUsesRemainderReceivable(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "语文I", 10)
	seedEnrollment(t, db, course.ID, courseTestStudent, "ENROLL-1", "100.00", "400.00", "300.00", "100.00", "999.00")
	app := newCourseTestApp(t, db)

	code, msg, data := doJSON(t, app, fiber.MethodGet,
		"/admin/courses/"+itoa(course.ID)+"/students", nil, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("报课学生列表 = %d（%s），期望 200", code, msg)
	}
	items := pageList(t, data)
	if len(items) != 1 {
		t.Fatalf("行数 = %d，期望 1", len(items))
	}
	row, _ := items[0].(map[string]any)
	if got, _ := row["remainderReceivable"].(string); got != "100.00" {
		t.Fatalf("remainderReceivable = %v，期望 \"100.00\"（源列 remainder_receivable）；"+
			"若为 999.00 说明误取了废弃列 unpaid", row["remainderReceivable"])
	}
	if got, _ := row["pay"].(string); got != "400.00" {
		t.Fatalf("pay = %v，期望 400.00（源列 receivable）", row["pay"])
	}
	if got, _ := row["cost"].(string); got != "300.00" {
		t.Fatalf("cost = %v，期望 300.00（源列 net_receipts）", row["cost"])
	}
	if _, hasUnpaid := row["unpaid"]; hasUnpaid {
		t.Fatalf("响应下发了 unpaid（%s）：废弃列禁下发（设计 §3.8-E4）", string(data))
	}
	if _, hasName := row["realName"]; hasName {
		t.Fatalf("响应下发了 realName（%s）：本域无 t_user，不得凭空编姓名", string(data))
	}
}

// ---------------------------------------------------------------- 端点 54：报名

// TestEnrollCreatesSnapshotAndRejectsDuplicate 端点 54 报课行快照恒等式 + 重复报名 3140 + 跨校区 1004。
//
// 变红条件：
//   - receivable ≠ net_receipts + remainder_receivable → 对账恒等式断言红；
//   - `confirm_discount_user_id` 为空 → 该行永远进不了欠费核销候选，断言红；
//   - 重复报名静默成功 → 库里出现第二行（断言行数）。
func TestEnrollCreatesSnapshotAndRejectsDuplicate(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "化学J", 10)
	app := newCourseTestApp(t, db)
	path := "/admin/courses/" + itoa(course.ID) + "/students"
	body := map[string]any{
		"userId": courseTestStudent, "pay": "500.00", "remainderReceivable": "200.00",
		"lessonCost": "100.00", "number": 5, "giveNumber": 1,
	}
	code, msg, data := doJSON(t, app, fiber.MethodPost, path, body, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("报名 = %d（%s），期望 200", code, msg)
	}
	payload := jsonMap(t, data)
	if enrolled, _ := payload["enrolled"].(bool); !enrolled {
		t.Fatalf("enrolled = %v，期望 true", payload["enrolled"])
	}
	var row model.CoursesStudent
	if err := db.Where("courses_id = ? AND student_id = ?", course.ID, courseTestStudent).First(&row).Error; err != nil {
		t.Fatalf("回读报课行失败: %v", err)
	}
	// 恒等式：receivable = net_receipts + remainder_receivable（这是"应收"的唯一定义）
	receivable, _ := money.Parse(row.Receivable)
	netReceipts, _ := money.Parse(row.NetReceipts)
	remainder, _ := money.Parse(row.RemainderReceivable)
	if receivable.Cents() != netReceipts.Cents()+remainder.Cents() {
		t.Fatalf("receivable(%s) ≠ net_receipts(%s) + remainder_receivable(%s)：应收恒等式被破坏",
			row.Receivable, row.NetReceipts, row.RemainderReceivable)
	}
	if row.RemainderNumber != 6 {
		t.Fatalf("remainder_number = %d，期望 6（number 5 + give_number 1）", row.RemainderNumber)
	}
	if row.ConfirmDiscountUserID == nil || strings.TrimSpace(*row.ConfirmDiscountUserID) == "" {
		t.Fatalf("confirm_discount_user_id 为空：该报课行将**永远进不了欠费核销候选**（§3.8-A17）")
	}
	requireMoney(t, "unpaid（废弃列）", row.Unpaid, "0.00")

	// 重复报名 → 3140，且库里仍只有一行
	code, msg, _ = doJSON(t, app, fiber.MethodPost, path, body, "X-Test-Token", "t")
	if code != apperr.CodeBusinessParam {
		t.Fatalf("重复报名 = %d（%s），期望 3140（已在读报课）", code, msg)
	}
	var count int64
	db.Model(&model.CoursesStudent{}).Where("courses_id = ? AND student_id = ?", course.ID, courseTestStudent).Count(&count)
	if count != 1 {
		t.Fatalf("报课行数 = %d，期望 1", count)
	}

	// 跨校区报名 → 1004（作用域校区 10，传入 99）
	crossBody := map[string]any{
		"userId": courseTestOther, "pay": "100.00", "lessonCost": "100.00", "campusId": 99,
	}
	if code, msg, _ := doJSON(t, app, fiber.MethodPost, path, crossBody, "X-Test-Token", "t"); code != infraerrors.ErrUnscoped.Code {
		t.Fatalf("跨校区报名 = %d（%s），期望 1004", code, msg)
	}
}

// ---------------------------------------------------------------- 端点 55：欠费列表

// TestArrearsListUsesRemainderReceivable **本端点最容易写错、且写错不会报错的一处**。
//
// 两条数据：
//
//	A：remainder_receivable=50.00 且 unpaid=0.00  ← **真欠费**（用 unpaid 判会被漏掉）
//	B：remainder_receivable=0.00  且 unpaid=999.00 ← **不欠费**（用 unpaid 判会被误报）
//
// 变红条件：判据换成 `unpaid > 0` → 列表里出现 B、且不含 A（两条断言同时红）。
func TestArrearsListUsesRemainderReceivable(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "英语K", 10)
	seedEnrollment(t, db, course.ID, courseTestStudent, "ARR-1", "100.00", "300.00", "250.00", "50.00", "0.00")
	seedEnrollment(t, db, course.ID, courseTestOther, "ARR-2", "100.00", "300.00", "300.00", "0.00", "999.00")
	app := newCourseTestApp(t, db)

	code, msg, data := doJSON(t, app, fiber.MethodGet, PathCourseArrears, nil, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("欠费列表 = %d（%s），期望 200", code, msg)
	}
	items := pageList(t, data)
	if len(items) != 1 {
		t.Fatalf("欠费行数 = %d，期望 1（只有 remainder_receivable>0 的那条）：%s", len(items), string(data))
	}
	row, _ := items[0].(map[string]any)
	if got, _ := row["studentId"].(string); got != courseTestStudent {
		t.Fatalf("欠费学生 = %v，期望 %s —— 若为 %s 说明判据用了废弃列 unpaid",
			row["studentId"], courseTestStudent, courseTestOther)
	}
	if got, _ := row["remainderReceivable"].(string); got != "50.00" {
		t.Fatalf("remainderReceivable = %v，期望 \"50.00\"", row["remainderReceivable"])
	}
	if got, _ := row["courseId"].(float64); got != float64(course.ID) {
		t.Fatalf("courseId = %v，期望 %d", row["courseId"], course.ID)
	}
	if _, has := row["unpaid"]; has {
		t.Fatalf("欠费列表下发了 unpaid：废弃列禁下发（设计 §3.8-E4）")
	}
}

// ---------------------------------------------------------------- 端点 56：欠费核销

// TestCounteractArrearsWritesBothColumns 端点 56：`net_receipts` 增、`remainder_receivable` 减（同一条 UPDATE）；
// 跨机构 → 1004。
//
// 变红条件：只写一列（实收加了、应收没减）→ 两列断言之一红；去掉机构校验 → 1004 用例红。
func TestCounteractArrearsWritesBothColumns(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "数学L", 10)
	// SP27 的候选集要 INNER JOIN t_courses_class（按 courses_id + class_id），故必须有一条规则
	seedClassRule(t, db, course.ID, 7001, courseTestTeacher, "1", model.CoursesClassStatusOngoing, "09:00", "10:00")
	enroll := seedEnrollment(t, db, course.ID, courseTestStudent, "CARR-1", "100.00", "300.00", "200.00", "100.00", "0.00")
	// SP27 的候选集是 `t1 INNER JOIN t_courses_class ON (coursesid, classid)` ⇒ 报课行的
	// class_id 必须与排班规则一致，否则候选集为空（核销变成静默 no-op）
	if err := db.Model(&model.CoursesStudent{}).Where("id = ?", enroll.ID).
		UpdateColumn("class_id", 7001).Error; err != nil {
		t.Fatalf("对齐报课行 class_id 失败: %v", err)
	}
	app := newCourseTestApp(t, db)

	body := map[string]any{
		"studentId": courseTestStudent, "institutionId": 1, "campusId": 10, "money": "60.00",
	}
	code, msg, data := doJSON(t, app, fiber.MethodPost, PathCourseArrearsCounteract, body, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("欠费核销 = %d（%s），期望 200", code, msg)
	}
	payload := jsonMap(t, data)
	if counteracted, _ := payload["counteracted"].(bool); !counteracted {
		t.Fatalf("counteracted = %v，期望 true", payload["counteracted"])
	}
	if got, _ := payload["amount"].(string); got != "60.00" {
		t.Fatalf("amount = %v，期望 \"60.00\"（实际核销额）", payload["amount"])
	}
	var row struct {
		NetReceipts string `gorm:"column:net_receipts"`
		Remainder   string `gorm:"column:remainder_receivable"`
	}
	if err := db.Raw("SELECT net_receipts, remainder_receivable FROM t_courses_student WHERE id = ?", enroll.ID).
		Scan(&row).Error; err != nil {
		t.Fatalf("回读报课行失败: %v", err)
	}
	requireMoney(t, "net_receipts", row.NetReceipts, "260.00")      // 200 + 60
	requireMoney(t, "remainder_receivable", row.Remainder, "40.00") // 100 - 60（只加实收不减应收是典型错法）

	// 跨机构（作用域机构 1，传入 2）→ 1004
	crossBody := map[string]any{
		"studentId": courseTestStudent, "institutionId": 2, "campusId": 10, "money": "10.00",
	}
	if code, msg, _ := doJSON(t, app, fiber.MethodPost, PathCourseArrearsCounteract, crossBody, "X-Test-Token", "t"); code != infraerrors.ErrUnscoped.Code {
		t.Fatalf("跨机构核销 = %d（%s），期望 1004", code, msg)
	}
}

// ---------------------------------------------------------------- 端点 57：学生课表

// TestStudentScheduleIsPerStudent 端点 57：课表按学生过滤（另一个学生报的课不得出现）；跨用户查 → 1004。
//
// 变红条件：漏掉 `s.student_id = ?` 过滤 → 两个学生都会看到两门课（行数 2）。
func TestStudentScheduleIsPerStudent(t *testing.T) {
	db := newCourseTestDB(t)
	mine := seedCourse(t, db, "我的课", 10)
	other := seedCourse(t, db, "别人的课", 10)
	seedEnrollment(t, db, mine.ID, courseTestStudent, "SCH-1", "100.00", "100.00", "100.00", "0.00", "0.00")
	seedEnrollment(t, db, other.ID, courseTestOther, "SCH-2", "100.00", "100.00", "100.00", "0.00", "0.00")
	mineRecord := seedRecord(t, db, mine.ID, 8001, "SCHREC-1", model.CoursesRecordStatusOngoing,
		time.Date(2026, 11, 20, 9, 0, 0, 0, time.Local))
	seedRecord(t, db, other.ID, 8002, "SCHREC-2", model.CoursesRecordStatusOngoing,
		time.Date(2026, 11, 20, 11, 0, 0, 0, time.Local))
	// 本人已打卡 → cost 回显
	att := &model.CoursesRecordStudent{
		BizNo: "SCHATT-1", CoursesID: mine.ID, ClassID: 8001, InstitutionID: 1, CampusID: 10,
		RecordID: mineRecord.ID, StudentID: courseTestStudent, Type: model.CoursesRecordStudentTypeNormal,
		StartTime: *mineRecord.StartTime, Cost: "100.00", GiveCost: "10.00",
		Pay: model.CoursesRecordStudentPayPaid,
	}
	if err := db.Create(att).Error; err != nil {
		t.Fatalf("建打卡行失败: %v", err)
	}
	app := newCourseTestApp(t, db)

	code, msg, data := doJSON(t, app, fiber.MethodGet, PathStudentSchedule, nil,
		"X-Test-Token", "t", "X-Test-Scope", "student")
	if code != 200 {
		t.Fatalf("学生课表 = %d（%s），期望 200", code, msg)
	}
	items := pageList(t, data)
	if len(items) != 1 {
		t.Fatalf("课表行数 = %d，期望 1（只含本人报名的课程）—— 2 说明漏了 student_id 过滤：%s",
			len(items), string(data))
	}
	row, _ := items[0].(map[string]any)
	if got, _ := row["courseId"].(float64); got != float64(mine.ID) {
		t.Fatalf("courseId = %v，期望 %d（本人课程）", row["courseId"], mine.ID)
	}
	if checked, _ := row["checked"].(bool); !checked {
		t.Fatalf("checked = false，期望 true（本人已有打卡行）")
	}
	if got, _ := row["cost"].(string); got != "100.00" {
		t.Fatalf("cost = %v，期望 \"100.00\"", row["cost"])
	}
	if got, _ := row["courseName"].(string); got != "我的课" {
		t.Fatalf("courseName = %v，期望 我的课", row["courseName"])
	}

	// 学生查别人 → 1004
	if code, msg, _ := doJSON(t, app, fiber.MethodGet,
		PathStudentSchedule+"?userId="+courseTestOther, nil,
		"X-Test-Token", "t", "X-Test-Scope", "student"); code != infraerrors.ErrUnscoped.Code {
		t.Fatalf("学生查他人课表 = %d（%s），期望 1004", code, msg)
	}
}

// ---------------------------------------------------------------- 端点 51：结束上课（跨 5 表）

// courseFinishFixture 端点 51 的完整夹具（结课链路的五张表全部就位）。
type courseFinishFixture struct {
	Course      *model.Courses
	Record      *model.CoursesRecord
	Enroll      *model.CoursesStudent
	DetailID    int64
	Recommender string
	Upline      string
}

// seedFinishFixture 造一节课的完整数据：资金双账户 + 报课行 + 排班实例 + 分账树 + 课酬方案。
//
// 关键设计（每条都对应一个断言）：
//   - 报课行 lesson_cost=100 → 全勤结课的 cost 应为 100.00；
//   - 分账树：推荐人 A 的上级 B 的 quota=20.00 → 结课后 B 应入账 20.00；
//   - 课酬方案：命中 detail 的 reward=100.00 → record.teacher_reward 应为 100.00 且 detailId == 该行 ID。
func seedFinishFixture(t *testing.T, db *gorm.DB) *courseFinishFixture {
	t.Helper()
	// ① 课程 + 分类（课酬匹配要用 class_type）
	classify := &model.CoursesClassify{
		InstitutionID: 1, CampusID: 10, ClassType: 1000, GradeID: 0, SubjectID: 0,
		Name: "集体班", UnitPrice: "100.00", MinPeople: 1, MaxPeople: 10,
	}
	if err := db.Create(classify).Error; err != nil {
		t.Fatalf("建分类失败: %v", err)
	}
	course := &model.Courses{
		InstitutionID: 1, CampusID: 10, ClassifyID: classify.ID, Name: "结课测试课",
		Status: model.CoursesStatusOngoing, Number: 10, Duration: "1.0", Week: "-1",
		OriginalCost: "100.00", RealPrice: "100.00", DiscountCash: "0.00",
	}
	if err := db.Create(course).Error; err != nil {
		t.Fatalf("建课程失败: %v", err)
	}
	// ② 资金双账户（spend 统计列的累加对象）
	if err := db.Create(&model.UserExpense{
		UserID: courseTestStudent, Balance: "1000.00", Spend: "0.00",
		TotalIncome: "1000.00", TotalExpenditure: "0.00",
		TotalRecommendedAmount: "0.00", SpecialExpenses: "0.00",
	}).Error; err != nil {
		t.Fatalf("建全局账户失败: %v", err)
	}
	if err := db.Create(&model.UserExpenseSchool{
		UserID: courseTestStudent, InstitutionID: 1, CampusID: 10, Balance: "500.00", Spend: "0.00",
		TotalIncome: "500.00", TotalExpenditure: "0.00",
		TotalRecommendedAmount: "0.00", SpecialExpenses: "0.00",
	}).Error; err != nil {
		t.Fatalf("建校区账户失败: %v", err)
	}
	// ③ 报课行（带推荐人 → 结课触发分账）
	confirm := courseTestOperator
	recommender := courseTestRecommender
	enroll := &model.CoursesStudent{
		BizNo: "FINISH-ENROLL-1", CoursesID: course.ID, ClassID: 9001,
		InstitutionID: 1, CampusID: 10, StudentID: courseTestStudent,
		Type: model.CoursesStudentTypeNormal, Status: model.CoursesStudentStatusNormal,
		Receivable: "1000.00", NetReceipts: "1000.00", Unpaid: "0.00",
		LessonCost: "100.00", Number: 10, FinishedNumber: 0, DiscountCash: "0.00",
		GiveNumber: 0, GiveCost: "0.00", RemainderNumber: 10, RemainderCost: "1000.00",
		RemainderReceivable: "0.00", BadDebt: "0.00",
		ConfirmDiscountUserID: &confirm, RecommenderUserID: &recommender,
	}
	if err := db.Create(enroll).Error; err != nil {
		t.Fatalf("建报课行失败: %v", err)
	}
	// ④ 排班实例（上课中）
	record := seedRecord(t, db, course.ID, 9001, "FINISH-REC-1", model.CoursesRecordStatusOngoing,
		time.Now().Add(-time.Hour))
	// ⑤ 分账树：B（根，quota 20）→ A（推荐人）
	parent := courseTestUpline
	root := courseTestUpline
	if err := db.Create(&model.UserDivideInto{
		UserID: courseTestUpline, Type: model.DivideTypePerLesson, Quota: "20.00", TotalIncome: "0.00",
		RootUserID: &root, ParentUserID: nil, LeftVal: 1, RightVal: 4, Layer: 1,
	}).Error; err != nil {
		t.Fatalf("建分账根节点失败: %v", err)
	}
	if err := db.Create(&model.UserDivideInto{
		UserID: courseTestRecommender, Type: model.DivideTypePerLesson, Quota: "0.00", TotalIncome: "0.00",
		RootUserID: &root, ParentUserID: &parent, LeftVal: 2, RightVal: 3, Layer: 2,
	}).Error; err != nil {
		t.Fatalf("建推荐人节点失败: %v", err)
	}
	// ⑥ 课酬方案 + 规则（命中：reward=100.00）
	effect := time.Now().AddDate(0, 0, -30)
	scheme := &model.CoursePayment{
		InstitutionID: 1, CampusID: 10, Actived: true, EffectDate: &effect,
	}
	if err := db.Create(scheme).Error; err != nil {
		t.Fatalf("建课酬方案失败: %v", err)
	}
	detail := &model.CoursePaymentDetail{
		CoursePaymentID: scheme.ID, GradeID: -1, SubjectID: -1, ClassType: 1000, ClassifyID: 0,
		Percentage: "0.0", MinPayment: "0.00", MaxPayment: "0.00", Reward: "100.00",
		TeacherCert: false, TeacherExpMin: "0.000", TeacherExpMax: "100.000", Actived: true,
	}
	if err := db.Create(detail).Error; err != nil {
		t.Fatalf("建课酬规则失败: %v", err)
	}
	return &courseFinishFixture{
		Course: course, Record: record, Enroll: enroll,
		DetailID: detail.ID, Recommender: courseTestRecommender, Upline: courseTestUpline,
	}
}

// TestFinishRecordCrossTableLinkage 端点 51：**一次调用 = 五张表联动**，逐表断言。
//
// 变红矩阵（每条断言对应一种真实错法）：
//
//	① t_courses_record_student.cost/give_cost/teacher_reward  → 漏写打卡行/课酬分摊
//	② t_user_expense.spend                                    → 漏累加全局统计列
//	③ t_user_expense_school.spend                             → 只加了全局、漏了校区
//	④ t_user_divide_into_log（money=quota）+ total_income      → 分账未入账/入错金额
//	⑤ t_courses_record（status=2 + income + teacher_reward）   → 汇总列没落/落错
//	⑥ t_courses_student（finished_number/remainder_*）         → 扣课时没扣
func TestFinishRecordCrossTableLinkage(t *testing.T) {
	db := newCourseTestDB(t)
	fx := seedFinishFixture(t, db)
	app := newCourseTestApp(t, db)

	code, msg, data := doJSON(t, app, fiber.MethodPost,
		"/admin/courses/records/"+itoa(fx.Record.ID)+"/finish", map[string]any{}, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("结束上课 = %d（%s），期望 200", code, msg)
	}
	payload := jsonMap(t, data)
	if got, _ := payload["status"].(float64); got != float64(model.CoursesRecordStatusFinished) {
		t.Fatalf("status = %v，期望 2", payload["status"])
	}
	if changed, _ := payload["changed"].(bool); !changed {
		t.Fatalf("changed = false，期望 true（首次结课必须真的写库）")
	}
	if got, _ := payload["totalSpend"].(string); got != "100.00" {
		t.Fatalf("totalSpend = %v，期望 \"100.00\"", payload["totalSpend"])
	}
	payroll, _ := payload["payroll"].(map[string]any)
	if got, _ := payroll["reward"].(string); got != "100.00" {
		t.Fatalf("payroll.reward = %v，期望 \"100.00\"（方案 reward 列）；"+
			"为 0.00 说明课酬端口没接上（quoter=nil）", payroll["reward"])
	}
	if got, _ := payroll["detailId"].(float64); got != float64(fx.DetailID) {
		t.Fatalf("payroll.detailId = %v，期望 %d（命中的课酬规则 ID）", payroll["detailId"], fx.DetailID)
	}
	divide, _ := payload["divide"].([]any)
	if len(divide) != 1 {
		t.Fatalf("divide 条数 = %d，期望 1（推荐人的上级应入账）：%s", len(divide), string(data))
	}
	d0, _ := divide[0].(map[string]any)
	if got, _ := d0["amount"].(string); got != "20.00" {
		t.Fatalf("divide[0].amount = %v，期望 \"20.00\"（源列 money）", d0["amount"])
	}
	if got, _ := d0["userId"].(string); got != fx.Upline {
		t.Fatalf("divide[0].userId = %v，期望 %s", d0["userId"], fx.Upline)
	}
	// 裁决后形状 `{userId, type, amount}`：type 必须来自日志行的 `type`（夹具用 type=2 按课次）
	if got, _ := d0["type"].(float64); got != float64(model.DivideTypePerLesson) {
		t.Fatalf("divide[0].type = %v，期望 %d（源列 type = 按课次）", d0["type"], model.DivideTypePerLesson)
	}
	// 防回潮：`level`/`quota` 无对应列，**任何形式的下发都不允许**（包括"填常量让它看起来有值"）
	for _, forbidden := range []string{"level", "quota"} {
		if v, has := d0[forbidden]; has {
			t.Fatalf("divide[0] 下发了 %q=%v：该字段在 t_user_divide_into_log 里没有对应列，"+
				"填常量顶替属伪造历史（团队裁决已删）", forbidden, v)
		}
	}

	// ① 打卡行三列
	var att struct {
		Cost     string     `gorm:"column:cost"`
		GiveCost string     `gorm:"column:give_cost"`
		Reward   string     `gorm:"column:teacher_reward"`
		EndTime  *time.Time `gorm:"column:end_time"`
	}
	if err := db.Raw(`SELECT cost, give_cost, teacher_reward, end_time FROM t_courses_record_student
		WHERE record_id = ? AND student_id = ?`, fx.Record.ID, courseTestStudent).Scan(&att).Error; err != nil {
		t.Fatalf("回读打卡行失败: %v", err)
	}
	requireMoney(t, "打卡行 cost", att.Cost, "100.00")
	requireMoney(t, "打卡行 give_cost", att.GiveCost, "0.00")
	requireMoney(t, "打卡行 teacher_reward", att.Reward, "100.00")
	if att.EndTime == nil {
		t.Fatalf("打卡行 end_time 为空：非空才是「已完成」（分成归属判据）")
	}

	// ② 全局账户 spend（**balance 必须不动**）
	var global struct {
		Spend   string `gorm:"column:spend"`
		Balance string `gorm:"column:balance"`
	}
	if err := db.Raw("SELECT spend, balance FROM t_user_expense WHERE user_id = ?", courseTestStudent).
		Scan(&global).Error; err != nil {
		t.Fatalf("回读全局账户失败: %v", err)
	}
	requireMoney(t, "t_user_expense.spend", global.Spend, "100.00")      // 漏累加统计列
	requireMoney(t, "t_user_expense.balance", global.Balance, "1000.00") // spend 是统计列，**不得动 balance**

	// ③ 校区账户 spend
	var school struct {
		Spend string `gorm:"column:spend"`
	}
	if err := db.Raw("SELECT spend FROM t_user_expense_school WHERE user_id = ? AND campus_id = 10",
		courseTestStudent).Scan(&school).Error; err != nil {
		t.Fatalf("回读校区账户失败: %v", err)
	}
	requireMoney(t, "t_user_expense_school.spend", school.Spend, "100.00") // 只加全局漏了校区

	// ④ 分账明细 + total_income
	var divideRow struct {
		UserID  string `gorm:"column:user_id"`
		Money   string `gorm:"column:money"`
		OrderNo string `gorm:"column:order_no"`
	}
	if err := db.Raw("SELECT user_id, money, order_no FROM t_user_divide_into_log WHERE student_id = ?",
		courseTestStudent).Scan(&divideRow).Error; err != nil {
		t.Fatalf("回读分账明细失败: %v", err)
	}
	if divideRow.UserID != fx.Upline {
		t.Fatalf("分账明细 user = %s，期望 %s", divideRow.UserID, fx.Upline)
	}
	requireMoney(t, "分账明细 money", divideRow.Money, "20.00")
	if divideRow.OrderNo != itoa(fx.Record.ID) {
		t.Fatalf("分账 order_no = %q，期望上课记录 ID %d（按课次幂等键）", divideRow.OrderNo, fx.Record.ID)
	}
	var upline struct {
		TotalIncome string `gorm:"column:total_income"`
	}
	if err := db.Raw("SELECT total_income FROM t_user_divide_into WHERE user_id = ?", fx.Upline).
		Scan(&upline).Error; err != nil {
		t.Fatalf("回读分账节点失败: %v", err)
	}
	requireMoney(t, "t_user_divide_into.total_income", upline.TotalIncome, "20.00")

	// ⑤ record 汇总列
	var rec struct {
		Status        int32  `gorm:"column:status"`
		Income        string `gorm:"column:income"`
		TeacherReward string `gorm:"column:teacher_reward"`
		StudentNumber int32  `gorm:"column:student_number"`
	}
	if err := db.Raw("SELECT status, income, teacher_reward, student_number FROM t_courses_record WHERE id = ?",
		fx.Record.ID).Scan(&rec).Error; err != nil {
		t.Fatalf("回读实例失败: %v", err)
	}
	if rec.Status != model.CoursesRecordStatusFinished || rec.StudentNumber != 1 {
		t.Fatalf("record = status %d / students %d，期望 2/1", rec.Status, rec.StudentNumber)
	}
	requireMoney(t, "record.income", rec.Income, "100.00")
	requireMoney(t, "record.teacher_reward", rec.TeacherReward, "100.00")

	// ⑥ 扣课时
	var enrollment struct {
		Finished      int32  `gorm:"column:finished_number"`
		Remainder     int32  `gorm:"column:remainder_number"`
		RemainderCost string `gorm:"column:remainder_cost"`
	}
	if err := db.Raw(`SELECT finished_number, remainder_number, remainder_cost FROM t_courses_student
		WHERE id = ?`, fx.Enroll.ID).Scan(&enrollment).Error; err != nil {
		t.Fatalf("回读报课行失败: %v", err)
	}
	if enrollment.Finished != 1 || enrollment.Remainder != 9 {
		t.Fatalf("扣课时 = finished %d / remainder %d，期望 1/9", enrollment.Finished, enrollment.Remainder)
	}
	requireMoney(t, "remainder_cost", enrollment.RemainderCost, "900.00")

	// 幂等：再结一次 → changed=false，且分账**不重复入账**
	code, msg, data = doJSON(t, app, fiber.MethodPost,
		"/admin/courses/records/"+itoa(fx.Record.ID)+"/finish", map[string]any{}, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("重复结课 = %d（%s），期望 200（幂等成功）", code, msg)
	}
	if changed, _ := jsonMap(t, data)["changed"].(bool); changed {
		t.Fatalf("重复结课 changed = true，期望 false（幂等命中：本次未写任何表）")
	}
	var logCount int64
	db.Model(&model.UserDivideIntoLog{}).Where("student_id = ?", courseTestStudent).Count(&logCount)
	if logCount != 1 {
		t.Fatalf("分账明细条数 = %d，期望 1（重复结课不得重复入账）", logCount)
	}
}

// TestFinishRecordRollsBackWhenDivideFails 端点 51 的**回滚变异**：让第 3 步（分账）失败，
// 断言前两步（扣课时 / spend / 打卡行）**全部回滚**。
//
// 手法：请求前 `DROP TABLE t_user_divide_into_log` ⇒ 结课事务内 INSERT 分账明细必然失败。
// 为什么不用"注入错误"：handler 层测试无法替换内部服务（`servicesFor` 现场构造），
// 而 DROP 表是**真实基础设施故障**的同构复现（表不存在 = SQL 报错 = 事务回滚）。
//
// 变红条件：把分账放到事务外（或吞掉错误）→ 断言 1 变红（接口返回 200），断言 2~5 变红（数据已落库）。
func TestFinishRecordRollsBackWhenDivideFails(t *testing.T) {
	db := newCourseTestDB(t)
	fx := seedFinishFixture(t, db)
	if err := db.Exec("DROP TABLE t_user_divide_into_log").Error; err != nil {
		t.Fatalf("删分账明细表失败: %v", err)
	}
	app := newCourseTestApp(t, db)

	code, msg, _ := doJSON(t, app, fiber.MethodPost,
		"/admin/courses/records/"+itoa(fx.Record.ID)+"/finish", map[string]any{}, "X-Test-Token", "t")
	// 断言 1：分账失败必须让整个请求失败，且**必须是数据库级失败**。
	//
	// 为什么钉死成 5002：夹具数据全部合法（实例存在且上课中、有在读学生、有课酬方案），
	// 唯一缺失的是分账明细表 ⇒ 能导致失败的只可能是第 ④ 步的 INSERT。
	// 若这里变成 2001/3121/3001，说明失败发生在第 ④ 步**之前**，该用例就退化成"空断言"。
	if code == 200 {
		t.Fatalf("分账失败时结课仍返回 200（%s）：分账没在结课事务内", msg)
	}
	if code != infraerrors.ErrDBError.Code {
		t.Fatalf("失败码 = %d（%s），期望 5002（数据库异常）——"+
			"若不是 5002，说明失败发生在前几步，回滚断言会变成空断言", code, msg)
	}

	// 断言 2：报课行扣课时**必须回滚**
	var enrollment struct {
		Finished      int32  `gorm:"column:finished_number"`
		Remainder     int32  `gorm:"column:remainder_number"`
		RemainderCost string `gorm:"column:remainder_cost"`
	}
	if err := db.Raw(`SELECT finished_number, remainder_number, remainder_cost FROM t_courses_student
		WHERE id = ?`, fx.Enroll.ID).Scan(&enrollment).Error; err != nil {
		t.Fatalf("回读报课行失败: %v", err)
	}
	if enrollment.Finished != 0 || enrollment.Remainder != 10 {
		t.Fatalf("扣课时未回滚：finished %d / remainder %d，期望 0/10",
			enrollment.Finished, enrollment.Remainder)
	}
	requireMoney(t, "remainder_cost（回滚后）", enrollment.RemainderCost, "1000.00")

	// 断言 3 / 4：两个账户的 spend 必须回滚
	var global struct {
		Spend string `gorm:"column:spend"`
	}
	db.Raw("SELECT spend FROM t_user_expense WHERE user_id = ?", courseTestStudent).Scan(&global)
	requireMoney(t, "t_user_expense.spend（回滚后）", global.Spend, "0.00")
	var school struct {
		Spend string `gorm:"column:spend"`
	}
	db.Raw("SELECT spend FROM t_user_expense_school WHERE user_id = ? AND campus_id = 10", courseTestStudent).Scan(&school)
	requireMoney(t, "t_user_expense_school.spend（回滚后）", school.Spend, "0.00")

	// 断言 5：打卡行不得留下 cost>0 的痕迹
	var att struct {
		Cost string `gorm:"column:cost"`
	}
	db.Raw(`SELECT cost FROM t_courses_record_student WHERE record_id = ? AND student_id = ?`,
		fx.Record.ID, courseTestStudent).Scan(&att)
	if strings.TrimSpace(att.Cost) != "" {
		amount, perr := money.Parse(att.Cost)
		if perr != nil || amount.Cents() != 0 {
			t.Fatalf("打卡行 cost = %q，期望无行或 0.00（未随失败回滚）", att.Cost)
		}
	}

	// 断言 6：实例状态不得变成已结束
	var rec struct {
		Status int32 `gorm:"column:status"`
	}
	db.Raw("SELECT status FROM t_courses_record WHERE id = ?", fx.Record.ID).Scan(&rec)
	if rec.Status == model.CoursesRecordStatusFinished {
		t.Fatalf("实例 status = 2，期望仍为 1（未随失败回滚）")
	}
}

// ---------------------------------------------------------------- 作用域 / 鉴权冒烟

// TestCourseEndpointsRequireScope 15 条课程端点全部要求作用域（无 scope → 1001）。
//
// 这条防的是"某条端点漏挂 mustScope"（无作用域时 Scoped 会 panic → 5001，
// 而 5001 看起来像"服务故障"，会让人去查 DB 而不是查中间件链）。
func TestCourseEndpointsRequireScope(t *testing.T) {
	db := newCourseTestDB(t)
	app := newCourseTestApp(t, db)
	cases := []struct {
		method string
		path   string
	}{
		{fiber.MethodGet, PathCourses},
		{fiber.MethodPost, PathCourses},
		{fiber.MethodPut, "/admin/courses/1"},
		{fiber.MethodGet, "/admin/courses/1/classes"},
		{fiber.MethodPost, "/admin/courses/1/classes"},
		{fiber.MethodGet, "/admin/courses/1/records"},
		{fiber.MethodPost, "/admin/courses/1/records/generate"},
		{fiber.MethodPost, "/admin/courses/records/1/start"},
		{fiber.MethodPost, "/admin/courses/records/1/finish"},
		{fiber.MethodPost, "/admin/courses/records/1/attendance"},
		{fiber.MethodGet, "/admin/courses/1/students"},
		{fiber.MethodPost, "/admin/courses/1/students"},
		{fiber.MethodGet, PathCourseArrears},
		{fiber.MethodPost, PathCourseArrearsCounteract},
		{fiber.MethodGet, PathStudentSchedule},
	}
	for _, tc := range cases {
		code, msg, _ := doJSON(t, app, tc.method, tc.path, nil, "X-Test-Token", "t", "X-Test-Scope", "none")
		if code != infraerrors.ErrUnauth.Code {
			t.Errorf("%s %s 无作用域时 code = %d（%s），期望 1001", tc.method, tc.path, code, msg)
		}
	}
}