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

## 1. 基础信息

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

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

### 1.3 响应格式

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

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

### 1.4 状态码说明

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

## 2. API接口列表

### 2.1 资产相关API

#### 2.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"
}
```

#### 2.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.2 策略相关API

#### 2.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.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.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.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.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"
}
```

### 2.3 用户相关API

#### 2.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"
}
```

#### 2.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"
}
```

#### 2.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"
}
```

### 2.4 应用相关API

#### 2.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"
}
```

### 2.5 认证相关API

#### 2.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"
}
```

#### 2.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"
}
```

## 3. 实体类定义

### 3.1 资产相关实体

#### 3.1.1 AssetData
```typescript
interface AssetData {
  totalValue: number;        // 总资产估值（CNY）
  todayProfit: number;       // 今日盈亏（CNY）
  totalReturnRate: number;   // 累计收益率（%）
}
```

#### 3.1.2 Holding
```typescript
interface Holding {
  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）
}
```

### 3.2 策略相关实体

#### 3.2.1 Strategy
```typescript
interface Strategy {
  id: string;               // 策略ID
  iconChar: string;         // 图标字符
  title: string;            // 策略标题
  tag: string;              // 策略标签
  desc: string;             // 策略描述
  bgClass: string;          // 背景样式类
  tagClass: string;         // 标签样式类
  tags: string[];           // 策略标签数组
  btnText: string;          // 按钮文本
  btnClass: string;         // 按钮样式类
  parameters?: object;      // 策略参数配置（可选）
  backtest?: BacktestData;  // 回测数据（可选）
}
```

#### 3.2.2 BacktestData
```typescript
interface BacktestData {
  totalReturn: number;      // 总收益
  maxDrawdown: number;      // 最大回撤
  sharpeRatio: number;      // 夏普比率
  winRate: number;          // 胜率
}
```

#### 3.2.3 StrategyCreate
```typescript
interface StrategyCreate {
  title: string;            // 策略标题
  tag: string;              // 策略标签
  desc: string;             // 策略描述
  tags: string[];           // 策略标签数组
  parameters: object;       // 策略参数配置
  iconChar?: string;        // 图标字符（可选）
  bgClass?: string;         // 背景样式类（可选）
  tagClass?: string;        // 标签样式类（可选）
}
```

#### 3.2.4 StrategyUpdate
```typescript
interface StrategyUpdate {
  title?: string;           // 策略标题（可选）
  tag?: string;             // 策略标签（可选）
  desc?: string;            // 策略描述（可选）
  tags?: string[];          // 策略标签数组（可选）
  parameters?: object;      // 策略参数配置（可选）
}
```

### 3.3 用户相关实体

#### 3.3.1 UserInfo
```typescript
interface UserInfo {
  userName: string;         // 用户名
  memberLevel: string;      // 会员等级
  runningDays: number;      // 连续运行天数
  avatar?: string;          // 头像URL（可选）
  email?: string;           // 邮箱（可选）
}
```

#### 3.3.2 UserStats
```typescript
interface UserStats {
  signalsCaptured: number;  // 已捕获信号数量
  winRate: number;          // 模拟胜率（%）
  totalTrades: number;      // 总交易次数
  averageProfit: number;    // 平均收益（%）
}
```

#### 3.3.3 UserUpdate
```typescript
interface UserUpdate {
  userName?: string;        // 用户名（可选）
  avatar?: string;          // 头像URL（可选）
  email?: string;           // 邮箱（可选）
}
```

#### 3.3.4 LoginRequest
```typescript
interface LoginRequest {
  email: string;            // 邮箱
  password: string;         // 密码
}
```

#### 3.3.5 RegisterRequest
```typescript
interface RegisterRequest {
  email: string;            // 邮箱
  password: string;         // 密码
  userName: string;         // 用户名
}
```

#### 3.3.6 AuthResponse
```typescript
interface AuthResponse {
  token: string;            // 认证令牌
  expireAt: string;         // 令牌过期时间
  user: {
    userName: string;       // 用户名
    memberLevel: string;    // 会员等级
  };
}
```

### 3.4 应用相关实体

#### 3.4.1 AppInfo
```typescript
interface AppInfo {
  version: string;          // 应用版本
  currentDate: string;      // 当前日期（YYYY-MM-DD）
  latestVersion: string;    // 最新版本
  updateAvailable: boolean; // 是否有更新
}
```

## 4. 响应包装类

### 4.1 ApiResponse
```typescript
interface ApiResponse<T> {
  code: number;             // 状态码，200表示成功
  data: T;                  // 响应数据
  message: string;          // 响应消息
}
```

## 5. 环境变量配置

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