# 用户资料完整度 API 文档

## 接口概述

**接口名称**：获取用户资料完整度
**接口路径**：`/api/account/profile-completeness`
**请求方法**：`GET`
**接口描述**：获取当前登录用户的资料完整度信息，包括各项必填信息的完成状态、完整度百分比、缺失项列表等。
**业务场景**：用于在用户登录后提醒用户完善个人资料，提升平台服务质量。

---

## 请求参数

### Headers

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `Cookie` | string | 是 | 包含用户会话信息（session cookie），用于身份认证 |

### Query Parameters

无

### Body Parameters

无（GET 请求无 Body）

---

## 响应格式

### 成功响应 (200 OK)

**Content-Type**: `application/json`

```json
{
  "success": true,
  "data": {
    "completeness": {
      "hasPassword": true,
      "hasPhone": true,
      "hasEmail": false,
      "isWechatUser": false
    },
    "completenessPercentage": 66,
    "needsAttention": false,
    "missingItems": ["邮箱"],
    "isComplete": false,
    "showReminder": false
  }
}
```

### 响应字段说明

#### 顶层字段

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `success` | boolean | 请求是否成功，`true` 表示成功 |
| `data` | object | 资料完整度数据对象 |

#### `data` 对象字段

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `completeness` | object | 各项资料的完成状态详情 |
| `completenessPercentage` | number | 资料完整度百分比（0-100） |
| `needsAttention` | boolean | 是否需要用户注意（提醒用户完善） |
| `missingItems` | array[string] | 缺失项的中文描述列表 |
| `isComplete` | boolean | 资料是否完全完整（100%） |
| `showReminder` | boolean | 是否显示提醒横幅（同 `needsAttention`） |

#### `completeness` 对象字段

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `hasPassword` | boolean | 是否已设置登录密码 |
| `hasPhone` | boolean | 是否已绑定手机号 |
| `hasEmail` | boolean | 是否已设置有效邮箱（排除临时邮箱） |
| `isWechatUser` | boolean | 是否为微信登录用户 |

---

## 业务逻辑说明

### 资料完整度计算规则

1. **必填项**（共 3 项）：
   - 登录密码（`hasPassword`）
   - 手机号（`hasPhone`）
   - 邮箱（`hasEmail`）

2. **完整度计算公式**：
   ```
   completenessPercentage = (已完成项数 / 3) × 100
   ```
   示例：
   - 已完成 2 项 → 66%
   - 已完成 3 项 → 100%

3. **邮箱有效性判断**：
   - 必须包含 `@` 符号
   - 不能是临时邮箱（如 `*@valuefrontier.temp`）

### 提醒逻辑（`needsAttention`）

**仅对微信登录用户进行提醒**，需同时满足以下条件：

1. `isWechatUser === true`（微信登录用户）
2. `completenessPercentage < 100`（资料不完整）

**后端额外的智能提醒策略**（Mock 模式未实现）：

- 新用户（注册 7 天内）：更容易触发提醒
- 每 7 天最多提醒一次（通过 session 记录）
- 完整度低于 50% 时优先提醒

### 缺失项列表（`missingItems`）

根据 `completeness` 对象生成中文描述：

| 条件 | 添加到 `missingItems` |
|------|----------------------|
| `!hasPassword` | `"登录密码"` |
| `!hasPhone` | `"手机号"` |
| `!hasEmail` | `"邮箱"` |

---

## 响应示例

### 示例 1：手机号登录用户，资料完整

**场景**：手机号登录，已设置密码和邮箱

```json
{
  "success": true,
  "data": {
    "completeness": {
      "hasPassword": true,
      "hasPhone": true,
      "hasEmail": true,
      "isWechatUser": false
    },
    "completenessPercentage": 100,
    "needsAttention": false,
    "missingItems": [],
    "isComplete": true,
    "showReminder": false
  }
}
```

### 示例 2：微信登录用户，未绑定手机号

**场景**：微信登录，未设置密码和手机号，触发提醒

```json
{
  "success": true,
  "data": {
    "completeness": {
      "hasPassword": false,
      "hasPhone": false,
      "hasEmail": true,
      "isWechatUser": true
    },
    "completenessPercentage": 33,
    "needsAttention": true,
    "missingItems": ["登录密码", "手机号"],
    "isComplete": false,
    "showReminder": true
  }
}
```

### 示例 3：微信登录用户，只缺邮箱

**场景**：微信登录，已设置密码和手机号，只缺邮箱

```json
{
  "success": true,
  "data": {
    "completeness": {
      "hasPassword": true,
      "hasPhone": true,
      "hasEmail": false,
      "isWechatUser": true
    },
    "completenessPercentage": 66,
    "needsAttention": true,
    "missingItems": ["邮箱"],
    "isComplete": false,
    "showReminder": true
  }
}
```

---

## 错误响应

### 401 Unauthorized - 未登录

**场景**：用户未登录或 Session 已过期

```json
{
  "success": false,
  "error": "用户未登录"
}
```

**HTTP 状态码**：`401`

### 500 Internal Server Error - 服务器错误

**场景**：服务器内部错误（如数据库连接失败）

```json
{
  "success": false,
  "error": "获取资料完整性错误: [错误详情]"
}
```

**HTTP 状态码**：`500`

---

## 调用示例

### JavaScript (Fetch API)

