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

// ---------------------------------------------------------------- 端点 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）。
	Mode string `json:"mode" validate:"required"`
}