one-pipe-system/docs/LOGIN_MODULE.md

登录模块说明文档

概述

本项目的登录模块已完成重构，采用了全新的架构设计，提供了完整的认证流程和权限管理功能。

功能特性

1. Mock 数据支持

系统内置了 4 个 Mock 账号，用于开发和演示：

账号类型	用户名	密码	角色	权限说明
超级管理员	super	123456	SUPER_ADMIN	拥有所有权限
平台管理员	admin	123456	ADMIN	账号、网卡、套餐、设备等管理权限
代理商	agent	123456	AGENT	网卡查看/操作、佣金管理等权限
企业客户	enterprise	123456	ENTERPRISE	自有网卡和设备的查看/操作权限

文件位置: src/mock/auth.ts

2. 记住密码功能

• 用户可以勾选"记住密码"选项
• 登录成功后，用户名和密码会被加密存储到 localStorage
• 下次访问登录页时自动填充账号信息
• 取消勾选会清除已保存的凭证

实现文件: src/utils/auth/rememberPassword.ts

核心函数:

// 保存凭证
saveCredentials(username, password, remember)

// 获取保存的凭证
getRememberedCredentials()

// 清除凭证
clearRememberedCredentials()

3. 完善的表单验证

提供了多种验证规则，适用于不同场景：

• 用户名验证: 3-20个字符，只能包含字母、数字和下划线
• 密码验证: 6-20个字符
• 强密码验证: 8-20个字符，必须包含大小写字母和数字
• 确认密码验证: 必须与密码一致
• 手机号验证: 支持中国大陆手机号格式
• 邮箱验证: 标准邮箱格式验证
• 验证码验证: 4位数字

实现文件: src/utils/auth/loginValidation.ts

使用示例:

import { usernameRules, passwordRules } from '@/utils/auth/loginValidation'

const rules = {
  username: usernameRules(t),
  password: passwordRules(t)
}

4. 权限路由守卫

优化了路由守卫，增加了以下功能：

白名单机制

不需要登录即可访问的路由：

• /login - 登录页
• /register - 注册页
• /forget-password - 忘记密码
• /exception/* - 异常页面

文件位置: src/router/guards/permission.ts

Token 验证

• 自动检查 Token 是否存在
• 验证 Token 是否有效
• Token 过期自动跳转到登录页

页面级权限验证

• 根据路由 meta 中的 roles 和 permissions 进行验证
• 无权限访问时自动跳转到 403 页面
• 支持通配符权限（如 *:*:* 表示所有权限）

登录重定向

• 访问需要登录的页面时，会记录当前路径
• 登录成功后自动跳转回之前访问的页面
• 如果是白名单路由，则跳转到首页

核心函数:

// 检查是否在白名单
isInWhiteList(path)

// 检查路由权限
hasRoutePermission(route, userInfo)

// 检查 Token 是否有效
isTokenValid(token)

// 构建登录重定向URL
buildLoginRedirect(currentPath)

5. useLogin Composable

将登录逻辑抽取为可复用的 Composable，提高代码可维护性。

文件位置: src/composables/useLogin.ts

提供的功能:

• 表单状态管理
• Mock 账号切换
• 登录逻辑处理
• 自动记住密码
• 登录成功通知
• 重定向处理

使用示例:

<script setup>
import { useLogin } from '@/composables/useLogin'

const {
  formRef,
  formData,
  rules,
  loading,
  mockAccounts,
  setupAccount,
  handleLogin
} = useLogin()
</script>

文件结构

src/
├── mock/
│   └── auth.ts                      # Mock 账号数据
├── utils/auth/
│   ├── rememberPassword.ts          # 记住密码工具
│   ├── loginValidation.ts           # 表单验证规则
│   └── index.ts                     # 统一导出
├── router/guards/
│   ├── permission.ts                # 权限验证工具
│   ├── beforeEach.ts                # 路由前置守卫（已优化）
│   └── afterEach.ts                 # 路由后置守卫
├── composables/
│   └── useLogin.ts                  # 登录逻辑 Composable
└── views/auth/login/
    └── index.vue                    # 登录页面（已重构）

权限配置示例

路由权限配置

// 在路由配置中添加 meta
{
  path: '/account/platform',
  meta: {
    title: '平台账号管理',
    roles: ['R_SUPER', 'R_ADMIN'], // 允许的角色
    permissions: ['account:view:*']  // 需要的权限
  }
}

用户权限定义

// 用户信息中包含角色和权限
{
  roles: ['R_ADMIN'],
  permissions: [
    'account:*:*',      // 账号管理所有权限
    'card:view:*',      // 网卡查看权限
    'card:operation:*'  // 网卡操作权限
  ]
}

开发建议

1. 切换到真实接口

当后端接口就绪后，只需修改 useLogin.ts 中的登录逻辑：

// 将 Mock 登录替换为真实 API
// const loginResult = mockLogin(formData.username, formData.password)
const loginResult = await AuthService.login({
  username: formData.username,
  password: formData.password
})

2. Token 刷新

在 src/router/guards/permission.ts 的 isTokenValid 函数中添加真实的 JWT 验证逻辑。

3. 权限粒度

根据实际业务需求，可以在以下层级添加权限验证：

• 路由级: 在路由 meta 中配置
• 页面级: 在页面组件中使用 v-if 判断
• 按钮级: 使用自定义指令（如 v-permission）

常见问题

Q1: 如何添加新的 Mock 账号？

编辑 src/mock/auth.ts，在 MOCK_ACCOUNTS 数组中添加新账号即可。

Q2: 记住密码的数据存在哪里？

存储在浏览器的 localStorage 中，key 为 remembered_credentials，数据经过 Base64 编码。

Q3: 如何自定义白名单路由？

编辑 src/router/guards/permission.ts 的 LOGIN_WHITE_LIST 数组。

Q4: 为什么登录后还是跳转到登录页？

检查以下几点：

1. Token 是否正确保存到 store
2. userStore.isLogin 是否设置为 true
3. 路由守卫中的权限验证是否通过

下一步计划

• 添加双因素认证（2FA）
• 实现 SSO 单点登录
• 添加第三方登录（微信、钉钉等）
• 完善密码强度检测
• 添加登录日志记录