# 阶段2b 接口定义文档

> 版本：v1.0
> 日期：2026-05-30

---

## 1. 工人模块接口

### 1.1 GET /api/wx/worker/profile

**说明**：获取工人档案

**请求头**：
- Authorization: Bearer {token}

**请求参数**：无

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "userIdentityId": 10,
    "name": "张三",
    "skills": "[\"采摘工\",\"分拣工\"]",
    "price": 200.00,
    "priceUnit": "DAY",
    "status": 1,
    "statusUpdatedAt": "2026-05-30 10:00:00",
    "complaintCount": 0
  }
}
```

---

### 1.2 PUT /api/wx/worker/profile

**说明**：创建/更新工人档案

**请求头**：
- Authorization: Bearer {token}
- Content-Type: application/json

**请求体**：
```json
{
  "name": "张三",
  "skills": "[\"采摘工\",\"分拣工\"]",
  "price": 200.00,
  "priceUnit": "DAY"
}
```

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": null
}
```

---

### 1.3 GET /api/wx/worker/recommend

**说明**：推荐招工列表（工种匹配+距离排序）

**请求头**：
- Authorization: Bearer {token}

**请求参数**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| workType | String | 否 | 工种筛选 |
| page | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页数量，默认10 |

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "workTypes": "[\"采摘工\"]",
      "price": 180.00,
      "priceUnit": "DAY",
      "workerCount": 5,
      "location": "洒渔镇黄兴村",
      "distance": 2.5,
      "farmerName": "李四",
      "createdAt": "2026-05-30 09:00:00"
    }
  ]
}
```

---

### 1.4 POST /api/wx/worker/apply

**说明**：报名招工

**请求头**：
- Authorization: Bearer {token}
- Content-Type: application/json

**请求体**：
```json
{
  "recruitId": 1
}
```

**响应示例**：
```json
{
  "code": 0,
  "msg": "报名成功",
  "data": {
    "applyId": 1,
    "smsSent": true
  }
}
```

**错误码**：
| code | msg | 说明 |
|------|-----|------|
| -1 | 已报名该招工 | 重复报名 |
| -2 | 账号信用受限 | complaint_count >= 3 |
| -3 | 请24小时后再试 | complaint_count = 2，限制中 |

---

### 1.5 PUT /api/wx/worker/status

**说明**：切换工作状态

**请求头**：
- Authorization: Bearer {token}
- Content-Type: application/json

**请求体**：
```json
{
  "status": 1
}
```

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": null
}
```

---

### 1.6 GET /api/wx/worker/applies

**说明**：报名历史

**请求头**：
- Authorization: Bearer {token}

**请求参数**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页数量，默认10 |

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "recruitId": 1,
      "workTypes": "[\"采摘工\"]",
      "price": 180.00,
      "location": "洒渔镇黄兴村",
      "farmerName": "李四",
      "smsSent": true,
      "applyTime": "2026-05-30 10:30:00"
    }
  ]
}
```

---

## 2. 客商模块接口

### 2.1 GET /api/wx/buyer/profile

**说明**：获取客商档案

**请求头**：
- Authorization: Bearer {token}

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "userIdentityId": 20,
    "name": "王五",
    "varieties": "[\"红富士\",\"嘎啦\"]",
    "priceRange": "3.0-4.5元/斤",
    "totalAmount": 50000.00,
    "standards": "80mm以上，无疤痕",
    "address": "洒渔镇收购点"
  }
}
```

---

### 2.2 PUT /api/wx/buyer/profile

**说明**：创建/更新客商档案

**请求头**：
- Authorization: Bearer {token}
- Content-Type: application/json

**请求体**：
```json
{
  "name": "王五",
  "varieties": "[\"红富士\",\"嘎啦\"]",
  "priceRange": "3.0-4.5元/斤",
  "totalAmount": 50000.00,
  "standards": "80mm以上，无疤痕",
  "address": "洒渔镇收购点"
}
```

---

### 2.3 GET /api/wx/buyer/goods

**说明**：货源列表

**请求头**：
- Authorization: Bearer {token}

**请求参数**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| variety | String | 否 | 品种筛选 |
| priceMin | BigDecimal | 否 | 最低价 |
| priceMax | BigDecimal | 否 | 最高价 |
| page | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页数量 |

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "李四",
      "varieties": "[\"红富士\"]",
      "yieldAmount": 20000.00,
      "expectedPrice": 4.00,
      "address": "洒渔镇黄兴村果园",
      "photos": "[\"http://...photo1.jpg\"]",
      "distance": 3.2
    }
  ]
}
```

---

### 2.4 GET /api/wx/buyer/goods/{id}

**说明**：货源详情

**请求头**：
- Authorization: Bearer {token}

**路径参数**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 果农档案ID |

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "李四",
    "varieties": "[\"红富士\"]",
    "yieldAmount": 20000.00,
    "expectedPrice": 4.00,
    "address": "洒渔镇黄兴村果园",
    "latitude": 27.3456789,
    "longitude": 103.7654321,
    "videoUrl": "http://localhost:8080/files/video.mp4",
    "photos": "[\"http://...photo1.jpg\",\"http://...photo2.jpg\"]"
  }
}
```

---

### 2.5 POST /api/wx/buyer/unlock

**说明**：解锁果农电话

**请求头**：
- Authorization: Bearer {token}
- Content-Type: application/json

**请求体**：
```json
{
  "growerId": 1
}
```

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "phone": "13800138000",
    "expireTime": "2026-06-06 10:30:00"
  }
}
```

---

### 2.6 GET /api/wx/buyer/preferences

**说明**：获取收购偏好

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "preferredVarieties": "[\"红富士\"]",
    "priceRange": "3.0-4.5元/斤",
    "minQuantity": 10000.00
  }
}
```

---

### 2.7 PUT /api/wx/buyer/preferences

**说明**：更新收购偏好

**请求体**：
```json
{
  "preferredVarieties": "[\"红富士\",\"花牛\"]",
  "priceRange": "3.0-5.0元/斤",
  "minQuantity": 5000.00
}
```

---

## 3. 农资模块接口

### 3.1 GET /api/wx/supplier/shop

**说明**：获取店铺信息

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "userIdentityId": 30,
    "shopName": "洒渔农资店",
    "ownerName": "赵六",
    "categories": "[\"化肥\",\"农药\"]",
    "address": "洒渔镇主街",
    "phone": "13900139000"
  }
}
```

---

### 3.2 PUT /api/wx/supplier/shop

**说明**：创建/更新店铺信息

**请求体**：
```json
{
  "shopName": "洒渔农资店",
  "ownerName": "赵六",
  "categories": "[\"化肥\",\"农药\",\"农具\"]",
  "address": "洒渔镇主街",
  "phone": "13900139000"
}
```

---

## 4. 后台管理接口

### 4.1 GET /api/admin/sms/config

**说明**：获取短信配置

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "signName": "洒渔用工",
    "templateCodeApply": "SMS_xxxxx1",
    "templateCodeAudit": "SMS_xxxxx2"
  }
}
```

---

### 4.2 PUT /api/admin/sms/config

**说明**：更新短信配置

**请求体**：
```json
{
  "signName": "洒渔用工",
  "templateCodeApply": "SMS_xxxxx1",
  "templateCodeAudit": "SMS_xxxxx2"
}
```

---

## 5. 接口统计

| 模块 | 接口数 |
|------|--------|
| 工人模块 | 6 |
| 客商模块 | 7 |
| 农资模块 | 2 |
| 后台管理 | 2 |
| **总计** | **17** |

**验收标准**：新增接口 >= 15 → 达标