# 阶段2a需求规格 — 果农核心功能

> 基于 requirements-specification.md + phase-2a-tasks.md 提取
> 阶段2a功能点：14 个

---

## 一、阶段范围

阶段2a聚焦**果农核心业务功能**，使果农能完善名片、发布招工、找到工人和客商。

### 功能模块

| 模块 | 功能点数 | 优先级 |
|------|---------|--------|
| 果农名片（信息维护+视频+照片+审核状态） | 4 | P0 |
| 招工发布与管理 | 5 | P0 |
| 找工人 | 2 | P0 |
| 找客商 | 2 | P0 |
| 后台审核（名片审核+待复核+SLA） | 3 | P0/P1 |

**总计**: 14 个功能点

---

## 二、功能需求

### 2.1 果农名片模块

#### 2.1.1 名片信息维护（P0）
- **功能**: 果农编辑和完善个人名片信息
- **字段**:
  - 苹果品种（多选，字典：红富士/嘎啦/花牛/青冠/国光/金帅）
  - 产量（斤，DECIMAL(10,2)）
  - 预期价格（元/斤，DECIMAL(8,2)）
  - 果园地址（文本，≤200字）
  - 经纬度（地理编码后存储，DECIMAL(10,7)）
- **操作**: GET 获取档案 / PUT 更新档案
- **接口**: `/api/wx/grower/profile`
- **约束**:
  - 仅果农身份可操作
  - 品种为JSON数组存储
  - 地址变更时需重新地理编码

#### 2.1.2 视频上传（P0）
- **功能**: 果农上传果园展示视频
- **上传流程（3步）**:
  1. **前端预处理**: 清除EXIF元数据 → 预校验格式/大小
  2. **后端接收存储**: 调用上传API → 存储到本地 `./uploads/video/` 目录
  3. **异步压缩**: 后端异步压缩为720p/2Mbps/≤5分钟
- **限制**:
  - 文件大小：≤50MB
  - 格式：MP4、MOV
  - 分辨率：压缩至720p
  - 码率：压缩至2Mbps
  - 时长：≤5分钟
- **接口**: `/api/wx/file/upload/video`（已实现）
- **存储**: 本地文件存储，数据库存URL
- **约束**:
  - 前端必须清除EXIF（防止位置信息泄露）
  - 压缩失败有重试机制
  - 仅允许上传1个视频

#### 2.1.3 照片上传（P0）
- **功能**: 果农上传果园照片
- **限制**:
  - 数量：≤9张
  - 单张大小：≤5MB
  - 格式：JPG、JPEG、PNG、GIF
- **接口**: `/api/wx/file/upload/image`（已实现）
- **存储**: 本地文件存储，URL以JSON数组存入 `grower_profile.photos`
- **约束**:
  - 前端清除EXIF
  - 支持删除已上传照片

#### 2.1.4 审核状态查看（P0）
- **功能**: 果农查看名片审核状态
- **状态流转**: 待审(0) → 已通过(1) / 被驳回(2)
- **展示**:
  - 待审：显示"审核中"
  - 已通过：显示"已通过"，名片对外可见
  - 被驳回：显示"已驳回" + 驳回原因
- **约束**:
  - 驳回后可修改重新提交
  - 重新提交后状态重置为"待审"

---

### 2.2 招工发布与管理模块

#### 2.2.1 发布招工（P0）
- **功能**: 果农发布招工需求
- **表单字段**:
  - 工种（多选，字典：采摘工/分拣工/装卸工/喷药工/修剪工/施肥工）
  - 价格（DECIMAL(8,2)）
  - 价格单位（元/天 | 元/个）
  - 需要人数（INT）
  - 天数（INT）
  - 工作地点（文本）
  - 经纬度（地理编码）
  - 备注（≤500字，支持语音输入）
- **发布规则**: 免审核直接发布（status=1）
- **接口**: `POST /api/wx/grower/recruit`
- **约束**:
  - 仅果农身份可发布
  - 必填字段：工种、价格、价格单位、人数、工作地点
  - 语音输入转文字后存入备注

#### 2.2.2 敏感关键词检测（P0）
- **功能**: 发布时自动检测敏感关键词
- **检测机制**:
  - 正则匹配敏感词库（色情/赌博/政治等明确违规词）
  - 检测到敏感词 → `keyword_flag=1`，进入待复核列表
  - 不阻塞发布，招工信息仍然可见
- **约束**:
  - 初始词库硬编码，后续可扩展
  - 审核员定时处理待复核列表
  - 误判可通过后台标记为正常

#### 2.2.3 招工编辑（P1）
- **功能**: 果农编辑已发布的招工信息
- **可编辑字段**: 价格、人数、天数、备注
- **接口**: `PUT /api/wx/grower/recruit/{id}`
- **约束**:
  - 仅可编辑自己发布的招工
  - 编辑后如含敏感词，重新触发检测

#### 2.2.4 招工下架（P0）
- **功能**: 果农下架已发布的招工
- **接口**: `DELETE /api/wx/grower/recruit/{id}`（逻辑删除，status=0）
- **约束**:
  - 仅可下架自己发布的招工
  - 下架后工人不可见

