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

// 课酬 / 维护 端点请求 DTO（端点 59、61、62、63）——AC-13d 第一批。
//
// 依据：unified/03-migration/academic-frontend-contract-v1.md §2.5（端点表）/ §3.4 D 表（字段级）；
// 设计 `academic-domain-design.md` §4.5（端点清单与角色）/ §3.5（SP28/SP29）/ §3.6（SP30/SP31）。
//
// ---------------------------------------------------------------------------
// 本批**只做 59/61/62/63**，58 与 60 因契约形状冲突暂停（已登记偏差，等裁决）
// ---------------------------------------------------------------------------
//
//		58 课酬方案 —— 契约把"方案（t_course_payment）"与"明细（t_course_payment_detail）"**压成一行**：
//		   `id/schoolId/campusId/effectDate` 是方案列，`teacherId/classifyId/percentage/min/max/reward` 是明细列，
//		   `actived` 两级都有；且 `teacherExp:number` **一个字段要承载 `teacher_exp_min` + `teacher_exp_max` 两列**。
//	  ⇒ 需要契约先回答三件事：入参是否嵌套 `details[]`、`id` 指方案还是明细、教龄区间怎么表达。
//	    在此之前**不落代码**（按"字段准入条件"硬门槛，写不出源列就不进契约）。
//
//		60 收支 —— 契约 `GET/POST /admin/expenditures[/types]` 把**字典**（`t_expenditure`）与
//		   **记录**（`t_expenditure_log`）放在同一组路径下，而行字段 `type/name/direction` 三个里
//		   `name`/`direction` 在记录表**不存在**（记录表只有 `expenditure_id`，方向要 JOIN 字典的 `type`）；
//		   `bizNo` 只在记录表有。⇒ 需要契约把"字典"与"记录"的响应分别定义（当前一行行结构无法同时满足两者）。
//
// 下面四个端点的字段全部可逐列溯源，故先行落地。
package handler

import "time"

// ---------------------------------------------------------------- 端点 59：课酬试算

// PayrollQuoteReq 端点 59 课酬试算请求体（`POST /admin/payroll/quote`）。
//
// 契约 §2.5 行 59 原文入参：`teacherId,schoolId,campusId,classifyId,teacherExp,date`（六个都必填）。
//
// ⚠ **本端点无法给出"最终课酬金额"**：最终金额还需要 `income`（本次课收入）、`studentCount`、
// `teacherRewardType` 三个入参，契约没给 ⇒ 本端点只返回**命中的规则**（含 percentage/min/max/reward），
// 由前端自行展示；**最终金额只在结课（端点 51）产生**，两者共用同一 `computeRecordReward`（不重复实现公式）。
// 已在交付报告登记为偏差（若产品要"试算金额"，契约补三个入参即可）。
type PayrollQuoteReq struct {
	// TeacherID 老师 ULID（必填）。
	TeacherID string `json:"teacherId" validate:"required,max=26"`
	// SchoolID 机构 ID（必填 >0；旧口径 schoolid = 目标态 institution_id）。
	SchoolID int64 `json:"schoolId" validate:"required,gt=0"`
	// CampusID 校区 ID（0 = 机构级方案；契约要求必传，0 合法）。
	CampusID int64 `json:"campusId"`
	// ClassifyID 课程分类 ID（必填 >0；提供 grade/subject/class_type 三个维度）。
	ClassifyID int64 `json:"classifyId" validate:"required,gt=0"`
	// TeacherExp 教龄（年；可含小数；负数按 0，与 dump 763609 一致）。
	TeacherExp float64 `json:"teacherExp"`
	// Date 试算日期（`2006-01-02` 或 RFC3339；方案 `effect_date <= date`，**含当日**）。
	Date string `json:"date" validate:"required"`
}

