From 60cb2c5e0f9820a68369df37f805763289c03f39 Mon Sep 17 00:00:00 2001 From: zzh <1368735060@qq.com> Date: Fri, 24 Jul 2026 11:09:55 +0800 Subject: [PATCH] fix: document marketing APIs and hide Order batch helpers from Swagger Add Chinese XML summaries for OMS-Marketing endpoints, and mark OrderService batch worker methods internal to stop OMS-Order swagger generation conflicts. Co-authored-by: Cursor --- .../MarketingCommissionAdminService.cs | 18 ++++++++++++ .../MarketingCommissionRuleService.cs | 9 ++++++ .../MarketingCouponTemplateService.cs | 18 ++++++++++++ .../Marketing/MarketingPointsRuleService.cs | 15 ++++++++++ .../MarketingPortalCommissionService.cs | 18 ++++++++++++ .../Marketing/MarketingPortalMemberService.cs | 9 ++++++ .../MarketingPortalReferralService.cs | 16 +++++----- .../MarketingReferralAdminService.cs | 12 ++++++++ .../Orders/OrderService.BatchCreate.cs | 29 +++++-------------- .../Orders/OrderService.BatchWorker.cs | 20 ++++++------- .../Orders/OrderService.ParcelQuote.cs | 2 +- 11 files changed, 125 insertions(+), 41 deletions(-) diff --git a/src/Oms.Application/Services/Marketing/MarketingCommissionAdminService.cs b/src/Oms.Application/Services/Marketing/MarketingCommissionAdminService.cs index e164659..362dcb1 100644 --- a/src/Oms.Application/Services/Marketing/MarketingCommissionAdminService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingCommissionAdminService.cs @@ -15,6 +15,9 @@ using Oms.Domain.MarketingAggregate.Repositories; namespace Oms.Application.Services.Marketing; +/// +/// ????????? API?????? +/// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingCommissionAdminService : ApplicationService { @@ -33,6 +36,9 @@ public class MarketingCommissionAdminService : ApplicationService private CommissionBalanceMutator CommissionBalanceMutator => LazyServiceProvider.GetRequiredService(); + /// + /// ????????? + /// [HttpPost("/marketing/commission-detail/list")] public async Task> GetDetailListAsync(CommissionDetailListInput input) { @@ -52,6 +58,9 @@ public class MarketingCommissionAdminService : ApplicationService }; } + /// + /// ????????? + /// [HttpPost("/marketing/commission-detail/adjust")] public async Task AdjustAsync(CommissionAdjustInput input) { @@ -85,6 +94,9 @@ public class MarketingCommissionAdminService : ApplicationService }); } + /// + /// ????????? + /// [HttpPost("/marketing/commission-withdraw/list")] public async Task> GetWithdrawListAsync(CommissionWithdrawListInput input) { @@ -123,6 +135,9 @@ public class MarketingCommissionAdminService : ApplicationService input.CustomerId = customer.ParentCustomerId ?? customer.Id; } + /// + /// ????????? + /// [HttpPost("/marketing/commission-withdraw/approve")] public async Task ApproveWithdrawAsync(CommissionWithdrawApproveInput input) { @@ -153,6 +168,9 @@ public class MarketingCommissionAdminService : ApplicationService await WithdrawRepository.UpdateAsync(request); } + /// + /// ??????? + /// [HttpPost("/marketing/commission-withdraw/reject")] public async Task RejectWithdrawAsync(CommissionWithdrawRejectInput input) { diff --git a/src/Oms.Application/Services/Marketing/MarketingCommissionRuleService.cs b/src/Oms.Application/Services/Marketing/MarketingCommissionRuleService.cs index c5e47f5..dc79370 100644 --- a/src/Oms.Application/Services/Marketing/MarketingCommissionRuleService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingCommissionRuleService.cs @@ -8,12 +8,18 @@ using Oms.Domain.MarketingAggregate.Repositories; namespace Oms.Application.Services.Marketing; +/// +/// 分成规则 API（管理端）。 +/// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingCommissionRuleService : ApplicationService { private IReferralCommissionRuleRepository RuleRepository => LazyServiceProvider.GetRequiredService(); + /// + /// 获取当前分成规则。 + /// [HttpPost("/marketing/commission-rule/get")] public async Task GetAsync() { @@ -21,6 +27,9 @@ public class MarketingCommissionRuleService : ApplicationService return rule == null ? null : MapOutput(rule); } + /// + /// 更新分成规则。 + /// [HttpPost("/marketing/commission-rule/update")] public async Task UpdateAsync(ReferralCommissionRuleSaveInput input) { diff --git a/src/Oms.Application/Services/Marketing/MarketingCouponTemplateService.cs b/src/Oms.Application/Services/Marketing/MarketingCouponTemplateService.cs index 82198f6..9537819 100644 --- a/src/Oms.Application/Services/Marketing/MarketingCouponTemplateService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingCouponTemplateService.cs @@ -12,12 +12,18 @@ using Oms.Domain.MarketingAggregate.Repositories; namespace Oms.Application.Services.Marketing; +/// +/// 优惠券模板 API（管理端）。 +/// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingCouponTemplateService : ApplicationService { private ICouponTemplateRepository TemplateRepository => LazyServiceProvider.GetRequiredService(); + /// + /// 分页查询优惠券模板。 + /// [HttpPost("/marketing/coupon-template/list")] public async Task> GetListAsync(CouponTemplateListInput input) { @@ -41,6 +47,9 @@ public class MarketingCouponTemplateService : ApplicationService }; } + /// + /// 新增优惠券模板（草稿）。 + /// [HttpPost("/marketing/coupon-template/create")] public async Task CreateAsync(CouponTemplateSaveInput input) { @@ -53,6 +62,9 @@ public class MarketingCouponTemplateService : ApplicationService await TemplateRepository.InsertAsync(entity); } + /// + /// 更新优惠券模板。 + /// [HttpPost("/marketing/coupon-template/update")] public async Task UpdateAsync(CouponTemplateSaveInput input) { @@ -72,6 +84,9 @@ public class MarketingCouponTemplateService : ApplicationService await TemplateRepository.UpdateAsync(entity); } + /// + /// 发布优惠券模板（草稿 → 生效）。 + /// [HttpPost("/marketing/coupon-template/publish")] public async Task PublishAsync(IdInput input) { @@ -85,6 +100,9 @@ public class MarketingCouponTemplateService : ApplicationService await TemplateRepository.UpdateAsync(entity); } + /// + /// 结束优惠券模板（生效 → 已结束）。 + /// [HttpPost("/marketing/coupon-template/end")] public async Task EndAsync(IdInput input) { diff --git a/src/Oms.Application/Services/Marketing/MarketingPointsRuleService.cs b/src/Oms.Application/Services/Marketing/MarketingPointsRuleService.cs index 468142b..92c56b1 100644 --- a/src/Oms.Application/Services/Marketing/MarketingPointsRuleService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingPointsRuleService.cs @@ -12,6 +12,9 @@ using Oms.Domain.MarketingAggregate.Repositories; namespace Oms.Application.Services.Marketing; +/// +/// 积分规则与流水 API（管理端）。 +/// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingPointsRuleService : ApplicationService { @@ -27,6 +30,9 @@ public class MarketingPointsRuleService : ApplicationService private MarketingPointsManager PointsManager => LazyServiceProvider.GetRequiredService(); + /// + /// 获取当前积分规则。 + /// [HttpPost("/marketing/points-rule/get")] public async Task GetAsync() { @@ -34,6 +40,9 @@ public class MarketingPointsRuleService : ApplicationService return rule == null ? null : MapRuleOutput(rule); } + /// + /// 更新积分规则。 + /// [HttpPost("/marketing/points-rule/update")] public async Task UpdateAsync(PointsRuleSaveInput input) { @@ -65,6 +74,9 @@ public class MarketingPointsRuleService : ApplicationService } } + /// + /// 分页查询积分流水。 + /// [HttpPost("/marketing/points-flow/list")] public async Task> GetFlowListAsync(PointsFlowListInput input) { @@ -113,6 +125,9 @@ public class MarketingPointsRuleService : ApplicationService }; } + /// + /// 人工调账积分。 + /// [HttpPost("/marketing/points/adjust")] public async Task AdjustAsync(PointsAdjustInput input) { diff --git a/src/Oms.Application/Services/Marketing/MarketingPortalCommissionService.cs b/src/Oms.Application/Services/Marketing/MarketingPortalCommissionService.cs index bbe91dc..54e1901 100644 --- a/src/Oms.Application/Services/Marketing/MarketingPortalCommissionService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingPortalCommissionService.cs @@ -13,6 +13,9 @@ using Oms.Domain.MarketingAggregate.Repositories; namespace Oms.Application.Services.Marketing; +/// +/// 门户推荐收益与提现 API。 +/// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingPortalCommissionService : ApplicationService { @@ -25,6 +28,9 @@ public class MarketingPortalCommissionService : ApplicationService private ICommissionWithdrawRequestRepository WithdrawRepository => LazyServiceProvider.GetRequiredService(); + /// + /// 推荐收益概览。 + /// [HttpGet("/marketing/commission/overview")] public async Task GetOverviewAsync() { @@ -59,6 +65,9 @@ public class MarketingPortalCommissionService : ApplicationService }; } + /// + /// 我的分成明细。 + /// [HttpGet("/marketing/commission/details")] public async Task> GetDetailsAsync( [FromQuery] CommissionDetailListInput input) @@ -116,6 +125,9 @@ public class MarketingPortalCommissionService : ApplicationService }; } + /// + /// 我的提现申请列表。 + /// [HttpGet("/marketing/commission/withdraw/list")] public async Task> GetWithdrawListAsync( [FromQuery] CommissionWithdrawListInput input) @@ -147,6 +159,9 @@ public class MarketingPortalCommissionService : ApplicationService }; } + /// + /// 佣金转入账户余额。 + /// [HttpPost("/marketing/commission/transfer-to-balance")] public async Task TransferToBalanceAsync(CommissionTransferInput input) { @@ -161,6 +176,9 @@ public class MarketingPortalCommissionService : ApplicationService input.Remark); } + /// + /// 申请提现到外部账户。 + /// [HttpPost("/marketing/commission/withdraw/apply")] public async Task ApplyWithdrawAsync(CommissionWithdrawApplyInput input) { diff --git a/src/Oms.Application/Services/Marketing/MarketingPortalMemberService.cs b/src/Oms.Application/Services/Marketing/MarketingPortalMemberService.cs index 9951293..5b132cc 100644 --- a/src/Oms.Application/Services/Marketing/MarketingPortalMemberService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingPortalMemberService.cs @@ -10,6 +10,9 @@ using Oms.Domain.MarketingAggregate.Repositories; namespace Oms.Application.Services.Marketing; +/// +/// 门户会员等级与积分 API。 +/// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingPortalMemberService : ApplicationService { @@ -25,6 +28,9 @@ public class MarketingPortalMemberService : ApplicationService private MarketingPointsManager PointsManager => LazyServiceProvider.GetRequiredService(); + /// + /// 我的会员等级与积分概览。 + /// [HttpGet("/marketing/member/overview")] public async Task GetOverviewAsync() { @@ -62,6 +68,9 @@ public class MarketingPortalMemberService : ApplicationService }; } + /// + /// 我的积分流水。 + /// [HttpGet("/marketing/member/points-flow")] public async Task> GetPointsFlowAsync([FromQuery] PointsFlowListInput input) { diff --git a/src/Oms.Application/Services/Marketing/MarketingPortalReferralService.cs b/src/Oms.Application/Services/Marketing/MarketingPortalReferralService.cs index da40dc8..4dfda12 100644 --- a/src/Oms.Application/Services/Marketing/MarketingPortalReferralService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingPortalReferralService.cs @@ -14,7 +14,7 @@ using Oms.Domain.OrdersAggregate.Repositories; namespace Oms.Application.Services.Marketing; /// -/// ???? API? +/// 门户邀请好友 API。 /// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingPortalReferralService : ApplicationService @@ -32,7 +32,7 @@ public class MarketingPortalReferralService : ApplicationService LazyServiceProvider.GetRequiredService(); /// - /// ??????? + /// 我的邀请码与下级人数。 /// [HttpGet("/marketing/referral/my-invite")] public async Task GetMyInviteAsync() @@ -42,7 +42,7 @@ public class MarketingPortalReferralService : ApplicationService CurrentUser); if (mainCustomer.ParentCustomerId.HasValue) { - throw new BusinessException("???????????"); + throw new BusinessException("子账号不可访问营销中心"); } var referralCode = await ReferralCodeProvisioner.GetOrCreateAsync(mainCustomer.Id); @@ -59,7 +59,7 @@ public class MarketingPortalReferralService : ApplicationService } /// - /// ??????? + /// 我的一级下级列表。 /// [HttpGet("/marketing/referral/referees")] public async Task> GetRefereesAsync( @@ -107,7 +107,7 @@ public class MarketingPortalReferralService : ApplicationService } /// - /// ????????????????? + /// 校验邀请码（匿名，注册归因用）。 /// [AllowAnonymous] [HttpGet("/marketing/referral/validate-code")] @@ -119,7 +119,7 @@ public class MarketingPortalReferralService : ApplicationService return new ReferralValidateCodeOutput { Valid = false, - Message = "???????" + Message = "邀请码不能为空" }; } @@ -129,7 +129,7 @@ public class MarketingPortalReferralService : ApplicationService return new ReferralValidateCodeOutput { Valid = false, - Message = "?????????" + Message = "邀请码无效或已停用" }; } @@ -139,7 +139,7 @@ public class MarketingPortalReferralService : ApplicationService return new ReferralValidateCodeOutput { Valid = false, - Message = "?????????" + Message = "邀请人不存在或非主客户" }; } diff --git a/src/Oms.Application/Services/Marketing/MarketingReferralAdminService.cs b/src/Oms.Application/Services/Marketing/MarketingReferralAdminService.cs index 11d429f..a813031 100644 --- a/src/Oms.Application/Services/Marketing/MarketingReferralAdminService.cs +++ b/src/Oms.Application/Services/Marketing/MarketingReferralAdminService.cs @@ -15,6 +15,9 @@ using Oms.Domain.MarketingAggregate.Repositories; namespace Oms.Application.Services.Marketing; +/// +/// ?????? API?????? +/// [ApiExplorerSettings(GroupName = "OMS-Marketing")] public class MarketingReferralAdminService : ApplicationService { @@ -27,6 +30,9 @@ public class MarketingReferralAdminService : ApplicationService private IMarketingAuditLogRepository AuditLogRepository => LazyServiceProvider.GetRequiredService(); + /// + /// ???????????? + /// [HttpPost("/marketing/referral/referrer-list")] public async Task> GetReferrerListAsync(ReferralReferrerListInput input) { @@ -65,6 +71,9 @@ public class MarketingReferralAdminService : ApplicationService }; } + /// + /// ??????????????? + /// [HttpPost("/marketing/referral/tree")] public async Task> GetTreeAsync(ReferralTreeInput input) { @@ -85,6 +94,9 @@ public class MarketingReferralAdminService : ApplicationService }; } + /// + /// ??????????????????????? + /// [HttpPost("/marketing/referral/rebind")] public async Task RebindAsync(ReferralRebindInput input) { diff --git a/src/Oms.Application/Services/Orders/OrderService.BatchCreate.cs b/src/Oms.Application/Services/Orders/OrderService.BatchCreate.cs index 2fc3084..6649f53 100644 --- a/src/Oms.Application/Services/Orders/OrderService.BatchCreate.cs +++ b/src/Oms.Application/Services/Orders/OrderService.BatchCreate.cs @@ -14,9 +14,9 @@ public partial class OrderService LazyServiceProvider.GetRequiredService(); /// - /// 批量 Worker 导入单行 Excel 数据。 + /// 批量 Worker 导入单行 Excel 数据（内部方法，勿暴露为 HTTP API）。 /// - public async Task ImportRowForBatchAsync( + internal async Task ImportRowForBatchAsync( OrderBatchImportRowPayload payload, int operatorUserId, CancellationToken cancellationToken = default) @@ -47,7 +47,7 @@ public partial class OrderService cancellationToken); } - public async Task TryResolveImportOrderIdAsync( + internal async Task TryResolveImportOrderIdAsync( OrderBatchImportRowPayload payload, CancellationToken cancellationToken = default) { @@ -87,18 +87,16 @@ public partial class OrderService /// /// 批量 Worker 创建小包订单。 /// - public async Task CreateParcelForBatchAsync( + internal Task CreateParcelForBatchAsync( OrderParcelCreateInput input, int operatorUserId, - CancellationToken cancellationToken = default) - { - return await CreateParcelForBatchAsync(input, operatorUserId, orderSource: null, customerSenderAddressId: null, cancellationToken); - } + CancellationToken cancellationToken = default) => + CreateParcelForBatchAsync(input, operatorUserId, orderSource: null, customerSenderAddressId: null, cancellationToken); /// /// 批量 Worker 创建小包订单（可指定 与默认发件地址）。 /// - public async Task CreateParcelForBatchAsync( + internal async Task CreateParcelForBatchAsync( OrderParcelCreateInput input, int operatorUserId, string? orderSource, @@ -117,17 +115,4 @@ public partial class OrderService return await CreateParcelCoreAsync(input, operatorUserId, createContext); } - - /// - /// 批量 Worker 创建小包订单（可指定 ）。 - /// - [Obsolete("Use CreateParcelForBatchAsync with customerSenderAddressId when importing.")] - public async Task CreateParcelForBatchAsync( - OrderParcelCreateInput input, - int operatorUserId, - string? orderSource, - CancellationToken cancellationToken = default) - { - return await CreateParcelForBatchAsync(input, operatorUserId, orderSource, null, cancellationToken); - } } diff --git a/src/Oms.Application/Services/Orders/OrderService.BatchWorker.cs b/src/Oms.Application/Services/Orders/OrderService.BatchWorker.cs index b681d90..92b12eb 100644 --- a/src/Oms.Application/Services/Orders/OrderService.BatchWorker.cs +++ b/src/Oms.Application/Services/Orders/OrderService.BatchWorker.cs @@ -10,25 +10,25 @@ namespace Oms.Application.Services.Orders; public partial class OrderService { - public Task PayForBatchAsync(int orderId, CancellationToken cancellationToken = default) => + internal Task PayForBatchAsync(int orderId, CancellationToken cancellationToken = default) => PayAsync(new OrderActionInput { Id = orderId }); - public Task PreDeclareForBatchAsync(int orderId, CancellationToken cancellationToken = default) => + internal Task PreDeclareForBatchAsync(int orderId, CancellationToken cancellationToken = default) => PreDeclareAsync(new OrderActionInput { Id = orderId }); - public Task InterceptForBatchAsync(int orderId, CancellationToken cancellationToken = default) => + internal Task InterceptForBatchAsync(int orderId, CancellationToken cancellationToken = default) => InterceptAsync(new OrderActionInput { Id = orderId }); - public Task CancelInterceptForBatchAsync(int orderId, CancellationToken cancellationToken = default) => + internal Task CancelInterceptForBatchAsync(int orderId, CancellationToken cancellationToken = default) => CancelInterceptAsync(new OrderActionInput { Id = orderId }); - public Task DeleteForBatchAsync(int orderId, CancellationToken cancellationToken = default) => + internal Task DeleteForBatchAsync(int orderId, CancellationToken cancellationToken = default) => DeleteAsync(new OrderActionInput { Id = orderId }); - public Task PrintForBatchAsync(int orderId, CancellationToken cancellationToken = default) => + internal Task PrintForBatchAsync(int orderId, CancellationToken cancellationToken = default) => PrintAsync(new OrderActionInput { Id = orderId }); - public async Task GenerateLabelPdfForBatchAsync( + internal async Task GenerateLabelPdfForBatchAsync( int orderId, CancellationToken cancellationToken = default) { @@ -42,7 +42,7 @@ public partial class OrderService cancellationToken); } - public async Task MarkProblematicForBatchAsync( + internal async Task MarkProblematicForBatchAsync( int orderId, string? payloadJson, int operatorUserId, @@ -76,7 +76,7 @@ public partial class OrderService } } - public async Task MarkClaimedForBatchAsync( + internal async Task MarkClaimedForBatchAsync( int orderId, string? payloadJson, CancellationToken cancellationToken = default) @@ -124,7 +124,7 @@ public partial class OrderService }); } - public async Task UpdateHandleStatusForBatchAsync( + internal async Task UpdateHandleStatusForBatchAsync( int orderId, string? payloadJson, CancellationToken cancellationToken = default) diff --git a/src/Oms.Application/Services/Orders/OrderService.ParcelQuote.cs b/src/Oms.Application/Services/Orders/OrderService.ParcelQuote.cs index c5648fe..56590a2 100644 --- a/src/Oms.Application/Services/Orders/OrderService.ParcelQuote.cs +++ b/src/Oms.Application/Services/Orders/OrderService.ParcelQuote.cs @@ -17,7 +17,7 @@ public partial class OrderService private sealed record PriceCheckCargoTarget(string Code, string DisplayName, string CargoAttribute); - public async Task BuildPriceCheckShippingOptionsAsync() + private async Task BuildPriceCheckShippingOptionsAsync() { var products = await SalesProductRepository.GetListAsync(x => x.IsActive == EnableStatus.Enabled); var sortedProducts = products