syntax = "v1" info ( title: "代理服务" desc: "新代理系统接口" version: "v1" ) // ============================================ // 公开接口（无需登录） // ============================================ @server ( prefix: api/v1/agent group: agent ) service main { // 获取推广链接数据 @handler GetLinkData get /link (GetLinkDataReq) returns (GetLinkDataResp) // 通过邀请码申请成为代理（必须提供邀请码） @handler ApplyForAgent post /apply (AgentApplyReq) returns (AgentApplyResp) // 通过邀请码注册（同时注册用户和代理） @handler RegisterByInviteCode post /register/invite (RegisterByInviteCodeReq) returns (RegisterByInviteCodeResp) } type ( GetLinkDataReq { LinkIdentifier string `form:"link_identifier"` // 推广链接标识 } GetLinkDataResp { AgentId string `json:"agent_id"` // 代理ID ProductId string `json:"product_id"` // 产品ID SetPrice float64 `json:"set_price"` // 代理设定价格 ActualBasePrice float64 `json:"actual_base_price"` // 实际底价 ProductName string `json:"product_name"` // 产品名称 ProductEn string `json:"product_en"` // 产品英文标识 SellPrice float64 `json:"sell_price"` // 销售价格（使用代理设定价格） Description string `json:"description"` // 产品描述 Features []Feature `json:"features"` // 产品功能列表 } AgentApplyReq { Region string `json:"region,optional"` Mobile string `json:"mobile"` Code string `json:"code"` Referrer string `json:"referrer"` InviteCode string `json:"invite_code,optional"` AgentCode int64 `json:"agent_code,optional"` } AgentApplyResp { AccessToken string `json:"accessToken"` AccessExpire int64 `json:"accessExpire"` RefreshAfter int64 `json:"refreshAfter"` AgentCode int64 `json:"agent_code"` } // 通过邀请码注册 RegisterByInviteCodeReq { Referrer string `json:"referrer"` InviteCode string `json:"invite_code,optional"` AgentCode int64 `json:"agent_code,optional"` Mobile string `json:"mobile"` Code string `json:"code"` Region string `json:"region,optional"` WechatId string `json:"wechat_id,optional"` } RegisterByInviteCodeResp { AccessToken string `json:"accessToken"` AccessExpire int64 `json:"accessExpire"` RefreshAfter int64 `json:"refreshAfter"` AgentId string `json:"agent_id"` // 代理ID Level int64 `json:"level"` // 代理等级 LevelName string `json:"level_name"` // 等级名称 AgentCode int64 `json:"agent_code"` } // 生成邀请码 GenerateInviteCodeReq { Count int64 `json:"count"` // 生成数量 ExpireDays int64 `json:"expire_days,optional"` // 过期天数（可选，0表示不过期） Remark string `json:"remark,optional"` // 备注（可选） } GenerateInviteCodeResp { Codes []string `json:"codes"` // 生成的邀请码列表 } // 获取邀请码列表 GetInviteCodeListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 Status int64 `form:"status,optional"` // 状态（可选） } GetInviteCodeListResp { Total int64 `json:"total"` // 总数 List []InviteCodeItem `json:"list"` // 列表 } InviteCodeItem { Id string `json:"id"` // 记录ID Code string `json:"code"` // 邀请码 TargetLevel int64 `json:"target_level"` // 目标等级 Status int64 `json:"status"` // 状态：0=未使用，1=已使用，2=已失效 UsedTime string `json:"used_time"` // 使用时间 ExpireTime string `json:"expire_time"` // 过期时间 Remark string `json:"remark"` // 备注 CreateTime string `json:"create_time"` // 创建时间 } // 删除邀请码 DeleteInviteCodeReq { Id string `json:"id"` // 邀请码ID } DeleteInviteCodeResp {} // 获取邀请链接 GetInviteLinkReq { InviteCode string `form:"invite_code"` // 邀请码 TargetPath string `form:"target_path,optional"` // 目标地址（可选，默认为注册页面） } GetInviteLinkResp { InviteLink string `json:"invite_link"` // 邀请链接 } // 获取代理等级特权信息 GetLevelPrivilegeResp { Levels []LevelPrivilegeItem `json:"levels"` UpgradeToGoldFee float64 `json:"upgrade_to_gold_fee"` UpgradeToDiamondFee float64 `json:"upgrade_to_diamond_fee"` UpgradeToGoldRebate float64 `json:"upgrade_to_gold_rebate"` UpgradeToDiamondRebate float64 `json:"upgrade_to_diamond_rebate"` } LevelPrivilegeItem { Level int64 `json:"level"` // 等级：1=普通，2=黄金，3=钻石 LevelName string `json:"level_name"` // 等级名称 LevelBonus float64 `json:"level_bonus"` // 等级加成（元） PriceReduction float64 `json:"price_reduction"` // 底价降低（元，相对于当前等级） PromoteRebate string `json:"promote_rebate"` // 推广返佣说明 MaxPromoteRebate float64 `json:"max_promote_rebate"` // 最高推广返佣金额（元） UpgradeRebate string `json:"upgrade_rebate"` // 下级升级返佣说明 Privileges []string `json:"privileges"` // 特权列表 CanUpgradeSubordinate bool `json:"can_upgrade_subordinate"` // 是否可以升级下级 } ) // ============================================ // 需要登录的接口 // ============================================ @server ( prefix: api/v1/agent group: agent jwt: JwtAuth middleware: UserAuthInterceptor ) service main { // 查看代理信息 @handler GetAgentInfo get /info returns (AgentInfoResp) // 生成推广链接 @handler GeneratingLink post /generating_link (AgentGeneratingLinkReq) returns (AgentGeneratingLinkResp) // 获取产品配置 @handler GetAgentProductConfig get /product_config returns (AgentProductConfigResp) // 获取团队统计 @handler GetTeamStatistics get /team/statistics returns (TeamStatisticsResp) // 获取转化率统计 @handler GetConversionRate get /conversion/rate returns (ConversionRateResp) // 获取下级列表 @handler GetSubordinateList get /subordinate/list (GetSubordinateListReq) returns (GetSubordinateListResp) // 获取下级贡献详情 @handler GetSubordinateContributionDetail get /subordinate/contribution/detail (GetSubordinateContributionDetailReq) returns (GetSubordinateContributionDetailResp) // 获取团队列表 @handler GetTeamList get /team/list (GetTeamListReq) returns (GetTeamListResp) // 获取收益信息 @handler GetRevenueInfo get /revenue returns (GetRevenueInfoResp) // 获取佣金记录 @handler GetCommissionList get /commission/list (GetCommissionListReq) returns (GetCommissionListResp) // 获取返佣记录（推广返佣） @handler GetRebateList get /rebate/list (GetRebateListReq) returns (GetRebateListResp) // 获取升级返佣记录 @handler GetUpgradeRebateList get /rebate/upgrade/list (GetUpgradeRebateListReq) returns (GetUpgradeRebateListResp) // 获取升级记录 @handler GetUpgradeList get /upgrade/list (GetUpgradeListReq) returns (GetUpgradeListResp) // 申请升级 @handler ApplyUpgrade post /upgrade/apply (ApplyUpgradeReq) returns (ApplyUpgradeResp) // 钻石代理升级下级 @handler UpgradeSubordinate post /upgrade/subordinate (UpgradeSubordinateReq) returns (UpgradeSubordinateResp) // 获取提现列表 @handler GetWithdrawalList get /withdrawal/list (GetWithdrawalListReq) returns (GetWithdrawalListResp) // 申请提现 @handler ApplyWithdrawal post /withdrawal/apply (ApplyWithdrawalReq) returns (ApplyWithdrawalResp) // 实名认证 @handler RealNameAuth post /real_name (RealNameAuthReq) returns (RealNameAuthResp) // 生成邀请码 @handler GenerateInviteCode post /invite_code/generate (GenerateInviteCodeReq) returns (GenerateInviteCodeResp) // 获取邀请码列表 @handler GetInviteCodeList get /invite_code/list (GetInviteCodeListReq) returns (GetInviteCodeListResp) // 删除邀请码 @handler DeleteInviteCode post /invite_code/delete (DeleteInviteCodeReq) returns (DeleteInviteCodeResp) // 获取邀请链接（根据邀请码生成） @handler GetInviteLink get /invite_link (GetInviteLinkReq) returns (GetInviteLinkResp) // 获取代理等级特权信息 @handler GetLevelPrivilege get /level/privilege returns (GetLevelPrivilegeResp) // 获取推广查询报告列表 @handler GetPromotionQueryList get /promotion/query/list (GetPromotionQueryListReq) returns (GetPromotionQueryListResp) } type ( // 代理信息 AgentInfoResp { AgentId string `json:"agent_id"` Level int64 `json:"level"` LevelName string `json:"level_name"` Region string `json:"region"` Mobile string `json:"mobile"` WechatId string `json:"wechat_id"` TeamLeaderId string `json:"team_leader_id"` IsRealName bool `json:"is_real_name"` AgentCode int64 `json:"agent_code"` } // 生成推广链接 AgentGeneratingLinkReq { ProductId string `json:"product_id"` // 产品ID SetPrice float64 `json:"set_price"` // 设定价格 TargetPath string `json:"target_path,optional"` // 目标地址（可选，默认为推广报告页面） } AgentGeneratingLinkResp { LinkIdentifier string `json:"link_identifier"` // 推广链接标识 FullLink string `json:"full_link"` // 完整短链URL } // 产品配置 AgentProductConfigResp { List []ProductConfigItem `json:"list"` } ProductConfigItem { ProductId string `json:"product_id"` // 产品ID ProductName string `json:"product_name"` // 产品名称 ProductEn string `json:"product_en"` // 产品英文标识 ActualBasePrice float64 `json:"actual_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"` // 提价手续费比例 } // 团队统计 TeamStatisticsResp { TotalCount int64 `json:"total_count"` // 团队总人数（不包括自己） DirectCount int64 `json:"direct_count"` // 直接下级数量 IndirectCount int64 `json:"indirect_count"` // 间接下级数量 GoldCount int64 `json:"gold_count"` // 黄金代理数量 NormalCount int64 `json:"normal_count"` // 普通代理数量 TodayNewMembers int64 `json:"today_new_members"` // 今日新增成员 MonthNewMembers int64 `json:"month_new_members"` // 本月新增成员 } // 转化率统计 ConversionRateResp { MyConversionRate ConversionRateData `json:"my_conversion_rate"` // 我的转化率 SubordinateConversionRate ConversionRateData `json:"subordinate_conversion_rate"` // 我的下级转化率 } ConversionRateData { Daily []PeriodConversionData `json:"daily"` // 日统计（今日、昨日、前日） Weekly []PeriodConversionData `json:"weekly"` // 周统计（这周、前一周、前两周） Monthly []PeriodConversionData `json:"monthly"` // 月统计（本月、上月、前两月） } PeriodConversionData { PeriodLabel string `json:"period_label"` // 时间段标签（如：今日、昨日、前日） QueryUsers int64 `json:"query_users"` // 查询订单数（订单数量，不是用户数） PaidUsers int64 `json:"paid_users"` // 付费订单数（订单数量，不是用户数） TotalAmount float64 `json:"total_amount"` // 总金额（已支付订单的总金额） QueryUserCount int64 `json:"query_user_count"` // 查询用户数（去重user_id后的用户数量） PaidUserCount int64 `json:"paid_user_count"` // 付费用户数（去重user_id后的用户数量） } // 下级列表 GetSubordinateListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetSubordinateListResp { Total int64 `json:"total"` // 总数 List []SubordinateItem `json:"list"` // 列表 } SubordinateItem { AgentId string `json:"agent_id"` // 代理ID Level int64 `json:"level"` // 等级 LevelName string `json:"level_name"` // 等级名称 Mobile string `json:"mobile"` // 手机号 CreateTime string `json:"create_time"` // 创建时间 TotalOrders int64 `json:"total_orders"` // 总订单数 TotalAmount float64 `json:"total_amount"` // 总金额 } // 下级贡献详情 GetSubordinateContributionDetailReq { SubordinateId string `form:"subordinate_id"` // 下级代理ID Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 TabType string `form:"tab_type,optional"` // 标签页类型：order=订单列表，invite=邀请列表 } GetSubordinateContributionDetailResp { Mobile string `json:"mobile"` // 手机号 LevelName string `json:"level_name"` // 等级名称 CreateTime string `json:"create_time"` // 创建时间 OrderStats OrderStatistics `json:"order_stats"` // 订单统计（仅统计有返佣的订单） RebateStats RebateStatistics `json:"rebate_stats"` // 返佣统计 InviteStats InviteStatistics `json:"invite_stats"` // 邀请统计 OrderList []OrderItem `json:"order_list"` // 订单列表（仅有贡献的订单） InviteList []InviteItem `json:"invite_list"` // 邀请列表 OrderListTotal int64 `json:"order_list_total"` // 订单列表总数 InviteListTotal int64 `json:"invite_list_total"` // 邀请列表总数 } OrderStatistics { TotalOrders int64 `json:"total_orders"` // 总订单量（仅统计有返佣的订单） MonthOrders int64 `json:"month_orders"` // 月订单 TodayOrders int64 `json:"today_orders"` // 今日订单 } RebateStatistics { TotalRebateAmount float64 `json:"total_rebate_amount"` // 总贡献返佣金额 TodayRebateAmount float64 `json:"today_rebate_amount"` // 今日贡献返佣金额 MonthRebateAmount float64 `json:"month_rebate_amount"` // 月贡献返佣金额 } InviteStatistics { TotalInvites int64 `json:"total_invites"` // 总的邀请 TodayInvites int64 `json:"today_invites"` // 今日邀请 MonthInvites int64 `json:"month_invites"` // 月邀请 } OrderItem { OrderNo string `json:"order_no"` // 订单号 ProductId string `json:"product_id"` // 产品ID ProductName string `json:"product_name"` // 产品名称 OrderAmount float64 `json:"order_amount"` // 订单金额 RebateAmount float64 `json:"rebate_amount"` // 返佣金额 CreateTime string `json:"create_time"` // 创建时间 } InviteItem { AgentId string `json:"agent_id"` // 代理ID Level int64 `json:"level"` // 等级 LevelName string `json:"level_name"` // 等级名称 Mobile string `json:"mobile"` // 手机号 CreateTime string `json:"create_time"` // 邀请时间 } // 团队列表 GetTeamListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 Mobile string `form:"mobile,optional"` // 手机号（可选，用于搜索） } GetTeamListResp { Statistics TeamStatistics `json:"statistics"` // 统计数据 Total int64 `json:"total"` // 总数 List []TeamMemberItem `json:"list"` // 列表 } TeamStatistics { TotalMembers int64 `json:"total_members"` // 团队成员总数 TodayNewMembers int64 `json:"today_new_members"` // 团队人员今日新增 MonthNewMembers int64 `json:"month_new_members"` // 团队人员月新增 TotalQueries int64 `json:"total_queries"` // 团队总查询总量 TodayPromotions int64 `json:"today_promotions"` // 团队今日推广量 MonthPromotions int64 `json:"month_promotions"` // 团队月推广量 TotalEarnings float64 `json:"total_earnings"` // 依靠团队得到的总收益 TodayEarnings float64 `json:"today_earnings"` // 今日收益 MonthEarnings float64 `json:"month_earnings"` // 月收益 } TeamMemberItem { AgentId string `json:"agent_id"` // 代理ID Level int64 `json:"level"` // 等级 LevelName string `json:"level_name"` // 等级名称 Mobile string `json:"mobile"` // 手机号 CreateTime string `json:"create_time"` // 加入团队时间 TodayQueries int64 `json:"today_queries"` // 当日查询量 TotalQueries int64 `json:"total_queries"` // 总查询量 TotalRebateAmount float64 `json:"total_rebate_amount"` // 返佣给我的总金额 TodayRebateAmount float64 `json:"today_rebate_amount"` // 返佣给我的今日金额 TotalInvites int64 `json:"total_invites"` // 邀请加入团队的总人数 TodayInvites int64 `json:"today_invites"` // 邀请加入团队的今日人数 IsDirect bool `json:"is_direct"` // 是否直接下级 } // 收益信息 GetRevenueInfoResp { Balance float64 `json:"balance"` // 可用余额 FrozenBalance float64 `json:"frozen_balance"` // 冻结余额 TotalEarnings float64 `json:"total_earnings"` // 累计收益（钱包总收益） WithdrawnAmount float64 `json:"withdrawn_amount"` // 累计提现 CommissionTotal float64 `json:"commission_total"` // 佣金累计总收益（推广订单获得的佣金） CommissionToday float64 `json:"commission_today"` // 佣金今日收益 CommissionMonth float64 `json:"commission_month"` // 佣金本月收益 RebateTotal float64 `json:"rebate_total"` // 返佣累计总收益（包括推广返佣和升级返佣） RebateToday float64 `json:"rebate_today"` // 返佣今日收益 RebateMonth float64 `json:"rebate_month"` // 返佣本月收益 } // 佣金记录 GetCommissionListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetCommissionListResp { Total int64 `json:"total"` // 总数 List []CommissionItem `json:"list"` // 列表 } CommissionItem { Id string `json:"id"` // 记录ID OrderId string `json:"order_id"` // 订单ID OrderNo string `json:"order_no"` // 订单号 ProductName string `json:"product_name"` // 产品名称 Amount float64 `json:"amount"` // 佣金金额 Status int64 `json:"status"` // 状态：1=已发放，2=已冻结，3=已取消 CreateTime string `json:"create_time"` // 创建时间 } // 返佣记录（推广返佣） GetRebateListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 RebateType *int64 `form:"rebate_type,optional"` // 返佣类型（可选）：1=直接上级返佣，2=钻石上级返佣，3=黄金上级返佣 } GetRebateListResp { Total int64 `json:"total"` // 总数 List []RebateItem `json:"list"` // 列表 } RebateItem { Id string `json:"id"` // 记录ID SourceAgentId string `json:"source_agent_id"` // 来源代理ID SourceAgentMobile string `json:"source_agent_mobile"` // 来源代理手机号 SourceAgentLevel int64 `json:"source_agent_level"` // 来源代理等级：1=普通，2=黄金，3=钻石 OrderId string `json:"order_id"` // 订单ID OrderNo string `json:"order_no"` // 订单号 RebateType int64 `json:"rebate_type"` // 返佣类型：1=直接上级，2=钻石上级，3=黄金上级 Amount float64 `json:"amount"` // 返佣金额 CreateTime string `json:"create_time"` // 创建时间 } // 升级返佣记录 GetUpgradeRebateListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetUpgradeRebateListResp { Total int64 `json:"total"` // 总数 List []UpgradeRebateItem `json:"list"` // 列表 } UpgradeRebateItem { Id string `json:"id"` // 记录ID SourceAgentId string `json:"source_agent_id"` // 来源代理ID（升级的代理） SourceAgentMobile string `json:"source_agent_mobile"` // 来源代理手机号 OrderNo string `json:"order_no"` // 订单号 FromLevel int64 `json:"from_level"` // 原等级 ToLevel int64 `json:"to_level"` // 目标等级 Amount float64 `json:"amount"` // 返佣金额 CreateTime string `json:"create_time"` // 创建时间 } // 升级记录 GetUpgradeListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetUpgradeListResp { Total int64 `json:"total"` // 总数 List []UpgradeItem `json:"list"` // 列表 } UpgradeItem { Id string `json:"id"` // 记录ID AgentId string `json:"agent_id"` // 代理ID FromLevel int64 `json:"from_level"` // 原等级 ToLevel int64 `json:"to_level"` // 目标等级 UpgradeType int64 `json:"upgrade_type"` // 升级类型：1=自主付费，2=钻石升级 UpgradeFee float64 `json:"upgrade_fee"` // 升级费用 RebateAmount float64 `json:"rebate_amount"` // 返佣金额 Status int64 `json:"status"` // 状态：1=待支付，2=已支付，3=已完成，4=已取消 CreateTime string `json:"create_time"` // 创建时间 } // 申请升级 ApplyUpgradeReq { ToLevel int64 `json:"to_level"` // 目标等级：2=黄金，3=钻石 } ApplyUpgradeResp { UpgradeId string `json:"upgrade_id"` // 升级记录ID OrderNo string `json:"order_no"` // 支付订单号 } // 钻石升级下级 UpgradeSubordinateReq { SubordinateId string `json:"subordinate_id"` // 下级代理ID ToLevel int64 `json:"to_level"` // 目标等级（只能是2=黄金） } UpgradeSubordinateResp { Success bool `json:"success"` } // 提现列表 GetWithdrawalListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetWithdrawalListResp { Total int64 `json:"total"` // 总数 List []WithdrawalItem `json:"list"` // 列表 } WithdrawalItem { Id string `json:"id"` // 记录ID WithdrawalNo string `json:"withdrawal_no"` // 提现单号 Amount float64 `json:"amount"` // 提现金额 TaxAmount float64 `json:"tax_amount"` // 税费金额 ActualAmount float64 `json:"actual_amount"` // 实际到账金额 Status int64 `json:"status"` // 状态：1=待审核，2=审核通过，3=审核拒绝，4=提现中，5=提现成功，6=提现失败 PayeeAccount string `json:"payee_account"` // 收款账户 PayeeName string `json:"payee_name"` // 收款人姓名 Remark string `json:"remark"` // 备注 CreateTime string `json:"create_time"` // 创建时间 } // 申请提现 ApplyWithdrawalReq { Amount float64 `json:"amount"` // 提现金额 PayeeAccount string `json:"payee_account"` // 收款账户 PayeeName string `json:"payee_name"` // 收款人姓名 } ApplyWithdrawalResp { WithdrawalId string `json:"withdrawal_id"` // 提现记录ID WithdrawalNo string `json:"withdrawal_no"` // 提现单号 } // 实名认证 RealNameAuthReq { Name string `json:"name"` // 姓名 IdCard string `json:"id_card"` // 身份证号 Mobile string `json:"mobile"` // 手机号 Code string `json:"code"` // 验证码 } RealNameAuthResp { Status string `json:"status"` // 状态：pending=待审核，approved=已通过，rejected=已拒绝 } // 推广查询列表 GetPromotionQueryListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetPromotionQueryListResp { Total int64 `json:"total"` // 总数 List []PromotionQueryItem `json:"list"` // 列表 } PromotionQueryItem { Id string `json:"id"` // 查询ID OrderId string `json:"order_id"` // 订单ID ProductName string `json:"product_name"` // 产品名称 CreateTime string `json:"create_time"` // 创建时间 QueryState string `json:"query_state"` // 查询状态 } ) // ============================================ // 短链重定向接口（公开访问，不需要认证和api前缀） // ============================================ @server ( group: agent ) service main { // 短链重定向 @handler ShortLinkRedirect get /s/:shortCode returns (ShortLinkRedirectResp) } type ( ShortLinkRedirectResp {} )