DEV-MERGE-LEGACY-BACKEND-2026/internal/org/repository/institution_repo.go

// 机构仓储（T6）：t_institution 的**作用域**数据访问。
//
// 与 identity 平台级仓储的关键差异（架构规格 §3.5）：
//   - **继承 scope.BaseRepo**：t_institution 是"租户内的机构"维度资源，每次查询必须经
//     Scoping 强制过滤——多租户防线的唯一收口点在 BaseRepo.Scoping，本包禁止裸查
//     （r.DB.Where(...) 不经过 Scoping = 跨校区/跨机构越权，风险登记册项）。
//   - scoping 行为（由 scope 包保证）：
//     Sc 为 nil → panic（fail-fast，正常请求链路 Auth 中间件保证作用域已注入）；
//     SuperAdmin=true → 不加机构过滤（平台超管跨机构视角）；
//     普通用户 → 强制 institution_id = Sc.InstitutionID（CampusID>0 时再强制 campus_id，
//     对 t_institution 无 campus_id 列，该校验在 service 作用域校验层完成）。
//
// 依赖方向铁律：org repository → infra/scope + org/model + infra/errors（全下层/同域），
// 不依赖 handler/service。
package repository

import (
	"context"
	stderrors "errors"

	"gorm.io/gorm"

	"yuansiwei/unified-backend/internal/infra/errors"
	appscope "yuansiwei/unified-backend/internal/infra/scope"
	"yuansiwei/unified-backend/internal/org/model"
)

// InstitutionRepo 机构仓储（作用域强制过滤）。
type InstitutionRepo struct {
	appscope.BaseRepo
}

// NewInstitutionRepo 构造机构仓储（Handler 在拿到 Scope 后调用；db 必填、sc 可为 nil——
// nil 进入 Scoping 会 panic，属预期 fail-fast，见 scope.BaseRepo 注释）。
//
// 注：t_institution 无 campus_id 列，故 CampusScoped=false——Scoping 只加 institution_id
// 过滤（校区级用户查机构列表时，机构按其机构归属展示，不下钻到校区维度）。
func NewInstitutionRepo(db *gorm.DB, sc *appscope.Scope) *InstitutionRepo {
	r := &InstitutionRepo{BaseRepo: appscope.NewBaseRepo(db, sc)}
	r.CampusScoped = false // 机构级资源：无 campus_id 列
	return r
}

// InstitutionFilter 机构列表筛选条件（keyword 模糊匹配机构名/状态精确匹配；均可空）。
type InstitutionFilter struct {
	Keyword string
	Status  string
}

// PagedList 分页取机构列表（强制作用域过滤，防 N+1 的标准两段式由 service 决定——
// 机构表数据量小（23 所业务机构），直接单查询 Count+Find）。
//
// 入参：
//   - ctx context.Context：请求上下文（GORM WithContext 传递取消/超时）。
//   - f InstitutionFilter：筛选条件（Keyword/Status 为空则不过滤该维度）。
//   - page int：页码（从 1 开始；<1 按 1 处理）。
//   - pageSize int：每页条数（0/负数按 10 兜底——与 response.ParsePage 同语义）。
//
// 出参：
//   - []model.Institution：当前页记录（无记录时返回非 nil 空切片，JSON 序列化为 [] 而非 null）。
//   - int64：符合筛选条件的总记录数（分页器"共 N 条"）。
//   - error：*AppError——ErrDBError(5002) 数据库异常；ErrUnscoped 由 scoping panic 兜底（全局 Recover）。
//
// 样例：
//
//	list, total, err := repo.PagedList(ctx, InstitutionFilter{Keyword: "实验"}, 1, 10)
func (r *InstitutionRepo) PagedList(ctx context.Context, f InstitutionFilter, page, pageSize int) ([]model.Institution, int64, error) {
	if page < 1 {
		page = 1
	}
	if pageSize < 1 {
		pageSize = 10
	}
	q := r.Scoping(r.WithContext(ctx).Model(&model.Institution{}))
	if f.Keyword != "" {
		q = q.Where("institution_name LIKE ?", "%"+f.Keyword+"%")
	}
	if f.Status != "" {
		q = q.Where("status = ?", f.Status)
	}
	var total int64
	if err := q.Count(&total).Error; err != nil { // GORM 纪律：Count 收 *int64
		return nil, 0, errors.WithCause(errors.ErrDBError, err)
	}
	list := make([]model.Institution, 0, pageSize)
	if err := q.Order("institution_id ASC").
		Offset((page - 1) * pageSize).
		Limit(pageSize).
		Find(&list).Error; err != nil {
		return nil, 0, errors.WithCause(errors.ErrDBError, err)
	}
	return list, total, nil
}

// Get 按机构 ID 取单个机构（强制作用域过滤：非超管取别家机构 → 查不到 → ErrNotFound，
// 由 service 层进一步判定"跨机构"语义，见 OrgService.assertInScope）。
//
// 入参：ctx 请求上下文；institutionID 机构 ID（>0）。
// 出参：*model.Institution（命中）；error——ErrNotFound(3001) 不存在或作用域外 / ErrDBError(5002)。
func (r *InstitutionRepo) Get(ctx context.Context, institutionID int64) (*model.Institution, error) {
	var it model.Institution
	err := r.Scoping(r.WithContext(ctx)).
		Where("institution_id = ?", institutionID).
		First(&it).Error
	if stderrors.Is(err, gorm.ErrRecordNotFound) {
		return nil, errors.ErrNotFound
	}
	if err != nil {
		return nil, errors.WithCause(errors.ErrDBError, err)
	}
	return &it, nil
}