sayu-app/deliveries/team-b-architecture/api-definition.md

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

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

---

一、接口总览

阶段2a新增接口

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

新增总计: 13 个接口

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

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

---

二、果农名片接口

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

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

请求头: Authorization: Bearer {token}

响应参数:

{
  "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}

请求参数:

{
  "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"
  ]
}

响应参数:

{
  "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}

请求参数:

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

响应参数:

{
  "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

响应参数:

{
  "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}

请求参数:

{
  "price": 180.00,
  "workerCount": 5,
  "days": 7,
  "remark": "价格上调，急招"
}

响应参数:

{
  "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}

响应参数:

{
  "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

响应参数:

{
  "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

响应参数:

{
  "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}

请求参数:

{
  "calleeIdentityId": 5    // 必填，被拨方身份ID
}

响应参数:

{
  "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

响应参数:

{
  "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}

请求参数:

{
  "action": "APPROVE",    // 必填，APPROVE/REJECT
  "reason": ""            // 驳回时必填
}

响应参数:

{
  "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

响应参数:

{
  "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}

请求参数:

{
  "action": "NORMAL",      // 必填，NORMAL/FORCE_OFFLINE
  "reason": ""             // 强制下架时必填
}

响应参数:

{
  "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