AssetManager.UniApp/API 接口设计文档.md

# API 接口设计文档

## 模块一：页面 API 需求汇总 (API Summary)

| 接口名称 | 请求方式 | 接口路径 (Route) | 业务功能描述 |
| :--- | :--- | :--- | :--- |
| 获取总资产数据 | GET | `/api/v1/assets` | 获取用户总资产估值、今日盈亏、累计收益率 |
| 获取持仓组合数据 | GET | `/api/v1/holdings` | 获取用户当前所有持仓组合列表 |
| 获取策略列表 | GET | `/api/v1/strategies` | 获取策略模板列表 |
| 获取策略详情 | GET | `/api/v1/strategies/{id}` | 获取单个策略的详细信息 |
| 创建策略 | POST | `/api/v1/strategies` | 创建新的策略配置 |
| 更新策略 | PUT | `/api/v1/strategies/{id}` | 更新策略配置 |
| 删除策略 | DELETE | `/api/v1/strategies/{id}` | 删除策略 |
| 获取用户信息 | GET | `/api/v1/user/info` | 获取用户基本信息 |
| 获取用户统计数据 | GET | `/api/v1/user/stats` | 获取用户交易统计数据 |
| 更新用户信息 | PUT | `/api/v1/user/info` | 更新用户基本信息 |
| 微信登录 | POST | `/api/v1/auth/wechat/login` | 通过微信code进行登录 |
| 微信绑定 | POST | `/api/v1/auth/wechat/bind` | 绑定微信账号 |
| 获取应用信息 | GET | `/api/v1/app/info` | 获取应用版本和当前日期 |
| 创建投资组合 | POST | `/api/v1/portfolios` | 创建新的投资组合 |
| 获取投资组合详情 | GET | `/api/v1/portfolios/{id}` | 获取单个投资组合的详细信息 |
| 获取交易记录 | GET | `/api/v1/transactions` | 获取交易历史记录 |
| 执行交易 | POST | `/api/v1/transactions` | 执行买入或卖出操作 |

## 模块二：API 接口详细定义 (API Specifications)

### 1. 获取总资产数据

* **功能描述**：获取用户总资产估值、今日盈亏和累计收益率等核心资产数据。
* **Method & URL**：`GET /api/v1/assets`
* **Request Parameters**：无
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "totalValue": 1284592.40, // decimal，总资产估值
      "currency": "CNY", // string，币种 (CNY/USD/HKD)
      "todayProfit": 12482.00, // decimal，今日盈亏
      "todayProfitCurrency": "CNY", // string，今日盈亏币种
      "totalReturnRate": 24.82 // decimal，累计收益率(%)
    }
  }
  ```

### 2. 获取持仓组合数据

* **功能描述**：获取用户当前所有持仓组合的列表，包含每个组合的基本信息和状态。
* **Method & URL**：`GET /api/v1/holdings`
* **Request Parameters**：无
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": [
      {
        "id": "hfea-001", // string，组合ID
        "name": "美股全天候杠杆", // string，组合名称
        "tags": "HFEA · 季度调仓", // string，组合标签
        "status": "监控中", // string，状态描述
        "statusType": "green", // string，状态类型
        "iconChar": "H", // string，图标字符
        "iconBgClass": "bg-green-100", // string，图标背景类
        "iconTextClass": "text-green-700", // string，图标文本类
        "value": 156240.00, // decimal，当前市值
        "currency": "USD", // string，币种 (CNY/USD/HKD)
        "returnRate": 42.82, // decimal，累计收益率(%)
        "returnType": "positive" // string，收益类型
      },
      {
        "id": "ma-002", // string，组合ID
        "name": "纳指双均线趋势", // string，组合名称
        "tags": "趋势跟踪 · 日线", // string，组合标签
        "status": "等待信号", // string，状态描述
        "statusType": "gray", // string，状态类型
        "iconChar": "T", // string，图标字符
        "iconBgClass": "bg-blue-100", // string，图标背景类
        "iconTextClass": "text-blue-700", // string，图标文本类
        "value": 412500.00, // decimal，当前市值
        "currency": "USD", // string，币种 (CNY/USD/HKD)
        "returnRate": -1.79, // decimal，累计收益率(%)
        "returnType": "negative" // string，收益类型
      },
      {
        "id": "hk-003", // string，组合ID
        "name": "港股价值投资", // string，组合名称
        "tags": "价值投资 · 蓝筹", // string，组合标签
        "status": "持有中", // string，状态描述
        "statusType": "green", // string，状态类型
        "iconChar": "H", // string，图标字符
        "iconBgClass": "bg-green-100", // string，图标背景类
        "iconTextClass": "text-green-700", // string，图标文本类
        "value": 896000.00, // decimal，当前市值
        "currency": "HKD", // string，币种 (CNY/USD/HKD)
        "returnRate": 12.56, // decimal，累计收益率(%)
        "returnType": "positive" // string，收益类型
      }
    ]
  }
  ```

