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 (
	"context"
	"encoding/json"
	"errors"
	"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"
	"yuansiwei/unified-backend/internal/academic/port"
	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 是**表级**
	// ⇒ 不清会直接建表失败。
	// ⚠ 测试库因此**放弃唯一约束**（含 `uk_biz_no` / `uk_user_inst_campus` 等）——
	// 这只是**规避 sqlite 索引名冲突**的手段：**生产 MySQL 的唯一约束照常生效**，
	// 幂等/去重行为不依赖测试库（那由 `INSERT IGNORE` + 唯一键在真库上保证）。
	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()
	return newCourseTestAppWithUsers(t, db, nil)
}

// newCourseTestAppWithUsers 同 `newCourseTestApp`，但可注入用户姓名端口（D4 用）。
//
// 入参：users `port.UserNameReader`（nil = 未注入，端点 53 的 realName 应全部为 null）。
func newCourseTestAppWithUsers(t *testing.T, db *gorm.DB, users port.UserNameReader) *fiber.App {
	t.Helper()
	h, err := New(Config{DB: db, Users: users})
	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))
	}
	// 未注入姓名端口时 `realName` 必须是 **null**（键在、值为 nil）：
	// - 不下发该键 → 前端 `row.realName` undefined 与 "" 混在一起，无法区分；
	// - 下发 "" → 把"没有这个人"和"姓名为空"混在一起。
	nameValue, hasName := row["realName"]
	if !hasName {
		t.Fatalf("响应缺少 realName 键（%s）：未注入端口时应下发 null，而不是省掉该键", string(data))
	}
	if nameValue != nil {
		t.Fatalf("realName = %v，期望 null（未注入姓名端口）", nameValue)
	}
}

// fakeUserNameReader 姓名端口测试替身（**只实现端口契约**：查不到的不进 map）。
type fakeUserNameReader struct {
	names map[string]string
	err   error
	// calls 记录调用次数（断言"批量一次"而不是逐行 N 次）
	calls int
	last  []string
}

// DisplayNames 实现 `port.UserNameReader`。
func (f *fakeUserNameReader) DisplayNames(_ context.Context, userIDs []string) (map[string]string, error) {
	f.calls++
	f.last = append([]string{}, userIDs...)
	if f.err != nil {
		return nil, f.err
	}
	out := make(map[string]string, len(userIDs))
	for _, id := range userIDs {
		if name, ok := f.names[id]; ok {
			out[id] = name
		}
	}
	return out, nil
}

// TestListCourseStudentsResolvesRealName 端点 53 的 `realName`（D4：跨域只读 port）。
//
// 三行数据覆盖三种情形：
//
//	A：端口能查到 → `realName` = 姓名
//	B：端口查不到 → `realName` = **null**（不是 ""）
//	C：端口返回空串 → 同样按"没名字"→ null（空串不该出现在响应里）
//
// 变红条件：
//   - 端口没接（仍是 null）→ A 红；
//   - 用空串兜底 → B/C 红；
//   - 逐行查询 → `calls != 1` 红（N+1）。
func TestListCourseStudentsResolvesRealName(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "姓名测试课", 10)
	const studentB = "01HSTUDENT0000000000000B"
	const studentC = "01HSTUDENT0000000000000C"
	seedEnrollment(t, db, course.ID, courseTestStudent, "NAME-1", "100.00", "300.00", "300.00", "0.00", "0.00")
	seedEnrollment(t, db, course.ID, studentB, "NAME-2", "100.00", "300.00", "300.00", "0.00", "0.00")
	seedEnrollment(t, db, course.ID, studentC, "NAME-3", "100.00", "300.00", "300.00", "0.00", "0.00")
	reader := &fakeUserNameReader{names: map[string]string{
		courseTestStudent: "张三",
		studentC:          "", // 端口返回空串：调用方必须当成"没名字"
	}}
	app := newCourseTestAppWithUsers(t, db, reader)

	code, msg, data := doJSON(t, app, fiber.MethodGet,
		"/admin/courses/"+itoa(course.ID)+"/students?pageSize=50", nil, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("报课学生列表 = %d（%s），期望 200", code, msg)
	}
	items := pageList(t, data)
	if len(items) != 3 {
		t.Fatalf("行数 = %d，期望 3", len(items))
	}
	byUser := make(map[string]map[string]any, len(items))
	for _, item := range items {
		row, _ := item.(map[string]any)
		uid, _ := row["userId"].(string)
		byUser[uid] = row
	}
	if got, _ := byUser[courseTestStudent]["realName"].(string); got != "张三" {
		t.Fatalf("A 行 realName = %v，期望 张三（端口已查到，不得为 null）",
			byUser[courseTestStudent]["realName"])
	}
	if v, ok := byUser[studentB]["realName"]; !ok || v != nil {
		t.Fatalf("B 行 realName = %v，期望 null（端口查不到；空串会让前端无法区分两种没名字）", v)
	}
	if v, ok := byUser[studentC]["realName"]; !ok || v != nil {
		t.Fatalf("C 行 realName = %v，期望 null（端口返回空串 ⇒ 等同于没名字）", v)
	}
	// 批量：一页 3 行只应调用端口 1 次（N+1 会变成 3 次）
	if reader.calls != 1 {
		t.Fatalf("姓名端口调用 %d 次，期望 1 次（批量）—— 多次说明逐行查", reader.calls)
	}
	if len(reader.last) != 3 {
		t.Fatalf("端口收到 %d 个 ID，期望 3（一页全部学生一次传入）", len(reader.last))
	}
}

