# 阶段2a接口定义 — 果农核心功能

> 新增接口总数：13 个
> 已有接口（复用）：4 个
> 覆盖功能点：14/14

---

## 一、接口总览

### 阶段2a新增接口

| 模块 | 接口数 | 说明 |
|------|--------|------|
| 果农名片 | 2 | 档案查询、档案更新 |
| 招工管理 | 4 | 发布、列表、编辑、下架 |
| 找工人/客商 | 2 | 工人列表、客商列表 |
| 拨号 | 1 | 获取手机号+记录日志 |
| 后台审核 | 4 | 名片审核列表/操作、待复核列表/操作 |

**新增总计**: 13 个接口

### 已有接口（阶段2a复用）

| 模块 | 接口数 | 说明 |
|------|--------|------|
| 文件上传 | 4 | 图片上传、视频上传、文件访问、文件删除 |

---

## 二、果农名片接口

### 2.1 GET /api/wx/grower/profile — 获取果农档案

**描述**: 获取当前果农的名片信息

**请求头**: `Authorization: Bearer {token}`

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "varieties": ["红富士", "嘎啦"],
    "yieldAmount": 50000.00,
    "expectedPrice": 4.00,
    "address": "洒渔镇黄兴村",
    "latitude": 27.3331000,
    "longitude": 103.7168000,
    "videoUrl": "http://localhost:8080/files/video/abc.mp4",
    "photos": [
      "http://localhost:8080/files/image/1.jpg",
      "http://localhost:8080/files/image/2.jpg"
    ],
    "auditStatus": 0,
    "auditRemark": null
  }
}
```

**错误码**:
- 2001: 果农档案不存在

---

### 2.2 PUT /api/wx/grower/profile — 更新果农档案

**描述**: 更新果农名片信息，审核状态重置为待审

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "name": "张三",                    // 必填，姓名
  "varieties": ["红富士", "嘎啦"],    // 必填，品种（JSON数组）
  "yieldAmount": 50000.00,           // 产量（斤）
  "expectedPrice": 4.00,             // 预期价格（元/斤）
  "address": "洒渔镇黄兴村",          // 必填，果园地址
  "latitude": 27.3331000,            // 纬度
  "longitude": 103.7168000,          // 经度
  "videoUrl": "http://localhost:8080/files/video/abc.mp4",
  "photos": [
    "http://localhost:8080/files/image/1.jpg"
  ]
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**业务逻辑**:
1. 验证必填字段（name、varieties、address）
2. 更新 grower_profile
3. 重置 audit_status=0，清空 audit_remark

**错误码**:
- 2002: 必填字段不能为空

---

## 三、招工管理接口

### 3.1 POST /api/wx/grower/recruit — 发布招工

**描述**: 发布招工信息，免审核直接发布

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "workTypes": ["采摘工", "分拣工"],   // 必填，工种（JSON数组）
  "price": 150.00,                    // 必填，价格
  "priceUnit": "DAY",                 // 必填，价格单位：DAY/PIECE
  "workerCount": 3,                   // 必填，需要人数
  "days": 5,                          // 天数
  "location": "洒渔镇黄兴村",          // 必填，工作地点
  "latitude": 27.3331000,             // 纬度
  "longitude": 103.7168000,           // 经度
  "remark": "需要有经验的采摘工"       // 备注
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "recruitId": 1
  }
}
```

**业务逻辑**:
1. 验证必填字段
2. 敏感词检测（remark字段）
3. keyword_flag=0 或 1
4. 创建 recruit_info（status=1）

**错误码**:
- 2003: 工种不能为空
- 2004: 价格必须大于0
- 2005: 人数必须大于0
- 2006: 工作地点不能为空

---

### 3.2 GET /api/wx/grower/recruit — 我的招工列表

**描述**: 获取当前果农发布的招工历史

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```
?page=1&pageSize=20
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "id": 1,
        "workTypes": ["采摘工", "分拣工"],
        "price": 150.00,
        "priceUnit": "DAY",
        "workerCount": 3,
        "days": 5,
        "location": "洒渔镇黄兴村",
        "status": 1,
        "keywordFlag": 0,
        "applyCount": 2,
        "createdAt": "2026-05-30 10:00:00"
      }
    ]
  }
}
```

---

### 3.3 PUT /api/wx/grower/recruit/{id} — 编辑招工

**描述**: 编辑已发布的招工信息

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "price": 180.00,
  "workerCount": 5,
  "days": 7,
  "remark": "价格上调，急招"
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**业务逻辑**:
1. 验证招工存在且属于当前用户
2. 更新可编辑字段（price、workerCount、days、remark）
3. 重新触发敏感词检测

**错误码**:
- 2007: 招工不存在
- 2008: 无权编辑此招工

---

### 3.4 DELETE /api/wx/grower/recruit/{id} — 下架招工

**描述**: 下架已发布的招工（逻辑删除）

**请求头**: `Authorization: Bearer {token}`

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**业务逻辑**:
1. 验证招工存在且属于当前用户
2. 更新 status=0

**错误码**:
- 2007: 招工不存在
- 2008: 无权操作此招工

---

## 四、找工人/客商接口

