jnc-server/app/main/api/desc/admin/admin_agent.api

syntax = "v1"

info (
	title:   "后台代理管理服务（简化版）"
	desc:    "新代理系统后台管理接口 - 系统简化后移除团队、返佣、升级、提现、实名、邀请码功能"
	author:  "team"
	version: "v1"
)

// ============================================
// 代理管理接口（简化版）
// ============================================
@server (
	prefix:     /api/v1/admin/agent
	group:      admin_agent
	middleware: AdminAuthInterceptor
)
service main {
	// 代理分页查询（简化：移除level, team_leader_id筛选）
	@handler AdminGetAgentList
	get /list (AdminGetAgentListReq) returns (AdminGetAgentListResp)

	// 代理审核
	@handler AdminAuditAgent
	post /audit (AdminAuditAgentReq) returns (AdminAuditAgentResp)

	// 代理推广链接分页查询
	@handler AdminGetAgentLinkList
	get /link/list (AdminGetAgentLinkListReq) returns (AdminGetAgentLinkListResp)

	// 代理订单分页查询
	@handler AdminGetAgentOrderList
	get /order/list (AdminGetAgentOrderListReq) returns (AdminGetAgentOrderListResp)

	// 代理佣金分页查询
	@handler AdminGetAgentCommissionList
	get /commission/list (AdminGetAgentCommissionListReq) returns (AdminGetAgentCommissionListResp)

	// 代理订单列表（整合订单、佣金、代理信息）
	@handler AdminGetAgentOrdersList
	get /orders/list (AdminGetAgentOrdersListReq) returns (AdminGetAgentOrdersListResp)

	// 代理订单退款
	@handler AdminRefundAgentOrder
	post /orders/refund (AdminRefundAgentOrderReq) returns (AdminRefundAgentOrderResp)

	// 系统配置查询（简化：移除等级、升级、返佣配置）
	@handler AdminGetAgentConfig
	get /config returns (AdminGetAgentConfigResp)

	// 系统配置更新（简化：移除等级、升级、返佣配置）
	@handler AdminUpdateAgentConfig
	post /config/update (AdminUpdateAgentConfigReq) returns (AdminUpdateAgentConfigResp)

	// 产品配置分页查询
	@handler AdminGetAgentProductConfigList
	get /product_config/list (AdminGetAgentProductConfigListReq) returns (AdminGetAgentProductConfigListResp)

	// 产品配置更新
	@handler AdminUpdateAgentProductConfig
	post /product_config/update (AdminUpdateAgentProductConfigReq) returns (AdminUpdateAgentProductConfigResp)

	// 代理提现记录分页查询
	@handler AdminGetAgentWithdrawList
	get /withdraw/list (AdminGetAgentWithdrawListReq) returns (AdminGetAgentWithdrawListResp)

	// 代理提现审核
	@handler AdminAuditAgentWithdraw
	post /withdraw/audit (AdminAuditAgentWithdrawReq) returns (AdminAuditAgentWithdrawResp)

	// 发送代理投诉通知短信
	@handler AdminSendAgentComplaintNotify
	post /complaint/notify (AdminSendAgentComplaintNotifyReq) returns (AdminSendAgentComplaintNotifyResp)

	// 获取统计概览数据
	@handler AdminGetStatisticsOverview
	get /statistics/overview returns (AdminGetStatisticsOverviewResp)

	// 获取订单趋势数据
	@handler AdminGetOrderTrends
	get /statistics/order/trends (AdminGetOrderTrendsReq) returns (AdminGetOrderTrendsResp)

	// 获取代理注册趋势
	@handler AdminGetAgentTrends
	get /statistics/agent/trends (AdminGetAgentTrendsReq) returns (AdminGetAgentTrendsResp)

	// 获取产品订单分布
	@handler AdminGetProductDistribution
	get /statistics/product/distribution returns (AdminGetProductDistributionResp)

	// 获取区域代理分布
	@handler AdminGetRegionDistribution
	get /statistics/region/distribution returns (AdminGetRegionDistributionResp)

	// 获取代理排行榜
	@handler AdminGetAgentRanking
	get /statistics/agent/ranking (AdminGetAgentRankingReq) returns (AdminGetAgentRankingResp)
}