// payrollQuoteView 端点 59 响应（契约 §4.6 `PayrollQuote` 的 9 个字段，**不得裁掉溯源字段**）。
//
// 字段来源（逐列溯源）：
//
//	detailId       ← t_course_payment_detail.id
//	schemeId       ← t_course_payment.id
//	schemeCampusId ← t_course_payment.campus_id（0 = 机构级方案）
//	schemeScope    ← 由命中层级推导（campus | institution）——**不是列**，而是"从哪个 campus_id 查到的"
//	ruleTier       ← 由命中规则类型推导（personal_classify | personal_grade_subject | cert_general | nocert_general）
//	percentage     ← t_course_payment_detail.percentage（**百分数字符串**，非金额）
//	min            ← min_payment；max ← max_payment；reward ← reward
//
// `schemeScope` / `ruleTier` 属**可推导的溯源标签**（不是新造业务值）：它们回答"这条规则为什么被命中"，
// 是排障必需项（§4.6 v0.1.29 明确"不得裁掉"）。
type payrollQuoteView struct {
	// DetailID 命中的课酬明细规则 ID。
	DetailID int64 `json:"detailId"`
	// SchemeID 命中的课酬方案 ID。
	SchemeID int64 `json:"schemeId"`
	// SchemeCampusID 命中方案所属校区（0 = 机构级）。
	SchemeCampusID int64 `json:"schemeCampusId"`
	// SchemeScope 方案层级（campus / institution）。
	SchemeScope string `json:"schemeScope"`
	// RuleTier 规则层级（personal_classify / personal_grade_subject / cert_general / nocert_general）。
	RuleTier string `json:"ruleTier"`
	// Percentage 课酬比例（**百分数字符串** "85.0"，不是 0.85、不是金额）。
	Percentage string `json:"percentage"`
	// Min 最低课酬标准（元字符串；"0.00" = 不限制）。
	Min string `json:"min"`
	// Max 最高课酬标准（元字符串；"0.00" = 不限制）。
	Max string `json:"max"`
	// Reward 额外课酬（元字符串；在比例基础上追加）。
	Reward string `json:"reward"`
}

// ---------------------------------------------------------------- 端点 61 / 62 / 63：维护

// MaintenanceResultResp 维护类端点（61/62/63）的响应（契约 §3.4 D 表：`affected` + `message`）。
//
// `affected` = 本次**实际写库**的行数；`message` = 面向运维的一段人话（含"可重跑/已是最新"判据）。
// 三个端点响应同构，用同一结构体（避免三份一模一样的东西漂移）。
type MaintenanceResultResp struct {
	// Affected 本次实际影响（写入）的行数。
	Affected int64 `json:"affected"`
	// Message 结果说明（含幂等判据：第二次执行应为 0 / 已是最新）。
	Message string `json:"message"`
}

// ActivitySyncReq 端点 63 活动数据同步请求体（`POST /admin/maintenance/activity-sync`）。
//
// 契约 §2.5 行 63：`mode` ∈ {`used-log`, `signed`}；缺省/非法 → **2001**（契约明确写 2001，
// 不是 2002——因为"缺参"与"枚举非法"在这里都按"必须指定同步模式"处理）。
type ActivitySyncReq struct {
	// Mode 同步模式（`used-log` → SP30 重建 used_log；`signed` → SP31 重放 signed）。
	//
	// ⚠ **不写 `validate:"required"`**：`required` 失败统一归 2001，而本端点要把
	// "缺失"（2001）与"传了但非法"（2002）分成两个码 ⇒ 缺失由 Handler 显式判。
	Mode string `json:"mode"`
}

// ---------------------------------------------------------------- 端点 58：课酬方案 + 明细

