DEV-MERGE-LEGACY-BACKEND-2026/internal/academic/dualrun/fixture/batch3_model.go

package fixture

import (
	"database/sql"
	"time"
)

// 本文件是**第三批（org 域）的数据形状**：机构 t_institution + 校区 t_campus。
//
// 口径（已拍板）：
//   - **两张表都走 D1**：`t_school.id` → `t_institution.institution_id`、`t_school_campus.id`
//     → `t_campus.campus_id`，**原值插入**。理由：两者都是 int 自然主键、数据量极小，
//     而 institution_id / campus_id 在几十张表里是裸 int，双跑要靠 id 直接对齐；
//     走 biz_no 反而要多一跳。
//   - **只迁数据用得到的机构**，不全量迁 t_school（61905 行里 61900 行与本项目无关）。
//   - `campus_id = 0` **不建行**：0 是"机构级/未分配"的约定值（DDL 里 `campus_id ... DEFAULT 0
//     COMMENT '校区ID（0=平台级/机构级）'`），建了会让前端校区下拉框多出一个"未知校区"。

// OrgOptions 是第三批的取样参数。
type OrgOptions struct {
	// InstitutionIDs 是要迁移的机构 id 集合（D1 原值）。
	//
	// 这是**显式决策**，不是从数据里自动推导的：多迁一个机构 = 多一个孤儿机构；
	// 少迁一个 = 引用它的一整批数据变成孤儿引用。集合必须由人确认。
	InstitutionIDs []int64
	// WithAllCampuses 是否迁移所选机构的**全部**校区（true）
	// 还是只迁数据里出现过的校区（false）。默认 true：机构迁了、校区不迁会让
	// 前端校区下拉框与机构对不上，且属于 org 域自身的不一致。
	WithAllCampuses bool
	OrgSourceDB     string
}

// DefaultOrgOptions 是默认取样 = **7 个机构**。
//
// ⚠ 初版统计给的是 5 个（`SELECT DISTINCT schoolid FROM t_courses` + campus 1/2 的 school_id=1），
// 实测逐来源清点后发现**漏了 2 个**，各自都带孤儿引用：
//
//	63332（用户注册）← finance_bk.t_user_balance_request  1 行（schoolid=63332, campusid=57）
//	63330（弘毅教育）← finance_bk.t_courses_classify    1 行（schoolid=63330）
//	                    —— 这张表不在原统计的 7 个来源清单里，是靠"按列名反查"找出来的
//
// 只迁 5 个会让这两个来源各留 1 条孤儿机构 + 1 条孤儿校区（实测见报告）。
func DefaultOrgOptions() OrgOptions {
	return OrgOptions{
		InstitutionIDs:  []int64{1, 63317, 63323, 63324, 63325, 63330, 63332},
		WithAllCampuses: true,
		OrgSourceDB:     "yuansiwei_i",
	}
}

// ---------- legacy（yuansiwei_i） ----------

// LegacySchool 对应 `yuansiwei_i.t_school`。
type LegacySchool struct {
	ID              int64
	Name            string
	ProvinceID      int64
	CityID          int64
	DistrictID      int64
	GradePeriod     string
	Status          int8 // tinyint(1)：1=正常 0=停用（业务口径，见 mapping 注释）
	IsOpenUserLogin int8
}

// LegacyCampus 对应 `yuansiwei_i.t_school_campus`。
type LegacyCampus struct {
	ID              int64
	Name            string
	SchoolID        int64
	ProvinceID      int64
	CityID          int64
	DistrictID      int64
	Status          int8
	Code            sql.NullString
	SelfSupport     int8 // bit(1) → 0/1
	IsOpenUserLogin int8
}

// ---------- target ----------

// TargetInstitution 对应 `t_institution`（16 列里只用得到的那些）。
type TargetInstitution struct {
	InstitutionID   int64
	InstitutionName string
	InstitutionCode sql.NullString // legacy 无对应列 → NULL（uk_institution_code 允许多 NULL）
	Address         sql.NullString // legacy 只有省市区 id，没有地址文本 → NULL
	Phone           sql.NullString // legacy 无 → NULL
	Status          string         // active / disabled
	CreatedAt       time.Time      // legacy 无时间列 → epoch 哨兵
	UpdatedAt       time.Time
}

// TargetCampus 对应 `t_campus`。
type TargetCampus struct {
	CampusID      int64
	InstitutionID int64
	CampusName    string
	CampusCode    sql.NullString // legacy code（varchar(16)）→ campus_code
	Address       sql.NullString
	Phone         sql.NullString
	Status        string
	SelfSupport   int8 // bit(1) → TINYINT(1)
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

// ---------- 引用完整性 ----------

// RefSource 是一个「带 institution_id / campus_id 的数据来源」。
type RefSource struct {
	Table     string // finance_bk 里的表名
	InstCol   string // 机构列
	CampusCol string // 校区列（空 = 该表没有校区列）
	Note      string
}

// DisabledCampusStat 是一个**停用校区**（status=0）的影响面。
//
// 这一块单列的理由：迁过去之后这些校区是 `disabled`，挂在它们上面的历史数据
// 在"按启用校区筛选"时看不到；而 `assertInScope` 会拒绝"给停用校区新增数据"（正确）。
// 两者叠加 = 业务侧会看到"历史数据消失"，必须让业务知情，不能靠"把 status 改成 1"掩盖。
type DisabledCampusStat struct {
	CampusID       int64
	Name           string
	InstitutionID  int64
	Courses        int64
	Records        int64
	ExpenseSchool  int64
	BalanceRequest int64
	ExpenditureLog int64
}

// CrossOrgStat 是**一类**跨机构统计。
//
// 跨机构有三个不同层次的来源，混在一起报会让人看不出"到底是哪一层不一致"：
//
//	A 课程级：t_courses.schoolid          vs 该课程 campusid 的校区真实所属
//	B 记录级：t_courses_record.schoolid   vs 该记录 campusid 的校区真实所属
//	C 记录 vs 课程：t_courses_record.schoolid vs 其 coursesid 对应课程的 schoolid
//
// A/B 是"数据挂的机构 vs 校区真实所属"，C 是"记录与课程的机构是否一致"（性质不同：
// 即使校区所属一致，记录也可能挂到了另一个机构下）。
type CrossOrgStat struct {
	Key          string // A / B / C
	Name         string
	Source       string // 参与比较的两列
	Total        int64
	Skipped      int64 // campusid=0（机构级）或 join 不到，不参与判定
	Consistent   int64
	Inconsistent int64
	Samples      []string
	Note         string
}

// RefStat 是一个来源的引用统计结果。
type RefStat struct {
	Source           string
	Rows             int64 // 该表总行数
	DistinctInst     int   // distinct institution_id
	DistinctCampus   int   // distinct campus_id（不含 0）
	OrphanInst       int64 // institution_id 在 target 里找不到的行数
	OrphanCampus     int64 // campus_id != 0 但在 target 里找不到的行数
	CampusZeroRows   int64 // campus_id = 0（机构级，不建行）的行数
	OrphanInstList   []string
	OrphanCampusList []string
}