perms-system-server/internal/model/user/sysUserModel.go

package user

import (
	"context"
	"database/sql"
	"errors"
	"fmt"
	"strings"
	"time"

	"github.com/zeromicro/go-zero/core/logx"
	"github.com/zeromicro/go-zero/core/stores/cache"
	"github.com/zeromicro/go-zero/core/stores/sqlx"
)

var ErrUpdateConflict = errors.New("update conflict: data has been modified by another operation")

// ErrTokenVersionMismatch 表示令牌版本与数据库当前版本不一致，刷新令牌失败。
// 典型场景：refreshToken rotation 并发到达 —— 只有持有当前 tokenVersion 的那一次能原子递增成功，
// 其余全部返回该错误，防止两个请求都"换到"新令牌（导致会话劫持）。
var ErrTokenVersionMismatch = errors.New("token version mismatch")

var _ SysUserModel = (*customSysUserModel)(nil)

type (
	UserListFilter struct {
		Username string
		Nickname string
		Status   int64
		DeptId   *int64
	}

	SysUserModel interface {
		sysUserModel
		FindListByPage(ctx context.Context, page, pageSize int64) ([]*SysUser, int64, error)
		FindListByFilter(ctx context.Context, filter UserListFilter, page, pageSize int64) ([]*SysUser, int64, error)
		FindListByProductMembers(ctx context.Context, productCode string, page, pageSize int64) ([]*SysUser, map[int64]string, int64, error)
		FindByIds(ctx context.Context, ids []int64) ([]*SysUser, error)
		FindIdsByDeptId(ctx context.Context, deptId int64) ([]int64, error)
		// FindIdsByDeptIdForShareTx 在调用方事务里取目标 deptId 下所有用户 id，并对命中行加 S 锁
		// （LOCK IN SHARE MODE）。用于 UpdateDept 收窄（DEV→NORMAL / DEV 部门 Enabled→Disabled /
		// NORMAL 部门 Enabled→Disabled）后需要批量递增 tokenVersion 时，阻塞并发
		// UpdateProfileWithTx 对同一批 sys_user 行的 X 锁，避免"枚举 userIds 的瞬间有行刚被挪出
		// 本部门 / 新行刚被挪入"导致的漏吊销 / 多吊销（审计 L-R16-2）。
		// session==nil 返回错误。
		FindIdsByDeptIdForShareTx(ctx context.Context, session sqlx.Session, deptId int64) ([]int64, error)
		// UpdateProfile 更新用户资料字段（昵称 / 邮箱 / 手机 / 备注 / 部门 / 状态），username 仅用于
		// 构造旧缓存键 `cacheSysUserUsernamePrefix` 做失效，**不会**被写入 SET 子句。若未来确实需要
		// 修改 username，请独立实现 `UpdateUsernameTx`：
		//   ① 同事务内做 old/new 两份 UsernameKey 的失效；
		//   ② 捕获 1062 (UNIQUE 冲突) → response.ErrConflict，不得混进本方法的签名（审计 L-R11-3）。
		UpdateProfile(ctx context.Context, id int64, username string, nickname, email, phone, remark string, deptId, newStatus int64, statusChanged bool, expectedUpdateTime int64) error
		// UpdateProfileWithTx 与 UpdateProfile 的 SET 子句等价，但 UPDATE 执行在调用方传入的事务里；
		// 用于"改 deptId → 同事务内先 FOR SHARE sys_dept 目标行"修复 DeleteDept vs UpdateUser
		// 的 write skew（审计 M-R11-3）。
		// 审计 L-R12-1：本方法**不再**自己做缓存失效——go-zero `m.ExecCtx` 的 DelCache 会在闭包
		// 成功返回时立即发生，这里"成功"只代表 session.ExecCtx 收到了行数，事务仍在进行中，
		// 并发 FindOne 会把尚未提交的旧值重新灌回 sysUser 低层缓存造成 stale。调用方**必须**在
		// TransactCtx 返回（事务 commit）成功之后调用 InvalidateProfileCache(id, username) 做
		// post-commit 失效；同模式对任何 `*WithTx` 方法都成立。
		UpdateProfileWithTx(ctx context.Context, session sqlx.Session, id int64, username string, nickname, email, phone, remark string, deptId, newStatus int64, statusChanged bool, expectedUpdateTime int64) error
		// InvalidateProfileCache 失效 sysUser 的 id / username 两把低层缓存键。仅应在事务
		// commit 成功后由调用方显式调用（见 UpdateProfileWithTx 说明）。best-effort：失效失败
		// 只留日志，最终由 TTL 兜底，不影响事务已完成的业务结果（审计 L-R12-1）。
		InvalidateProfileCache(ctx context.Context, id int64, username string)
		// UpdatePassword 审计 H-R11-1：expectedUpdateTime 必须由调用方用**外层校验旧密码时拿到的
		// 那一份 updateTime** 显式透传；禁止函数内部再 FindOne 自对齐乐观锁，否则内层 CAS 等于退化
		// 为 last-write-wins，被"旧会话 + 知道旧密码"的攻击者可以把管理员紧急改过的新密码盖回。
		// username 仅用于构造 `cacheSysUserUsernamePrefix` 缓存键失效（sysUser.username 唯一，本函数
		// 不会修改它）。
		UpdatePassword(ctx context.Context, id int64, username string, password string, mustChangePassword, expectedUpdateTime int64) error
		// UpdateStatus 审计 M-R11-2：username 由调用方透传，避免仅为构造缓存键而多打一次 FindOne。
		UpdateStatus(ctx context.Context, id int64, username string, status int64, expectedUpdateTime int64) error
		// IncrementTokenVersion 审计 M-R11-2：username 由调用方透传，避免仅为构造缓存键而多打一次 FindOne。
		IncrementTokenVersion(ctx context.Context, id int64, username string) (int64, error)
		IncrementTokenVersionIfMatch(ctx context.Context, id int64, username string, expected int64) (int64, error)
		// IncrementTokenVersionWithTx 在调用方提供的事务内递增 sys_user.tokenVersion，供 UpdateMember
		// 降级 / 禁用等业务把旧 access/refresh token 立刻打到 middleware 的 `claims.TokenVersion !=
		// ud.TokenVersion` / refresh CAS 的拒绝分支（审计 M-R15-1 方案 A）。
		//
		// 与非事务版本 IncrementTokenVersion 的差异：
		//   - 不在方法内做任何缓存失效；tx 成功提交后由调用方走 InvalidateProfileCache(id, username)
		//     + UserDetailsLoader.Del/CleanByProduct 的 post-commit 链路（对齐 UpdateProfileWithTx
		//     的 L-R12-1 契约；若事务回滚，调用方**不要**触发失效，避免"操作失败但用户被踢下线"）；
		//   - session==nil 直接报错——非事务场景请改走 IncrementTokenVersion。
		// 返回新的 tokenVersion（SELECT LAST_INSERT_ID()）供调用方 log / forensic 比对。
		IncrementTokenVersionWithTx(ctx context.Context, session sqlx.Session, id int64) (int64, error)
		// BatchIncrementTokenVersionWithTx 批量递增一组 userIds 的 tokenVersion，供 UpdateProduct
		// 禁用时吊销该产品全体成员已签发的 access/refresh（审计 L-R15-3）。
		//
		// 契约：
		//   - 不做缓存失效；tx 提交后调用方按 (id, username) 对逐个 InvalidateProfileCache，UD 聚合
		//     缓存通过 UserDetailsLoader.CleanByProduct 失效；
		//   - 调用方负责对 ids 去重并控制长度，空切片直接返回 nil；
		//   - session==nil 返回错误。
		BatchIncrementTokenVersionWithTx(ctx context.Context, session sqlx.Session, ids []int64) error
		// UpdateSelfInfo 更新用户自身安全字段（昵称/头像/邮箱/手机），不涉及 deptId/status/tokenVersion。
		// username 仅用于构造缓存键失效。avatar 使用 sql.NullString 语义写入（空串置 NULL）。
		UpdateSelfInfo(ctx context.Context, id int64, username string, nickname, avatar, email, phone string, expectedUpdateTime int64) error
	}

	customSysUserModel struct {
		*defaultSysUserModel
	}
)