### 4.1 GET /api/wx/grower/workers — 工人列表

**描述**: 查找附近空闲工人

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```
?workType=采摘工&page=1&pageSize=20
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 10,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "identityId": 5,
        "name": "李四",
        "skills": ["采摘工", "分拣工"],
        "price": 150.00,
        "priceUnit": "DAY",
        "status": 1,
        "distance": 2.5
      }
    ]
  }
}
```

**业务逻辑**:
1. 查询 worker_profile.status=1（空闲）
2. 可选按工种筛选
3. 计算距离（Haversine公式）
4. 按距离升序排序
5. 分页返回

---

### 4.2 GET /api/wx/grower/buyers — 客商列表

**描述**: 查找收购客商

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```
?page=1&pageSize=20
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "identityId": 10,
        "name": "王五果业",
        "varieties": ["红富士", "嘎啦"],
        "priceRange": "3.5-4.5",
        "totalAmount": 100000.00,
        "standards": "果径≥80mm",
        "address": "昭通市水果批发市场"
      }
    ]
  }
}
```

---

## 五、拨号接口

### 5.1 POST /api/wx/call/phone — 拨号接口

**描述**: 获取对方手机号并记录拨号日志

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "calleeIdentityId": 5    // 必填，被拨方身份ID
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "phone": "138****8888",      // 脱敏手机号（前端显示）
    "realPhone": "13800138000"   // 真实手机号（用于拨号）
  }
}
```

**业务逻辑**:
1. 验证被拨方存在
2. 记录拨号日志（call_log）
3. 返回手机号

**错误码**:
- 2009: 被拨方不存在

---

## 六、后台审核接口

### 6.1 GET /api/admin/audit/grower-profile — 名片审核列表

**描述**: 获取待审核的果农名片列表

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```
?page=1&pageSize=10&status=0
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 3,
    "page": 1,
    "pageSize": 10,
    "list": [
      {
        "id": 1,
        "growerName": "张三",
        "varieties": ["红富士"],
        "yieldAmount": 50000.00,
        "address": "洒渔镇黄兴村",
        "videoUrl": "http://localhost:8080/files/video/abc.mp4",
        "photos": ["http://localhost:8080/files/image/1.jpg"],
        "auditStatus": 0,
        "createdAt": "2026-05-30 10:00:00"
      }
    ]
  }
}
```

---

### 6.2 PUT /api/admin/audit/grower-profile/{id} — 名片审核操作

**描述**: 对果农名片执行审核操作

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "action": "APPROVE",    // 必填，APPROVE/REJECT
  "reason": ""            // 驳回时必填
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**业务逻辑**:
1. 验证审核记录存在
2. APPROVE → audit_status=1
3. REJECT → audit_status=2，audit_remark=reason
4. 记录审核日志

**错误码**:
- 2010: 审核记录不存在
- 2011: 驳回原因不能为空

---

### 6.3 GET /api/admin/audit/recruit-review — 待复核招工列表

**描述**: 获取敏感关键词标记的招工列表

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```
?page=1&pageSize=10
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 10,
    "list": [
      {
        "id": 1,
        "workTypes": ["采摘工"],
        "price": 150.00,
        "remark": "日薪300元...",
        "keywordFlag": 1,
        "publisherName": "张三",
        "createdAt": "2026-05-30 10:00:00"
      }
    ]
  }
}
```

---

### 6.4 PUT /api/admin/audit/recruit-review/{id} — 待复核操作

**描述**: 处理待复核招工

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "action": "NORMAL",      // 必填，NORMAL/FORCE_OFFLINE
  "reason": ""             // 强制下架时必填
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**业务逻辑**:
1. 验证招工存在
2. NORMAL → keyword_flag=0
3. FORCE_OFFLINE → status=0，记录原因

**错误码**:
- 2012: 招工不存在
- 2013: 下架原因不能为空

---

## 七、已有接口（阶段2a复用）

### 7.1 POST /api/wx/file/upload/image — 上传图片

**描述**: 上传图片文件（已实现）

**请求**: multipart/form-data

**限制**: ≤5MB/张，格式：jpg,jpeg,png,gif

### 7.2 POST /api/wx/file/upload/video — 上传视频

**描述**: 上传视频文件（已实现）

**请求**: multipart/form-data

**限制**: ≤50MB，格式：mp4,mov,avi

### 7.3 GET /api/wx/file/files/{category}/{filename} — 访问文件

**描述**: 访问已上传的文件（已实现，免认证）

### 7.4 DELETE /api/wx/file/delete — 删除文件

**描述**: 删除已上传的文件（已实现）

---

## 八、接口统计

| 模块 | 新增接口 | 已有接口 | 总计 |
|------|---------|---------|------|
| 果农名片 | 2 | - | 2 |
| 招工管理 | 4 | - | 4 |
| 找工人/客商 | 2 | - | 2 |
| 拨号 | 1 | - | 1 |
| 后台审核 | 4 | - | 4 |
| 文件上传 | - | 4 | 4 |
| **总计** | **13** | **4** | **17** |

| HTTP方法 | 数量 |
|---------|------|
| GET | 6 |
| POST | 4 |
| PUT | 5 |
| DELETE | 2 |