// TestListCourseStudentsNameReaderFailureDegradesToNull 端口报错时**降级为 null**、列表仍 200。
//
// 为什么不让它 5002：列表页因"少一列姓名"整页失败，用户连报课/欠费都看不到——
// 展示类依赖必须可降级（与 `MembershipChecker` 那种安全依赖相反）。
func TestListCourseStudentsNameReaderFailureDegradesToNull(t *testing.T) {
	db := newCourseTestDB(t)
	course := seedCourse(t, db, "降级测试课", 10)
	seedEnrollment(t, db, course.ID, courseTestStudent, "DEGRADE-1", "100.00", "300.00", "300.00", "0.00", "0.00")
	reader := &fakeUserNameReader{err: errors.New("identity 库不可用")}
	app := newCourseTestAppWithUsers(t, db, reader)
	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 v, ok := row["realName"]; !ok || v != nil {
		t.Fatalf("realName = %v，期望 null（端口报错时降级）", v)
	}
	if got, _ := row["remainderReceivable"].(string); got != "0.00" {
		t.Fatalf("remainderReceivable = %v，期望 0.00（降级不得影响其它字段）", row["remainderReceivable"])
	}
}

// ---------------------------------------------------------------- 端点 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.CodeEnrollmentDuplicate {
		t.Fatalf("重复报名 = %d（%s），期望 3143（重复报名）", 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：课酬分摊口径（D16）

// TestFinishRecordRewardDistributionSkipsGiveRows **D16：课酬只分给 `type∈{1,2}`，赠送行恒 0**。
//
// PHP 原文（`CoursesRecordHelper.php:806-818`）：`$stuCount = count(type IN (1,2))`，
// 平摊与写回**都只针对 `type IN (1,2)`**，赠送行**永远保持 0**。
//
// 夹具：1 条 type=1（正常）+ 1 条 type=3（赠送），单节课课酬合计 = 100.00。
//
//	正确（PHP）：正常行 **100.00**、赠送行 **0.00**、Σ(type∈{1,2}) == 100.00
//	错误（除数用全部行数）：正常行 50.00、赠送行 50.00 ⇒ **多条断言同时红**
func TestFinishRecordRewardDistributionSkipsGiveRows(t *testing.T) {
	db := newCourseTestDB(t)
	fx := seedFinishFixture(t, db)
	const giveStudent = "01HSTUDENT0000000000000G"
	app := newCourseTestApp(t, db)
	code, msg, data := doJSON(t, app, fiber.MethodPost,
		"/admin/courses/records/"+itoa(fx.Record.ID)+"/finish",
		map[string]any{"items": []map[string]any{
			{"userId": courseTestStudent, "type": 1, "cost": "100.00"},
			{"userId": giveStudent, "type": 3, "cost": "0.00"},
		}}, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("结束上课（含赠送生）= %d（%s），期望 200", code, msg)
	}
	payroll, _ := jsonMap(t, data)["payroll"].(map[string]any)
	if got, _ := payroll["reward"].(string); got != "100.00" {
		t.Fatalf("payroll.reward = %v，期望 100.00（单节课课酬合计，与分摊无关）", payroll["reward"])
	}
	requireMoney(t, "正常行 teacher_reward", readTeacherReward(t, db, fx.Record.ID, courseTestStudent), "100.00")
	requireMoney(t, "赠送行 teacher_reward", readTeacherReward(t, db, fx.Record.ID, giveStudent), "0.00")
	requireMoney(t, "Σ(type∈{1,2})", readTeacherRewardSumExcludingGive(t, db, fx.Record.ID), "100.00")
	// student_number 是**全部行数**（含赠送），与平摊人数是两个数
	var studentNumber int32
	db.Raw("SELECT student_number FROM t_courses_record WHERE id = ?", fx.Record.ID).Scan(&studentNumber)
	if studentNumber != 2 {
		t.Fatalf("student_number = %d，期望 2（全部打卡行数，含赠送生）", studentNumber)
	}
}

// TestFinishRecordAllGiveClassKeepsRecordReward **D16 边界：全班赠送（stuCount=0）**。
//
// PHP 的 `if($stuCount)` 不进入 ⇒ **一行都不写**（学生行全 0），但 record 上**仍写课酬**。
// ⇒ 恒等式在这一情形**不成立**；断言只能是"所有行 0"，**不得**断言 Σ == record
// （无条件断言会让"全赠送班"恒红，最后被人改成跳过 = 把防线删掉）。
func TestFinishRecordAllGiveClassKeepsRecordReward(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{"items": []map[string]any{
			{"userId": courseTestStudent, "type": 3, "cost": "0.00"},
		}}, "X-Test-Token", "t")
	if code != 200 {
		t.Fatalf("结束上课（全班赠送）= %d（%s），期望 200", code, msg)
	}
	requireMoney(t, "赠送行 teacher_reward", readTeacherReward(t, db, fx.Record.ID, courseTestStudent), "0.00")
	payroll, _ := jsonMap(t, data)["payroll"].(map[string]any)
	if got, _ := payroll["reward"].(string); got != "100.00" {
		t.Fatalf("payroll.reward = %v，期望 100.00（全班赠送照常算课酬，只是不分摊）", payroll["reward"])
	}
	var recReward string
	db.Raw("SELECT teacher_reward FROM t_courses_record WHERE id = ?", fx.Record.ID).Scan(&recReward)
	requireMoney(t, "record.teacher_reward", recReward, "100.00")
}