func NewSysUserModel(conn sqlx.SqlConn, c cache.CacheConf, cachePrefix string, opts ...cache.Option) SysUserModel {
	return &customSysUserModel{
		defaultSysUserModel: newSysUserModel(conn, c, cachePrefix, opts...),
	}
}

func (m *customSysUserModel) FindListByPage(ctx context.Context, page, pageSize int64) ([]*SysUser, int64, error) {
	var total int64
	countQuery := fmt.Sprintf("SELECT COUNT(*) FROM %s", m.table)
	if err := m.QueryRowNoCacheCtx(ctx, &total, countQuery); err != nil {
		return nil, 0, err
	}

	var list []*SysUser
	query := fmt.Sprintf("SELECT %s FROM %s ORDER BY id DESC LIMIT ?,?", sysUserRows, m.table)
	if err := m.QueryRowsNoCacheCtx(ctx, &list, query, (page-1)*pageSize, pageSize); err != nil {
		return nil, 0, err
	}

	return list, total, nil
}

func (m *customSysUserModel) FindListByFilter(ctx context.Context, filter UserListFilter, page, pageSize int64) ([]*SysUser, int64, error) {
	var conditions []string
	var args []interface{}

	if filter.Username != "" {
		conditions = append(conditions, "`username` LIKE ?")
		args = append(args, "%"+filter.Username+"%")
	}
	if filter.Nickname != "" {
		conditions = append(conditions, "`nickname` LIKE ?")
		args = append(args, "%"+filter.Nickname+"%")
	}
	if filter.Status > 0 {
		conditions = append(conditions, "`status` = ?")
		args = append(args, filter.Status)
	}
	if filter.DeptId != nil {
		conditions = append(conditions, "`deptId` = ?")
		args = append(args, *filter.DeptId)
	}

	where := ""
	if len(conditions) > 0 {
		where = " WHERE " + strings.Join(conditions, " AND ")
	}

	var total int64
	countQuery := fmt.Sprintf("SELECT COUNT(*) FROM %s%s", m.table, where)
	if err := m.QueryRowNoCacheCtx(ctx, &total, countQuery, args...); err != nil {
		return nil, 0, err
	}

	var list []*SysUser
	queryArgs := append(args, (page-1)*pageSize, pageSize)
	query := fmt.Sprintf("SELECT %s FROM %s%s ORDER BY id DESC LIMIT ?,?", sysUserRows, m.table, where)
	if err := m.QueryRowsNoCacheCtx(ctx, &list, query, queryArgs...); err != nil {
		return nil, 0, err
	}

	return list, total, nil
}