### 3. 获取策略列表

* **功能描述**：获取策略模板列表，用于创建投资组合时选择策略。
* **Method & URL**：`GET /api/v1/strategies`
* **Request Parameters**：无
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": [
      {
        "id": "hfea", // string，策略ID
        "iconChar": "H", // string，图标字符
        "title": "HFEA 风险平价策略", // string，策略标题
        "tag": "高风险 · 高预期收益", // string，策略标签
        "desc": "针对杠杆ETF平衡的对冲策略，核心逻辑为 TMF (3x长债) 与 UPRO (3x标普) 的季度平衡。", // string，策略描述
        "bgClass": "bg-emerald-900", // string，背景类
        "tagClass": "text-emerald-700", // string，标签类
        "tags": ["季调", "止损机制"], // string[]，策略特性标签
        "btnText": "配置参数", // string，按钮文本
        "btnClass": "btn-primary" // string，按钮类
      }
    ]
  }
  ```

### 4. 获取策略详情

* **功能描述**：获取单个策略的详细信息，包含策略原理和配置参数。
* **Method & URL**：`GET /api/v1/strategies/{id}`
* **Request Parameters**：
  * `id`：string，路径参数，必填，策略ID
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "id": "hfea", // string，策略ID
      "name": "HFEA 风险平价策略", // string，策略名称
      "description": "针对杠杆ETF平衡的对冲策略，核心逻辑为 TMF (3x长债) 与 UPRO (3x标普) 的季度平衡。", // string，策略描述
      "riskLevel": "high", // string，风险等级
      "parameters": [ // object[]，策略参数列表
        {
          "name": "rebalancePeriod", // string，参数名称
          "displayName": "再平衡周期", // string，显示名称
          "type": "select", // string，参数类型
          "options": ["每日", "每周", "每月", "每季度", "每年"], // string[]，可选值
          "defaultValue": "每季度" // string，默认值
        }
      ]
    }
  }
  ```

### 5. 创建策略

* **功能描述**：创建新的策略配置。
* **Method & URL**：`POST /api/v1/strategies`
* **Request Parameters**：无
* **Request Body**：
  ```json
  {
    "alias": "纳指长期定投", // string，必填，策略别名
    "type": "weight", // string，必填，策略类型
    "config": { // object，必填，策略配置参数
      "period": "每季度", // string，再平衡周期
      "threshold": 5, // decimal，偏离阈值(%)
      "assets": [ // object[]，资产配置
        {
          "code": "UPRO", // string，资产代码
          "targetWeight": 55 // decimal，目标权重(%)
        },
        {
          "code": "TMF", // string，资产代码
          "targetWeight": 45 // decimal，目标权重(%)
        }
      ]
    }
  }
  ```
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "id": "strategy-001", // string，策略ID
      "alias": "纳指长期定投", // string，策略别名
      "type": "weight", // string，策略类型
      "config": { // object，策略配置
        "period": "每季度",
        "threshold": 5,
        "assets": [
          {
            "code": "UPRO",
            "targetWeight": 55
          },
          {
            "code": "TMF",
            "targetWeight": 45
          }
        ]
      },
      "createdAt": "2024-01-01T00:00:00Z" // DateTime，创建时间
    }
  }
  ```

### 6. 更新策略

* **功能描述**：更新现有策略的配置。
* **Method & URL**：`PUT /api/v1/strategies/{id}`
* **Request Parameters**：
  * `id`：string，路径参数，必填，策略ID
* **Request Body**：
  ```json
  {
    "alias": "纳指长期定投优化版", // string，必填，策略别名
    "config": { // object，必填，策略配置参数
      "period": "每月", // string，再平衡周期
      "threshold": 3, // decimal，偏离阈值(%)
      "assets": [ // object[]，资产配置
        {
          "code": "UPRO", // string，资产代码
          "targetWeight": 60 // decimal，目标权重(%)
        },
        {
          "code": "TMF", // string，资产代码
          "targetWeight": 40 // decimal，目标权重(%)
        }
      ]
    }
  }
  ```
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "id": "strategy-001", // string，策略ID
      "alias": "纳指长期定投优化版", // string，策略别名
      "type": "weight", // string，策略类型
      "config": { // object，策略配置
        "period": "每月",
        "threshold": 3,
        "assets": [
          {
            "code": "UPRO",
            "targetWeight": 60
          },
          {
            "code": "TMF",
            "targetWeight": 40
          }
        ]
      },
      "updatedAt": "2024-01-02T00:00:00Z" // DateTime，更新时间
    }
  }
  ```

