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 int64 `json:"agent_id"` // 代理ID ProductId int64 `json:"product_id"` // 产品ID SetPrice float64 `json:"set_price"` // 代理设定价格 ActualBasePrice float64 `json:"actual_base_price"` // 实际底价 ProductName string `json:"product_name"` // 产品名称 } AgentApplyReq { Region string `json:"region,optional"` // 区域（可选） Mobile string `json:"mobile"` // 手机号 Code string `json:"code"` // 验证码 InviteCode string `json:"invite_code"` // 邀请码（必填，只能通过邀请码成为代理） } AgentApplyResp { AccessToken string `json:"accessToken"` AccessExpire int64 `json:"accessExpire"` RefreshAfter int64 `json:"refreshAfter"` } // 通过邀请码注册 RegisterByInviteCodeReq { InviteCode string `json:"invite_code"` // 邀请码 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 int64 `json:"agent_id"` // 代理ID Level int64 `json:"level"` // 代理等级 LevelName string `json:"level_name"` // 等级名称 } // 生成邀请码 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 int64 `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"` // 创建时间 } // 获取邀请链接 GetInviteLinkResp { InviteLink string `json:"invite_link"` // 邀请链接 QrCodeUrl string `json:"qr_code_url"` // 二维码URL } ) // ============================================ // 需要登录的接口 // ============================================ @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 GetSubordinateList get /subordinate/list (GetSubordinateListReq) returns (GetSubordinateListResp) // 获取收益信息 @handler GetRevenueInfo get /revenue returns (GetRevenueInfoResp) // 获取佣金记录 @handler GetCommissionList get /commission/list (GetCommissionListReq) returns (GetCommissionListResp) // 获取返佣记录 @handler GetRebateList get /rebate/list (GetRebateListReq) returns (GetRebateListResp) // 获取升级记录 @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 GetInviteLink get /invite_link returns (GetInviteLinkResp) } type ( // 代理信息 AgentInfoResp { AgentId int64 `json:"agent_id"` // 代理ID Level int64 `json:"level"` // 代理等级：1=普通，2=黄金，3=钻石 LevelName string `json:"level_name"` // 等级名称 Region string `json:"region"` // 区域（可选） Mobile string `json:"mobile"` // 手机号 WechatId string `json:"wechat_id"` // 微信号（可选） TeamLeaderId int64 `json:"team_leader_id"` // 团队首领ID IsRealName bool `json:"is_real_name"` // 是否已实名 } // 生成推广链接 AgentGeneratingLinkReq { ProductId int64 `json:"product_id"` // 产品ID SetPrice float64 `json:"set_price"` // 设定价格 } AgentGeneratingLinkResp { LinkIdentifier string `json:"link_identifier"` // 推广链接标识 } // 产品配置 AgentProductConfigResp { List []ProductConfigItem `json:"list"` } ProductConfigItem { ProductId int64 `json:"product_id"` // 产品ID ProductName string `json:"product_name"` // 产品名称 BasePrice float64 `json:"base_price"` // 基础底价 LevelBonus float64 `json:"level_bonus"` // 等级加成 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"` // 间接下级数量 ByLevel TeamLevelStats `json:"by_level"` // 按等级统计 } TeamLevelStats { Diamond int64 `json:"diamond"` // 钻石数量 Gold int64 `json:"gold"` // 黄金数量 Normal int64 `json:"normal"` // 普通数量 } // 下级列表 GetSubordinateListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetSubordinateListResp { Total int64 `json:"total"` // 总数 List []SubordinateItem `json:"list"` // 列表 } SubordinateItem { AgentId int64 `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"` // 总金额 } // 收益信息 GetRevenueInfoResp { Balance float64 `json:"balance"` // 可用余额 FrozenBalance float64 `json:"frozen_balance"` // 冻结余额 TotalEarnings float64 `json:"total_earnings"` // 累计收益 WithdrawnAmount float64 `json:"withdrawn_amount"` // 累计提现 } // 佣金记录 GetCommissionListReq { Page int64 `form:"page"` // 页码 PageSize int64 `form:"page_size"` // 每页数量 } GetCommissionListResp { Total int64 `json:"total"` // 总数 List []CommissionItem `json:"list"` // 列表 } CommissionItem { Id int64 `json:"id"` // 记录ID OrderId int64 `json:"order_id"` // 订单ID 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"` // 每页数量 } GetRebateListResp { Total int64 `json:"total"` // 总数 List []RebateItem `json:"list"` // 列表 } RebateItem { Id int64 `json:"id"` // 记录ID SourceAgentId int64 `json:"source_agent_id"` // 来源代理ID OrderId int64 `json:"order_id"` // 订单ID RebateType int64 `json:"rebate_type"` // 返佣类型：1=直接上级，2=钻石上级，3=黄金上级 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 int64 `json:"id"` // 记录ID AgentId int64 `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 int64 `json:"upgrade_id"` // 升级记录ID OrderNo string `json:"order_no"` // 支付订单号 } // 钻石升级下级 UpgradeSubordinateReq { SubordinateId int64 `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 int64 `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 int64 `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=已拒绝 } )