type UserWithMemberType struct {
	SysUser
	MemberType string `db:"memberType"`
}

func (m *customSysUserModel) FindListByProductMembers(ctx context.Context, productCode string, page, pageSize int64) ([]*SysUser, map[int64]string, int64, error) {
	memberTable := "`sys_product_member`"

	var total int64
	countQuery := fmt.Sprintf("SELECT COUNT(*) FROM %s u INNER JOIN %s pm ON u.`id` = pm.`userId` WHERE pm.`productCode` = ?", m.table, memberTable)
	if err := m.QueryRowNoCacheCtx(ctx, &total, countQuery, productCode); err != nil {
		return nil, nil, 0, err
	}

	var list []*UserWithMemberType
	fields := strings.Join(sysUserFieldNames, ",u.")
	query := fmt.Sprintf("SELECT u.%s, pm.`memberType` FROM %s u INNER JOIN %s pm ON u.`id` = pm.`userId` WHERE pm.`productCode` = ? ORDER BY u.`id` DESC LIMIT ?,?", fields, m.table, memberTable)
	if err := m.QueryRowsNoCacheCtx(ctx, &list, query, productCode, (page-1)*pageSize, pageSize); err != nil {
		return nil, nil, 0, err
	}

	users := make([]*SysUser, len(list))
	memberMap := make(map[int64]string, len(list))
	for i, item := range list {
		users[i] = &item.SysUser
		memberMap[item.Id] = item.MemberType
	}

	return users, memberMap, total, nil
}

