ideship/admin
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: document marketing APIs and hide Order batch helpers from Swagger

Browse Source 
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 <cursoragent@cursor.com>
This commit is contained in:
zzh 2026-07-24 11:09:55 +08:00
parent 8f043599ec
commit 60cb2c5e0f
11 changed files with 125 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/Oms.Application/Services/Marketing/MarketingCommissionAdminService.cs
View File

@ -15,6 +15,9 @@ using Oms.Domain.MarketingAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// ????????? API??????
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingCommissionAdminService : ApplicationService
{
@ -33,6 +36,9 @@ public class MarketingCommissionAdminService : ApplicationService
private CommissionBalanceMutator CommissionBalanceMutator =>
LazyServiceProvider.GetRequiredService<CommissionBalanceMutator>();
/// <summary>
/// ?????????
/// </summary>
[HttpPost("/marketing/commission-detail/list")]
public async Task<OmsPageResult<CommissionDetailOutput>> GetDetailListAsync(CommissionDetailListInput input)
{
@ -52,6 +58,9 @@ public class MarketingCommissionAdminService : ApplicationService
};
}
/// <summary>
/// ?????????
/// </summary>
[HttpPost("/marketing/commission-detail/adjust")]
public async Task AdjustAsync(CommissionAdjustInput input)
{
@ -85,6 +94,9 @@ public class MarketingCommissionAdminService : ApplicationService
});
}
/// <summary>
/// ?????????
/// </summary>
[HttpPost("/marketing/commission-withdraw/list")]
public async Task<OmsPageResult<CommissionWithdrawOutput>> GetWithdrawListAsync(CommissionWithdrawListInput input)
{
@ -123,6 +135,9 @@ public class MarketingCommissionAdminService : ApplicationService
input.CustomerId = customer.ParentCustomerId ?? customer.Id;
}
/// <summary>
/// ?????????
/// </summary>
[HttpPost("/marketing/commission-withdraw/approve")]
public async Task ApproveWithdrawAsync(CommissionWithdrawApproveInput input)
{
@ -153,6 +168,9 @@ public class MarketingCommissionAdminService : ApplicationService
await WithdrawRepository.UpdateAsync(request);
}
/// <summary>
/// ???????
/// </summary>
[HttpPost("/marketing/commission-withdraw/reject")]
public async Task RejectWithdrawAsync(CommissionWithdrawRejectInput input)
{

9
src/Oms.Application/Services/Marketing/MarketingCommissionRuleService.cs
View File

@ -8,12 +8,18 @@ using Oms.Domain.MarketingAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// 分成规则 API（管理端）。
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingCommissionRuleService : ApplicationService
{
private IReferralCommissionRuleRepository RuleRepository =>
LazyServiceProvider.GetRequiredService<IReferralCommissionRuleRepository>();
/// <summary>
/// 获取当前分成规则。
/// </summary>
[HttpPost("/marketing/commission-rule/get")]
public async Task<ReferralCommissionRuleOutput?> GetAsync()
{
@ -21,6 +27,9 @@ public class MarketingCommissionRuleService : ApplicationService
return rule == null ? null : MapOutput(rule);
}
/// <summary>
/// 更新分成规则。
/// </summary>
[HttpPost("/marketing/commission-rule/update")]
public async Task UpdateAsync(ReferralCommissionRuleSaveInput input)
{

18
src/Oms.Application/Services/Marketing/MarketingCouponTemplateService.cs
View File

@ -12,12 +12,18 @@ using Oms.Domain.MarketingAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// 优惠券模板 API（管理端）。
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingCouponTemplateService : ApplicationService
{
private ICouponTemplateRepository TemplateRepository =>
LazyServiceProvider.GetRequiredService<ICouponTemplateRepository>();
/// <summary>
/// 分页查询优惠券模板。
/// </summary>
[HttpPost("/marketing/coupon-template/list")]
public async Task<OmsPageResult<CouponTemplateOutput>> GetListAsync(CouponTemplateListInput input)
{
@ -41,6 +47,9 @@ public class MarketingCouponTemplateService : ApplicationService
};
}
/// <summary>
/// 新增优惠券模板（草稿）。
/// </summary>
[HttpPost("/marketing/coupon-template/create")]
public async Task CreateAsync(CouponTemplateSaveInput input)
{
@ -53,6 +62,9 @@ public class MarketingCouponTemplateService : ApplicationService
await TemplateRepository.InsertAsync(entity);
}
/// <summary>
/// 更新优惠券模板。
/// </summary>
[HttpPost("/marketing/coupon-template/update")]
public async Task UpdateAsync(CouponTemplateSaveInput input)
{
@ -72,6 +84,9 @@ public class MarketingCouponTemplateService : ApplicationService
await TemplateRepository.UpdateAsync(entity);
}
/// <summary>
/// 发布优惠券模板（草稿 → 生效）。
/// </summary>
[HttpPost("/marketing/coupon-template/publish")]
public async Task PublishAsync(IdInput input)
{
@ -85,6 +100,9 @@ public class MarketingCouponTemplateService : ApplicationService
await TemplateRepository.UpdateAsync(entity);
}
/// <summary>
/// 结束优惠券模板（生效 → 已结束）。
/// </summary>
[HttpPost("/marketing/coupon-template/end")]
public async Task EndAsync(IdInput input)
{

15
src/Oms.Application/Services/Marketing/MarketingPointsRuleService.cs
View File

@ -12,6 +12,9 @@ using Oms.Domain.MarketingAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// 积分规则与流水 API（管理端）。
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingPointsRuleService : ApplicationService
{
@ -27,6 +30,9 @@ public class MarketingPointsRuleService : ApplicationService
private MarketingPointsManager PointsManager =>
LazyServiceProvider.GetRequiredService<MarketingPointsManager>();
/// <summary>
/// 获取当前积分规则。
/// </summary>
[HttpPost("/marketing/points-rule/get")]
public async Task<PointsRuleOutput?> GetAsync()
{
@ -34,6 +40,9 @@ public class MarketingPointsRuleService : ApplicationService
return rule == null ? null : MapRuleOutput(rule);
}
/// <summary>
/// 更新积分规则。
/// </summary>
[HttpPost("/marketing/points-rule/update")]
public async Task UpdateAsync(PointsRuleSaveInput input)
{
@ -65,6 +74,9 @@ public class MarketingPointsRuleService : ApplicationService
}
}
/// <summary>
/// 分页查询积分流水。
/// </summary>
[HttpPost("/marketing/points-flow/list")]
public async Task<OmsPageResult<PointsFlowOutput>> GetFlowListAsync(PointsFlowListInput input)
{
@ -113,6 +125,9 @@ public class MarketingPointsRuleService : ApplicationService
};
}
/// <summary>
/// 人工调账积分。
/// </summary>
[HttpPost("/marketing/points/adjust")]
public async Task AdjustAsync(PointsAdjustInput input)
{

18
src/Oms.Application/Services/Marketing/MarketingPortalCommissionService.cs
View File

@ -13,6 +13,9 @@ using Oms.Domain.MarketingAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// 门户推荐收益与提现 API。
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingPortalCommissionService : ApplicationService
{
@ -25,6 +28,9 @@ public class MarketingPortalCommissionService : ApplicationService
private ICommissionWithdrawRequestRepository WithdrawRepository =>
LazyServiceProvider.GetRequiredService<ICommissionWithdrawRequestRepository>();
/// <summary>
/// 推荐收益概览。
/// </summary>
[HttpGet("/marketing/commission/overview")]
public async Task<CommissionOverviewOutput> GetOverviewAsync()
{
@ -59,6 +65,9 @@ public class MarketingPortalCommissionService : ApplicationService
};
}
/// <summary>
/// 我的分成明细。
/// </summary>
[HttpGet("/marketing/commission/details")]
public async Task<OmsPageResult<CommissionDetailOutput>> GetDetailsAsync(
[FromQuery] CommissionDetailListInput input)
@ -116,6 +125,9 @@ public class MarketingPortalCommissionService : ApplicationService
};
}
/// <summary>
/// 我的提现申请列表。
/// </summary>
[HttpGet("/marketing/commission/withdraw/list")]
public async Task<OmsPageResult<CommissionWithdrawOutput>> GetWithdrawListAsync(
[FromQuery] CommissionWithdrawListInput input)
@ -147,6 +159,9 @@ public class MarketingPortalCommissionService : ApplicationService
};
}
/// <summary>
/// 佣金转入账户余额。
/// </summary>
[HttpPost("/marketing/commission/transfer-to-balance")]
public async Task TransferToBalanceAsync(CommissionTransferInput input)
{
@ -161,6 +176,9 @@ public class MarketingPortalCommissionService : ApplicationService
input.Remark);
}
/// <summary>
/// 申请提现到外部账户。
/// </summary>
[HttpPost("/marketing/commission/withdraw/apply")]
public async Task<CommissionWithdrawOutput> ApplyWithdrawAsync(CommissionWithdrawApplyInput input)
{

9
src/Oms.Application/Services/Marketing/MarketingPortalMemberService.cs
View File

@ -10,6 +10,9 @@ using Oms.Domain.MarketingAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// 门户会员等级与积分 API。
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingPortalMemberService : ApplicationService
{
@ -25,6 +28,9 @@ public class MarketingPortalMemberService : ApplicationService
private MarketingPointsManager PointsManager =>
LazyServiceProvider.GetRequiredService<MarketingPointsManager>();
/// <summary>
/// 我的会员等级与积分概览。
/// </summary>
[HttpGet("/marketing/member/overview")]
public async Task<MemberOverviewOutput> GetOverviewAsync()
{
@ -62,6 +68,9 @@ public class MarketingPortalMemberService : ApplicationService
};
}
/// <summary>
/// 我的积分流水。
/// </summary>
[HttpGet("/marketing/member/points-flow")]
public async Task<OmsPageResult<PointsFlowOutput>> GetPointsFlowAsync([FromQuery] PointsFlowListInput input)
{

16
src/Oms.Application/Services/Marketing/MarketingPortalReferralService.cs
View File

@ -14,7 +14,7 @@ using Oms.Domain.OrdersAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// ???? API?
/// 门户邀请好友 API。
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingPortalReferralService : ApplicationService
@ -32,7 +32,7 @@ public class MarketingPortalReferralService : ApplicationService
LazyServiceProvider.GetRequiredService<MarketingReferralCodeProvisioner>();
/// <summary>
/// ???????
/// 我的邀请码与下级人数。
/// </summary>
[HttpGet("/marketing/referral/my-invite")]
public async Task<ReferralMyInviteOutput> 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
}
/// <summary>
/// ???????
/// 我的一级下级列表。
/// </summary>
[HttpGet("/marketing/referral/referees")]
public async Task<OmsPageResult<ReferralRefereeOutput>> GetRefereesAsync(
@ -107,7 +107,7 @@ public class MarketingPortalReferralService : ApplicationService
}
/// <summary>
/// ?????????????????
/// 校验邀请码（匿名，注册归因用）。
/// </summary>
[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 = "邀请人不存在或非主客户"
};
}