#### 2.2.5 我的招工列表（P1）
- **功能**: 果农查看自己发布的招工历史
- **展示**: 工种、价格、人数、发布时间、状态、报名人数
- **接口**: `GET /api/wx/grower/recruit`
- **约束**:
  - 按发布时间倒序
  - 支持分页

---

### 2.3 找工人模块

#### 2.3.1 工人列表（P0）
- **功能**: 果农查找附近空闲工人
- **筛选**: 工种（单选）
- **列表展示**: 工人姓名、工种标签、报价（元/天或元/个）、距离（km）、状态（空闲/忙碌）
- **排序**: 按距离升序
- **接口**: `GET /api/wx/grower/workers`
- **距离计算**:
  - 果园地址 → 地理编码 → 经纬度存储
  - 查询时使用 Haversine 公式计算距离
  - 经纬度精确到小数点后7位
- **约束**:
  - 仅显示状态为"空闲"的工人
  - 返回距离（km，保留1位小数）
  - 分页查询，每页20条

#### 2.3.2 一键拨号（P0）
- **功能**: 果农点击工人电话按钮拨号
- **流程**:
  1. 调用 `/api/wx/call/phone` 获取手机号
  2. 后端记录拨号日志（call_log表）
  3. 返回脱敏手机号，前端唤起系统拨号
- **约束**:
  - 拨号日志记录：拨号方ID、被拨方ID、拨号时间
  - 手机号通过单独接口获取（不在列表中直接返回）

---

### 2.4 找客商模块

#### 2.4.1 客商列表（P0）
- **功能**: 果农查找收购客商
- **列表展示**: 客商姓名/公司名、收购品种、收购价格区间、收购数量、收购点地址
- **接口**: `GET /api/wx/grower/buyers`
- **约束**:
  - 展示客商基本信息
  - 分页查询

#### 2.4.2 一键拨号（P0）
- **功能**: 果农点击客商电话按钮拨号
- **流程**: 同找工人拨号流程
- **约束**:
  - 记录拨号日志
  - 手机号脱敏

---

### 2.5 后台审核模块

#### 2.5.1 名片审核（P0）
- **功能**: 审核员审核果农名片
- **审核内容**: 视频内容、照片内容、信息真实性
- **操作**: 通过 / 驳回（需填原因）
- **接口**:
  - `GET /api/admin/audit/grower-profile` — 审核列表
  - `PUT /api/admin/audit/grower-profile/{id}` — 审核操作
- **约束**:
  - 仅审核员和超级管理员可操作
  - 驳回必须填写原因
  - 审核结果通知果农

#### 2.5.2 待复核列表（P0）
- **功能**: 审核员处理敏感关键词标记的招工
- **展示**: 招工内容、标记关键词、发布者、发布时间
- **操作**: 标记为正常 / 强制下架
- **接口**:
  - `GET /api/admin/audit/recruit-review` — 待复核列表
  - `PUT /api/admin/audit/recruit-review/{id}` — 处理操作
- **约束**:
  - 仅审核员和超级管理员可操作
  - 强制下架需填写原因

#### 2.5.3 审核SLA提醒（P1）
- **功能**: 审核超时自动提醒
- **规则**:
  - 待审核超过24小时 → 提醒审核员
  - 待审核超过48小时 → 升级提醒超级管理员
- **实现**: 定时任务扫描，短信/站内信通知
- **约束**:
  - 仅提醒未处理的审核项
  - 每个审核项最多提醒3次

---

## 三、非功能需求

### 3.1 性能需求
- 文件上传：≤50MB文件，上传时间≤30s（局域网环境）
- 列表查询：≤500ms（含距离计算）
- 视频压缩：异步处理，不影响用户操作

### 3.2 安全需求
- 视频/照片上传：格式白名单校验，防止恶意文件
- 敏感词检测：防止色情/赌博/政治违规内容
- 手机号保护：拨号接口单独获取，列表不返回
- EXIF清除：防止位置信息泄露

### 3.3 可用性需求
- 视频压缩失败：自动重试3次
- 文件上传失败：支持重新上传
- 网络中断：前端提示重试

---

## 四、数据模型（阶段2a涉及）

### 4.1 已有表（需扩展使用）

| 表名 | 阶段2a用途 |
|------|-----------|
| grower_profile | 果农档案CRUD |
| recruit_info | 招工信息CRUD |
| worker_profile | 工人列表查询 |
| buyer_profile | 客商列表查询 |
| call_log | 拨号日志记录 |
| audit_log | 审核日志记录 |

### 4.2 关键字段说明

**grower_profile**:
- `varieties`: JSON数组，如 `["红富士","嘎啦"]`
- `photos`: JSON数组，如 `["http://localhost:8080/files/image/xxx.jpg"]`
- `video_url`: 单个URL
- `latitude`/`longitude`: DECIMAL(10,7)，用于距离计算

**recruit_info**:
- `work_types`: JSON数组，如 `["采摘工","分拣工"]`
- `keyword_flag`: 0正常/1待复核
- `status`: 0下架/1发布中