func (m *customSysUserModel) FindIdsByDeptId(ctx context.Context, deptId int64) ([]int64, error) {
	var ids []int64
	query := fmt.Sprintf("SELECT `id` FROM %s WHERE `deptId` = ?", m.table)
	if err := m.QueryRowsNoCacheCtx(ctx, &ids, query, deptId); err != nil {
		return nil, err
	}
	return ids, nil
}

// FindIdsByDeptIdForShareTx 见接口注释（审计 L-R16-2）。
func (m *customSysUserModel) FindIdsByDeptIdForShareTx(ctx context.Context, session sqlx.Session, deptId int64) ([]int64, error) {
	if session == nil {
		return nil, errors.New("FindIdsByDeptIdForShareTx requires a non-nil session")
	}
	var ids []int64
	// ORDER BY id 让 S 锁的申请顺序确定，与并发的 UpdateProfileWithTx（按 id 触发 X 锁）交叉时
	// 形成固定加锁偏序，减小死锁概率；同时方便上层日志对照。
	query := fmt.Sprintf("SELECT `id` FROM %s WHERE `deptId` = ? ORDER BY `id` LOCK IN SHARE MODE", m.table)
	if err := session.QueryRowsCtx(ctx, &ids, query, deptId); err != nil {
		return nil, err
	}
	return ids, nil
}

func (m *customSysUserModel) UpdateProfile(ctx context.Context, id int64, username string, nickname, email, phone, remark string, deptId, newStatus int64, statusChanged bool, expectedUpdateTime int64) error {
	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, username)
	now := time.Now().Unix()

	res, err := m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (sql.Result, error) {
		if statusChanged {
			query := fmt.Sprintf("UPDATE %s SET `nickname`=?, `email`=?, `phone`=?, `remark`=?, `deptId`=?, `status`=?, `tokenVersion`=`tokenVersion`+1, `updateTime`=? WHERE `id`=? AND `updateTime`=?", m.table)
			return conn.ExecCtx(ctx, query, nickname, email, phone, remark, deptId, newStatus, now, id, expectedUpdateTime)
		}
		query := fmt.Sprintf("UPDATE %s SET `nickname`=?, `email`=?, `phone`=?, `remark`=?, `deptId`=?, `updateTime`=? WHERE `id`=? AND `updateTime`=?", m.table)
		return conn.ExecCtx(ctx, query, nickname, email, phone, remark, deptId, now, id, expectedUpdateTime)
	}, sysUserIdKey, sysUserUsernameKey)
	if err != nil {
		return err
	}
	affected, _ := res.RowsAffected()
	if affected == 0 {
		return ErrUpdateConflict
	}
	return nil
}

func (m *customSysUserModel) UpdateSelfInfo(ctx context.Context, id int64, username string, nickname, avatar, email, phone string, expectedUpdateTime int64) error {
	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, username)
	now := time.Now().Unix()

	var avatarVal sql.NullString
	if avatar != "" {
		avatarVal = sql.NullString{String: avatar, Valid: true}
	}

	res, err := m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (sql.Result, error) {
		query := fmt.Sprintf("UPDATE %s SET `nickname`=?, `avatar`=?, `email`=?, `phone`=?, `updateTime`=? WHERE `id`=? AND `updateTime`=?", m.table)
		return conn.ExecCtx(ctx, query, nickname, avatarVal, email, phone, now, id, expectedUpdateTime)
	}, sysUserIdKey, sysUserUsernameKey)
	if err != nil {
		return err
	}
	affected, _ := res.RowsAffected()
	if affected == 0 {
		return ErrUpdateConflict
	}
	return nil
}

