# API设计和集成

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
| 2.5 | 2025-09-24 | 更新技术栈信息，修正数据库类型 | Winston |
| 2.6 | 2025-09-27 | 添加移动端应用API端点信息 | Winston |

## API集成策略
- **API集成策略**: 保持现有RESTful API设计，增强OpenAPI文档
- **认证**: JWT Bearer Token，保持现有认证机制
- **版本控制**: 使用v1前缀 (`/api/v1/`)，保持向后兼容

### OpenAPI规范
```yaml
openapi: 3.0.0
info:
  title: D8D Starter API
  version: 1.0.0
  description: D8D Starter项目RESTful API文档
servers:
  - url: http://localhost:8080/api/v1
    description: 本地开发环境
  - url: https://api.example.com/api/v1
    description: 生产环境

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
          nullable: true
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Role:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        permissions:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaginatedUsers:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        total:
          type: integer
        current:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer

security:
  - BearerAuth: []
```

## API端点示例
**用户管理端点**:
- **方法**: GET
- **端点**: `/api/v1/users`
- **用途**: 获取用户分页列表
- **集成**: 使用通用CRUD服务，支持搜索和过滤

**请求示例**:
```json
{
  "page": 1,
  "pageSize": 10,
  "keyword": "搜索词",
  "sortBy": "createdAt",
  "sortOrder": "DESC"
}
```

**响应示例**:
```json
{
  "data": [
    {
      "id": 1,
      "email": "user@example.com",
      "roles": [{"id": 1, "name": "admin"}]
    }
  ],
  "pagination": {
    "total": 100,
    "current": 1,
    "pageSize": 10
  }
}
```

**文件管理端点**:
- **方法**: POST
- **端点**: `/api/v1/files/upload-policy`
- **用途**: 生成文件上传策略和预签名URL
- **集成**: 使用MinIO服务，支持分段上传和大文件处理

**请求示例**:
```json
{
  "name": "example.pdf",
  "type": "application/pdf",
  "size": 1048576,
  "description": "示例文件"
}
```

**响应示例**:
```json
{
  "file": {
    "id": 123,
    "name": "example.pdf",
    "path": "user-1/uuid-example.pdf",
    "size": 1048576,
    "type": "application/pdf",
    "uploadUserId": 1,
    "uploadTime": "2025-09-19T10:30:00.000Z"
  },
  "uploadPolicy": {
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "minioadmin/20250919/us-east-1/s3/aws4_request",
    "x-amz-date": "20250919T103000Z",
    "policy": "base64-encoded-policy",
    "x-amz-signature": "signature",
    "host": "https://minio.example.com",
    "key": "user-1/uuid-example.pdf",
    "bucket": "d8dai"
  }
}
```

## 移动端应用特有API端点

**课堂系统实时通信API**:
- **协议**: WebSocket (Socket.IO)
- **端点**: Socket.IO连接端点
- **用途**: 实时课堂消息传递、学生举手、老师控制等
- **事件类型**:
  - `join_classroom`: 加入课堂
  - `leave_classroom`: 离开课堂
  - `send_message`: 发送消息
  - `hand_up`: 学生举手
  - `teacher_control`: 老师课堂控制

**股票训练系统实时数据API**:
- **协议**: WebSocket (Socket.IO)
- **端点**: Socket.IO连接端点
- **用途**: 实时股票数据推送、交易信息、K线图数据
- **事件类型**:
  - `subscribe_stock`: 订阅股票数据
  - `unsubscribe_stock`: 取消订阅
  - `stock_data`: 股票实时数据推送
  - `trade_execution`: 交易执行结果

**阿里云RTC音视频API**:
- **协议**: RESTful API + WebRTC
- **端点**: `/api/v1/rtc/token`
- **用途**: 生成RTC音视频通信token
- **请求示例**:
```json
{
  "channelName": "classroom-123",
  "userId": "user-456",
  "role": "teacher"
}
```

**响应示例**:
```json
{
  "token": "rtc-token-string",
  "appId": "your-app-id",
  "channelName": "classroom-123"
}
```

**视频回放API**:
- **方法**: GET
- **端点**: `/api/v1/videos/{id}/playback`
- **用途**: 获取视频回放信息和播放地址
- **响应示例**:
```json
{
  "video": {
    "id": 123,
    "title": "股票分析课程",
    "duration": 3600,
    "playbackUrl": "https://cdn.example.com/videos/123.mp4",
    "thumbnail": "https://cdn.example.com/thumbnails/123.jpg"
  }
}
```

## API安全集成

**移动端API安全要求**:
- **JWT认证**: 所有移动端API必须使用JWT Bearer Token认证
- **权限控制**: 基于用户角色（TEACHER, STUDENT, TRAINEE）进行权限验证
- **实时通信安全**: Socket.IO连接需要验证用户身份和权限
- **音视频安全**: RTC token生成需要验证用户身份和课堂权限
- **数据加密**: 敏感数据传输使用TLS加密

**移动端API错误处理**:
```json
{
  "code": "CLASSROOM_NOT_FOUND",
  "message": "课堂不存在或已结束",
  "timestamp": "2025-09-27T10:30:00.000Z"
}
```