12
src/Oms.Application/Services/Marketing/MarketingReferralAdminService.cs
View File

@ -15,6 +15,9 @@ using Oms.Domain.MarketingAggregate.Repositories;
namespace Oms.Application.Services.Marketing;
/// <summary>
/// ?????? API??????
/// </summary>
[ApiExplorerSettings(GroupName = "OMS-Marketing")]
public class MarketingReferralAdminService : ApplicationService
{
@ -27,6 +30,9 @@ public class MarketingReferralAdminService : ApplicationService
private IMarketingAuditLogRepository AuditLogRepository =>
LazyServiceProvider.GetRequiredService<IMarketingAuditLogRepository>();
/// <summary>
/// ????????????
/// </summary>
[HttpPost("/marketing/referral/referrer-list")]
public async Task<OmsPageResult<ReferralReferrerOutput>> GetReferrerListAsync(ReferralReferrerListInput input)
{
@ -65,6 +71,9 @@ public class MarketingReferralAdminService : ApplicationService
};
}
/// <summary>
/// ???????????????
/// </summary>
[HttpPost("/marketing/referral/tree")]
public async Task<OmsPageResult<ReferralTreeNodeOutput>> GetTreeAsync(ReferralTreeInput input)
{
@ -85,6 +94,9 @@ public class MarketingReferralAdminService : ApplicationService
};
}
/// <summary>
/// ???????????????????????
/// </summary>
[HttpPost("/marketing/referral/rebind")]
public async Task RebindAsync(ReferralRebindInput input)
{

29
src/Oms.Application/Services/Orders/OrderService.BatchCreate.cs
View File

@ -14,9 +14,9 @@ public partial class OrderService
LazyServiceProvider.GetRequiredService<IOrderBatchJobPublisher>();
/// <summary>
/// 批量 Worker 导入单行 Excel 数据。
/// 批量 Worker 导入单行 Excel 数据（内部方法，勿暴露为 HTTP API）。
/// </summary>
public async Task<OrderParcelCreateOutput> ImportRowForBatchAsync(
internal async Task<OrderParcelCreateOutput> ImportRowForBatchAsync(
OrderBatchImportRowPayload payload,
int operatorUserId,
CancellationToken cancellationToken = default)
@ -47,7 +47,7 @@ public partial class OrderService
cancellationToken);
}
public async Task<int?> TryResolveImportOrderIdAsync(
internal async Task<int?> TryResolveImportOrderIdAsync(
OrderBatchImportRowPayload payload,
CancellationToken cancellationToken = default)
{
@ -87,18 +87,16 @@ public partial class OrderService
/// <summary>
/// 批量 Worker 创建小包订单。
/// </summary>
public async Task<OrderParcelCreateOutput> CreateParcelForBatchAsync(
internal Task<OrderParcelCreateOutput> 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);
/// <summary>
/// 批量 Worker 创建小包订单（可指定 <paramref name="orderSource"/> 与默认发件地址）。
/// </summary>
public async Task<OrderParcelCreateOutput> CreateParcelForBatchAsync(
internal async Task<OrderParcelCreateOutput> CreateParcelForBatchAsync(
OrderParcelCreateInput input,
int operatorUserId,
string? orderSource,
@ -117,17 +115,4 @@ public partial class OrderService
return await CreateParcelCoreAsync(input, operatorUserId, createContext);
}
/// <summary>
/// 批量 Worker 创建小包订单（可指定 <paramref name="orderSource"/>）。
/// </summary>
[Obsolete("Use CreateParcelForBatchAsync with customerSenderAddressId when importing.")]
public async Task<OrderParcelCreateOutput> CreateParcelForBatchAsync(
OrderParcelCreateInput input,
int operatorUserId,
string? orderSource,
CancellationToken cancellationToken = default)
{
return await CreateParcelForBatchAsync(input, operatorUserId, orderSource, null, cancellationToken);
}
}

20
src/Oms.Application/Services/Orders/OrderService.BatchWorker.cs
View File

@ -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<OrderPrintOutput> PrintForBatchAsync(int orderId, CancellationToken cancellationToken = default) =>
internal Task<OrderPrintOutput> PrintForBatchAsync(int orderId, CancellationToken cancellationToken = default) =>
PrintAsync(new OrderActionInput { Id = orderId });
public async Task<LabelPdfGenerateResult> GenerateLabelPdfForBatchAsync(
internal async Task<LabelPdfGenerateResult> 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)

2
src/Oms.Application/Services/Orders/OrderService.ParcelQuote.cs
View File

@ -17,7 +17,7 @@ public partial class OrderService
private sealed record PriceCheckCargoTarget(string Code, string DisplayName, string CargoAttribute);
public async Task<OrderPriceCheckShippingOptionsOutput> BuildPriceCheckShippingOptionsAsync()
private async Task<OrderPriceCheckShippingOptionsOutput> BuildPriceCheckShippingOptionsAsync()
{
var products = await SalesProductRepository.GetListAsync(x => x.IsActive == EnableStatus.Enabled);
var sortedProducts = products