// UpdateProfileWithTx 见接口注释（审计 M-R11-3 + L-R12-1）。
// 实现上**绕过** m.ExecCtx 的 pre-commit DelCache 语义——仅调用 session.ExecCtx，缓存失效由
// 调用方在事务 commit 成功后显式走 InvalidateProfileCache。
// session==nil 时直接拒绝（非事务场景必须改走 UpdateProfile）。
func (m *customSysUserModel) UpdateProfileWithTx(ctx context.Context, session sqlx.Session, id int64, username string, nickname, email, phone, remark string, deptId, newStatus int64, statusChanged bool, expectedUpdateTime int64) error {
	if session == nil {
		return errors.New("UpdateProfileWithTx requires a non-nil session")
	}
	_ = username // 保留形参以维持调用方契约一致，失效由 InvalidateProfileCache 另行处理
	now := time.Now().Unix()

	var (
		res sql.Result
		err error
	)
	if statusChanged {
		query := fmt.Sprintf("UPDATE %s SET `nickname`=?, `email`=?, `phone`=?, `remark`=?, `deptId`=?, `status`=?, `tokenVersion`=`tokenVersion`+1, `updateTime`=? WHERE `id`=? AND `updateTime`=?", m.table)
		res, err = session.ExecCtx(ctx, query, nickname, email, phone, remark, deptId, newStatus, now, id, expectedUpdateTime)
	} else {
		query := fmt.Sprintf("UPDATE %s SET `nickname`=?, `email`=?, `phone`=?, `remark`=?, `deptId`=?, `updateTime`=? WHERE `id`=? AND `updateTime`=?", m.table)
		res, err = session.ExecCtx(ctx, query, nickname, email, phone, remark, deptId, now, id, expectedUpdateTime)
	}
	if err != nil {
		return err
	}
	affected, _ := res.RowsAffected()
	if affected == 0 {
		return ErrUpdateConflict
	}
	return nil
}

// InvalidateProfileCache 见接口注释（审计 L-R12-1）。这里不暴露错误——post-commit 阶段
// DB 已为权威，缓存清理失败只会让 sysUser 低层缓存继续提供旧值直至 TTL 过期，而 Logic 层
// 紧接其后的 UserDetailsLoader.Clean 已经失效了上层 UserDetails 聚合缓存；两级缓存一起过期
// 的最坏情形仍然等价于 loadUser 的 cache-miss 路径，不会放大故障面。
func (m *customSysUserModel) InvalidateProfileCache(ctx context.Context, id int64, username string) {
	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, username)
	if err := m.DelCacheCtx(ctx, sysUserIdKey, sysUserUsernameKey); err != nil {
		// 审计 L-R13-5 方案 B：失败原因拆成 ctx 取消 vs 其它两档——前者打独立 audit tag 方便
		// 运维按 `cache_invalidation_skipped_due_to_ctx_cancel` 建看板，避免与真正的 Redis 故障
		// 混在一起报警；其它错误仍然 Errorf，保持与 sqlc 原生失效路径（Insert/Update 触发的
		// DelCache 失败）一致的可观测性口径。
		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
			logx.WithContext(ctx).Errorw("cache invalidation skipped: ctx canceled",
				logx.Field("audit", "cache_invalidation_skipped_due_to_ctx_cancel"),
				logx.Field("scope", "sysUserModel.InvalidateProfileCache"),
				logx.Field("id", id),
				logx.Field("err", err.Error()),
			)
		} else {
			logx.WithContext(ctx).Errorf("sysUserModel.InvalidateProfileCache failed: id=%d err=%v", id, err)
		}
	}
}

