From fac4eb5e0f6be1af1a2a1bd06b87f2bc1434c23c Mon Sep 17 00:00:00 2001
From: fanfpy <fanfpy@example.com>
Date: Thu, 5 Mar 2026 10:17:44 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=99PortfolioController=E7=9A=84AP?=
 =?UTF-8?q?I=E6=B7=BB=E5=8A=A0=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../Controllers/PortfolioController.cs        | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/AssetManager.API/Controllers/PortfolioController.cs b/AssetManager.API/Controllers/PortfolioController.cs
index d664ddf..b6031ae 100644
--- a/AssetManager.API/Controllers/PortfolioController.cs
+++ b/AssetManager.API/Controllers/PortfolioController.cs
@@ -36,11 +36,19 @@ public class PortfolioController : ControllerBase
     }
 
 
+    /// <summary>
+    /// 获取当前登录用户ID
+    /// </summary>
     private string GetCurrentUserId()
     {
         return User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
     }
 
+    /// <summary>
+    /// 创建投资组合（账本）
+    /// </summary>
+    /// <param name="request">创建请求参数（包含名称、策略、初始持仓等）</param>
+    /// <returns>创建的投资组合信息</returns>
     [HttpPost]
     public ActionResult<ApiResponse<CreatePortfolioResponse>> CreatePortfolio([FromBody] CreatePortfolioRequest request)
     {
@@ -83,6 +91,10 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取当前用户的投资组合列表
+    /// </summary>
+    /// <returns>投资组合列表</returns>
     [HttpGet]
     public ActionResult<ApiResponse<GetPortfoliosResponse>> GetPortfolios()
     {
@@ -125,6 +137,10 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取当前用户的总资产概览
+    /// </summary>
+    /// <returns>总资产数据（总市值、今日盈亏、累计收益率等）</returns>
     [HttpGet("assets")]
     public ActionResult<ApiResponse<TotalAssetsResponse>> GetTotalAssets()
     {
@@ -167,6 +183,11 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取单个投资组合详情
+    /// </summary>
+    /// <param name="id">投资组合ID</param>
+    /// <returns>投资组合详情（含持仓明细）</returns>
     [HttpGet("{id}")]
     public ActionResult<ApiResponse<PortfolioDetailResponse>> GetPortfolioById(string id)
     {
@@ -209,6 +230,13 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 获取投资组合的交易记录（流水）
+    /// </summary>
+    /// <param name="portfolioId">投资组合ID</param>
+    /// <param name="limit">每页记录数（默认10）</param>
+    /// <param name="offset">偏移量（默认0）</param>
+    /// <returns>交易记录列表</returns>
     [HttpGet("transactions")]
     public ActionResult<ApiResponse<GetTransactionsResponse>> GetTransactions([FromQuery] string portfolioId, [FromQuery] int limit = 10, [FromQuery] int offset = 0)
     {
@@ -251,6 +279,11 @@ public class PortfolioController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// 记录一笔交易（买入/卖出）
+    /// </summary>
+    /// <param name="request">交易请求参数（类型、标的、数量、价格等）</param>
+    /// <returns>创建的交易记录</returns>
     [HttpPost("transactions")]
     public ActionResult<ApiResponse<CreateTransactionResponse>> CreateTransaction([FromBody] CreateTransactionRequest request)
     {