# 农场后台接口

## 概览

- 地址：`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 按事件类型补投递