func (m *customSysUserModel) UpdatePassword(ctx context.Context, id int64, username string, password string, mustChangePassword, expectedUpdateTime int64) error {
	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, username)
	// 审计 H-R11-1：expectedUpdateTime 必须来自**外层校验旧密码时读到的**快照。不要再内部 FindOne
	// 自取 data.UpdateTime —— 那会让 CAS 在本函数内自我对齐，退化为 last-write-wins，让"会话持有 +
	// 知道旧密码"的攻击者可以把 admin 紧急改过的新密码盖回到自己手里那一份。
	res, err := m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (sql.Result, error) {
		query := fmt.Sprintf("UPDATE %s SET `password` = ?, `mustChangePassword` = ?, `tokenVersion` = `tokenVersion` + 1, `updateTime` = ? WHERE `id` = ? AND `updateTime` = ?", m.table)
		return conn.ExecCtx(ctx, query, password, mustChangePassword, time.Now().Unix(), id, expectedUpdateTime)
	}, sysUserIdKey, sysUserUsernameKey)
	if err != nil {
		return err
	}
	if affected, _ := res.RowsAffected(); affected == 0 {
		// 行被删除或被并发改过（任何字段，包括 status/password/profile）：统一回 ErrUpdateConflict。
		return ErrUpdateConflict
	}
	return nil
}

// UpdateStatus 修改用户 status，并强制递增 tokenVersion 让已签发令牌失效。
// 审计 L-N4：WHERE 必须带 `updateTime=?` 乐观锁，和 UpdateProfile / UpdatePassword 语义对齐。
// 上游 UpdateUserStatusLogic 已经从 ValidateStatusChange 拿到 sysUser，调用方应把
// `sysUser.UpdateTime` 当作 expectedUpdateTime 传入：
//   - expectedUpdateTime 不匹配 → ErrUpdateConflict；上层统一回 409 "数据已被其他操作修改"。
//   - 避免并发冻结/解冻请求走"last-write-wins"，出现两个 admin 同时点"冻结"/"解冻"
//     时后到者覆盖先到者、tokenVersion 被连续加两次把刚刚解冻的用户再次踢下线的诡异现象。
//
// 审计 L-R17-6 · 无条件递增 tokenVersion 是**刻意**设计（不要改成"仅冻结时 +1"的条件递增）：
//   - Enabled→Disabled（冻结）：签发层吊销旧 access/refresh token，JWT middleware 凭
//     `claims.tokenVersion < DB.tokenVersion` 一票否决。
//   - Disabled→Enabled（解冻）：用户已因 Status!=Enabled 无法登录/刷新，+1 在业务上是空动作；
//     但保留 +1 覆盖"冻结 → Redis Clean 失败 → 解冻"这条极窄路径里"旧 access token 凭残留
//     UD 复活"的可能，与 UpdateUserStatusLogic 的 L-R17-6 注释同口径。
func (m *customSysUserModel) UpdateStatus(ctx context.Context, id int64, username string, status int64, expectedUpdateTime int64) error {
	// 审计 M-R11-2：username 由调用方（ValidateStatusChange 返回的目标用户对象）显式透传，
	// 不再内部 FindOne。真实并发安全继续靠 `WHERE updateTime = expectedUpdateTime` 乐观锁兜底。
	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, username)
	res, err := m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (sql.Result, error) {
		query := fmt.Sprintf("UPDATE %s SET `status` = ?, `tokenVersion` = `tokenVersion` + 1, `updateTime` = ? WHERE `id` = ? AND `updateTime` = ?", m.table)
		return conn.ExecCtx(ctx, query, status, time.Now().Unix(), id, expectedUpdateTime)
	}, sysUserIdKey, sysUserUsernameKey)
	if err != nil {
		return err
	}
	if affected, _ := res.RowsAffected(); affected == 0 {
		// 行被删除或被并发改过：对外统一回 ErrUpdateConflict，避免对已删除 / 被并发改过的行
		// 返回 nil 让上层误判为"冻结生效"（审计 M-2 / L-N4）。
		return ErrUpdateConflict
	}
	return nil
}

