vf_react/docs/API_ENDPOINTS.md

# API 接口文档

本文档记录了项目中所有 API 接口的详细信息。

## 目录
- [认证相关 API](#认证相关-api)
- [个人中心相关 API](#个人中心相关-api)
- [事件相关 API](#事件相关-api)
- [股票相关 API](#股票相关-api)
- [公司相关 API](#公司相关-api)
- [订阅/支付相关 API](#订阅支付相关-api)

---

## 认证相关 API

### POST /api/auth/send-verification-code
发送验证码到手机号或邮箱

**请求参数**:
```json
{
  "credential": "13800138000",  // 手机号或邮箱
  "type": "phone",              // 'phone' | 'email'
  "purpose": "login"            // 'login' | 'register'
}
```

**响应示例**:
```json
{
  "success": true,
  "message": "验证码已发送到 13800138000",
  "dev_code": "123456"  // 仅开发环境返回
}
```

**错误响应**:
```json
{
  "success": false,
  "error": "发送验证码失败"
}
```

**Mock 数据**: ✅ `src/mocks/handlers/auth.js` 行 21-44

**涉及文件**:
- `src/components/Auth/AuthFormContent.js` 行 164-207

---

### POST /api/auth/login-with-code
使用验证码登录（支持自动注册新用户）

**请求参数**:
```json
{
  "credential": "13800138000",
  "verification_code": "123456",
  "login_type": "phone"  // 'phone' | 'email'
}
```

**响应示例**:
```json
{
  "success": true,
  "message": "登录成功",
  "isNewUser": false,
  "user": {
    "id": 1,
    "phone": "13800138000",
    "nickname": "用户昵称",
    "email": null,
    "avatar_url": "https://...",
    "has_wechat": false
  },
  "token": "mock_token_1_1234567890"
}
```

**错误响应**:
```json
{
  "success": false,
  "error": "验证码错误"
}
```

**Mock 数据**: ✅ `src/mocks/handlers/auth.js` 行 47-115

**涉及文件**:
- `src/components/Auth/AuthFormContent.js` 行 252-327

**注意事项**:
- 后端需要支持自动注册新用户（当用户不存在时）
- 前端已添加 `.trim()` 防止空格问题

---

### GET /api/auth/session
检查当前登录状态

**响应示例**:
```json
{
  "success": true,
  "isAuthenticated": true,
  "user": {
    "id": 1,
    "phone": "13800138000",
    "nickname": "用户昵称"
  }
}
```

**Mock 数据**: ✅ `src/mocks/handlers/auth.js` 行 269-290

---

### POST /api/auth/logout
退出登录

**响应示例**:
```json
{
  "success": true,
  "message": "退出成功"
}
```

**Mock 数据**: ✅ `src/mocks/handlers/auth.js` 行 317-329

---

## 个人中心相关 API

### GET /api/account/watchlist
获取用户自选股列表

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "stock_code": "000001.SZ",
      "stock_name": "平安银行",
      "added_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

**Mock 数据**: ❌ 待创建 `src/mocks/handlers/account.js`

**涉及文件**:
- `src/views/Dashboard/Center.js` 行 94

---

### GET /api/account/watchlist/realtime
获取自选股实时行情

**响应示例**:
```json
{
  "success": true,
  "data": {
    "000001.SZ": {
      "price": 12.34,
      "change": 0.56,
      "change_percent": 4.76,
      "volume": 123456789
    }
  }
}
```

**Mock 数据**: ❌ 待创建

**涉及文件**:
- `src/views/Dashboard/Center.js` 行 133

---

### GET /api/account/events/following
获取用户关注的事件列表

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "事件标题",
      "followed_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

**Mock 数据**: ❌ 待创建

**涉及文件**:
- `src/views/Dashboard/Center.js` 行 95

---

### GET /api/account/events/comments
获取用户的事件评论

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "event_id": 123,
      "content": "评论内容",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

**Mock 数据**: ❌ 待创建

**涉及文件**:
- `src/views/Dashboard/Center.js` 行 96

---

### GET /api/subscription/current
获取当前订阅信息

**响应示例**:
```json
{
  "success": true,
  "data": {
    "plan": "premium",
    "expires_at": "2025-01-01T00:00:00Z",
    "auto_renew": true
  }
}
```

**Mock 数据**: ❌ 待创建 `src/mocks/handlers/subscription.js`

**涉及文件**:
- `src/views/Dashboard/Center.js` 行 97

---

## 事件相关 API

### GET /api/events
获取事件列表

**查询参数**:
- `page`: 页码（默认 1）
- `per_page`: 每页数量（默认 10）
- `sort`: 排序方式 ('new' | 'hot' | 'returns')
- `importance`: 重要性筛选 ('all' | 'high' | 'medium' | 'low')
- `date_range`: 日期范围
- `q`: 搜索关键词
- `industry_classification`: 行业分类
- `industry_code`: 行业代码

**响应示例**:
```json
{
  "success": true,
  "data": {
    "events": [
      {
        "id": 1,
        "title": "事件标题",
        "importance": "high",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 100
    }
  }
}
```

**Mock 数据**: ⚠️ 部分实现（需完善）

**涉及文件**:
- `src/views/Community/index.js` 行 148

---

### GET /api/events/:id
获取事件详情

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "事件标题",
    "content": "事件内容",
    "importance": "high",
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

**Mock 数据**: ❌ 待创建

---

### GET /api/events/:id/stocks
获取事件相关股票

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "stock_code": "000001.SZ",
      "stock_name": "平安银行",
      "correlation": 0.85
    }
  ]
}
```

**Mock 数据**: ✅ `src/mocks/handlers/event.js` 行 12-38

---

### GET /api/events/popular-keywords
获取热门关键词

**查询参数**:
- `limit`: 返回数量（默认 20）

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "keyword": "人工智能",
      "count": 123,
      "trend": "up"
    }
  ]
}
```

**Mock 数据**: ❌ 待创建

**涉及文件**:
- `src/views/Community/index.js` 行 180

---

### GET /api/events/hot
获取热点事件

**查询参数**:
- `days`: 天数范围（默认 5）
- `limit`: 返回数量（默认 4）

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "热点事件标题",
      "heat_score": 95.5
    }
  ]
}
```

**Mock 数据**: ❌ 待创建

**涉及文件**:
- `src/views/Community/index.js` 行 192

---

## 待补充 API

以下 API 将在重构其他文件时逐步添加：

- 股票相关 API
- 公司相关 API
- 订阅/支付相关 API
- 用户资料相关 API
- 行业分类相关 API

---

## 更新日志

- 2024-XX-XX: 创建文档，记录认证和个人中心相关 API