### 7. 删除策略

* **功能描述**：删除指定的策略。
* **Method & URL**：`DELETE /api/v1/strategies/{id}`
* **Request Parameters**：
  * `id`：string，路径参数，必填，策略ID
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "deleted": true // bool，删除成功状态
    }
  }
  ```

### 8. 获取用户信息

* **功能描述**：获取用户基本信息，包含用户名、会员等级、连续运行天数等。
* **Method & URL**：`GET /api/v1/user/info`
* **Request Parameters**：无
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "userName": "首席策略员 0x42", // string，用户名
      "memberLevel": "全球实验室 Pro", // string，会员等级
      "runningDays": 412, // int，连续运行天数
      "avatar": "https://via.placeholder.com/100", // string，头像URL
      "email": "user@example.com" // string，邮箱
    }
  }
  ```

### 9. 获取用户统计数据

* **功能描述**：获取用户交易统计数据，包含已捕获信号数、模拟胜率等。
* **Method & URL**：`GET /api/v1/user/stats`
* **Request Parameters**：无
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "signalsCaptured": 1248, // int，已捕获信号数
      "winRate": 58.4, // decimal，模拟胜率(%)
      "totalTrades": 2136, // int，总交易次数
      "totalReturn": 124820.50 // decimal，总收益金额
    }
  }
  ```

### 10. 更新用户信息

* **功能描述**：更新用户基本信息。
* **Method & URL**：`PUT /api/v1/user/info`
* **Request Parameters**：无
* **Request Body**：
  ```json
  {
    "userName": "新用户名", // string，用户名
    "email": "newemail@example.com", // string，邮箱
    "avatar": "https://new-avatar-url.com/avatar.jpg" // string，头像URL
  }
  ```
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "userName": "新用户名", // string，用户名
      "memberLevel": "全球实验室 Pro", // string，会员等级
      "runningDays": 412, // int，连续运行天数
      "avatar": "https://new-avatar-url.com/avatar.jpg", // string，头像URL
      "email": "newemail@example.com", // string，邮箱
      "updatedAt": "2024-01-01T00:00:00Z" // DateTime，更新时间
    }
  }
  ```

### 11. 微信登录

* **功能描述**：通过微信code进行登录认证。
* **Method & URL**：`POST /api/v1/auth/wechat/login`
* **Request Parameters**：无
* **Request Body**：
  ```json
  {
    "code": "wx-code-123456", // string，必填，微信登录code
    "encryptedData": "encrypted-data", // string，可选，加密数据
    "iv": "initialization-vector" // string，可选，初始化向量
  }
  ```
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "token": "mock-wechat-token-123456", // string，认证令牌
      "userInfo": { // object，用户信息
        "id": "user-001", // string，用户ID
        "openid": "mock-openid-123456", // string，微信openid
        "nickname": "微信用户", // string，昵称
        "avatar": "https://via.placeholder.com/100", // string，头像URL
        "memberLevel": "全球实验室 Pro", // string，会员等级
        "runningDays": 412 // int，连续运行天数
      }
    }
  }
  ```

### 12. 微信绑定

* **功能描述**：绑定微信账号到现有用户。
* **Method & URL**：`POST /api/v1/auth/wechat/bind`
* **Request Parameters**：无
* **Request Body**：
  ```json
  {
    "code": "wx-code-789012", // string，必填，微信登录code
    "encryptedData": "encrypted-data", // string，可选，加密数据
    "iv": "initialization-vector" // string，可选，初始化向量
  }
  ```
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "token": "mock-wechat-token-789012", // string，认证令牌
      "userInfo": { // object，用户信息
        "id": "user-001", // string，用户ID
        "openid": "mock-openid-123456", // string，微信openid
        "email": "user@example.com", // string，邮箱
        "nickname": "微信用户", // string，昵称
        "avatar": "https://via.placeholder.com/100", // string，头像URL
        "memberLevel": "全球实验室 Pro", // string，会员等级
        "runningDays": 412 // int，连续运行天数
      }
    }
  }
  ```

