From 8000162f0262c1b7304bd15edfbea1107d831a65 Mon Sep 17 00:00:00 2001
From: zzh <1368735060@qq.com>
Date: Sat, 11 Jul 2026 15:46:32 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BB=93=E5=82=A8=E4=B8=8E=E5=BA=97?=
 =?UTF-8?q?=E9=93=BA=E6=8E=A5=E5=8F=A3=E8=A1=A5=E5=85=85=20Swagger=20?=
 =?UTF-8?q?=E4=B8=AD=E6=96=87=E5=91=BD=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

为 WarehouseService、PlatformStoreService、PlatformStoreOrderService 全部新增接口添加 XML 注释，便于 Swagger 中文展示与前端对接。

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../Orders/PlatformStoreOrderService.cs       | 50 +++++++++++++++++++
 .../Services/Orders/PlatformStoreService.cs   | 19 +++++++
 .../Warehouse/WarehouseService.BinLocation.cs | 10 ++++
 .../Warehouse/WarehouseService.Inbound.cs     | 30 +++++++++++
 .../Warehouse/WarehouseService.Inventory.cs   | 16 ++++++
 .../Warehouse/WarehouseService.Parcel.cs      | 18 +++++++
 .../Warehouse/WarehouseService.Sku.cs         | 25 ++++++++++
 7 files changed, 168 insertions(+)

diff --git a/src/Oms.Application/Services/Orders/PlatformStoreOrderService.cs b/src/Oms.Application/Services/Orders/PlatformStoreOrderService.cs
index 74d55ee..a527b38 100644
--- a/src/Oms.Application/Services/Orders/PlatformStoreOrderService.cs
+++ b/src/Oms.Application/Services/Orders/PlatformStoreOrderService.cs
@@ -35,6 +35,11 @@ public class PlatformStoreOrderService : ApplicationService
     private ISalesProductRepository SalesProductRepository => LazyServiceProvider.GetRequiredService<ISalesProductRepository>();
     private OrderService OrderService => LazyServiceProvider.GetRequiredService<OrderService>();
 