```javascript
async function checkProfileCompleteness() {
  try {
    const response = await fetch('/api/account/profile-completeness', {
      method: 'GET',
      credentials: 'include', // 重要：携带 Cookie
      headers: {
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    if (data.success) {
      console.log('资料完整度:', data.data.completenessPercentage + '%');
      console.log('是否需要提醒:', data.data.needsAttention);

      if (data.data.needsAttention) {
        console.log('缺失项:', data.data.missingItems.join('、'));
      }
    }
  } catch (error) {
    console.error('检查资料完整性失败:', error);
  }
}
```

### cURL

```bash
curl -X GET 'http://localhost:5001/api/account/profile-completeness' \
  -H 'Cookie: session=your_session_cookie_here' \
  -H 'Content-Type: application/json'
```

### Axios

```javascript
import axios from 'axios';

async function checkProfileCompleteness() {
  try {
    const { data } = await axios.get('/api/account/profile-completeness', {
      withCredentials: true // 携带 Cookie
    });

    if (data.success) {
      return data.data;
    }
  } catch (error) {
    if (error.response?.status === 401) {
      console.error('用户未登录');
    } else {
      console.error('检查失败:', error.message);
    }
  }
}
```

---

## 调用时机建议

### ✅ 推荐调用场景

1. **用户登录后**：首次登录或刷新页面后检查一次
2. **资料更新后**：用户修改个人资料后重新检查
3. **手动触发**：用户点击"检查资料完整度"按钮

### ❌ 避免的场景

1. **导航栏每次 render 时**：会导致频繁请求
2. **组件重新渲染时**：应使用缓存或标志位避免重复
3. **轮询调用**：此接口不需要轮询，用户资料变化频率低

### 最佳实践

```javascript
// 使用 React Hooks 的最佳实践
function useProfileCompleteness() {
  const [completeness, setCompleteness] = useState(null);
  const hasChecked = useRef(false);
  const { isAuthenticated, user } = useAuth();

  const check = useCallback(async () => {
    // 避免重复检查
    if (hasChecked.current) return;

    try {
      const response = await fetch('/api/account/profile-completeness', {
        credentials: 'include'
      });

      if (response.ok) {
        const data = await response.json();
        if (data.success) {
          setCompleteness(data.data);
          hasChecked.current = true; // 标记已检查
        }
      }
    } catch (error) {
      console.warn('检查失败:', error);
    }
  }, []);

  // 仅在登录后检查一次
  useEffect(() => {
    if (isAuthenticated && user && !hasChecked.current) {
      check();
    }
  }, [isAuthenticated, user, check]);

  // 提供手动刷新方法
  const refresh = useCallback(() => {
    hasChecked.current = false;
    check();
  }, [check]);

  return { completeness, refresh };
}
```

---

## Mock 模式说明

在 Mock 模式下（`REACT_APP_ENABLE_MOCK=true`），此接口由 MSW (Mock Service Worker) 拦截：

### Mock 实现位置

- **Handler**: `src/mocks/handlers/account.js`
- **数据源**: `src/mocks/data/users.js` (getCurrentUser)

### Mock 特点

1. **真实计算**：基于当前登录用户的实际数据计算完整度
2. **状态同步**：与登录状态同步，登录后才返回真实用户数据
3. **未登录返回 401**：模拟真实后端行为
4. **延迟模拟**：300ms 网络延迟，模拟真实请求

### Mock 测试数据

| 测试账号 | 手机号 | 密码 | 邮箱 | 微信 | 完整度 |
|---------|--------|------|------|------|--------|
| 测试用户 | 13800138000 | ✅ | ❌ | ❌ | 66% |
| 投资达人 | 13900139000 | ✅ | ✅ | ✅ | 100% |

---

## 前端集成示例

### 显示资料完整度横幅

```jsx
import { useProfileCompleteness } from './hooks/useProfileCompleteness';

function App() {
  const { completeness } = useProfileCompleteness();

  return (
    <>
      {/* 资料完整度提醒横幅 */}
      {completeness?.showReminder && (
        <Alert status="info" variant="subtle">
          <AlertIcon />
          <Box flex="1">
            <AlertTitle>完善资料，享受更好服务</AlertTitle>
            <AlertDescription>
              您还需要设置：{completeness.missingItems.join('、')}
              （{completeness.completenessPercentage}% 完成）
            </AlertDescription>
          </Box>
          <Button size="sm" onClick={() => navigate('/settings')}>
            立即完善
          </Button>
        </Alert>
      )}

      {/* 主要内容 */}
      <MainContent />
    </>
  );
}
```

---

## 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|----------|
| v1.0 | 2024-10-17 | 初始版本，支持资料完整度检查和智能提醒 |

---

## 相关接口

- `GET /api/auth/session` - 检查登录状态
- `GET /api/account/profile` - 获取完整用户资料
- `PUT /api/account/profile` - 更新用户资料
- `POST /api/auth/logout` - 退出登录

---

## 技术支持

如有问题，请联系开发团队或查看：
- **Mock 配置指南**: [MOCK_GUIDE.md](./MOCK_GUIDE.md)
- **项目文档**: [CLAUDE.md](./CLAUDE.md)

---

**文档生成日期**：2024-10-17
**API 版本**：v1.0
**Mock 支持**：✅ 已实现