feat: 新增多密码验证支持及架构文档

refactor: 重构用户模型和密码验证逻辑
feat(epay): 添加支付类型支持
docs: 添加安装和配置指南文档
fix: 修复优惠券过期检查逻辑
perf: 优化设备解绑缓存清理流程
test: 添加密码验证测试用例
chore: 更新依赖版本

internal/logic/auth/deviceLoginLogic.go

@@ -19,13 +19,14 @@ import (
 	"gorm.io/gorm"
 )
 
+// DeviceLoginLogic 设备登录逻辑结构体
 type DeviceLoginLogic struct {
 	logger.Logger
 	ctx    context.Context
 	svcCtx *svc.ServiceContext
 }
 
-// Device Login
+// NewDeviceLoginLogic 创建设备登录逻辑实例
 func NewDeviceLoginLogic(ctx context.Context, svcCtx *svc.ServiceContext) *DeviceLoginLogic {
 	return &DeviceLoginLogic{
 		Logger: logger.WithContext(ctx),
@@ -34,14 +35,17 @@ func NewDeviceLoginLogic(ctx context.Context, svcCtx *svc.ServiceContext) *Devic
 	}
 }
 
+// DeviceLogin 设备登录主要逻辑
 func (l *DeviceLoginLogic) DeviceLogin(req *types.DeviceLoginRequest) (resp *types.LoginResponse, err error) {
+	// 检查设备登录是否启用
 	if !l.svcCtx.Config.Device.Enable {
 		return nil, xerr.NewErrMsg("Device login is disabled")
 	}
 
 	loginStatus := false
 	var userInfo *user.User
-	// Record login status
+
+	// 延迟执行：记录登录状态日志
 	defer func() {
 		if userInfo != nil && userInfo.Id != 0 {
 			loginLog := log.Login{
@@ -67,14 +71,61 @@ func (l *DeviceLoginLogic) DeviceLogin(req *types.DeviceLoginRequest) (resp *typ
 		}
 	}()
 
-	// Check if device exists by identifier
+	// 根据设备标识符查找设备信息
 	deviceInfo, err := l.svcCtx.UserModel.FindOneDeviceByIdentifier(l.ctx, req.Identifier)
 	if err != nil {
 		if errors.Is(err, gorm.ErrRecordNotFound) {
-			// Device not found, create new user and device
-			userInfo, err = l.registerUserAndDevice(req)
-			if err != nil {
-				return nil, err
+			// 设备未找到，但需要检查认证方法是否已存在
+			authMethod, authErr := l.svcCtx.UserModel.FindUserAuthMethodByOpenID(l.ctx, "device", req.Identifier)
+			if authErr != nil && !errors.Is(authErr, gorm.ErrRecordNotFound) {
+				l.Errorw("query auth method failed",
+					logger.Field("identifier", req.Identifier),
+					logger.Field("error", authErr.Error()),
+				)
+				return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query auth method failed: %v", authErr.Error())
+			}
+
+			if authMethod != nil {
+				// 认证方法存在但设备记录不存在，可能是数据不一致，获取用户信息并重新创建设备记录
+				userInfo, err = l.svcCtx.UserModel.FindOne(l.ctx, authMethod.UserId)
+				if err != nil {
+					l.Errorw("query user by auth method failed",
+						logger.Field("user_id", authMethod.UserId),
+						logger.Field("identifier", req.Identifier),
+						logger.Field("error", err.Error()),
+					)
+					return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query user failed: %v", err.Error())
+				}
+				
+				// 重新创建缺失的设备记录
+				deviceInfo := &user.Device{
+					Ip:         req.IP,
+					UserId:     userInfo.Id,
+					UserAgent:  req.UserAgent,
+					Identifier: req.Identifier,
+					Enabled:    true,
+					Online:     false,
+				}
+				if err := l.svcCtx.UserModel.InsertDevice(l.ctx, deviceInfo); err != nil {
+					l.Errorw("failed to recreate device record",
+						logger.Field("user_id", userInfo.Id),
+						logger.Field("identifier", req.Identifier),
+						logger.Field("error", err.Error()),
+					)
+					return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "recreate device record failed: %v", err)
+				}
+				
+				l.Infow("found existing auth method without device record, recreated device record",
+					logger.Field("user_id", userInfo.Id),
+					logger.Field("identifier", req.Identifier),
+					logger.Field("device_id", deviceInfo.Id),
+				)
+			} else {
+				// 设备和认证方法都不存在，创建新用户和设备
+				userInfo, err = l.registerUserAndDevice(req)
+				if err != nil {
+					return nil, err
+				}
 			}
 		} else {
 			l.Errorw("query device failed",
@@ -84,7 +135,7 @@ func (l *DeviceLoginLogic) DeviceLogin(req *types.DeviceLoginRequest) (resp *typ
 			return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query device failed: %v", err.Error())
 		}
 	} else {
-		// Device found, get user info
+		// 设备已存在，获取用户信息
 		userInfo, err = l.svcCtx.UserModel.FindOne(l.ctx, deviceInfo.UserId)
 		if err != nil {
 			l.Errorw("query user failed",
@@ -95,10 +146,10 @@ func (l *DeviceLoginLogic) DeviceLogin(req *types.DeviceLoginRequest) (resp *typ
 		}
 	}
 
-	// Generate session id
+	// 生成会话ID
 	sessionId := uuidx.NewUUID().String()
 
-	// Generate token
+	// 生成JWT令牌
 	token, err := jwt.NewJwtToken(
 		l.svcCtx.Config.JwtAuth.AccessSecret,
 		time.Now().Unix(),
@@ -115,7 +166,7 @@ func (l *DeviceLoginLogic) DeviceLogin(req *types.DeviceLoginRequest) (resp *typ
 		return nil, errors.Wrapf(xerr.NewErrCode(xerr.ERROR), "token generate error: %v", err.Error())
 	}
 
-	// Store session id in redis
+	// 将会话ID存储到Redis中
 	sessionIdCacheKey := fmt.Sprintf("%v:%v", config.SessionIdKey, sessionId)
 	if err = l.svcCtx.Redis.Set(l.ctx, sessionIdCacheKey, userInfo.Id, time.Duration(l.svcCtx.Config.JwtAuth.AccessExpire)*time.Second).Err(); err != nil {
 		l.Errorw("set session id error",
@@ -131,6 +182,7 @@ func (l *DeviceLoginLogic) DeviceLogin(req *types.DeviceLoginRequest) (resp *typ
 	}, nil
 }
 
+// registerUserAndDevice 注册新用户和设备
 func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest) (*user.User, error) {
 	l.Infow("device not found, creating new user and device",
 		logger.Field("identifier", req.Identifier),
@@ -138,8 +190,9 @@ func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest)
 	)
 
 	var userInfo *user.User
+	// 使用数据库事务确保数据一致性
 	err := l.svcCtx.UserModel.Transaction(l.ctx, func(db *gorm.DB) error {
-		// Create new user
+		// 创建新用户
 		userInfo = &user.User{
 			OnlyFirstPurchase: &l.svcCtx.Config.Invite.OnlyFirstPurchase,
 		}
@@ -150,7 +203,7 @@ func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest)
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "create user failed: %v", err)
 		}
 
-		// Update refer code
+		// 更新用户邀请码
 		userInfo.ReferCode = uuidx.UserInviteCode(userInfo.Id)
 		if err := db.Model(&user.User{}).Where("id = ?", userInfo.Id).Update("refer_code", userInfo.ReferCode).Error; err != nil {
 			l.Errorw("failed to update refer code",
@@ -160,7 +213,7 @@ func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest)
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "update refer code failed: %v", err)
 		}
 
-		// Create device auth method
+		// 创建设备认证方式记录
 		authMethod := &user.AuthMethods{
 			UserId:         userInfo.Id,
 			AuthType:       "device",
@@ -176,7 +229,7 @@ func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest)
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "create device auth method failed: %v", err)
 		}
 
-		// Insert device record
+		// 插入设备记录
 		deviceInfo := &user.Device{
 			Ip:         req.IP,
 			UserId:     userInfo.Id,
@@ -194,7 +247,7 @@ func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest)
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "insert device failed: %v", err)
 		}
 
-		// Activate trial if enabled
+		// 如果启用了试用，则激活试用订阅
 		if l.svcCtx.Config.Register.EnableTrial {
 			if err := l.activeTrial(userInfo.Id, db); err != nil {
 				return err
@@ -218,7 +271,7 @@ func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest)
 		logger.Field("refer_code", userInfo.ReferCode),
 	)
 
-	// Register log
+	// 记录注册日志
 	registerLog := log.Register{
 		AuthMethod: "device",
 		Identifier: req.Identifier,
@@ -244,7 +297,9 @@ func (l *DeviceLoginLogic) registerUserAndDevice(req *types.DeviceLoginRequest)
 	return userInfo, nil
 }
 
+// activeTrial 激活试用订阅
 func (l *DeviceLoginLogic) activeTrial(userId int64, db *gorm.DB) error {
+	// 查找试用订阅模板
 	sub, err := l.svcCtx.SubscribeModel.FindOne(l.ctx, l.svcCtx.Config.Register.TrialSubscribe)
 	if err != nil {
 		l.Errorw("failed to find trial subscription template",
@@ -255,11 +310,13 @@ func (l *DeviceLoginLogic) activeTrial(userId int64, db *gorm.DB) error {
 		return err
 	}
 
+	// 计算试用期时间
 	startTime := time.Now()
 	expireTime := tool.AddTime(l.svcCtx.Config.Register.TrialTimeUnit, l.svcCtx.Config.Register.TrialTime, startTime)
 	subscribeToken := uuidx.SubscribeToken(fmt.Sprintf("Trial-%v", userId))
 	subscribeUUID := uuidx.NewUUID().String()
 
+	// 创建用户订阅记录
 	userSub := &user.Subscribe{
 		UserId:      userId,
 		OrderId:     0,

internal/logic/auth/resetPasswordLogic.go

@@ -104,7 +104,8 @@ func (l *ResetPasswordLogic) ResetPassword(req *types.ResetPasswordRequest) (res
 
 	// Update password
 	userInfo.Password = tool.EncodePassWord(req.Password)
-	if err := l.svcCtx.UserModel.Update(l.ctx, userInfo); err != nil {
+	userInfo.Algo = "default"
+	if err = l.svcCtx.UserModel.Update(l.ctx, userInfo); err != nil {
 		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "update user info failed: %v", err.Error())
 	}
 

internal/logic/auth/telephoneLoginLogic.go

@@ -98,7 +98,7 @@ func (l *TelephoneLoginLogic) TelephoneLogin(req *types.TelephoneLoginRequest, r
 
 	if req.TelephoneCode == "" {
 		// Verify password
-		if !tool.VerifyPassWord(req.Password, userInfo.Password) {
+		if !tool.MultiPasswordVerify(userInfo.Algo, userInfo.Salt, req.Password, userInfo.Password) {
 			return nil, errors.Wrapf(xerr.NewErrCode(xerr.UserPasswordError), "user password")
 		}
 	} else {

internal/logic/auth/telephoneResetPasswordLogic.go

@@ -78,6 +78,7 @@ func (l *TelephoneResetPasswordLogic) TelephoneResetPassword(req *types.Telephon
 	// Generate password
 	pwd := tool.EncodePassWord(req.Password)
 	userInfo.Password = pwd
+	userInfo.Algo = "default"
 	err = l.svcCtx.UserModel.Update(l.ctx, userInfo)
 	if err != nil {
 		return nil, errors.Wrapf(xerr.NewErrCode(xerr.ERROR), "update user password failed: %v", err.Error())

internal/logic/auth/telephoneUserRegisterLogic.go

@@ -107,6 +107,7 @@ func (l *TelephoneUserRegisterLogic) TelephoneUserRegister(req *types.TelephoneR
 	pwd := tool.EncodePassWord(req.Password)
 	userInfo := &user.User{
 		Password:          pwd,
+		Algo:              "default",
 		OnlyFirstPurchase: &l.svcCtx.Config.Invite.OnlyFirstPurchase,
 		AuthMethods: []user.AuthMethods{
 			{

internal/logic/auth/userRegisterLogic.go

@@ -90,6 +90,7 @@ func (l *UserRegisterLogic) UserRegister(req *types.UserRegisterRequest) (resp *
 	pwd := tool.EncodePassWord(req.Password)
 	userInfo := &user.User{
 		Password:          pwd,
+		Algo:              "default",
 		OnlyFirstPurchase: &l.svcCtx.Config.Invite.OnlyFirstPurchase,
 	}
 	if referer != nil {