// PayrollPlanDetailReq 明细入参（POST / PUT 共用，**两级形状的内层**）。
//
// 字段 → 目标列（`t_course_payment_detail`）：
//
//	teacherId→teacher_id / classifyId→classify_id / classType→class_type / gradeId→grade_id /
//	subjectId→subject_id / teacherCert→teacher_cert / teacherExpMin→teacher_exp_min /
//	teacherExpMax→teacher_exp_max / percentage→percentage / min→min_payment / max→max_payment /
//	reward→reward / displayName→name / detailActived→actived
//
// ⚠ 三处命名**故意与契约 mock 不同**（D17 裁决，因两表同名列会互相覆盖）：
//
//	`displayName` ← 明细 `name`（计算方式名）；方案名走 `schemeName`；
//	`detailActived` ← 明细 `actived`；方案级启用走 `actived`；
//	教龄是**区间两字段** `teacherExpMin/teacherExpMax`（单值装不下区间，且前端改档会把 max 写坏）。
type PayrollPlanDetailReq struct {
	// TeacherID 老师 ULID（空 = 通用规则；个人规则才填）。
	TeacherID string `json:"teacherId" validate:"max=26"`
	// ClassifyID 课程分类（0 = 不限定分类；个人规则精确档用）。
	ClassifyID int64 `json:"classifyId"`
	// ClassType 班级类型（对应 t_courses_classify.class_type；必填 >0）。
	ClassType int32 `json:"classType" validate:"required,gt=0"`
	// GradeID 年级（-1 = 通配；0 = 混合）。
	GradeID int32 `json:"gradeId"`
	// SubjectID 科目（-1 = 通配；0 = 混合）。
	SubjectID int32 `json:"subjectId"`
	// TeacherCert 是否持证档（true = 持证通用档；false = 通用/无证档）。
	TeacherCert bool `json:"teacherCert"`
	// TeacherExpMin 教龄区间下界（"1.000"；空 → "0.000"）。
	TeacherExpMin string `json:"teacherExpMin" validate:"max=10"`
	// TeacherExpMax 教龄区间上界（"5.000"；空 → "0.000"；**不得小于 Min**，否则 2002）。
	TeacherExpMax string `json:"teacherExpMax" validate:"max=10"`
	// Percentage 课酬比例（**百分数** "85.0" = 85%；0~100，最多 1 位小数；必填）。
	Percentage string `json:"percentage" validate:"required,max=10"`
	// Min 最低课酬标准（元字符串；可空 → "0.00" = 不限制）。
	Min string `json:"min"`
	// Max 最高课酬标准（元字符串；可空 → "0.00" = 不限制）。
	Max string `json:"max"`
	// Reward 额外课酬（元字符串；可空 → "0.00"）。
	Reward string `json:"reward"`
	// DisplayName 计算方式名称（源列 `name`；与方案名 schemeName 分开）。
	DisplayName string `json:"displayName" validate:"max=300"`
	// DetailActived 明细级启用（源列 `actived`；与方案级 actived 分开）。
	DetailActived bool `json:"detailActived"`
}

// CreatePayrollPlanReq 端点 58 新建请求体（`POST /admin/payroll/plans`）。
type CreatePayrollPlanReq struct {
	// InstitutionID 机构（非超管须与作用域一致，否则 1004）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区（0 = 机构级方案）。
	CampusID int64 `json:"campusId"`
	// SchemeName 方案名称（必填；源列 `t_course_payment.name`）。
	SchemeName string `json:"schemeName" validate:"required,max=200"`
	// EffectDate 生效日期（`2006-01-02` 或 RFC3339；可空）。
	EffectDate string `json:"effectDate"`
	// Actived 方案级启用（源列 `t_course_payment.actived`）。
	Actived bool `json:"actived"`
	// Details 明细（可空 = 只建空方案；通常至少一条）。
	Details []PayrollPlanDetailReq `json:"details"`
}

