From 455d47f8873d2a0025d1d268bc38f705a376e527 Mon Sep 17 00:00:00 2001
From: niannian zheng <niannian.zheng@zurich.com.cn>
Date: Sat, 28 Feb 2026 16:02:59 +0800
Subject: [PATCH] =?UTF-8?q?refactor(API):=20=E7=BB=9F=E4=B8=80=E8=B7=AF?=
 =?UTF-8?q?=E7=94=B1=E6=A0=BC=E5=BC=8F=E5=B9=B6=E6=B7=BB=E5=8A=A0=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 将控制器路由从`[controller]`格式改为明确路径
- 为所有接口添加XML文档注释，说明功能和使用方法
- 保持路由风格一致，部分接口添加版本前缀
---
 .../Controllers/AuthController.cs             | 11 +++-
 .../Controllers/PortfolioController.cs        | 50 ++++++++++++++++++-
 .../Controllers/StrategyController.cs         | 44 +++++++++++++++-
 .../Controllers/UserController.cs             | 24 ++++++++-
 4 files changed, 124 insertions(+), 5 deletions(-)

diff --git a/AssetManager.API/Controllers/AuthController.cs b/AssetManager.API/Controllers/AuthController.cs
index 6eb3acf..d82c8ec 100644
--- a/AssetManager.API/Controllers/AuthController.cs
+++ b/AssetManager.API/Controllers/AuthController.cs
@@ -10,7 +10,7 @@ using System.Linq;
 namespace AssetManager.API.Controllers;
 
 [ApiController]
-[Route("api/[controller]")]
+[Route("api/auth")]
 public class AuthController : ControllerBase
 {
     private readonly ILogger<AuthController> _logger;
@@ -27,6 +27,15 @@ public class AuthController : ControllerBase
     }
 
 