// IncrementTokenVersion 强制递增当前用户的 tokenVersion，让**所有**已签发的 access/refresh 立即失效。
//
// WARN: 仅限"强制全量会话失效"场景调用——主动 Logout 或封禁/重置密码。Refresh / Rotate 场景
// 必须调用 IncrementTokenVersionIfMatch 走 CAS 语义，否则会回到 R5 以前的并发 rotate 窗口，
// 两次并发 refresh 都能换到新令牌，等同于会话劫持（见审计 L-2）。
// 调用前请先走 TokenOpLimiter 等限流，避免被反复触发把合法用户 kick 出登录。
func (m *customSysUserModel) IncrementTokenVersion(ctx context.Context, id int64, username string) (int64, error) {
	// 审计 M-R11-2：username 由调用方显式透传，不再内部 FindOne 仅为构造缓存键。
	// 调用方（Logout 唯一入口）在 UserDetailsLoader.Load 之后天然已经持有 ud.Username。
	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, username)

	var newVersion int64
	err := m.TransactCtx(ctx, func(ctx context.Context, session sqlx.Session) error {
		query := fmt.Sprintf("UPDATE %s SET `tokenVersion` = LAST_INSERT_ID(`tokenVersion` + 1), `updateTime` = ? WHERE `id` = ?", m.table)
		res, err := session.ExecCtx(ctx, query, time.Now().Unix(), id)
		if err != nil {
			return err
		}
		// 审计 L-R10-3：FindOne 与本次 UPDATE 之间若有并发 DELETE，affected=0 仍会返回 nil 让
		// SELECT LAST_INSERT_ID() 在全新事务里读出 0，调用方无法区分"真的递增成功"和"目标已被删除"。
		// 对外统一回 ErrUpdateConflict，调用方据此做日志/告警或跳过后续 Clean，避免对 tokenVersion=0
		// 之类的伪返回值做错误假设（如"版本从 1 起递增"的默认契约踩坑）。
		if affected, _ := res.RowsAffected(); affected == 0 {
			return ErrUpdateConflict
		}
		return session.QueryRowCtx(ctx, &newVersion, "SELECT LAST_INSERT_ID()")
	})
	if err != nil {
		return 0, err
	}

	_ = m.DelCacheCtx(ctx, sysUserIdKey, sysUserUsernameKey)
	return newVersion, nil
}

// IncrementTokenVersionIfMatch 原子递增 tokenVersion；仅当 DB 里当前 tokenVersion == expected 时才会生效。
// 这是 refreshToken rotation 的原子 CAS：两个并发的刷新请求只有一个能命中 WHERE tokenVersion=expected，
// 另一个 affected=0 返回 ErrTokenVersionMismatch，从而避免"两边都换到新令牌"的会话劫持窗口。
//
// 由上游透传 username 以便构造 cacheSysUserUsernamePrefix 的缓存键进行失效，避免为此多查一次 FindOne
// （见审计 M-8）。上游通常已经通过 UserDetailsLoader.Load 拿到 username，零额外成本。
func (m *customSysUserModel) IncrementTokenVersionIfMatch(ctx context.Context, id int64, username string, expected int64) (int64, error) {
	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, username)

	var newVersion int64
	err := m.TransactCtx(ctx, func(ctx context.Context, session sqlx.Session) error {
		query := fmt.Sprintf("UPDATE %s SET `tokenVersion` = LAST_INSERT_ID(`tokenVersion` + 1), `updateTime` = ? WHERE `id` = ? AND `tokenVersion` = ?", m.table)
		res, err := session.ExecCtx(ctx, query, time.Now().Unix(), id, expected)
		if err != nil {
			return err
		}
		affected, _ := res.RowsAffected()
		if affected == 0 {
			return ErrTokenVersionMismatch
		}
		return session.QueryRowCtx(ctx, &newVersion, "SELECT LAST_INSERT_ID()")
	})
	if err != nil {
		return 0, err
	}

	_ = m.DelCacheCtx(ctx, sysUserIdKey, sysUserUsernameKey)
	return newVersion, nil
}