type (
	// 代理分页查询（简化）
	AdminGetAgentListReq {
		Page     int64   `form:"page"` // 页码
		PageSize int64   `form:"pageSize"` // 每页数量
		Mobile   *string `form:"mobile,optional"` // 手机号（可选）
		Region   *string `form:"region,optional"` // 区域（可选）
	}
	AgentListItem {
		Id            string  `json:"id"` // 主键
		UserId        string  `json:"user_id"` // 用户ID
		Region        string  `json:"region"` // 区域
		Mobile        string  `json:"mobile"` // 手机号
		WechatId      string  `json:"wechat_id"` // 微信号
		AgentCode     int64   `json:"agent_code"` // 代理编码
		Balance       float64 `json:"balance"` // 钱包余额
		FrozenAmount  float64 `json:"frozen_amount"` // 冻结余额
		TotalEarnings float64 `json:"total_earnings"` // 累计收益
		CreateTime    string  `json:"create_time"` // 创建时间
	}
	AdminGetAgentListResp {
		Total int64           `json:"total"` // 总数
		Items []AgentListItem `json:"items"` // 列表数据
	}
	// 代理审核
	AdminAuditAgentReq {
		AuditId     int64  `json:"audit_id"` // 审核记录ID
		Status      int64  `json:"status"` // 审核状态：1=通过，2=拒绝
		AuditReason string `json:"audit_reason"` // 审核原因（拒绝时必填）
	}
	AdminAuditAgentResp {
		Success bool `json:"success"`
	}
	// 推广链接分页查询
	AdminGetAgentLinkListReq {
		Page           int64   `form:"page"` // 页码
		PageSize       int64   `form:"pageSize"` // 每页数量
		AgentId        *string `form:"agent_id,optional"` // 代理ID（可选）
		ProductId      *string `form:"product_id,optional"` // 产品ID（可选）
		LinkIdentifier *string `form:"link_identifier,optional"` // 推广码（可选）
	}
	AgentLinkListItem {
		Id          string  `json:"id"` // 主键
		AgentId     string  `json:"agent_id"` // 代理ID
		ProductId   string  `json:"product_id"` // 产品ID
		ProductName string  `json:"product_name"` // 产品名称
		SetPrice    float64 `json:"set_price"` // 设定价格
		ShortLink   string  `json:"short_link"` // 短链链接
		CreateTime  string  `json:"create_time"` // 创建时间
	}
	AdminGetAgentLinkListResp {
		Total int64               `json:"total"` // 总数
		Items []AgentLinkListItem `json:"items"` // 列表数据
	}
	// 代理订单分页查询
	AdminGetAgentOrderListReq {
		Page          int64   `form:"page"` // 页码
		PageSize      int64   `form:"pageSize"` // 每页数量
		AgentId       *string `form:"agent_id,optional"` // 代理ID（可选）
		OrderId       *string `form:"order_id,optional"` // 订单ID（可选）
		ProcessStatus *int64  `form:"process_status,optional"` // 处理状态（可选）
	}
	AgentOrderListItem {
		Id              string  `json:"id"` // 主键
		AgentId         string  `json:"agent_id"` // 代理ID
		OrderId         string  `json:"order_id"` // 订单ID
		ProductId       string  `json:"product_id"` // 产品ID
		ProductName     string  `json:"product_name"` // 产品名称
		OrderAmount     float64 `json:"order_amount"` // 订单金额
		SetPrice        float64 `json:"set_price"` // 设定价格
		ActualBasePrice float64 `json:"actual_base_price"` // 实际底价
		PriceCost       float64 `json:"price_cost"` // 提价成本
		AgentProfit     float64 `json:"agent_profit"` // 代理收益
		ProcessStatus   int64   `json:"process_status"` // 处理状态
		CreateTime      string  `json:"create_time"` // 创建时间
	}
	AdminGetAgentOrderListResp {
		Total int64                `json:"total"` // 总数
		Items []AgentOrderListItem `json:"items"` // 列表数据
	}
	// 代理佣金分页查询
	AdminGetAgentCommissionListReq {
		Page     int64   `form:"page"` // 页码
		PageSize int64   `form:"pageSize"` // 每页数量
		AgentId  *string `form:"agent_id,optional"` // 代理ID（可选）
		OrderId  *string `form:"order_id,optional"` // 订单ID（可选）
		Status   *int64  `form:"status,optional"` // 状态（可选）
	}
	AgentCommissionListItem {
		Id          string  `json:"id"` // 主键
		AgentId     string  `json:"agent_id"` // 代理ID
		OrderId     string  `json:"order_id"` // 订单ID
		ProductName string  `json:"product_name"` // 产品名称
		Amount      float64 `json:"amount"` // 金额
		Status      int64   `json:"status"` // 状态
		CreateTime  string  `json:"create_time"` // 创建时间
	}
	AdminGetAgentCommissionListResp {
		Total int64                     `json:"total"` // 总数
		Items []AgentCommissionListItem `json:"items"` // 列表数据
	}
	// 代理订单列表（整合订单、佣金、代理信息）
	AdminGetAgentOrdersListReq {
		Page     int64 `form:"page"` // 页码
		PageSize int64 `form:"pageSize"` // 每页数量
		// 代理筛选
		AgentId     *string `form:"agent_id,optional"` // 代理ID（可选）
		AgentMobile *string `form:"agent_mobile,optional"` // 代理手机号（可选）
		// 用户筛选
		UserMobile *string `form:"user_mobile,optional"` // 用户手机号（可选）
		// 订单筛选
		OrderNo         *string `form:"order_no,optional"` // 商户订单号（可选）
		PlatformOrderId *string `form:"platform_order_id,optional"` // 支付订单号（可选）
		ProductName     *string `form:"product_name,optional"` // 产品名称（可选）
		// 支付筛选
		PaymentPlatform *string `form:"payment_platform,optional"` // 支付方式（可选）
		PaymentScene    *string `form:"payment_scene,optional"` // 支付平台（可选）
		// 状态筛选
		OrderStatus      *string `form:"order_status,optional"` // 订单状态（可选）
		CommissionStatus *int64  `form:"commission_status,optional"` // 佣金状态（可选）
		// 时间筛选
		CreateTimeStart *string `form:"create_time_start,optional"` // 创建时间开始（可选）
		CreateTimeEnd   *string `form:"create_time_end,optional"` // 创建时间结束（可选）
		PayTimeStart    *string `form:"pay_time_start,optional"` // 支付时间开始（可选）
		PayTimeEnd      *string `form:"pay_time_end,optional"` // 支付时间结束（可选）
		// 排序
		OrderBy   *string `form:"order_by,optional"` // 排序字段（可选）
		OrderType *string `form:"order_type,optional"` // 排序方式（可选）
	}
	AgentOrdersListItem {
		Id              string `json:"id"` // 主键
		OrderNo         string `json:"order_no"` // 商户订单号
		PlatformOrderId string `json:"platform_order_id"` // 支付订单号
		// 代理信息
		AgentId     string `json:"agent_id"` // 代理ID
		AgentMobile string `json:"agent_mobile"` // 代理手机号
		// 用户信息
		UserId     string  `json:"user_id"` // 用户ID
		UserMobile *string `json:"user_mobile"` // 用户手机号
		// 产品信息
		ProductId   string `json:"product_id"` // 产品ID
		ProductName string `json:"product_name"` // 产品名称
		// 金额信息
		OrderAmount      float64 `json:"order_amount"` // 订单金额
		CommissionAmount float64 `json:"commission_amount"` // 佣金金额
		// 支付信息
		PaymentPlatform string `json:"payment_platform"` // 支付方式
		PaymentScene    string `json:"payment_scene"` // 支付平台
		// 状态
		OrderStatus      string `json:"order_status"` // 订单状态
		CommissionStatus int64  `json:"commission_status"` // 佣金状态
		// 时间
		CreateTime string  `json:"create_time"` // 创建时间
		PayTime    *string `json:"pay_time"` // 支付时间
		QueryId   *string `json:"query_id"` // 查询记录ID（用于报告结果跳转）
	}
	AdminGetAgentOrdersListResp {
		Total int64                 `json:"total"` // 总数
		Items []AgentOrdersListItem `json:"items"` // 列表数据
	}
	// 代理订单退款
	AdminRefundAgentOrderReq {
		OrderId      string   `json:"order_id"` // 订单ID
		RefundAmount float64 `json:"refund_amount"` // 退款金额
		RefundReason string  `json:"refund_reason"` // 退款原因
	}
	AdminRefundAgentOrderResp {
		Success  bool    `json:"success"` // 是否成功
		Message  string  `json:"message"` // 消息
		RefundNo *string `json:"refund_no"` // 退款单号
	}
	// 系统配置查询（简化：只保留佣金冻结配置）
	AdminGetAgentConfigResp {
		CommissionFreeze CommissionFreezeConfig `json:"commission_freeze"` // 佣金冻结配置
		TaxRate          float64                `json:"tax_rate"` // 税率
	}
	CommissionFreezeConfig {
		Ratio     float64 `json:"ratio"` // 佣金冻结比例（例如：0.1表示10%）
		Threshold float64 `json:"threshold"` // 佣金冻结阈值（订单单价达到此金额才触发冻结，单位：元）
		Days      int64   `json:"days"` // 佣金冻结解冻天数（单位：天，例如：30表示30天后解冻）
	}
	// 系统配置更新（简化）
	AdminUpdateAgentConfigReq {
		CommissionFreeze *CommissionFreezeConfig `json:"commission_freeze,optional"` // 佣金冻结配置
		TaxRate          *float64                `json:"tax_rate,optional"` // 税率
	}
	AdminUpdateAgentConfigResp {
		Success bool `json:"success"`
	}
	// 产品配置分页查询
	AdminGetAgentProductConfigListReq {
		Page        int64   `form:"page"` // 页码
		PageSize    int64   `form:"pageSize"` // 每页数量
		ProductId   *string `form:"product_id,optional"` // 产品ID（可选）
		ProductName *string `form:"product_name,optional"` // 产品名称（可选，用于搜索）
	}
	AgentProductConfigItem {
		Id             string  `json:"id"` // 主键
		ProductId      string  `json:"product_id"` // 产品ID
		ProductName    string  `json:"product_name"` // 产品名称
		BasePrice      float64 `json:"base_price"` // 基础底价
		PriceRangeMin  float64 `json:"price_range_min"` // 最低定价
		PriceRangeMax  float64 `json:"price_range_max"` // 最高定价
		PriceThreshold float64 `json:"price_threshold"` // 提价标准阈值
		PriceFeeRate   float64 `json:"price_fee_rate"` // 提价手续费比例
		CreateTime     string  `json:"create_time"` // 创建时间
	}
	AdminGetAgentProductConfigListResp {
		Total int64                    `json:"total"` // 总数
		Items []AgentProductConfigItem `json:"items"` // 列表数据
	}
	// 产品配置更新
	AdminUpdateAgentProductConfigReq {
		Id             string   `json:"id"` // 主键
		BasePrice      float64  `json:"base_price"` // 基础底价
		PriceRangeMax  float64  `json:"price_range_max"` // 最高定价
		PriceThreshold *float64 `json:"price_threshold,optional"` // 提价标准阈值（可选）
		PriceFeeRate   *float64 `json:"price_fee_rate,optional"` // 提价手续费比例（可选）
	}
	AdminUpdateAgentProductConfigResp {
		Success bool `json:"success"`
	}
	// ============================================
	// 代理提现相关
	// ============================================
	// 代理提现记录分页查询
	AdminGetAgentWithdrawListReq {
		Page     int64   `form:"page"` // 页码
		PageSize int64   `form:"pageSize"` // 每页数量
		AgentId  *string `form:"agent_id,optional"` // 代理ID（可选）
		Status   *int64  `form:"status,optional"` // 状态（可选）：0=待审核，1=已通过，2=已拒绝
	}
	AgentWithdrawListItem {
		Id                 string  `json:"id"` // 主键
		AgentId            string  `json:"agent_id"` // 代理ID
		AgentMobile        string  `json:"agent_mobile"` // 代理手机号
		AgentCode          int64   `json:"agent_code"` // 代理编码
		WithdrawAmount     float64 `json:"withdraw_amount"` // 提现金额
		TaxAmount          float64 `json:"tax_amount"` // 税费金额
		ActualAmount       float64 `json:"actual_amount"` // 实际到账金额（税后）
		FrozenAmount       float64 `json:"frozen_amount"` // 冻结金额
		AccountName        string  `json:"account_name"` // 收款人姓名
		BankCardNumber     string  `json:"bank_card_number"` // 银行卡号（脱敏）
		BankCardNumberFull string  `json:"bank_card_number_full"` // 银行卡号（完整，用于审核）
		BankBranch         string  `json:"bank_branch"` // 开户支行
		Status             int64   `json:"status"` // 状态：0=待审核，1=已通过，2=已拒绝
		AuditUserId        string  `json:"audit_user_id"` // 审核人ID
		AuditTime          string  `json:"audit_time"` // 审核时间
		AuditRemark        string  `json:"audit_remark"` // 审核备注
		CreateTime         string  `json:"create_time"` // 创建时间
	}
	AdminGetAgentWithdrawListResp {
		Total int64                   `json:"total"` // 总数
		Items []AgentWithdrawListItem `json:"items"` // 列表数据
	}
	// 代理提现审核
	AdminAuditAgentWithdrawReq {
		WithdrawId  string `json:"withdraw_id"` // 提现记录ID
		Status      int64  `json:"status"` // 审核状态：1=通过，2=拒绝
		AuditRemark string `json:"audit_reason,optional"` // 审核原因（拒绝时必填）
	}
	AdminAuditAgentWithdrawResp {
		Success bool   `json:"success"` // 是否成功
		Message string `json:"message"` // 消息
	}
	// 发送代理投诉通知短信请求
	AdminSendAgentComplaintNotifyReq {
		AgentId  string `json:"agent_id"` // 代理ID
		UserName string `json:"user_name"` // 投诉用户姓名
	}
	// 发送代理投诉通知短信响应
	AdminSendAgentComplaintNotifyResp {
		Success bool   `json:"success"` // 是否成功
		Message string `json:"message"` // 消息
	}
	// ============================================
	// 统计分析相关类型
	// ============================================
	// 统计概览响应
	AdminGetStatisticsOverviewResp {
		TotalAgents      int64   `json:"total_agents"` // 代理总数
		TodayNewAgents   int64   `json:"today_new_agents"` // 今日新增代理
		TotalOrders      int64   `json:"total_orders"` // 总订单数
		TodayOrders      int64   `json:"today_orders"` // 今日订单数
		TotalOrderAmount float64 `json:"total_order_amount"` // 总订单金额
		TodayOrderAmount float64 `json:"today_order_amount"` // 今日订单金额
		TotalCommission  float64 `json:"total_commission"` // 总佣金支出
		TodayCommission  float64 `json:"today_commission"` // 今日佣金支出
		PendingWithdraw  float64 `json:"pending_withdraw"` // 待审核提现金额
		MonthOrderAmount float64 `json:"month_order_amount"` // 本月订单金额
		MonthCommission  float64 `json:"month_commission"` // 本月佣金支出
	}
	// 订单趋势请求
	AdminGetOrderTrendsReq {
		StartDate string `form:"start_date,optional"` // 开始日期 YYYY-MM-DD
		EndDate   string `form:"end_date,optional"` // 结束日期 YYYY-MM-DD
	}
	// 订单趋势响应
	AdminGetOrderTrendsResp {
		Dates   []string  `json:"dates"` // 日期列表
		Amounts []float64 `json:"amounts"` // 金额列表
		Counts  []int64   `json:"counts"` // 订单数列表
	}
	// 代理注册趋势请求
	AdminGetAgentTrendsReq {
		StartDate string `form:"start_date,optional"` // 开始日期 YYYY-MM-DD
		EndDate   string `form:"end_date,optional"` // 结束日期 YYYY-MM-DD
	}
	// 代理注册趋势响应
	AdminGetAgentTrendsResp {
		Dates  []string `json:"dates"` // 日期列表
		Counts []int64  `json:"counts"` // 新增代理数列表
	}
	// 产品订单分布响应
	AdminGetProductDistributionResp {
		Products []string  `json:"products"` // 产品名称列表
		Counts   []int64   `json:"counts"` // 订单数量列表
		Amounts  []float64 `json:"amounts"` // 订单金额列表
	}
	// 区域代理分布响应
	AdminGetRegionDistributionResp {
		Regions []string `json:"regions"` // 区域名称列表
		Counts  []int64  `json:"counts"` // 代理数量列表
	}
	// 代理排行榜请求
	AdminGetAgentRankingReq {
		Type  string `form:"type"` // 排行类型: commission=佣金排行, orders=订单量排行
		Limit int64  `form:"limit,optional"` // 返回数量，默认10
	}
	// 代理排行榜响应
	AdminGetAgentRankingResp {
		Items []AgentRankingItem `json:"items"` // 排行榜列表
	}
	// 代理排行榜项
	AgentRankingItem {
		AgentId     string  `json:"agent_id"` // 代理ID
		AgentMobile string  `json:"agent_mobile"` // 代理手机号
		Region      string  `json:"region"` // 区域
		Value       float64 `json:"value"` // 值（佣金或订单数）
	}
)