// UpdatePayrollPlanReq 端点 58 更新请求体（`PUT /admin/payroll/plans/:id`，`:id` = **方案 id**）。
//
// 语义：方案字段 nil = 不改；`details` 缺省（nil）= **不动明细**，给了（哪怕空数组）= **整体替换**。
// 用 `*[]T` 表达这个区别——只有指针能区分"没传"与"传了空数组"。
type UpdatePayrollPlanReq struct {
	// InstitutionID 机构（非超管须与作用域一致）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区（nil = 不改）。
	CampusID *int64 `json:"campusId"`
	// SchemeName 方案名称（nil = 不改）。
	SchemeName *string `json:"schemeName"`
	// EffectDate 生效日期（nil = 不改）。
	EffectDate *string `json:"effectDate"`
	// Actived 方案级启用（nil = 不改）。
	Actived *bool `json:"actived"`
	// Details 明细（nil = 不动；`[]` = 清空；非空 = 整体替换）。
	Details *[]PayrollPlanDetailReq `json:"details"`
}

// payrollPlanDetailView 端点 58 响应的明细（契约 D 表 + D17 裁决字段 + 出口定点化）。
//
// 出场口径（**三条都有"写错就红"的用例兜着**）：
//
//	teacherId    → `null`（通用档，源列 NULL）或老师 ULID；**不下发空串**（空串无法区分"通用"与"脏数据"）。
//	percentage   → 恒 1 位小数（"85.0"）。`decimal(5,1)` 的位数就是它的量纲指纹：被按金额
//	               格式化成 "85.00" 说明量纲被污染，数值恰好不变 ⇒ 只有位数断言抓得住。
//	min/max/reward、teacherExpMin/Max → 金额 2 位、教龄 3 位（`money.Amount.String()` / `FormatYears`）。
type payrollPlanDetailView struct {
	// DetailID 明细 ID（源列 `t_course_payment_detail.id`）。
	DetailID int64 `json:"detailId"`
	// TeacherID 老师 ULID（源列 `teacher_id`；NULL → `null`）。
	TeacherID *string `json:"teacherId"`
	// ClassifyID 课程分类 ID。
	ClassifyID int64 `json:"classifyId"`
	// ClassType 班级类型。
	ClassType int32 `json:"classType"`
	// GradeID 年级（-1 通配）。
	GradeID int32 `json:"gradeId"`
	// SubjectID 科目（-1 通配）。
	SubjectID int32 `json:"subjectId"`
	// TeacherCert 是否持证档。
	TeacherCert bool `json:"teacherCert"`
	// TeacherExpMin 教龄下界（源列 `teacher_exp_min`）。
	TeacherExpMin string `json:"teacherExpMin"`
	// TeacherExpMax 教龄上界（源列 `teacher_exp_max`）。
	TeacherExpMax string `json:"teacherExpMax"`
	// Percentage 课酬比例（**百分数**，非金额）。
	Percentage string `json:"percentage"`
	// Min 最低课酬（源列 `min_payment`）。
	Min string `json:"min"`
	// Max 最高课酬（源列 `max_payment`）。
	Max string `json:"max"`
	// Reward 额外课酬（源列 `reward`）。
	Reward string `json:"reward"`
	// DisplayName 计算方式名（源列 `name`）。
	DisplayName string `json:"displayName"`
	// DetailActived 明细级启用（源列 `actived`）。
	DetailActived bool `json:"detailActived"`
}

// payrollPlanView 端点 58 响应（方案 + 明细两级）。
type payrollPlanView struct {
	// ID 方案 ID（= `PUT /plans/:id` 的 `:id`）。
	ID int64 `json:"id"`
	// InstitutionID 机构（源列 `institution_id`）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区（源列 `campus_id`；0 = 机构级）。
	CampusID int64 `json:"campusId"`
	// SchemeName 方案名称（源列 `t_course_payment.name`）。
	SchemeName string `json:"schemeName"`
	// EffectDate 生效日期（源列 `effect_date`；可空 → null）。
	EffectDate *time.Time `json:"effectDate"`
	// Actived 方案级启用（源列 `t_course_payment.actived`）。
	Actived bool `json:"actived"`
	// Details 明细（空 → []）。
	Details []payrollPlanDetailView `json:"details"`
}