### 13. 获取应用信息

* **功能描述**：获取应用版本信息和当前日期。
* **Method & URL**：`GET /api/v1/app/info`
* **Request Parameters**：无
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "version": "v2.4.0", // string，应用版本
      "currentDate": "2024-01-01" // string，当前日期
    }
  }
  ```

### 14. 创建投资组合

* **功能描述**：创建新的投资组合，包含基础设置和初始持仓。
* **Method & URL**：`POST /api/v1/portfolios`
* **Request Parameters**：无
* **Request Body**：
  ```json
  {
    "name": "养老定投", // string，必填，组合名称
    "strategyId": "hfea", // string，必填，策略ID
    "currency": "USD", // string，必填，组合币种 (CNY/USD/HKD)
    "stocks": [ // object[]，必填，初始持仓
      {
        "name": "UPRO", // string，必填，标的名称
        "code": "UPRO.US", // string，必填，标的代码
        "price": 605.15, // decimal，必填，买入均价
        "amount": 142, // int，必填，持有数量
        "date": "2024-01-01", // string，必填，建仓日期
        "currency": "USD" // string，必填，标的币种
      },
      {
        "name": "TMF", // string，必填，标的名称
        "code": "TMF.US", // string，必填，标的代码
        "price": 87.89, // decimal，必填，买入均价
        "amount": 800, // int，必填，持有数量
        "date": "2024-01-01", // string，必填，建仓日期
        "currency": "USD" // string，必填，标的币种
      }
    ]
  }
  ```
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "id": "portfolio-001", // string，组合ID
      "name": "养老定投", // string，组合名称
      "strategyId": "hfea", // string，策略ID
      "currency": "USD", // string，组合币种 (CNY/USD/HKD)
      "totalValue": 156240.00, // decimal，总市值
      "returnRate": 0, // decimal，收益率
      "status": "运行中", // string，状态
      "createdAt": "2024-01-01T00:00:00Z" // DateTime，创建时间
    }
  }
  ```

### 15. 获取投资组合详情

* **功能描述**：获取单个投资组合的详细信息，包含资产状况、持仓明细和交易记录。
* **Method & URL**：`GET /api/v1/portfolios/{id}`
* **Request Parameters**：
  * `id`：string，路径参数，必填，组合ID
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "id": "portfolio-001", // string，组合ID
      "name": "美股全天候杠杆", // string，组合名称
      "currency": "USD", // string，组合币种 (CNY/USD/HKD)
      "strategy": { // object，策略信息
        "id": "hfea", // string，策略ID
        "name": "HFEA 风险平价", // string，策略名称
        "status": "监控中" // string，策略状态
      },
      "portfolioValue": 156240.00, // decimal，组合净值
      "totalReturn": 42.82, // decimal，历史收益率(%)
      "todayProfit": 1240.50, // decimal，今日盈亏
      "todayProfitCurrency": "USD", // string，今日盈亏币种
      "positions": [ // object[]，持仓明细
        {
          "name": "UPRO", // string，标的名称
          "code": "UPRO.US", // string，标的代码
          "shares": 142, // int，持有数量
          "marketValue": "85,932.00", // string，市值
          "currency": "USD", // string，标的币种
          "weight": 55, // decimal，仓位占比(%)
          "pnl": 12400.00, // decimal，持仓盈亏
          "pnlPercent": 16.8 // decimal，盈亏比例(%)
        },
        {
          "name": "TMF", // string，标的名称
          "code": "TMF.US", // string，标的代码
          "shares": 800, // int，持有数量
          "marketValue": "70,308.00", // string，市值
          "currency": "USD", // string，标的币种
          "weight": 45, // decimal，仓位占比(%)
          "pnl": -3200.50, // decimal，持仓盈亏
          "pnlPercent": -4.3 // decimal，盈亏比例(%)
        }
      ],
      "transactions": [ // object[]，交易记录
        {
          "date": "02-14", // string，交易日期
          "time": "14:30", // string，交易时间
          "type": "buy", // string，交易类型
          "title": "定期定投 UPRO", // string，交易标题
          "amount": "$500.00", // string，交易金额
          "currency": "USD" // string，交易币种
        }
      ]
    }
  }
  ```

### 16. 获取交易记录

* **功能描述**：获取用户的交易历史记录。
* **Method & URL**：`GET /api/v1/transactions`
* **Request Parameters**：
  * `portfolioId`：string，查询参数，可选，组合ID
  * `limit`：int，查询参数，可选，返回数量限制
  * `offset`：int，查询参数，可选，偏移量
* **Request Body**：无
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": [
      {
        "id": "tx-001", // string，交易ID
        "portfolioId": "portfolio-001", // string，组合ID
        "date": "2024-02-14", // string，交易日期
        "time": "14:30:00", // string，交易时间
        "type": "buy", // string，交易类型
        "title": "定期定投 UPRO", // string，交易标题
        "amount": 500.00, // decimal，交易金额
        "currency": "USD", // string，货币类型
        "status": "completed" // string，交易状态
      }
    ]
  }
  ```

