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`

**核心函数**:
```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 单点登录
- [ ] 添加第三方登录（微信、钉钉等）
- [ ] 完善密码强度检测
- [ ] 添加登录日志记录