// readTeacherReward 读某学生在该课的 `teacher_reward`（无行 → 空串，断言会红）。
func readTeacherReward(t *testing.T, db *gorm.DB, recordID int64, studentID string) string {
	t.Helper()
	var out struct {
		Reward string `gorm:"column:teacher_reward"`
	}
	if err := db.Raw("SELECT teacher_reward FROM t_courses_record_student WHERE record_id = ? AND student_id = ?",
		recordID, studentID).Scan(&out).Error; err != nil {
		t.Fatalf("读 teacher_reward 失败: %v", err)
	}
	return out.Reward
}

// readTeacherRewardSumExcludingGive 求和非赠送行的 `teacher_reward`（D16 条件式恒等式）。
func readTeacherRewardSumExcludingGive(t *testing.T, db *gorm.DB, recordID int64) string {
	t.Helper()
	var out struct {
		Sum string `gorm:"column:sum_reward"`
	}
	if err := db.Raw("SELECT COALESCE(SUM(teacher_reward),0) AS sum_reward FROM t_courses_record_student "+
		"WHERE record_id = ? AND type IN (1,2)", recordID).Scan(&out).Error; err != nil {
		t.Fatalf("求和非赠送行 teacher_reward 失败: %v", err)
	}
	return out.Sum
}

// ---------------------------------------------------------------- 端点 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)
	}
}

