template-10584/docs/useUser-hook-guide.md

# useUser Hook 使用指南

## 概述

`useUser` hook 是一个用于管理用户状态的自定义 React Hook，类似于项目中的 `useCart` hook。它提供了用户登录状态管理、用户信息获取和更新、权限检查等功能，方便在整个应用中全局调用。

## 功能特性

- ✅ 用户登录状态管理
- ✅ 用户信息本地存储和同步
- ✅ 从服务器获取最新用户信息
- ✅ 用户信息更新
- ✅ 权限和角色检查
- ✅ 实名认证状态检查
- ✅ 用户余额和积分获取
- ✅ 自动处理登录过期

## 基本用法

### 1. 导入 Hook

```typescript
import { useUser } from '@/hooks/useUser';
```

### 2. 在组件中使用

```typescript
const MyComponent = () => {
  const {
    user,           // 用户信息
    isLoggedIn,     // 是否已登录
    loading,        // 加载状态
    loginUser,      // 登录方法
    logoutUser,     // 退出登录方法
    fetchUserInfo,  // 获取用户信息
    updateUser,     // 更新用户信息
    getDisplayName, // 获取显示名称
    isCertified,    // 是否已实名认证
    getBalance,     // 获取余额
    getPoints       // 获取积分
  } = useUser();

  // 使用用户信息
  if (loading) {
    return <div>加载中...</div>;
  }

  if (!isLoggedIn) {
    return <div>请先登录</div>;
  }

  return (
    <div>
      <h1>欢迎，{getDisplayName()}</h1>
      <p>余额：¥{getBalance()}</p>
      <p>积分：{getPoints()}</p>
      {isCertified() && <span>已实名认证</span>}
    </div>
  );
};
```

## API 参考

### 状态属性

| 属性 | 类型 | 描述 |
|------|------|------|
| `user` | `User \| null` | 当前用户信息 |
| `isLoggedIn` | `boolean` | 用户是否已登录 |
| `loading` | `boolean` | 是否正在加载 |

### 方法

#### `loginUser(token: string, userInfo: User)`
用户登录，保存用户信息和 token 到本地存储。

```typescript
const handleLogin = async () => {
  const { access_token, user } = await loginApi(credentials);
  loginUser(access_token, user);
};
```

#### `logoutUser()`
用户退出登录，清除本地存储的用户信息。

```typescript
const handleLogout = () => {
  logoutUser();
  // 跳转到首页或登录页
};
```

#### `fetchUserInfo()`
从服务器获取最新的用户信息。

```typescript
const refreshUserInfo = async () => {
  const userInfo = await fetchUserInfo();
  console.log('最新用户信息:', userInfo);
};
```

#### `updateUser(userData: Partial<User>)`
更新用户信息。

```typescript
const updateProfile = async () => {
  try {
    await updateUser({
      nickname: '新昵称',
      avatar: 'new-avatar-url'
    });
    console.log('更新成功');
  } catch (error) {
    console.error('更新失败:', error);
  }
};
```

### 工具方法

#### `hasPermission(permission: string)`
检查用户是否有特定权限。

```typescript
if (hasPermission('user:edit')) {
  // 显示编辑按钮
}
```

#### `hasRole(roleCode: string)`
检查用户是否有特定角色。

```typescript
if (hasRole('admin')) {
  // 显示管理员功能
}
```

#### `getAvatarUrl()`
获取用户头像 URL。

```typescript
<Avatar src={getAvatarUrl()} />
```

#### `getDisplayName()`
获取用户显示名称（优先级：昵称 > 真实姓名 > 用户名）。

```typescript
<span>欢迎，{getDisplayName()}</span>
```

#### `isCertified()`
检查用户是否已实名认证。

```typescript
{isCertified() && <Badge>已认证</Badge>}
```

#### `getBalance()`
获取用户余额。

```typescript
<span>余额：¥{getBalance()}</span>
```

#### `getPoints()`
获取用户积分。

```typescript
<span>积分：{getPoints()}</span>
```

## 使用场景

### 1. 用户资料页面

```typescript
const UserProfile = () => {
  const { user, updateUser, getDisplayName, getAvatarUrl } = useUser();

  const handleUpdateProfile = async (formData) => {
    await updateUser(formData);
  };

  return (
    <div>
      <Avatar src={getAvatarUrl()} />
      <h2>{getDisplayName()}</h2>
      <ProfileForm onSubmit={handleUpdateProfile} />
    </div>
  );
};
```

### 2. 权限控制

```typescript
const AdminPanel = () => {
  const { hasRole, hasPermission } = useUser();

  if (!hasRole('admin')) {
    return <div>无权限访问</div>;
  }

  return (
    <div>
      {hasPermission('user:delete') && (
        <Button danger>删除用户</Button>
      )}
    </div>
  );
};
```

### 3. 登录状态检查

```typescript
const ProtectedComponent = () => {
  const { isLoggedIn, loading } = useUser();

  if (loading) return <Loading />;
  
  if (!isLoggedIn) {
    return <LoginPrompt />;
  }

  return <ProtectedContent />;
};
```

### 4. 用户余额显示

```typescript
const WalletCard = () => {
  const { getBalance, getPoints, fetchUserInfo } = useUser();

  const refreshBalance = () => {
    fetchUserInfo(); // 刷新用户信息包括余额
  };

  return (
    <div>
      <div>余额：¥{getBalance()}</div>
      <div>积分：{getPoints()}</div>
      <Button onClick={refreshBalance}>刷新</Button>
    </div>
  );
};
```

## 注意事项

1. **自动登录过期处理**：当 API 返回 401 错误时，hook 会自动清除登录状态。

2. **本地存储同步**：用户信息会自动同步到本地存储，页面刷新后状态会保持。

3. **错误处理**：所有异步操作都包含错误处理，失败时会显示相应的提示信息。

4. **性能优化**：用户信息只在必要时从服务器获取，避免不必要的网络请求。

## 与 useCart 的对比

| 特性 | useCart | useUser |
|------|---------|---------|
| 数据存储 | 购物车商品 | 用户信息 |
| 本地持久化 | ✅ | ✅ |
| 服务器同步 | ❌ | ✅ |
| 状态管理 | ✅ | ✅ |
| 全局访问 | ✅ | ✅ |
| 权限控制 | ❌ | ✅ |

这样，用户信息管理就像购物车一样方便了，可以在任何组件中轻松访问和操作用户状态！