Initial commit: One Pipe System
完整的管理系统，包含账户管理、卡片管理、套餐管理、财务管理等功能模块。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
sexygoat
244
docs/LOGIN_MODULE.md
Normal file
244
docs/LOGIN_MODULE.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# 登录模块说明文档
|
||||
|
||||
## 概述
|
||||
|
||||
本项目的登录模块已完成重构，采用了全新的架构设计，提供了完整的认证流程和权限管理功能。
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 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`
|
||||
|
||||
**核心函数**:
|
||||
```typescript
|
||||
// 保存凭证
|
||||
saveCredentials(username, password, remember)
|
||||
|
||||
// 获取保存的凭证
|
||||
getRememberedCredentials()
|
||||
|
||||
// 清除凭证
|
||||
clearRememberedCredentials()
|
||||
```
|
||||
|
||||
### 3. 完善的表单验证
|
||||
|
||||
提供了多种验证规则，适用于不同场景：
|
||||
|
||||
- **用户名验证**: 3-20个字符，只能包含字母、数字和下划线
|
||||
- **密码验证**: 6-20个字符
|
||||
- **强密码验证**: 8-20个字符，必须包含大小写字母和数字
|
||||
- **确认密码验证**: 必须与密码一致
|
||||
- **手机号验证**: 支持中国大陆手机号格式
|
||||
- **邮箱验证**: 标准邮箱格式验证
|
||||
- **验证码验证**: 4位数字
|
||||
|
||||
**实现文件**: `src/utils/auth/loginValidation.ts`
|
||||
|
||||
**使用示例**:
|
||||
```typescript
|
||||
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 页面
|
||||
- 支持通配符权限（如 `*:*:*` 表示所有权限）
|
||||
|
||||
#### 登录重定向
|
||||
- 访问需要登录的页面时，会记录当前路径
|
||||
- 登录成功后自动跳转回之前访问的页面
|
||||
- 如果是白名单路由，则跳转到首页
|
||||
|
||||
**核心函数**:
|
||||
```typescript
|
||||
// 检查是否在白名单
|
||||
isInWhiteList(path)
|
||||
|
||||
// 检查路由权限
|
||||
hasRoutePermission(route, userInfo)
|
||||
|
||||
// 检查 Token 是否有效
|
||||
isTokenValid(token)
|
||||
|
||||
// 构建登录重定向URL
|
||||
buildLoginRedirect(currentPath)
|
||||
```
|
||||
|
||||
### 5. useLogin Composable
|
||||
|
||||
将登录逻辑抽取为可复用的 Composable，提高代码可维护性。
|
||||
|
||||
**文件位置**: `src/composables/useLogin.ts`
|
||||
|
||||
**提供的功能**:
|
||||
- 表单状态管理
|
||||
- Mock 账号切换
|
||||
- 登录逻辑处理
|
||||
- 自动记住密码
|
||||
- 登录成功通知
|
||||
- 重定向处理
|
||||
|
||||
**使用示例**:
|
||||
```vue
|
||||
<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 # 登录页面（已重构）
|
||||
```
|
||||
|
||||
## 权限配置示例
|
||||
|
||||
### 路由权限配置
|
||||
|
||||
```typescript
|
||||
// 在路由配置中添加 meta
|
||||
{
|
||||
path: '/account/platform',
|
||||
meta: {
|
||||
title: '平台账号管理',
|
||||
roles: ['R_SUPER', 'R_ADMIN'], // 允许的角色
|
||||
permissions: ['account:view:*'] // 需要的权限
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 用户权限定义
|
||||
|
||||
```typescript
|
||||
// 用户信息中包含角色和权限
|
||||
{
|
||||
roles: ['R_ADMIN'],
|
||||
permissions: [
|
||||
'account:*:*', // 账号管理所有权限
|
||||
'card:view:*', // 网卡查看权限
|
||||
'card:operation:*' // 网卡操作权限
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 开发建议
|
||||
|
||||
### 1. 切换到真实接口
|
||||
|
||||
当后端接口就绪后，只需修改 `useLogin.ts` 中的登录逻辑：
|
||||
|
||||
```typescript
|
||||
// 将 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 单点登录
|
||||
- [ ] 添加第三方登录（微信、钉钉等）
|
||||
- [ ] 完善密码强度检测
|
||||
- [ ] 添加登录日志记录
|
||||
Reference in New Issue
Block a user