# 个人资产策略管理系统 - 后端API文档

## 文档概述

本文档定义了个人资产策略管理系统的后端API接口规范，包括资产管理、策略管理、用户管理等功能模块的API接口。前端通过这些接口与后端进行数据交互，实现完整的业务功能。

## 基础信息

### 基础URL
```
https://api.demo.com 
```

### 认证方式
- **Bearer Token**：在请求头中添加 `Authorization: Bearer <token>`
- **Token获取**：通过登录接口获取，有效期为24小时

### 响应格式

所有API接口返回统一的JSON格式：

```json
{
  "code": 200,           // 状态码，200表示成功，其他表示错误
  "data": {},            // 响应数据，根据接口不同返回不同结构
  "message": "success"   // 响应消息，错误时返回错误信息
}
```

### 状态码说明

| 状态码 | 描述 |
|-------|------|
| 200   | 成功 |
| 400   | 请求参数错误 |
| 401   | 未授权 |
| 403   | 禁止访问 |
| 404   | 资源不存在 |
| 500   | 服务器内部错误 |

## API接口列表

### 1. 资产相关API

#### 1.1 获取总资产数据

**接口**：`GET /api/assets`

**请求参数**：无

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| totalValue | number | 总资产估值（CNY） |
| todayProfit | number | 今日盈亏（CNY） |
| totalReturnRate | number | 累计收益率（%） |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "totalValue": 1284592.40,
    "todayProfit": 12482.00,
    "totalReturnRate": 24.82
  },
  "message": "success"
}
```

#### 1.2 获取持仓组合数据

**接口**：`GET /api/holdings`

**请求参数**：无

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 持仓组合ID |
| name | string | 持仓组合名称 |
| tags | string | 持仓组合标签 |
| status | string | 状态（监控中/等待信号） |
| statusType | string | 状态类型（green/gray） |
| iconChar | string | 图标字符 |
| iconBgClass | string | 图标背景样式类 |
| iconTextClass | string | 图标文本样式类 |
| value | number | 当前市值（CNY） |
| returnRate | number | 累计收益率（%） |
| returnType | string | 收益类型（positive/negative） |

**示例响应**：

```json
{
  "code": 200,
  "data": [
    {
      "id": "hfea-001",
      "name": "美股全天候杠杆",
      "tags": "HFEA · 季度调仓",
      "status": "监控中",
      "statusType": "green",
      "iconChar": "H",
      "iconBgClass": "bg-green-100",
      "iconTextClass": "text-green-700",
      "value": 156240.00,
      "returnRate": 42.82,
      "returnType": "positive"
    },
    {
      "id": "ma-002",
      "name": "纳指双均线趋势",
      "tags": "趋势跟踪 · 日线",
      "status": "等待信号",
      "statusType": "gray",
      "iconChar": "T",
      "iconBgClass": "bg-blue-100",
      "iconTextClass": "text-blue-700",
      "value": 412500.00,
      "returnRate": -1.79,
      "returnType": "negative"
    }
  ],
  "message": "success"
}
```

### 2. 策略相关API

#### 2.1 获取策略列表

**接口**：`GET /api/strategies`

**请求参数**：无

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 策略ID |
| iconChar | string | 图标字符 |
| title | string | 策略标题 |
| tag | string | 策略标签 |
| desc | string | 策略描述 |
| bgClass | string | 背景样式类 |
| tagClass | string | 标签样式类 |
| tags | array<string> | 策略标签数组 |
| btnText | string | 按钮文本 |
| btnClass | string | 按钮样式类 |

**示例响应**：

```json
{
  "code": 200,
  "data": [
    {
      "id": "hfea",
      "iconChar": "H",
      "title": "HFEA 风险平价策略",
      "tag": "高风险 · 高预期收益",
      "desc": "针对杠杆ETF平衡的对冲策略，核心逻辑为 TMF (3x长债) 与 UPRO (3x标普) 的季度平衡。",
      "bgClass": "bg-emerald-900",
      "tagClass": "text-emerald-700",
      "tags": ["季调", "止损机制"],
      "btnText": "配置参数",
      "btnClass": "btn-primary"
    },
    {
      "id": "ma",
      "iconChar": "T",
      "title": "双均线趋势跟随",
      "tag": "中风险 · 低回撤要求",
      "desc": "利用快线（EMA10）上穿慢线（EMA60）捕捉强势波段，金叉买入，死叉离场。",
      "bgClass": "bg-blue-600",
      "tagClass": "text-blue-700",
      "tags": ["日线", "左侧止盈"],
      "btnText": "预览模型",
      "btnClass": "btn-secondary"
    }
  ],
  "message": "success"
}
```

#### 2.2 获取单个策略详情

**接口**：`GET /api/strategies/{id}`

**请求参数**：

| 参数名 | 类型 | 位置 | 描述 |
|-------|------|------|------|
| id | string | 路径参数 | 策略ID |

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 策略ID |
| iconChar | string | 图标字符 |
| title | string | 策略标题 |
| tag | string | 策略标签 |
| desc | string | 策略描述 |
| bgClass | string | 背景样式类 |
| tagClass | string | 标签样式类 |
| tags | array<string> | 策略标签数组 |
| parameters | object | 策略参数配置 |
| backtest | object | 回测数据 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "id": "hfea",
    "iconChar": "H",
    "title": "HFEA 风险平价策略",
    "tag": "高风险 · 高预期收益",
    "desc": "针对杠杆ETF平衡的对冲策略，核心逻辑为 TMF (3x长债) 与 UPRO (3x标普) 的季度平衡。",
    "bgClass": "bg-emerald-900",
    "tagClass": "text-emerald-700",
    "tags": ["季调", "止损机制"],
    "parameters": {
      "tmfRatio": 0.55,
      "uproRatio": 0.45,
      "rebalanceInterval": "quarterly",
      "stopLoss": 0.2
    },
    "backtest": {
      "totalReturn": 1.85,
      "maxDrawdown": 0.32,
      "sharpeRatio": 0.87,
      "winRate": 0.58
    }
  },
  "message": "success"
}
```

