阶段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发布中