claw_bot 99094eeed8 feat(P4): 首页添加骨架屏，加载时显示占位动画

- 资产卡片区域：深色骨架屏匹配原有卡片风格
- 持仓列表区域：模拟卡片布局的骨架占位
- 添加 loading 状态控制，数据加载完成后切换
- 骨架屏带渐变动画效果，提升用户体验

2026-03-13 03:02:33 +00:00

23 KiB

Executable File

Raw Blame History

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：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{
  "alias": "纳指长期定投优化版", // string，必填，策略别名
  "config": { // object，必填，策略配置参数
    "period": "每月", // string，再平衡周期
    "threshold": 3, // decimal，偏离阈值(%)
    "assets": [ // object[]，资产配置
      {
        "code": "UPRO", // string，资产代码
        "targetWeight": 60 // decimal，目标权重(%)
      },
      {
        "code": "TMF", // string，资产代码
        "targetWeight": 40 // decimal，目标权重(%)
      }
    ]
  }
}

Response：

{
  "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：

{
  "code": 200,
  "message": "success",
  "data": {
    "deleted": true // bool，删除成功状态
  }
}

8. 获取用户信息

功能描述：获取用户基本信息，包含用户名、会员等级、连续运行天数等。
Method & URL：GET /api/v1/user/info
Request Parameters：无
Request Body：无

Response：

{
  "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：

{
  "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：

{
  "userName": "新用户名", // string，用户名
  "email": "newemail@example.com", // string，邮箱
  "avatar": "https://new-avatar-url.com/avatar.jpg" // string，头像URL
}

Response：

{
  "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：

{
  "code": "wx-code-123456", // string，必填，微信登录code
  "encryptedData": "encrypted-data", // string，可选，加密数据
  "iv": "initialization-vector" // string，可选，初始化向量
}

Response：

{
  "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：

{
  "code": "wx-code-789012", // string，必填，微信登录code
  "encryptedData": "encrypted-data", // string，可选，加密数据
  "iv": "initialization-vector" // string，可选，初始化向量
}

Response：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{
  "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，创建时间
  }
}

统一响应格式

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

{
  "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	数组	["季调", "止损机制"]

安全要求

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

性能要求

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

部署要求

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

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

23 KiB Executable File Raw Blame History Unescape Escape

API 接口设计文档

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

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

1. 获取总资产数据

2. 获取持仓组合数据

3. 获取策略列表

4. 获取策略详情

5. 创建策略

6. 更新策略

7. 删除策略

8. 获取用户信息

9. 获取用户统计数据

10. 更新用户信息

11. 微信登录

12. 微信绑定

13. 获取应用信息

14. 创建投资组合

15. 获取投资组合详情

16. 获取交易记录

17. 执行交易

统一响应格式

响应码说明

数据类型说明

安全要求

性能要求

部署要求

23 KiB

Executable File

Raw Blame History