cocos-farm/FarmAdmin/docs/farm-admin-api.md

农场后台接口

概览

• 地址：GET /admin/game/farm/overview
• 参数：
  • gameId：默认 farm
• 返回值：
  • metrics：玩家数、游戏金币总量、待处理兑换单、成熟作物数、失败事件数
  • serverTimeMs：服务端时间
• 相关 IM：无

兑换汇率

查询汇率

• 地址：GET /admin/game/farm/exchange-rates
• 参数：
  • gameId：默认 farm
  • exchangeType：station_to_game / game_to_station，可选
  • status：active / disabled / maintenance，可选
• 返回值：
  • items：汇率列表
  • serverTimeMs：服务端时间
• 相关 IM：无

创建汇率

• 地址：POST /admin/game/farm/exchange-rates
• 参数：
  • gameId：默认 farm
  • exchangeType：兑换方向
  • stationCoinAmount：站内 COIN 数量
  • gameCoinAmount：农场游戏金币数量
  • minStationCoin：单笔最小站内金币
  • maxStationCoin：单笔最大站内金币，0 表示不限
  • dailyStationCoinLimit：单用户每日上限，0 表示不限
  • effectiveFromMs：生效开始时间
  • effectiveToMs：生效结束时间，0 表示长期
• 返回值：
  • rate：创建后的汇率配置
  • serverTimeMs：服务端时间
• 相关 IM：无

更新汇率

• 地址：PATCH /admin/game/farm/exchange-rates/:rate_id
• 参数：
  • rate_id：汇率配置 ID
  • status：状态
  • stationCoinAmount：站内 COIN 数量
  • gameCoinAmount：农场游戏金币数量
  • minStationCoin：单笔最小站内金币
  • maxStationCoin：单笔最大站内金币
  • dailyStationCoinLimit：单用户每日上限
  • effectiveFromMs：生效开始时间
  • effectiveToMs：生效结束时间
• 返回值：
  • rate：更新后的汇率配置
  • serverTimeMs：服务端时间
• 相关 IM：无

作物配置

查询作物

• 地址：GET /admin/game/farm/crops
• 参数：
  • gameId：默认 farm
  • status：active / disabled，可选
• 返回值：
  • items：作物配置列表
  • serverTimeMs：服务端时间
• 相关 IM：无

创建作物

• 地址：POST /admin/game/farm/crops
• 参数：
  • gameId：默认 farm
  • cropName：作物名称
  • requiredLevel：解锁等级
  • seedPriceGameCoin：种子价格
  • sellPriceGameCoin：单个作物售卖价格
  • matureQuantity：成熟数量
  • description：作物描述
  • growthStages：生长阶段列表，每项包含阶段名、图片资源 ID、图片路径、需要秒数
• 返回值：
  • crop：创建后的作物配置
  • serverTimeMs：服务端时间
• 相关 IM：无

更新作物

• 地址：PATCH /admin/game/farm/crops/:crop_id
• 参数：
  • crop_id：作物 ID
  • status：状态
  • requiredLevel：种植等级
  • growDurationMs：成熟时间
  • seedPriceGameCoin：种子价格
  • sellPriceGameCoin：单个作物售卖价格
  • matureQuantity：成熟数量
  • harvestMinQuantity：最小产量
  • harvestMaxQuantity：最大产量
  • stealableQuantity：最多可偷数量
  • harvestExp：收获经验
  • description：作物描述
  • growthStages：生长阶段列表
• 返回值：
  • crop：更新后的作物配置
  • serverTimeMs：服务端时间
• 相关 IM：无

道具配置

查询道具

• 地址：GET /admin/game/farm/items
• 参数：
  • gameId：默认 farm
  • itemType：seed / crop / tool / material，可选
  • status：active / disabled，可选
• 返回值：
  • items：道具配置列表
  • serverTimeMs：服务端时间
• 相关 IM：无

玩家账户

查询玩家

• 地址：GET /admin/game/farm/players
• 参数：
  • gameId：默认 farm
  • userId：用户 ID，可选
  • status：active / disabled / maintenance，可选
  • pageSize：默认 50
  • cursor：下一页游标
• 返回值：
  • items：玩家农场账户列表
  • nextCursor：下一页游标
  • pageSize：本次页大小
  • serverTimeMs：服务端时间
• 相关 IM：无

兑换订单

查询订单

• 地址：GET /admin/game/farm/exchange-orders
• 参数：
  • gameId：默认 farm
  • userId：用户 ID，可选
  • exchangeType：兑换方向，可选
  • status：订单状态，可选
  • startTimeMs：开始时间，可选
  • endTimeMs：结束时间，可选
  • pageSize：默认 50
  • cursor：下一页游标
• 返回值：
  • items：兑换订单列表
  • nextCursor：下一页游标
  • pageSize：本次页大小
  • serverTimeMs：服务端时间
• 相关 IM：无

重试兑换

• 地址：POST /admin/game/farm/exchange-orders/:exchange_id/retry
• 参数：
  • exchange_id：兑换单 ID
• 返回值：
  • order：重试后的兑换单
  • serverTimeMs：服务端时间
• 相关 IM：无

事件队列

查询事件

• 地址：GET /admin/game/farm/events
• 参数：
  • gameId：默认 farm
  • status：pending / processing / delivered / failed，可选
  • eventType：事件类型，可选
  • targetUserId：通知目标用户，可选
  • pageSize：默认 50
  • cursor：下一页游标
• 返回值：
  • items：事件列表
  • nextCursor：下一页游标
  • pageSize：本次页大小
  • serverTimeMs：服务端时间
• 相关 IM：成熟、被偷、兑换成功等事件由 notice-service 后续投递

重试事件

• 地址：POST /admin/game/farm/events/:event_id/retry
• 参数：
  • event_id：事件 ID
• 返回值：
  • event：重试后的事件
  • serverTimeMs：服务端时间
• 相关 IM：成功后由 notice-service 按事件类型补投递