#### 2.3 创建新策略

**接口**：`POST /api/strategies`

**请求参数**：

| 字段名 | 类型 | 描述 | 必填 |
|-------|------|------|------|
| title | string | 策略标题 | 是 |
| tag | string | 策略标签 | 是 |
| desc | string | 策略描述 | 是 |
| tags | array<string> | 策略标签数组 | 是 |
| parameters | object | 策略参数配置 | 是 |
| iconChar | string | 图标字符 | 否 |
| bgClass | string | 背景样式类 | 否 |
| tagClass | string | 标签样式类 | 否 |

**示例请求**：

```json
{
  "title": "自定义策略",
  "tag": "中风险 · 自定义",
  "desc": "基于移动平均线的趋势策略",
  "tags": ["日线", "趋势跟踪"],
  "parameters": {
    "fastPeriod": 10,
    "slowPeriod": 60,
    "stopLoss": 0.15
  },
  "iconChar": "C",
  "bgClass": "bg-purple-600",
  "tagClass": "text-purple-700"
}
```

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 新创建的策略ID |
| title | string | 策略标题 |
| status | string | 创建状态 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "id": "custom-001",
    "title": "自定义策略",
    "status": "created"
  },
  "message": "success"
}
```

#### 2.4 更新策略

**接口**：`PUT /api/strategies/{id}`

**请求参数**：

| 参数名 | 类型 | 位置 | 描述 |
|-------|------|------|------|
| id | string | 路径参数 | 策略ID |

**请求体**：

| 字段名 | 类型 | 描述 | 必填 |
|-------|------|------|------|
| title | string | 策略标题 | 否 |
| tag | string | 策略标签 | 否 |
| desc | string | 策略描述 | 否 |
| tags | array<string> | 策略标签数组 | 否 |
| parameters | object | 策略参数配置 | 否 |

**示例请求**：

```json
{
  "title": "更新后的策略",
  "parameters": {
    "tmfRatio": 0.6,
    "uproRatio": 0.4
  }
}
```

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 策略ID |
| status | string | 更新状态 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "id": "hfea",
    "status": "updated"
  },
  "message": "success"
}
```

#### 2.5 删除策略

**接口**：`DELETE /api/strategies/{id}`

**请求参数**：

| 参数名 | 类型 | 位置 | 描述 |
|-------|------|------|------|
| id | string | 路径参数 | 策略ID |

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 策略ID |
| status | string | 删除状态 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "id": "custom-001",
    "status": "deleted"
  },
  "message": "success"
}
```

### 3. 用户相关API

#### 3.1 获取用户信息

**接口**：`GET /api/user/info`

**请求参数**：无

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| userName | string | 用户名 |
| memberLevel | string | 会员等级 |
| runningDays | number | 连续运行天数 |
| avatar | string | 头像URL |
| email | string | 邮箱 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "userName": "首席策略员 0x42",
    "memberLevel": "全球实验室 Pro",
    "runningDays": 412,
    "avatar": "https://example.com/avatar.png",
    "email": "user@example.com"
  },
  "message": "success"
}
```

#### 3.2 获取用户统计数据

**接口**：`GET /api/user/stats`