// IncrementTokenVersionWithTx 见接口注释（审计 M-R15-1 方案 A）。
func (m *customSysUserModel) IncrementTokenVersionWithTx(ctx context.Context, session sqlx.Session, id int64) (int64, error) {
	if session == nil {
		return 0, errors.New("IncrementTokenVersionWithTx requires a non-nil session")
	}
	query := fmt.Sprintf("UPDATE %s SET `tokenVersion` = LAST_INSERT_ID(`tokenVersion` + 1), `updateTime` = ? WHERE `id` = ?", m.table)
	res, err := session.ExecCtx(ctx, query, time.Now().Unix(), id)
	if err != nil {
		return 0, err
	}
	// 与 IncrementTokenVersion 的 L-R10-3 契约一致：affected=0 表示目标已被并发删除，回
	// ErrUpdateConflict 让上层业务事务自行 rollback——不递增 tokenVersion 比"哑失败后继续走
	// post-commit 失效链"安全（后者会把已不存在的 userId 从缓存里删除，没有副作用但污染日志）。
	if affected, _ := res.RowsAffected(); affected == 0 {
		return 0, ErrUpdateConflict
	}
	var newVersion int64
	if err := session.QueryRowCtx(ctx, &newVersion, "SELECT LAST_INSERT_ID()"); err != nil {
		return 0, err
	}
	return newVersion, nil
}

// BatchIncrementTokenVersionWithTx 见接口注释（审计 L-R15-3）。
func (m *customSysUserModel) BatchIncrementTokenVersionWithTx(ctx context.Context, session sqlx.Session, ids []int64) error {
	if session == nil {
		return errors.New("BatchIncrementTokenVersionWithTx requires a non-nil session")
	}
	if len(ids) == 0 {
		return nil
	}
	placeholders := make([]string, len(ids))
	args := make([]interface{}, 0, len(ids)+1)
	args = append(args, time.Now().Unix())
	for i, id := range ids {
		placeholders[i] = "?"
		args = append(args, id)
	}
	// 批量 UPDATE 不再回读每行新 tokenVersion——调用方（UpdateProduct 禁用）只关心"集体递增
	// 发生了"，不做 forensic 比对；若未来需要逐行返回，请改走 IN(..) + SELECT 的两步模式，
	// 不要试图让 LAST_INSERT_ID() 承担 N 行的反向通道（它只会保留最后一次赋值）。
	query := fmt.Sprintf("UPDATE %s SET `tokenVersion` = `tokenVersion` + 1, `updateTime` = ? WHERE `id` IN (%s)", m.table, strings.Join(placeholders, ","))
	if _, err := session.ExecCtx(ctx, query, args...); err != nil {
		return err
	}
	return nil
}

func (m *customSysUserModel) FindByIds(ctx context.Context, ids []int64) ([]*SysUser, error) {
	if len(ids) == 0 {
		return nil, nil
	}
	placeholders := make([]string, len(ids))
	args := make([]interface{}, len(ids))
	for i, id := range ids {
		placeholders[i] = "?"
		args[i] = id
	}
	var list []*SysUser
	query := fmt.Sprintf("SELECT %s FROM %s WHERE `id` IN (%s)", sysUserRows, m.table, strings.Join(placeholders, ","))
	if err := m.QueryRowsNoCacheCtx(ctx, &list, query, args...); err != nil {
		return nil, err
	}
	return list, nil
}