+    /// <summary>
+    /// 查询店铺订单列表。
+    /// </summary>
+    /// <param name="input">入参：店铺订单分页查询条件。</param>
+    /// <returns>店铺订单分页结果。</returns>
     [HttpPost("/order/platform-store-order/list")]
     public async Task<OmsPageResult<PlatformStoreOrderOutput>> GetListAsync(PlatformStoreOrderListInput input)
     {
@@ -81,6 +86,12 @@ public class PlatformStoreOrderService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 查询店铺订单详情。
+    /// </summary>
+    /// <param name="id">店铺订单 ID。</param>
+    /// <param name="customerId">客户 ID（可选）。</param>
+    /// <returns>店铺订单详情（含商品行）。</returns>
     [HttpGet("/order/platform-store-order/detail")]
     public async Task<PlatformStoreOrderOutput> GetDetailAsync([FromQuery] int id, [FromQuery] int? customerId = null)
     {
@@ -101,6 +112,12 @@ public class PlatformStoreOrderService : ApplicationService
         return MapOrderOutput(order, store?.StoreNickname ?? string.Empty, lines, skuMap, linkedServiceNo);
     }
 
+    /// <summary>
+    /// 查询店铺订单状态汇总。
+    /// </summary>
+    /// <param name="customerId">客户 ID（可选）。</param>
+    /// <param name="storeId">店铺 ID（可选）。</param>
+    /// <returns>各履约状态数量汇总。</returns>
     [HttpGet("/order/platform-store-order/summary")]
     public async Task<PlatformStoreOrderSummaryOutput> GetSummaryAsync([FromQuery] int? customerId = null, [FromQuery] int? storeId = null)
     {
@@ -123,6 +140,11 @@ public class PlatformStoreOrderService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 同步店铺订单状态（平台 SDK 占位）。
+    /// </summary>
+    /// <param name="input">入参：订单 ID 列表。</param>
+    /// <returns>同步结果提示。</returns>
     [HttpPost("/order/platform-store-order/sync-status")]
     public async Task<PlatformStoreOrderActionOutput> SyncStatusAsync(PlatformStoreOrderIdsInput input)
     {
@@ -137,6 +159,11 @@ public class PlatformStoreOrderService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 店铺订单 RTS 就绪发货（平台 SDK 占位）。
+    /// </summary>
+    /// <param name="input">入参：订单 ID 列表。</param>
+    /// <returns>操作结果提示。</returns>
     [HttpPost("/order/platform-store-order/ready-to-ship")]
     public async Task<PlatformStoreOrderActionOutput> ReadyToShipAsync(PlatformStoreOrderIdsInput input)
     {
@@ -151,6 +178,11 @@ public class PlatformStoreOrderService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 拉取店铺订单面单（平台 SDK 占位）。
+    /// </summary>
+    /// <param name="input">入参：订单 ID。</param>
+    /// <returns>操作结果提示。</returns>
     [HttpPost("/order/platform-store-order/fetch-label")]
     public async Task<PlatformStoreOrderActionOutput> FetchLabelAsync(PlatformStoreOrderIdInput input)
     {
@@ -165,6 +197,10 @@ public class PlatformStoreOrderService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 切换店铺订单搁置状态。
+    /// </summary>
+    /// <param name="input">入参：订单 ID 与是否搁置。</param>
     [HttpPost("/order/platform-store-order/toggle-suspend")]
     public async Task ToggleSuspendAsync(PlatformStoreOrderToggleSuspendInput input)
     {
@@ -180,6 +216,10 @@ public class PlatformStoreOrderService : ApplicationService
         await StoreOrderRepository.UpdateAsync(order);
     }
 
+    /// <summary>
+    /// 删除店铺订单。
+    /// </summary>
+    /// <param name="input">入参：订单 ID 列表。</param>
     [HttpPost("/order/platform-store-order/delete")]
     public async Task DeleteAsync(PlatformStoreOrderIdsInput input)
     {
@@ -205,6 +245,11 @@ public class PlatformStoreOrderService : ApplicationService
         }
     }
 
+    /// <summary>
+    /// 店铺订单匹配库存并创建小包单。
+    /// </summary>
+    /// <param name="input">入参：订单 ID、仓库、销售产品等。</param>
+    /// <returns>匹配结果与关联小包单号。</returns>
     [HttpPost("/order/platform-store-order/match-inventory")]
     public async Task<PlatformStoreOrderMatchInventoryOutput> MatchInventoryAsync(PlatformStoreOrderMatchInventoryInput input)
     {
@@ -230,6 +275,11 @@ public class PlatformStoreOrderService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 批量匹配店铺订单库存并创建小包单。
+    /// </summary>
+    /// <param name="input">入参：订单 ID 列表、仓库、销售产品等。</param>
+    /// <returns>批量匹配结果（成功/失败明细）。</returns>
     [HttpPost("/order/platform-store-order/batch-match-inventory")]
     public async Task<PlatformStoreOrderBatchMatchInventoryOutput> BatchMatchInventoryAsync(
         PlatformStoreOrderBatchMatchInventoryInput input)
diff --git a/src/Oms.Application/Services/Orders/PlatformStoreService.cs b/src/Oms.Application/Services/Orders/PlatformStoreService.cs
index a3a6e29..b842e38 100644
--- a/src/Oms.Application/Services/Orders/PlatformStoreService.cs
+++ b/src/Oms.Application/Services/Orders/PlatformStoreService.cs
@@ -20,6 +20,11 @@ public class PlatformStoreService : ApplicationService
     private ICustomerRepository CustomerRepository => LazyServiceProvider.GetRequiredService<ICustomerRepository>();
     private ISalesStoreRepository StoreRepository => LazyServiceProvider.GetRequiredService<ISalesStoreRepository>();
 
+    /// <summary>
+    /// 查询店铺授权列表。
+    /// </summary>
+    /// <param name="input">入参：店铺分页查询条件。</param>
+    /// <returns>店铺分页结果。</returns>
     [HttpPost("/order/platform-store/list")]
     public async Task<OmsPageResult<PlatformStoreOutput>> GetListAsync(PlatformStorePageInput input)
     {
@@ -44,6 +49,11 @@ public class PlatformStoreService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 获取店铺 OAuth 授权地址。
+    /// </summary>
+    /// <param name="input">入参：平台编码与回调地址。</param>
+    /// <returns>授权跳转 URL。</returns>
     [HttpPost("/order/platform-store/auth-url")]
     public async Task<PlatformStoreAuthUrlOutput> GetAuthUrlAsync(PlatformStoreAuthUrlInput input)
     {
@@ -64,6 +74,11 @@ public class PlatformStoreService : ApplicationService
         };
     }
 
+    /// <summary>
+    /// 保存店铺授权（新增或编辑）。
+    /// </summary>
+    /// <param name="input">入参：店铺保存数据。</param>
+    /// <returns>保存后的店铺信息。</returns>
     [HttpPost("/order/platform-store/save")]
     public async Task<PlatformStoreOutput> SaveAsync(PlatformStoreSaveInput input)
     {
@@ -111,6 +126,10 @@ public class PlatformStoreService : ApplicationService
         return MapOutput(entity);
     }
 
+    /// <summary>
+    /// 删除店铺授权。
+    /// </summary>
+    /// <param name="input">入参：店铺 ID 列表。</param>
     [HttpPost("/order/platform-store/delete")]
     public async Task DeleteAsync(PlatformStoreIdsInput input)
     {
diff --git a/src/Oms.Application/Services/Warehouse/WarehouseService.BinLocation.cs b/src/Oms.Application/Services/Warehouse/WarehouseService.BinLocation.cs
index 3697e9e..aa7676e 100644
--- a/src/Oms.Application/Services/Warehouse/WarehouseService.BinLocation.cs
+++ b/src/Oms.Application/Services/Warehouse/WarehouseService.BinLocation.cs
@@ -8,6 +8,11 @@ namespace Oms.Application.Services.Warehouse;
 
 public partial class WarehouseService
 {
+    /// <summary>
+    /// 查询库位列表。
+    /// </summary>
+    /// <param name="input">入参：仓库 ID 与筛选条件。</param>
+    /// <returns>库位列表。</returns>
     [HttpPost("/warehouse/bin-location/list")]
     public async Task<OmsItemsResult<WarehouseBinLocationOutput>> GetBinLocationListAsync(WarehouseBinLocationListInput input)
     {
@@ -30,6 +35,11 @@ public partial class WarehouseService
         };
     }
 
+    /// <summary>
+    /// 保存库位（新增或编辑）。
+    /// </summary>
+    /// <param name="input">入参：库位保存数据。</param>
+    /// <returns>保存后的库位。</returns>
     [HttpPost("/warehouse/bin-location/save")]
     public async Task<WarehouseBinLocationOutput> SaveBinLocationAsync(WarehouseBinLocationSaveInput input)
     {
diff --git a/src/Oms.Application/Services/Warehouse/WarehouseService.Inbound.cs b/src/Oms.Application/Services/Warehouse/WarehouseService.Inbound.cs
index 267f0fe..1c230d1 100644
--- a/src/Oms.Application/Services/Warehouse/WarehouseService.Inbound.cs
+++ b/src/Oms.Application/Services/Warehouse/WarehouseService.Inbound.cs
@@ -11,6 +11,11 @@ namespace Oms.Application.Services.Warehouse;
 
 public partial class WarehouseService
 {
+    /// <summary>
+    /// 查询入库预报列表。
+    /// </summary>
+    /// <param name="input">入参：入库预报分页查询条件。</param>
+    /// <returns>入库预报分页结果。</returns>
     [HttpPost("/warehouse/inbound/list")]
     public async Task<OmsPageResult<WarehouseInboundOutput>> GetInboundListAsync(WarehouseInboundListInput input)
     {
@@ -50,6 +55,12 @@ public partial class WarehouseService
         };
     }
 
+    /// <summary>
+    /// 查询入库预报详情。
+    /// </summary>
+    /// <param name="id">入库预报 ID。</param>
+    /// <param name="customerId">客户 ID（可选）。</param>
+    /// <returns>入库预报详情（含箱与明细）。</returns>
     [HttpGet("/warehouse/inbound/detail")]
     public async Task<WarehouseInboundDetailOutput> GetInboundDetailAsync(
         [FromQuery] int id,
@@ -84,6 +95,11 @@ public partial class WarehouseService
         };
     }
 
+    /// <summary>
+    /// 保存入库预报（新增或编辑）。
+    /// </summary>
+    /// <param name="input">入参：入库预报保存数据。</param>
+    /// <returns>保存后的入库预报详情。</returns>
     [HttpPost("/warehouse/inbound/save")]
     public async Task<WarehouseInboundDetailOutput> SaveInboundAsync(WarehouseInboundSaveInput input)
     {
@@ -171,6 +187,10 @@ public partial class WarehouseService
         return await GetInboundDetailAsync(notice.Id, customerId);
     }
 
+    /// <summary>
+    /// 删除入库预报。
+    /// </summary>
+    /// <param name="input">入参：入库预报 ID。</param>
     [HttpPost("/warehouse/inbound/delete")]
     public async Task DeleteInboundAsync(IdInput input)
     {
@@ -185,6 +205,10 @@ public partial class WarehouseService
         await InboundNoticeRepository.DeleteAsync(notice);
     }
 
+    /// <summary>
+    /// 确认入库收货并上架。
+    /// </summary>
+    /// <param name="input">入参：收货箱与实收数量。</param>
     [HttpPost("/warehouse/inbound/confirm-receive")]
     public async Task ConfirmInboundReceiveAsync(WarehouseInboundConfirmReceiveInput input)
     {
@@ -266,6 +290,12 @@ public partial class WarehouseService
         await InboundNoticeRepository.UpdateAsync(notice);
     }
 
+    /// <summary>
+    /// 查询入库预报状态汇总。
+    /// </summary>
+    /// <param name="customerId">客户 ID（可选）。</param>
+    /// <param name="warehouseId">仓库 ID（可选）。</param>
+    /// <returns>各状态数量汇总。</returns>
     [HttpGet("/warehouse/inbound/summary")]
     public async Task<WarehouseInboundSummaryOutput> GetInboundSummaryAsync([FromQuery] int? customerId = null, [FromQuery] int? warehouseId = null)
     {
diff --git a/src/Oms.Application/Services/Warehouse/WarehouseService.Inventory.cs b/src/Oms.Application/Services/Warehouse/WarehouseService.Inventory.cs
index d2ab769..4611d39 100644
--- a/src/Oms.Application/Services/Warehouse/WarehouseService.Inventory.cs
+++ b/src/Oms.Application/Services/Warehouse/WarehouseService.Inventory.cs
@@ -8,6 +8,11 @@ namespace Oms.Application.Services.Warehouse;
 
 public partial class WarehouseService
 {
+    /// <summary>
+    /// 查询库存列表。
+    /// </summary>
+    /// <param name="input">入参：库存分页查询条件。</param>
+    /// <returns>按 SKU 汇总的库存分页结果。</returns>
     [HttpPost("/warehouse/inventory/list")]
     public async Task<OmsPageResult<WarehouseInventoryOutput>> GetInventoryListAsync(WarehouseInventoryListInput input)
     {
@@ -58,6 +63,13 @@ public partial class WarehouseService
         };
     }
 
+    /// <summary>
+    /// 查询 SKU 在各库位的库存明细。
+    /// </summary>
+    /// <param name="skuId">SKU ID。</param>
+    /// <param name="warehouseId">仓库 ID。</param>
+    /// <param name="customerId">客户 ID（可选）。</param>
+    /// <returns>库位库存明细列表。</returns>
     [HttpGet("/warehouse/inventory/bin-detail")]
     public async Task<OmsItemsResult<WarehouseInventoryBinDetailOutput>> GetInventoryBinDetailAsync(
         [FromQuery] int skuId,
@@ -103,6 +115,10 @@ public partial class WarehouseService
         };
     }
 
+    /// <summary>
+    /// 库存移库（库位间调拨）。
+    /// </summary>
+    /// <param name="input">入参：源库位、目标库位与数量。</param>
     [HttpPost("/warehouse/inventory/relocate")]
     public async Task RelocateInventoryAsync(WarehouseInventoryRelocateInput input)
     {
diff --git a/src/Oms.Application/Services/Warehouse/WarehouseService.Parcel.cs b/src/Oms.Application/Services/Warehouse/WarehouseService.Parcel.cs
index 272bc1f..48ed137 100644
--- a/src/Oms.Application/Services/Warehouse/WarehouseService.Parcel.cs
+++ b/src/Oms.Application/Services/Warehouse/WarehouseService.Parcel.cs
@@ -11,6 +11,11 @@ namespace Oms.Application.Services.Warehouse;
 
 public partial class WarehouseService
 {
+    /// <summary>
+    /// 查询包裹列表。
+    /// </summary>
+    /// <param name="input">入参：包裹分页查询条件。</param>
+    /// <returns>包裹分页结果。</returns>
     [HttpPost("/warehouse/parcel/list")]
     public async Task<OmsPageResult<WarehouseParcelOutput>> GetParcelListAsync(WarehouseParcelListInput input)
     {
@@ -46,6 +51,11 @@ public partial class WarehouseService
         };
     }
 
+    /// <summary>
+    /// 保存包裹（新增或编辑）。
+    /// </summary>
+    /// <param name="input">入参：包裹保存数据。</param>
+    /// <returns>保存后的包裹。</returns>
     [HttpPost("/warehouse/parcel/save")]
     public async Task<WarehouseParcelOutput> SaveParcelAsync(WarehouseParcelSaveInput input)
     {
@@ -124,6 +134,10 @@ public partial class WarehouseService
         return MapParcelOutput(parcel, savedItems);
     }
 
+    /// <summary>
+    /// 删除包裹。
+    /// </summary>
+    /// <param name="input">入参：包裹 ID。</param>
     [HttpPost("/warehouse/parcel/delete")]
     public async Task DeleteParcelAsync(IdInput input)
     {
@@ -138,6 +152,10 @@ public partial class WarehouseService
         await ParcelRepository.DeleteAsync(parcel);
     }
 
+    /// <summary>
+    /// 包裹上架入库。
+    /// </summary>
+    /// <param name="input">入参：上架明细（SKU、库位、数量）。</param>
     [HttpPost("/warehouse/parcel/putaway")]
     public async Task PutawayParcelAsync(WarehouseParcelPutawayInput input)
     {
diff --git a/src/Oms.Application/Services/Warehouse/WarehouseService.Sku.cs b/src/Oms.Application/Services/Warehouse/WarehouseService.Sku.cs
index bae190c..0cd6525 100644
--- a/src/Oms.Application/Services/Warehouse/WarehouseService.Sku.cs
+++ b/src/Oms.Application/Services/Warehouse/WarehouseService.Sku.cs
@@ -9,6 +9,11 @@ namespace Oms.Application.Services.Warehouse;
 
 public partial class WarehouseService
 {
+    /// <summary>
+    /// 查询 SKU 列表。
+    /// </summary>
+    /// <param name="input">入参：SKU 分页查询条件。</param>
+    /// <returns>SKU 分页结果。</returns>
     [HttpPost("/warehouse/sku/list")]
     public async Task<OmsPageResult<WarehouseSkuOutput>> GetSkuListAsync(WarehouseSkuListInput input)
     {
@@ -44,6 +49,12 @@ public partial class WarehouseService
         };
     }
 
+    /// <summary>
+    /// 查询 SKU 详情。
+    /// </summary>
+    /// <param name="id">SKU ID。</param>
+    /// <param name="customerId">客户 ID（可选）。</param>
+    /// <returns>SKU 详情。</returns>
     [HttpGet("/warehouse/sku/detail")]
     public async Task<WarehouseSkuOutput> GetSkuDetailAsync([FromQuery] int id, [FromQuery] int? customerId = null)
     {
@@ -53,6 +64,11 @@ public partial class WarehouseService
         return MapSkuOutput(entity, inventories.Sum(x => x.Qty));
     }
 
+    /// <summary>
+    /// 保存 SKU（新增或编辑）。
+    /// </summary>
+    /// <param name="input">入参：SKU 保存数据。</param>
+    /// <returns>保存后的 SKU。</returns>
     [HttpPost("/warehouse/sku/save")]
     public async Task<WarehouseSkuOutput> SaveSkuAsync(WarehouseSkuSaveInput input)
     {
@@ -102,6 +118,10 @@ public partial class WarehouseService
         return MapSkuOutput(entity, 0);
     }
 
+    /// <summary>
+    /// 删除 SKU。
+    /// </summary>
+    /// <param name="input">入参：SKU ID。</param>
     [HttpPost("/warehouse/sku/delete")]
     public async Task DeleteSkuAsync(IdInput input)
     {
@@ -117,6 +137,11 @@ public partial class WarehouseService
         await SkuRepository.DeleteAsync(entity);
     }
 
+    /// <summary>
+    /// 绑定平台 SKU 与库内 SKU 映射。
+    /// </summary>
+    /// <param name="input">入参：映射关系。</param>
+    /// <returns>映射结果。</returns>
     [HttpPost("/warehouse/sku/bind-mapping")]
     public async Task<WarehouseSkuMappingOutput> BindSkuMappingAsync(WarehouseSkuBindMappingInput input)
     {