**请求参数**：无

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| signalsCaptured | number | 已捕获信号数量 |
| winRate | number | 模拟胜率（%） |
| totalTrades | number | 总交易次数 |
| averageProfit | number | 平均收益（%） |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "signalsCaptured": 1248,
    "winRate": 58.4,
    "totalTrades": 2138,
    "averageProfit": 2.3
  },
  "message": "success"
}
```

#### 3.3 更新用户信息

**接口**：`PUT /api/user/info`

**请求参数**：

| 字段名 | 类型 | 描述 | 必填 |
|-------|------|------|------|
| userName | string | 用户名 | 否 |
| avatar | string | 头像URL | 否 |
| email | string | 邮箱 | 否 |

**示例请求**：

```json
{
  "userName": "策略大师 0x42",
  "email": "newemail@example.com"
}
```

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| status | string | 更新状态 |
| userName | string | 更新后的用户名 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "status": "updated",
    "userName": "策略大师 0x42"
  },
  "message": "success"
}
```

### 4. 应用相关API

#### 4.1 获取应用信息

**接口**：`GET /api/app/info`

**请求参数**：无

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| version | string | 应用版本 |
| currentDate | string | 当前日期（YYYY-MM-DD） |
| latestVersion | string | 最新版本 |
| updateAvailable | boolean | 是否有更新 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "version": "v2.4.0",
    "currentDate": "2026-02-16",
    "latestVersion": "v2.4.0",
    "updateAvailable": false
  },
  "message": "success"
}
```

## 5. 认证相关API

#### 5.1 用户登录

**接口**：`POST /api/auth/login`

**请求参数**：

| 字段名 | 类型 | 描述 | 必填 |
|-------|------|------|------|
| email | string | 邮箱 | 是 |
| password | string | 密码 | 是 |

**示例请求**：

```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| token | string | 认证令牌 |
| expireAt | string | 令牌过期时间 |
| user | object | 用户基本信息 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expireAt": "2026-02-17T10:00:00Z",
    "user": {
      "userName": "首席策略员 0x42",
      "memberLevel": "全球实验室 Pro"
    }
  },
  "message": "success"
}
```

#### 5.2 用户注册

**接口**：`POST /api/auth/register`

**请求参数**：

| 字段名 | 类型 | 描述 | 必填 |
|-------|------|------|------|
| email | string | 邮箱 | 是 |
| password | string | 密码 | 是 |
| userName | string | 用户名 | 是 |

**示例请求**：

```json
{
  "email": "newuser@example.com",
  "password": "password123",
  "userName": "新用户"
}
```

**响应参数**：

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 用户ID |
| status | string | 注册状态 |

**示例响应**：

```json
{
  "code": 200,
  "data": {
    "id": "user-001",
    "status": "registered"
  },
  "message": "success"
}
```

## 6. 部署与集成

### 6.1 环境变量配置

后端服务需要配置以下环境变量：

| 环境变量 | 描述 | 默认值 |
|---------|------|--------|
| PORT | 服务端口 | 3000 |
| DATABASE_URL | 数据库连接URL | - |
| JWT_SECRET | JWT密钥 | - |
| JWT_EXPIRES_IN | JWT过期时间 | 24h |
| CORS_ORIGIN | CORS允许的源 | * |

### 6.2 API集成示例

前端使用示例（基于之前的API工具类）：

```javascript
// 导入API工具类
import { api } from '@/utils/api';

// 登录获取token
const login = async (email, password) => {
  const response = await api.auth.login({ email, password });
  if (response.code === 200) {
    // 存储token
    localStorage.setItem('token', response.data.token);
    return response.data;
  }
};

// 获取资产数据
const fetchAssetData = async () => {
  const response = await api.assets.getAssetData();
  if (response.code === 200) {
    return response.data;
  }
};
```

## 7. 监控与维护

### 7.1 日志记录

后端服务应记录以下类型的日志：
- 访问日志：记录API请求和响应
- 错误日志：记录系统错误和异常
- 业务日志：记录重要的业务操作

### 7.2 健康检查

提供健康检查接口：

**接口**：`GET /api/health`

**响应**：

```json
{
  "status": "healthy",
  "timestamp": "2026-02-16T10:00:00Z",
  "services": {
    "database": "connected",
    "cache": "connected"
  }
}
```

## 8. 安全考虑

### 8.1 数据安全
- 使用HTTPS加密传输
- 密码使用bcrypt等算法加密存储
- 敏感数据脱敏处理

### 8.2 API安全
- 实现请求频率限制
- 验证请求参数
- 防止SQL注入和XSS攻击
- 定期更新依赖包，修复安全漏洞

## 9. 版本控制

API版本控制采用URL路径前缀方式：

```
https://api.demo.com/v1/...
https://api.demo.com/v2/...
```

当API接口发生重大变更时，应增加版本号，保持向后兼容。

## 10. 总结

本文档定义了个人资产策略管理系统的后端API接口规范，覆盖了资产管理、策略管理、用户管理等核心功能模块。后端开发团队应严格按照本文档实现API接口，确保与前端的无缝集成。

随着业务的发展，API接口可能需要不断调整和扩展，文档应及时更新以反映最新的API规范。