Files
bd-server/app/main/api/desc/admin/admin_agent.api

407 lines
18 KiB
Plaintext
Raw Normal View History

2026-05-08 11:30:05 +08:00
syntax = "v1"
info (
title: "后台代理管理服务"
desc: "后台代理相关接口"
author: "team"
version: "v1"
)
// 代理管理接口
@server (
prefix: /api/v1/admin/agent
group: admin_agent
middleware: AdminAuthInterceptor
)
service main {
// 代理分页查询
@handler AdminGetAgentList
get /list (AdminGetAgentListReq) returns (AdminGetAgentListResp)
// 代理编辑
@handler AdminUpdateAgent
post /update (AdminUpdateAgentReq) returns (AdminUpdateAgentResp)
// 代理推广链接分页查询
@handler AdminGetAgentLinkList
get /agent-link/list (AdminGetAgentLinkListReq) returns (AdminGetAgentLinkListResp)
// 代理佣金分页查询
@handler AdminGetAgentCommissionList
get /agent-commission/list (AdminGetAgentCommissionListReq) returns (AdminGetAgentCommissionListResp)
// 代理佣金状态更新
@handler AdminUpdateAgentCommissionStatus
post /agent-commission/update-status (AdminUpdateAgentCommissionStatusReq) returns (AdminUpdateAgentCommissionStatusResp)
// 批量解冻代理佣金
@handler AdminBatchUnfreezeAgentCommission
post /agent-commission/batch-unfreeze (AdminBatchUnfreezeAgentCommissionReq) returns (AdminBatchUnfreezeAgentCommissionResp)
// 代理提现分页查询
@handler AdminGetAgentWithdrawalList
get /agent-withdrawal/list (AdminGetAgentWithdrawalListReq) returns (AdminGetAgentWithdrawalListResp)
// 获取代理钱包信息
@handler AdminGetAgentWallet
get /wallet/:agent_id (AdminGetAgentWalletReq) returns (AdminGetAgentWalletResp)
// 修改代理钱包余额
@handler AdminUpdateAgentWalletBalance
post /wallet/update-balance (AdminUpdateAgentWalletBalanceReq) returns (AdminUpdateAgentWalletBalanceResp)
// 平台抽佣分页查询
@handler AdminGetAgentPlatformDeductionList
get /agent-platform-deduction/list (AdminGetAgentPlatformDeductionListReq) returns (AdminGetAgentPlatformDeductionListResp)
// 代理产品配置分页查询
@handler AdminGetAgentProductionConfigList
get /agent-production-config/list (AdminGetAgentProductionConfigListReq) returns (AdminGetAgentProductionConfigListResp)
// 代理产品配置编辑
@handler AdminUpdateAgentProductionConfig
post /agent-production-config/update (AdminUpdateAgentProductionConfigReq) returns (AdminUpdateAgentProductionConfigResp)
// 银行卡提现审核(确认/拒绝)
@handler AdminReviewBankCardWithdrawal
post /agent-withdrawal/bank-card/review (AdminReviewBankCardWithdrawalReq) returns (AdminReviewBankCardWithdrawalResp)
// 获取提现统计数据
@handler AdminGetWithdrawalStatistics
get /agent-withdrawal/statistics (AdminGetWithdrawalStatisticsReq) returns (AdminGetWithdrawalStatisticsResp)
// 获取代理订单统计数据
@handler AdminGetAgentOrderStatistics
get /agent-order/statistics (AdminGetAgentOrderStatisticsReq) returns (AdminGetAgentOrderStatisticsResp)
// 获取代理统计数据
@handler AdminGetAgentStatistics
get /statistics (AdminGetAgentStatisticsReq) returns (AdminGetAgentStatisticsResp)
// 获取代理链接产品统计
@handler AdminGetAgentLinkProductStatistics
get /agent-link/product-statistics (AdminGetAgentLinkProductStatisticsReq) returns (AdminGetAgentLinkProductStatisticsResp)
// 获取系统配置
@handler AdminGetSystemConfig
get /system-config (AdminGetSystemConfigResp)
// 更新系统配置
@handler AdminUpdateSystemConfig
post /system-config (AdminUpdateSystemConfigReq) returns (AdminUpdateSystemConfigResp)
// 代理钱包流水分页查询
@handler AdminGetAgentWalletTransactionList
get /wallet-transaction/list (AdminGetAgentWalletTransactionListReq) returns (AdminGetAgentWalletTransactionListResp)
}
type (
// 代理分页查询请求
AdminGetAgentListReq {
Page int64 `form:"page"` // 页码
PageSize int64 `form:"pageSize"` // 每页数量
Mobile *string `form:"mobile,optional"` // 手机号(可选)
Region *string `form:"region,optional"` // 区域(可选)
CreateTimeStart *string `form:"create_time_start,optional"` // 成为代理时间开始(可选)
CreateTimeEnd *string `form:"create_time_end,optional"` // 成为代理时间结束(可选)
ParentAgentId *int64 `form:"parent_agent_id,optional"` // 上级代理ID可选
}
// 代理列表项
AgentListItem {
Id int64 `json:"id"` // 主键
UserId int64 `json:"user_id"` // 用户ID
ParentAgentId int64 `json:"parent_agent_id"` // 上级代理ID
LevelName string `json:"level_name"` // 等级名称
Region string `json:"region"` // 区域
Mobile string `json:"mobile"` // 手机号
MembershipExpiryTime string `json:"membership_expiry_time"` // 会员到期时间
Balance float64 `json:"balance"` // 钱包余额
TotalEarnings float64 `json:"total_earnings"` // 累计收益
FrozenBalance float64 `json:"frozen_balance"` // 冻结余额
WithdrawnAmount float64 `json:"withdrawn_amount"` // 提现总额
CreateTime string `json:"create_time"` // 创建时间
IsRealNameVerified bool `json:"is_real_name_verified"` // 是否已实名认证
RealName string `json:"real_name"` // 实名姓名
IdCard string `json:"id_card"` // 身份证号
RealNameStatus string `json:"real_name_status"` // 实名状态pending/approved/rejected
}
// 代理分页查询响应
AdminGetAgentListResp {
Total int64 `json:"total"` // 总数
Items []AgentListItem `json:"items"` // 列表数据
}
// 代理编辑请求
AdminUpdateAgentReq {
Id int64 `json:"id"` // 主键
Mobile string `json:"mobile"` // 手机号
LevelName string `json:"level_name"` // 等级名称
Region string `json:"region"` // 区域
MembershipExpiryTime string `json:"membership_expiry_time"` // 会员到期时间YYYY-MM-DD HH:mm:ss
}
// 代理编辑响应
AdminUpdateAgentResp {
Success bool `json:"success"` // 是否成功
}
// 代理推广链接分页查询请求
AdminGetAgentLinkListReq {
Page int64 `form:"page"` // 页码
PageSize int64 `form:"pageSize"` // 每页数量
AgentId *int64 `form:"agent_id,optional"` // 代理ID可选
ProductName *string `form:"product_name,optional"` // 产品名(可选)
LinkIdentifier *string `form:"link_identifier,optional"` // 推广码(可选)
}
// 代理推广链接列表项
AgentLinkListItem {
AgentId int64 `json:"agent_id"` // 代理ID
ProductName string `json:"product_name"` // 产品名
Price float64 `json:"price"` // 价格
LinkIdentifier string `json:"link_identifier"` // 推广码
CreateTime string `json:"create_time"` // 创建时间
}
// 代理推广链接分页查询响应
AdminGetAgentLinkListResp {
Total int64 `json:"total"` // 总数
Items []AgentLinkListItem `json:"items"` // 列表数据
}
// 代理佣金分页查询请求
AdminGetAgentCommissionListReq {
Page int64 `form:"page"` // 页码
PageSize int64 `form:"pageSize"` // 每页数量
AgentId *int64 `form:"agent_id,optional"` // 代理ID可选
OrderId *int64 `form:"order_id,optional"` // 订单ID可选
ProductName *string `form:"product_name,optional"` // 产品名(可选)
Status *int64 `form:"status,optional"` // 状态(可选)
CreateTimeStart *string `form:"create_time_start,optional"` // 创建时间开始(可选)
CreateTimeEnd *string `form:"create_time_end,optional"` // 创建时间结束(可选)
}
// 代理佣金列表项
AgentCommissionListItem {
Id int64 `json:"id"` // 主键
AgentId int64 `json:"agent_id"` // 代理ID
OrderId int64 `json:"order_id"` // 订单ID
Amount float64 `json:"amount"` // 金额
ProductName string `json:"product_name"` // 产品名
Status int64 `json:"status"` // 状态
CreateTime string `json:"create_time"` // 创建时间
}
// 代理佣金分页查询响应
AdminGetAgentCommissionListResp {
Total int64 `json:"total"` // 总数
Items []AgentCommissionListItem `json:"items"` // 列表数据
}
// 代理佣金状态更新请求
AdminUpdateAgentCommissionStatusReq {
Id int64 `json:"id"` // 佣金记录ID
Status int64 `json:"status"` // 状态:0-已结算,1-冻结中,2-已取消
}
// 代理佣金状态更新响应
AdminUpdateAgentCommissionStatusResp {
Success bool `json:"success"` // 是否成功
}
// 批量解冻代理佣金请求
AdminBatchUnfreezeAgentCommissionReq {
AgentId *int64 `json:"agent_id,optional"` // 代理ID可选。如果不传则解冻所有冻结中的佣金
}
// 批量解冻代理佣金响应
AdminBatchUnfreezeAgentCommissionResp {
Success bool `json:"success"` // 是否成功
Count int64 `json:"count"` // 解冻的数量
Amount float64 `json:"amount"` // 解冻的总金额
}
// 代理提现分页查询请求
AdminGetAgentWithdrawalListReq {
Page int64 `form:"page"` // 页码
PageSize int64 `form:"pageSize"` // 每页数量
AgentId *int64 `form:"agent_id,optional"` // 代理ID可选
Status *int64 `form:"status,optional"` // 状态(可选)
WithdrawNo *string `form:"withdraw_no,optional"` // 提现单号(可选)
WithdrawType *int64 `form:"withdraw_type,optional"` // 提现类型可选1-支付宝,2-银行卡
}
// 代理提现列表项
AgentWithdrawalListItem {
Id int64 `json:"id"` // 主键
AgentId int64 `json:"agent_id"` // 代理ID
WithdrawNo string `json:"withdraw_no"` // 提现单号
Amount float64 `json:"amount"` // 金额
ActualAmount float64 `json:"actual_amount"` // 实际到账金额(扣税后)
TaxAmount float64 `json:"tax_amount"` // 扣税金额
Status int64 `json:"status"` // 状态
PayeeAccount string `json:"payee_account"` // 收款账户
Remark string `json:"remark"` // 备注
CreateTime string `json:"create_time"` // 创建时间
WithdrawType int64 `json:"withdraw_type"` // 提现类型:1-支付宝,2-银行卡
BankCardNo string `json:"bank_card_no"` // 银行卡号
BankName string `json:"bank_name"` // 开户支行
PayeeName string `json:"payee_name"` // 收款人姓名
}
// 代理提现分页查询响应
AdminGetAgentWithdrawalListResp {
Total int64 `json:"total"` // 总数
Items []AgentWithdrawalListItem `json:"items"` // 列表数据
}
// 平台抽佣分页查询请求
AdminGetAgentPlatformDeductionListReq {
Page int64 `form:"page"` // 页码
PageSize int64 `form:"pageSize"` // 每页数量
AgentId *int64 `form:"agent_id,optional"` // 代理ID可选
Type *string `form:"type,optional"` // 类型cost/pricing可选
Status *int64 `form:"status,optional"` // 状态(可选)
}
// 平台抽佣列表项
AgentPlatformDeductionListItem {
Id int64 `json:"id"` // 主键
AgentId int64 `json:"agent_id"` // 代理ID
Amount float64 `json:"amount"` // 金额
Type string `json:"type"` // 类型cost/pricing
Status int64 `json:"status"` // 状态
CreateTime string `json:"create_time"` // 创建时间
}
// 平台抽佣分页查询响应
AdminGetAgentPlatformDeductionListResp {
Total int64 `json:"total"` // 总数
Items []AgentPlatformDeductionListItem `json:"items"` // 列表数据
}
// 代理产品配置分页查询请求
AdminGetAgentProductionConfigListReq {
Page int64 `form:"page"` // 页码
PageSize int64 `form:"pageSize"` // 每页数量
ProductName *string `form:"product_name,optional"` // 产品名(可选)
Id *int64 `form:"id,optional"` // 配置ID可选
}
// 代理产品配置分页查询响应
AdminGetAgentProductionConfigListResp {
Total int64 `json:"total"` // 总数
Items []AgentProductionConfigItem `json:"items"` // 列表数据
}
// 代理产品配置列表项
AgentProductionConfigItem {
Id int64 `json:"id"` // 主键
ProductName string `json:"product_name"` // 产品名
CostPrice float64 `json:"cost_price"` // 成本
PriceRangeMin float64 `json:"price_range_min"` // 最低定价
PriceRangeMax float64 `json:"price_range_max"` // 最高定价
PricingStandard float64 `json:"pricing_standard"` // 定价标准
OverpricingRatio float64 `json:"overpricing_ratio"` // 超价比例
CreateTime string `json:"create_time"` // 创建时间
}
// 代理产品配置编辑请求
AdminUpdateAgentProductionConfigReq {
Id int64 `json:"id"` // 主键
CostPrice float64 `json:"cost_price"` // 成本
PriceRangeMin float64 `json:"price_range_min"` // 最低定价
PriceRangeMax float64 `json:"price_range_max"` // 最高定价
PricingStandard float64 `json:"pricing_standard"` // 定价标准
OverpricingRatio float64 `json:"overpricing_ratio"` // 超价比例
}
// 代理产品配置编辑响应
AdminUpdateAgentProductionConfigResp {
Success bool `json:"success"` // 是否成功
}
// 银行卡提现审核请求
AdminReviewBankCardWithdrawalReq {
WithdrawalId int64 `json:"withdrawal_id"` // 提现记录ID
Action int64 `json:"action"` // 操作:1-确认,2-拒绝
Remark string `json:"remark"` // 备注(拒绝时必填)
}
// 银行卡提现审核响应
AdminReviewBankCardWithdrawalResp {
Success bool `json:"success"` // 是否成功
}
// 获取提现统计数据请求
AdminGetWithdrawalStatisticsReq {}
// 获取提现统计数据响应
AdminGetWithdrawalStatisticsResp {
TotalWithdrawalAmount float64 `json:"total_withdrawal_amount"` // 总提现金额
TodayWithdrawalAmount float64 `json:"today_withdrawal_amount"` // 今日提现金额
TotalActualAmount float64 `json:"total_actual_amount"` // 总实际到账金额
TotalTaxAmount float64 `json:"total_tax_amount"` // 总扣税金额
}
// 获取代理订单统计数据请求
AdminGetAgentOrderStatisticsReq {}
// 获取代理订单统计数据响应
AdminGetAgentOrderStatisticsResp {
TotalAgentOrderCount int64 `json:"total_agent_order_count"` // 总代理订单数
TodayAgentOrderCount int64 `json:"today_agent_order_count"` // 今日代理订单数
}
// 获取代理统计数据请求
AdminGetAgentStatisticsReq {}
// 获取代理统计数据响应
AdminGetAgentStatisticsResp {
TotalAgentCount int64 `json:"total_agent_count"` // 总代理数
TodayAgentCount int64 `json:"today_agent_count"` // 今日新增代理数
}
// 获取代理链接产品统计请求
AdminGetAgentLinkProductStatisticsReq {}
// 代理链接产品统计列表项
AgentLinkProductStatisticsItem {
ProductName string `json:"product_name"` // 产品名称
LinkCount int64 `json:"link_count"` // 推广链接数量
}
// 获取代理链接产品统计响应
AdminGetAgentLinkProductStatisticsResp {
Items []AgentLinkProductStatisticsItem `json:"items"` // 列表数据
}
// 获取代理钱包信息请求
AdminGetAgentWalletReq {
AgentId int64 `path:"agent_id"` // 代理ID
}
// 获取代理钱包信息响应
AdminGetAgentWalletResp {
Balance float64 `json:"balance"` // 可用余额
FrozenBalance float64 `json:"frozen_balance"` // 冻结余额
TotalEarnings float64 `json:"total_earnings"` // 总收益
}
// 修改代理钱包余额请求
AdminUpdateAgentWalletBalanceReq {
AgentId int64 `json:"agent_id"` // 代理ID
Amount float64 `json:"amount"` // 修改金额(正数增加,负数减少)
}
// 修改代理钱包余额响应
AdminUpdateAgentWalletBalanceResp {
Success bool `json:"success"` // 是否成功
Balance float64 `json:"balance"` // 修改后的余额
}
// 更新系统配置请求
AdminUpdateSystemConfigReq {
CommissionSafeMode *bool `json:"commission_safe_mode,optional"` // 佣金安全防御模式true-冻结模式false-直接结算模式
}
// 更新系统配置响应
AdminUpdateSystemConfigResp {
Success bool `json:"success"` // 是否成功
}
// 获取系统配置响应
AdminGetSystemConfigResp {
CommissionSafeMode bool `json:"commission_safe_mode"` // 佣金安全防御模式
}
// 代理钱包流水分页查询请求
AdminGetAgentWalletTransactionListReq {
Page int64 `form:"page"` // 页码
PageSize int64 `form:"pageSize"` // 每页数量
AgentId int64 `form:"agent_id"` // 代理ID
TransactionType *string `form:"transaction_type,optional"` // 交易类型(可选)
CreateTimeStart *string `form:"create_time_start,optional"` // 创建时间开始(可选)
CreateTimeEnd *string `form:"create_time_end,optional"` // 创建时间结束(可选)
}
// 代理钱包流水列表项
AgentWalletTransactionListItem {
Id int64 `json:"id"` // 主键
AgentId int64 `json:"agent_id"` // 代理ID
TransactionType string `json:"transaction_type"` // 交易类型
Amount float64 `json:"amount"` // 变动金额
BalanceBefore float64 `json:"balance_before"` // 变动前余额
BalanceAfter float64 `json:"balance_after"` // 变动后余额
FrozenBalanceBefore float64 `json:"frozen_balance_before"` // 变动前冻结余额
FrozenBalanceAfter float64 `json:"frozen_balance_after"` // 变动后冻结余额
TransactionId *string `json:"transaction_id"` // 关联交易ID
RelatedUserId *int64 `json:"related_user_id"` // 关联用户ID
Remark *string `json:"remark"` // 备注说明
CreateTime string `json:"create_time"` // 创建时间
}
// 代理钱包流水分页查询响应
AdminGetAgentWalletTransactionListResp {
Total int64 `json:"total"` // 总数
Items []AgentWalletTransactionListItem `json:"items"` // 列表数据
}
)