### 17. 执行交易

* **功能描述**：执行买入或卖出操作。
* **Method & URL**：`POST /api/v1/transactions`
* **Request Parameters**：无
* **Request Body**：
  ```json
  {
    "portfolioId": "portfolio-001", // string，必填，组合ID
    "type": "buy", // string，必填，交易类型(buy/sell)
    "stockCode": "UPRO.US", // string，必填，标的代码
    "amount": 10, // int，必填，交易数量
    "price": 605.15, // decimal，必填，交易价格
    "currency": "USD", // string，必填，交易币种 (CNY/USD/HKD)
    "remark": "定期定投" // string，可选，交易备注
  }
  ```
* **Response**：
  ```json
  {
    "code": 200,
    "message": "success",
    "data": {
      "id": "tx-002", // string，交易ID
      "portfolioId": "portfolio-001", // string，组合ID
      "type": "buy", // string，交易类型
      "stockCode": "UPRO.US", // string，标的代码
      "amount": 10, // int，交易数量
      "price": 605.15, // decimal，交易价格
      "currency": "USD", // string，交易币种 (CNY/USD/HKD)
      "totalAmount": 6051.50, // decimal，交易总金额
      "status": "processing", // string，交易状态
      "createdAt": "2024-01-01T00:00:00Z" // DateTime，创建时间
    }
  }
  ```

## 统一响应格式

所有接口均返回统一格式的响应体：

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

### 响应码说明

| 响应码 | 说明 |
| :--- | :--- |
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要重新登录 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
| 502 | 网关错误 |
| 503 | 服务不可用 |

### 数据类型说明

| 类型 | 说明 | 示例 |
| :--- | :--- | :--- |
| int | 整数 | 412 |
| string | 字符串 | "养老定投" |
| decimal | 小数 | 42.82 |
| bool | 布尔值 | true |
| DateTime | 日期时间 | "2024-01-01T00:00:00Z" |
| object | 对象 | {"name": "UPRO", "code": "UPRO.US"} |
| array | 数组 | ["季调", "止损机制"] |

## 安全要求

1. **认证授权**：所有接口（除登录外）均需在请求头中携带 `Authorization: Bearer {token}`
2. **数据验证**：所有输入参数均需进行严格的数据类型和业务规则验证
3. **错误处理**：统一的错误处理机制，避免敏感信息泄露
4. **日志记录**：关键操作需记录详细日志，但避免记录敏感信息
5. **CORS配置**：正确配置跨域资源共享，仅允许指定域名访问

## 性能要求

1. **响应时间**：常规接口响应时间不超过 500ms
2. **缓存策略**：合理使用缓存，减少重复计算
3. **并发处理**：支持高并发请求，合理使用数据库连接池
4. **数据分页**：列表接口必须支持分页，默认每页 20 条数据

## 部署要求

1. **环境配置**：支持多环境部署（开发、测试、生产）
2. **监控告警**：集成监控系统，及时发现和处理异常
3. **版本管理**：API 版本号通过 URL 路径管理（如 /api/v1/）
4. **文档更新**：API 文档需与代码同步更新，保持一致性

---

**注**：本文档严格遵循 RESTful API 设计规范，所有字段均明确标注了数据类型和是否必填，可直接用于自动生成 C# 强类型实体类和 Controller。