// TestFinishRecordRewardFormula 端点 51 的课酬公式 —— **逐条对齐 PHP 原文**
// （`CoursesRecordHelper.php:781-821`，权威在应用层而非 dump）。
//
// 六个子例，每个对应一条"写错就错钱"的顺序/口径：
//
//	① 纯比例：pct=85.0 → 100×85% = **85.00**
//	② 下限：85% 算出 85 < min 90 → **90.00**
//	③ 上限：pct=200 → 200 > max 150 → **150.00**
//	④ **顺序（核心）**：pct=100 + reward 50 = 150，先加再加夹 max 120 → **120.00**
//	   （错误顺序"先夹 min/max 再加 reward"会得 100+50 = 150 ⇒ 多发 30）
//	⑤ **顺序（下限侧）**：pct=0 + reward 50 = 50，夹到 min 80 → **80.00**
//	   （错误顺序会得 clamp(0)=80 + 50 = 130 ⇒ 多发 50）
//	⑥ **固定课酬 `teacher_reward_type=2`**：忽略 pct/reward，1 人 → makeupCost[1] = **70.00**
//
// 变红条件：把顺序写反（④⑤）、漏 elseif 上限优先（③）、漏 type=2 分支（⑥）、
// 把 percentage 当 0~1 比率（①）—— 任一条都会红。
func TestFinishRecordRewardFormula(t *testing.T) {
	cases := []struct {
		name       string
		percentage string
		minPayment string
		maxPayment string
		reward     string
		rewardType int8
		want       string
	}{
		{"纯比例 85%", "85.0", "0.00", "0.00", "0.00", 1, "85.00"},
		{"下限抬到 90", "85.0", "90.00", "0.00", "0.00", 1, "90.00"},
		{"上限压到 150", "200.0", "0.00", "150.00", "0.00", 1, "150.00"},
		{"顺序：先加 reward 再夹上限（reward 被吃掉）", "100.0", "0.00", "120.00", "50.00", 1, "120.00"},
		{"顺序：先加 reward 再夹下限", "0.0", "80.00", "0.00", "50.00", 1, "80.00"},
		{"固定课酬 type=2：1 人 → 70", "85.0", "0.00", "0.00", "999.00", 2, "70.00"},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			db := newCourseTestDB(t)
			fx := seedFinishFixture(t, db)
			if err := db.Model(&model.CoursePaymentDetail{}).Where("id = ?", fx.DetailID).
				Updates(map[string]any{
					"percentage":  tc.percentage,
					"min_payment": tc.minPayment,
					"max_payment": tc.maxPayment,
					"reward":      tc.reward,
				}).Error; err != nil {
				t.Fatalf("改写课酬规则失败: %v", err)
			}
			app := newCourseTestApp(t, db)
			code, msg, data := doJSON(t, app, fiber.MethodPost,
				"/admin/courses/records/"+itoa(fx.Record.ID)+"/finish",
				map[string]any{"rewardType": tc.rewardType}, "X-Test-Token", "t")
			if code != 200 {
				t.Fatalf("结束上课 = %d（%s），期望 200", code, msg)
			}
			payroll, _ := jsonMap(t, data)["payroll"].(map[string]any)
			if got, _ := payroll["reward"].(string); got != tc.want {
				t.Fatalf("payroll.reward = %v，期望 %s（percentage=%s min=%s max=%s reward=%s type=%d，课收入 100.00/1 人）",
					payroll["reward"], tc.want, tc.percentage, tc.minPayment, tc.maxPayment, tc.reward, tc.rewardType)
			}
			// 落库一致性：record.teacher_reward 与打卡行 teacher_reward 都必须等于该值
			var rec struct {
				TeacherReward string `gorm:"column:teacher_reward"`
			}
			if err := db.Raw("SELECT teacher_reward FROM t_courses_record WHERE id = ?", fx.Record.ID).
				Scan(&rec).Error; err != nil {
				t.Fatalf("回读实例失败: %v", err)
			}
			requireMoney(t, "record.teacher_reward", rec.TeacherReward, tc.want)
			var stu struct {
				TeacherReward string `gorm:"column:teacher_reward"`
			}
			if err := db.Raw("SELECT teacher_reward FROM t_courses_record_student WHERE record_id = ? AND student_id = ?",
				fx.Record.ID, courseTestStudent).Scan(&stu).Error; err != nil {
				t.Fatalf("回读打卡行失败: %v", err)
			}
			requireMoney(t, "打卡行 teacher_reward", stu.TeacherReward, tc.want)
		})
	}
}

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