+    /// <summary>
+    /// 微信登录接口
+    /// </summary>
+    /// <param name="request">登录请求参数，包含微信授权码和用户信息</param>
+    /// <returns>登录结果，包含JWT令牌、用户信息和过期时间</returns>
+    /// <remarks>
+    /// 此接口用于微信小程序或公众号的用户登录，通过微信授权码换取OpenID，
+    /// 然后查找或创建用户，并生成JWT令牌返回给客户端。
+    /// </remarks>
     [HttpPost("wechat-login")]
     public async Task<ActionResult<ApiResponse<WechatLoginResponse>>> WechatLogin([FromBody] WechatLoginRequest request)
     {
diff --git a/AssetManager.API/Controllers/PortfolioController.cs b/AssetManager.API/Controllers/PortfolioController.cs
index 572e439..24810cc 100644
--- a/AssetManager.API/Controllers/PortfolioController.cs
+++ b/AssetManager.API/Controllers/PortfolioController.cs
@@ -8,7 +8,7 @@ using Microsoft.Extensions.Logging;
 namespace AssetManager.API.Controllers;
 
 [ApiController]
-[Route("api/v1/[controller]")]
+[Route("api/v1/portfolio")]
 [Authorize]
 public class PortfolioController : ControllerBase
 {
@@ -21,6 +21,14 @@ public class PortfolioController : ControllerBase
         _portfolioService = portfolioService;
     }
 
+    /// <summary>
+    /// 创建新投资组合
+    /// </summary>
+    /// <param name="request">投资组合创建请求参数</param>
+    /// <returns>创建的投资组合详情</returns>
+    /// <remarks>
+    /// 此接口用于创建新的投资组合。
+    /// </remarks>
     [HttpPost]
     public ActionResult<ApiResponse<CreatePortfolioResponse>> CreatePortfolio([FromBody] CreatePortfolioRequest request)
     {
@@ -52,6 +60,13 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取投资组合列表
+    /// </summary>
+    /// <returns>投资组合列表</returns>
+    /// <remarks>
+    /// 此接口用于获取投资组合列表。
+    /// </remarks>
     [HttpGet]
     public ActionResult<ApiResponse<GetPortfoliosResponse>> GetPortfolios()
     {
@@ -83,6 +98,13 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取总资产情况
+    /// </summary>
+    /// <returns>总资产情况</returns>
+    /// <remarks>
+    /// 此接口用于获取用户的总资产情况。
+    /// </remarks>
     [HttpGet("assets")]
     public ActionResult<ApiResponse<TotalAssetsResponse>> GetTotalAssets()
     {
@@ -114,6 +136,14 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取单个投资组合详情
+    /// </summary>
+    /// <param name="id">投资组合ID</param>
+    /// <returns>投资组合详情</returns>
+    /// <remarks>
+    /// 此接口用于获取指定投资组合的详细信息。
+    /// </remarks>
     [HttpGet("{id}")]
     public ActionResult<ApiResponse<PortfolioDetailResponse>> GetPortfolioById(string id)
     {
@@ -145,6 +175,16 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取交易记录
+    /// </summary>
+    /// <param name="portfolioId">投资组合ID</param>
+    /// <param name="limit">每页记录数</param>
+    /// <param name="offset">偏移量</param>
+    /// <returns>交易记录列表</returns>
+    /// <remarks>
+    /// 此接口用于获取指定投资组合的交易记录。
+    /// </remarks>
     [HttpGet("transactions")]
     public ActionResult<ApiResponse<GetTransactionsResponse>> GetTransactions([FromQuery] string portfolioId, [FromQuery] int limit = 10, [FromQuery] int offset = 0)
     {
@@ -176,6 +216,14 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 创建新交易
+    /// </summary>
+    /// <param name="request">交易创建请求参数</param>
+    /// <returns>创建的交易详情</returns>
+    /// <remarks>
+    /// 此接口用于创建新的交易。
+    /// </remarks>
     [HttpPost("transactions")]
     public ActionResult<ApiResponse<CreateTransactionResponse>> CreateTransaction([FromBody] CreateTransactionRequest request)
     {
diff --git a/AssetManager.API/Controllers/StrategyController.cs b/AssetManager.API/Controllers/StrategyController.cs
index c3d14f9..89a49a5 100644
--- a/AssetManager.API/Controllers/StrategyController.cs
+++ b/AssetManager.API/Controllers/StrategyController.cs
@@ -10,7 +10,7 @@ using System.Security.Claims;
 namespace AssetManager.API.Controllers;
 
 [ApiController]
-[Route("api/v1/[controller]s")]
+[Route("api/v1/strategy")]
 [Authorize]
 public class StrategyController : ControllerBase
 {
@@ -28,7 +28,14 @@ public class StrategyController : ControllerBase
         return User.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? throw new Exception("User not authenticated");
     }
 
-    [HttpGet]
+    /// <summary>
+    /// 获取策略列表
+    /// </summary>
+    /// <returns>策略列表</returns>
+    /// <remarks>
+    /// 此接口用于获取当前登录用户的所有策略列表。
+    /// </remarks>
+    [HttpGet("strategies")]
     public ActionResult<ApiResponse<List<Strategy>>> GetStrategies()
     {
         try
@@ -60,6 +67,14 @@ public class StrategyController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取单个策略详情
+    /// </summary>
+    /// <param name="id">策略ID</param>
+    /// <returns>策略详情</returns>
+    /// <remarks>
+    /// 此接口用于获取指定策略的详细信息。
+    /// </remarks>
     [HttpGet("{id}")]
     public ActionResult<ApiResponse<Strategy>> GetStrategyById(string id)
     {
@@ -92,6 +107,14 @@ public class StrategyController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 创建新策略
+    /// </summary>
+    /// <param name="request">策略创建请求参数</param>
+    /// <returns>创建的策略详情</returns>
+    /// <remarks>
+    /// 此接口用于创建新的策略。
+    /// </remarks>
     [HttpPost]
     public ActionResult<ApiResponse<Strategy>> CreateStrategy([FromBody] CreateStrategyRequest request)
     {
@@ -124,6 +147,15 @@ public class StrategyController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 更新策略
+    /// </summary>
+    /// <param name="id">策略ID</param>
+    /// <param name="request">策略更新请求参数</param>
+    /// <returns>更新后的策略详情</returns>
+    /// <remarks>
+    /// 此接口用于更新指定策略的信息。
+    /// </remarks>
     [HttpPut("{id}")]
     public ActionResult<ApiResponse<Strategy>> UpdateStrategy(string id, [FromBody] UpdateStrategyRequest request)
     {
@@ -156,6 +188,14 @@ public class StrategyController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 删除策略
+    /// </summary>
+    /// <param name="id">策略ID</param>
+    /// <returns>删除结果</returns>
+    /// <remarks>
+    /// 此接口用于删除指定的策略。
+    /// </remarks>
     [HttpDelete("{id}")]
     public ActionResult<ApiResponse<object>> DeleteStrategy(string id)
     {
diff --git a/AssetManager.API/Controllers/UserController.cs b/AssetManager.API/Controllers/UserController.cs
index f06af36..4c2f0f7 100644
--- a/AssetManager.API/Controllers/UserController.cs
+++ b/AssetManager.API/Controllers/UserController.cs
@@ -8,7 +8,7 @@ using AssetManager.Data;
 namespace AssetManager.API.Controllers;
 
 [ApiController]
-[Route("api/user")]
+[Route("api/v1/user")]
 [Authorize]
 public class UserController : ControllerBase
 {
@@ -21,6 +21,13 @@ public class UserController : ControllerBase
         _databaseService = databaseService;
     }
 
+    /// <summary>
+    /// 获取用户信息
+    /// </summary>
+    /// <returns>用户信息</returns>
+    /// <remarks>
+    /// 此接口用于获取当前登录用户的详细信息。
+    /// </remarks>
     [HttpGet("info")]
     public ActionResult<ApiResponse<UserInfoResponse>> GetUserInfo()
     {
@@ -86,6 +93,13 @@ public class UserController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取用户统计数据
+    /// </summary>
+    /// <returns>用户统计数据</returns>
+    /// <remarks>
+    /// 此接口用于获取当前登录用户的统计数据，如捕获的信号数、胜率等。
+    /// </remarks>
     [HttpGet("stats")]
     public ActionResult<ApiResponse<UserStatsResponse>> GetUserStats()
     {
@@ -150,6 +164,14 @@ public class UserController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 更新用户信息
+    /// </summary>
+    /// <param name="request">用户信息更新请求参数</param>
+    /// <returns>更新结果</returns>
+    /// <remarks>
+    /// 此接口用于更新当前登录用户的信息。
+    /// </remarks>
     [HttpPut("info")]
     public ActionResult<ApiResponse<UpdateUserResponse>> UpdateUserInfo([FromBody] UpdateUserRequest request)
     {