# 洒渔镇苹果产业供需对接平台 — 需求规格说明书 V2

> 版本：V2.0
> 编制日期：2026-05-30
> 基于：功能清单V1.0 + 6角色需求研讨V2（投票≥5/6通过）
> 变更：视频上传改为直传OSS、新增信用机制、拨号日志、审核SLA升级、API前缀分离

---

## 一、项目概述

### 1.1 项目背景
洒渔镇是云南昭通苹果主产区，产业链涉及果农、采摘工人、收购客商、农资供应商四类主体。当前供需信息主要靠熟人介绍和集市口口相传，效率低、信息不对称。本平台通过微信小程序+后台管理系统，实现苹果产业供需信息的线上化对接。

### 1.2 项目目标
- 为果农提供招工、找客商、买农资的一站式服务
- 为工人提供就近找活、技能展示的信息渠道
- 为客商提供货源筛选、精准对接的信息平台
- 为政府管理部门提供产业数据统计和决策支持

### 1.3 用户角色

| 角色 | 代号 | 说明 |
|------|------|------|
| 果农 | GROWER | 苹果种植户，发布招工、展示货源 |
| 工人 | WORKER | 采摘/套袋/搬运等农业工人 |
| 客商 | BUYER | 苹果收购商/公司 |
| 农资商 | SUPPLIER | 化肥/果袋/农药等农资店铺 |
| 超级管理员 | ADMIN | 系统最高权限 |
| 数据录入员 | DATA_ENTRY | Excel导入、用户管理 |
| 审核员 | AUDITOR | 内容审核、投诉处理 |
| 运维人员 | OPERATOR | 数据大屏、报表导出 |

---

## 二、功能需求

### 2.1 公共基础模块

#### 2.1.1 微信登录（P0）
- **流程**：微信`wx.login()`→后端换openid+手机号→JWT token
- **身份路由**：
  - 0个身份 → 提示"未找到信息，请联系村委会"
  - 1个身份 → 直接进入对应首页
  - N个身份 → 身份选择页（大卡片列表，≥120px高度）
- **兜底**：拒绝授权→弹窗引导→联系村委会管理员后台绑定
- **验收**：
  - [ ] 新用户首次登录提示联系村委会
  - [ ] 单身份用户直接进入对应首页
  - [ ] 多身份用户展示身份选择页
  - [ ] 拒绝授权后可联系管理员绑定

#### 2.1.2 个人中心（P1）
- 退出登录（清除Token）
- 关于我们（平台介绍、联系方式、免责声明）

---

### 2.2 果农端 (GROWER)

#### 2.2.1 首页
| 功能 | 优先级 | 描述 |
|------|--------|------|
| 问候语 | P1 | "早安，[姓名]！" + 当地实时天气 |
| 今日行情 | P0 | 苹果品种收购价格区间，涨价红/降价绿色块，展示更新时间 |
| 金刚区 | P0 | 4个核心入口：找工人、找客商、买农资、发布需求 |

#### 2.2.2 找工人（P0）
- **筛选**：工种（采摘/套袋/搬运/装卸）
- **列表**：工人姓名、工种标签、报价（元/天或元/个）、距离、状态（空闲/忙碌）
- **拨号**：点击调用单独拨号接口（记录日志），唤起系统拨号
- **距离**：果园地址→经纬度→Haversine公式

#### 2.2.3 发布招工（P0）
- **表单**：工种（多选）、价格、价格单位（元/天|元/个）、人数、天数、工作地点、备注（支持语音输入）
- **发布规则**：免审核直接发布
- **内容管控**：敏感关键词自动标记→待复核列表→人工审核→后台强制下架
- **管理**：下架、重新编辑、查看历史记录（P1）

#### 2.2.4 找客商（P0）
- **列表**：客商姓名/公司名、收购品种、收购价格、收购数量、收购点地址
- **拨号**：点击调用拨号接口（记录日志）

#### 2.2.5 买农资（P1）
- **分类**：化肥、果袋、反光膜、选果机、农药
- **列表**：店铺名称、主营产品、距离、联系电话（一键拨号）

#### 2.2.6 我的名片（P0）
- **信息**：苹果品种（多选）、产量（斤）、预期价格（元/斤）、果园地址
- **视频**：前端直传OSS（后端申请凭证），≤50MB/MP4/MOV，前端清除EXIF，后端压缩720p/2Mbps/≤5分钟
- **照片**：≤9张，单张≤5MB，前端清除EXIF
- **审核状态**：待审/已通过/被驳回（驳回显示原因）

---

### 2.3 工人端 (WORKER)

#### 2.3.1 首页·找活（P0）
- **推荐**：工种匹配+距离排序，展示附近招工需求
- **卡片**：工种、价格、天数、人数、果农姓名、距离
- **报名**：点击→短信通知果农→自动变为"忙碌"
- **防骚扰**：同一工人每天对同一果农最多1条短信（自然日）

#### 2.3.2 工作记录（P1）
- **报名列表**：果农姓名、工种、报名时间、状态（已报名/已联系）
- **联系果农**：详情中一键拨号（记录日志）

#### 2.3.3 我的状态（P0）
- **切换**：空闲/工作中，手动切换
- **自动恢复**：3天无操作自动恢复"空闲"（`last_active_time`判断）
- **报名联动**：报名后自动"忙碌"

#### 2.3.4 信用机制
- 被投诉1次 → 警告
- 被投诉2次 → 限制报名24小时
- 被投诉3次 → 状态锁定，需管理员解除

#### 2.3.5 我的信息（P1）
- 展示姓名、技能、电话
- 技能不可自行修改，需联系管理员

---

### 2.4 客商端 (BUYER)

#### 2.4.1 首页·找货（P0）
- **筛选**：苹果品种、价格区间、距离
- **列表**：果农姓名、品种、存量、下树时间、地址

#### 2.4.2 货源详情（P0）
- **信息**：种植面积、苹果规格（糖度/果径）、果园视频/照片
- **联系授权**：
  1. 勾选具体苹果批次（如"红富士 20000斤"）
  2. 解锁该果农电话，有效期7天
  3. 过期需重新勾选
  4. 存储解锁记录：客商ID、果农ID、批次ID、解锁时间、过期时间
- **拨号**：解锁后一键拨号（记录日志）

#### 2.4.3 我的需求（P1）
- 收购偏好：品种（多选）、价格区间、收购总量、收购标准

---

### 2.5 农资端 (SUPPLIER)

#### 2.5.1 我的店铺（P1）
- **信息**：店铺名称、店主姓名、主营种类（多选）、详细地址、联系电话
- **保存**：提交后更新搜索库
- **扩展**：`supplier_shop`表预留`goods`字段，兼容后续在线下单

---

### 2.6 后台管理端

#### 2.6.1 系统管理

| 功能 | 优先级 | 描述 |
|------|--------|------|
| 角色管理 | P0 | 超级管理员、数据录入员、审核员、运维人员 |
| 账号管理 | P0 | 管理员账号增删改查+权限分配 |
| 字典管理 | P0 | 苹果品种、工种、农资种类、行政区划（洒渔镇下辖村） |
| 操作日志 | P1 | 登录/导入/审核/删除等关键操作记录，只追加不修改 |
| 短信配置 | P1 | 短信签名、通知模板配置 |

#### 2.6.2 数据导入与用户管理（核心）

**Excel模板**（P0）：果农/工人/客商/农资四类

**导入流程**（P0）：
1. 下载模板→填写→上传
2. 预览：总行数、有效行数、错误行数、重复行数
3. 错误行红色高亮，鼠标悬停显示原因
4. 确认入库
5. ≤100行同步，>100行异步+完成通知

**字段映射**（P0）：MVP硬编码（手机号/电话→phone，姓名→name等）

**去重规则**：手机号+身份类型唯一，重复数据标记，用户可选跳过或覆盖

**用户池**（P0）：列表搜索、身份绑定/解绑、信息修正（P1）

#### 2.6.3 业务审核中心

| 功能 | 优先级 | 描述 |
|------|--------|------|
| 名片审核 | P0 | 审核果农视频/照片，通过/驳回（需填原因） |
| 待复核列表 | P0 | 敏感关键词标记的招工信息，人工审核 |
| 招工巡查 | P1 | 查看所有招工，强制下架违规内容 |
| 举报处理 | P2 | 处理用户投诉（虚假招工、骚扰电话） |

**审核规则**：
- 单级审核，审核员直接操作
- SLA≤24小时，超时自动提醒审核员
- 超过48小时升级提醒超级管理员
- 操作日志不可篡改

#### 2.6.4 数据统计与决策大屏

| 功能 | 优先级 | 描述 |
|------|--------|------|
| 行情管理 | P0 | 配置首页"今日行情"价格区间 |
| 宏观概览 | P0 | 注册用户总数、今日活跃、供需比 |
| 撮合指标 | P0 | 电话拨打次数、短信发送条数、有效撮合率 |
| 流量指标 | P1 | PV/UV、名片浏览量 |
| 产业地图 | P1 | 果农分布热力图、客商来源TOP10、劳动力分布图 |
| 报表导出 | P1 | 用户列表、撮合记录、操作日志导出Excel |

**技术方案**：定时任务每5分钟刷新，Redis缓存

---

## 三、数据模型设计

### 3.1 核心数据表

#### sys_user（用户基础表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| openid | VARCHAR(64) | UNIQUE | 微信openid |
| phone | VARCHAR(255) | - | 手机号（AES加密存储） |
| phone_hash | VARCHAR(64) | UNIQUE | 手机号SHA256哈希（查询用） |
| nickname | VARCHAR(50) | - | 微信昵称 |
| avatar | VARCHAR(255) | - | 微信头像URL |
| status | TINYINT | INDEX | 状态：0禁用 1正常 |
| last_active_time | DATETIME | - | 最后活跃时间 |
| created_at | DATETIME | - | 创建时间 |
| updated_at | DATETIME | - | 更新时间 |

#### user_identity（身份关联表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_id | BIGINT | INDEX | 关联sys_user.id |
| identity_type | VARCHAR(20) | INDEX | GROWER/WORKER/BUYER/SUPPLIER |
| status | TINYINT | - | 0禁用 1正常 |
| created_at | DATETIME | - | 创建时间 |

#### grower_profile（果农档案表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_identity_id | BIGINT | INDEX | 关联user_identity.id |
| name | VARCHAR(50) | - | 姓名 |
| varieties | VARCHAR(200) | - | 苹果品种（JSON数组） |
| yield_amount | DECIMAL(10,2) | - | 产量（斤） |
| expected_price | DECIMAL(8,2) | - | 预期价格（元/斤） |
| address | VARCHAR(200) | - | 果园地址 |
| latitude | DECIMAL(10,7) | INDEX | 纬度（经纬度复合索引） |
| longitude | DECIMAL(10,7) | INDEX | 经度（经纬度复合索引） |
| video_url | VARCHAR(255) | - | 果园视频OSS URL |
| photos | TEXT | - | 照片URL（JSON数组） |
| audit_status | TINYINT | INDEX | 0待审 1通过 2驳回 |
| audit_remark | VARCHAR(200) | - | 驳回原因 |

#### recruit_info（招工信息表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_identity_id | BIGINT | INDEX | 发布者身份ID |
| work_types | VARCHAR(100) | - | 工种（JSON数组） |
| price | DECIMAL(8,2) | - | 价格 |
| price_unit | VARCHAR(10) | - | DAY/PIECE |
| worker_count | INT | - | 需要人数 |
| days | INT | - | 天数 |
| location | VARCHAR(200) | - | 工作地点 |
| latitude | DECIMAL(10,7) | INDEX | 纬度 |
| longitude | DECIMAL(10,7) | INDEX | 经度 |
| remark | VARCHAR(500) | - | 备注 |
| status | TINYINT | INDEX | 0下架 1发布中 |
| keyword_flag | TINYINT | INDEX | 0正常 1待复核 |
| created_at | DATETIME | - | 发布时间 |

#### worker_profile（工人档案表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_identity_id | BIGINT | INDEX | 关联user_identity.id |
| name | VARCHAR(50) | - | 姓名 |
| skills | VARCHAR(100) | - | 技能（JSON数组） |
| price | DECIMAL(8,2) | - | 报价 |
| price_unit | VARCHAR(10) | - | DAY/PIECE |
| status | TINYINT | INDEX | 0忙碌 1空闲 |
| status_updated_at | DATETIME | - | 状态更新时间 |
| complaint_count | INT | - | 投诉次数 |

#### worker_apply（工人报名表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| worker_identity_id | BIGINT | INDEX | 工人身份ID |
| recruit_id | BIGINT | INDEX | 招工信息ID |
| farmer_identity_id | BIGINT | INDEX | 果农身份ID |
| sms_sent | TINYINT | - | 短信是否已发送 |
| apply_time | DATETIME | - | 报名时间 |

#### sms_daily_limit（短信限流表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| worker_identity_id | BIGINT | INDEX | 工人身份ID |
| farmer_identity_id | BIGINT | INDEX | 果农身份ID |
| sms_date | DATE | INDEX | 发送日期（自然日） |
| sms_count | INT | - | 当日发送次数 |

#### buyer_profile（客商档案表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_identity_id | BIGINT | INDEX | 关联user_identity.id |
| name | VARCHAR(50) | - | 姓名/公司名 |
| varieties | VARCHAR(200) | - | 收购品种（JSON数组） |
| price_range | VARCHAR(50) | - | 价格区间 |
| total_amount | DECIMAL(10,2) | - | 收购总量（斤） |
| standards | VARCHAR(200) | - | 收购标准 |
| address | VARCHAR(200) | - | 收购点地址 |

#### phone_unlock_record（联系授权记录表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| buyer_identity_id | BIGINT | INDEX | 客商身份ID |
| grower_identity_id | BIGINT | INDEX | 果农身份ID |
| batch_id | BIGINT | - | 苹果批次ID |
| unlock_time | DATETIME | - | 解锁时间 |
| expire_time | DATETIME | INDEX | 过期时间（+7天） |

#### supplier_shop（农资店铺表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| user_identity_id | BIGINT | INDEX | 关联user_identity.id |
| shop_name | VARCHAR(50) | - | 店铺名称 |
| owner_name | VARCHAR(50) | - | 店主姓名 |
| categories | VARCHAR(200) | - | 主营种类（JSON数组） |
| address | VARCHAR(200) | - | 详细地址 |
| phone | VARCHAR(20) | - | 联系电话 |
| has_online_order | TINYINT | - | 预留：是否支持在线下单 |

#### market_price（今日行情表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| variety | VARCHAR(50) | INDEX | 苹果品种 |
| price_min | DECIMAL(8,2) | - | 最低价（元/斤） |
| price_max | DECIMAL(8,2) | - | 最高价（元/斤） |
| trend | TINYINT | - | 0持平 1涨价 2降价 |
| update_date | DATE | INDEX | 更新日期 |

#### call_log（拨号日志表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| caller_identity_id | BIGINT | INDEX | 拨号方身份ID |
| callee_identity_id | BIGINT | INDEX | 被拨方身份ID |
| call_time | DATETIME | - | 拨号时间 |

#### audit_log（审核日志表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| operator_id | BIGINT | INDEX | 操作员ID |
| target_type | VARCHAR(50) | - | 审核对象类型 |
| target_id | BIGINT | - | 审核对象ID |
| action | VARCHAR(20) | - | APPROVE/REJECT |
| remark | VARCHAR(200) | - | 备注/驳回原因 |
| created_at | DATETIME | - | 操作时间 |

#### operation_log（操作日志表）
| 字段 | 类型 | 索引 | 说明 |
|------|------|------|------|
| id | BIGINT | PK | 主键 |
| operator_id | BIGINT | INDEX | 操作员ID |
| action | VARCHAR(50) | - | 操作类型 |
| target | VARCHAR(100) | - | 操作对象 |
| detail | TEXT | - | 操作详情 |
| ip | VARCHAR(50) | - | 操作IP |
| created_at | DATETIME | - | 操作时间 |

---

## 四、接口设计概要

### 4.1 认证与权限

**认证机制**：
- 小程序端：微信code→后端换JWT token
- 后台管理端：账号密码→JWT token
- 独立拦截器，互不混淆

**URL前缀**：
- `/api/wx/*` — 小程序端接口
- `/api/admin/*` — 后台管理端接口

**权限模型**：RBAC，所有接口默认拒绝，显式授权

**数据过滤**：接口返回过滤敏感字段，手机号通过单独拨号接口获取

### 4.2 核心接口清单

#### 认证模块
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/wx/auth/login | POST | 微信登录 |
| /api/wx/auth/identity-list | GET | 获取身份列表 |
| /api/admin/auth/login | POST | 后台登录 |

#### 果农模块
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/wx/grower/profile | GET/PUT | 果农档案 |
| /api/wx/grower/recruit | POST/GET | 发布/查询招工 |
| /api/wx/grower/recruit/{id} | PUT/DELETE | 编辑/下架招工 |
| /api/wx/grower/upload-credential | POST | 申请OSS上传凭证 |
| /api/wx/grower/upload-callback | POST | OSS上传完成回调 |

#### 工人模块
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/wx/worker/profile | GET/PUT | 工人档案 |
| /api/wx/worker/recommend | GET | 推荐招工列表 |
| /api/wx/worker/apply | POST | 报名 |
| /api/wx/worker/status | PUT | 切换状态 |

#### 客商模块
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/wx/buyer/profile | GET/PUT | 客商档案 |
| /api/wx/buyer/goods | GET | 货源列表 |
| /api/wx/buyer/goods/{id} | GET | 货源详情 |
| /api/wx/buyer/unlock | POST | 解锁果农电话 |

#### 通用模块
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/wx/call/phone | POST | 获取电话号码（记录拨号日志） |
| /api/wx/market-price | GET | 今日行情 |

#### 后台管理模块
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/admin/import/upload | POST | 上传Excel |
| /api/admin/import/preview | POST | 预览导入数据 |
| /api/admin/import/confirm | POST | 确认入库 |
| /api/admin/users | GET | 用户列表 |
| /api/admin/users/{id} | GET/PUT | 用户详情/修改 |
| /api/admin/audit/list | GET | 审核列表 |
| /api/admin/audit/{id} | PUT | 审核操作 |
| /api/admin/market-price | GET/PUT | 行情配置 |
| /api/admin/dashboard | GET | 大屏数据 |
| /api/admin/complaint/list | GET | 投诉列表 |
| /api/admin/complaint/{id} | PUT | 处理投诉 |

---

## 五、非功能性需求

### 5.1 适老化设计
- 正文≥18px(rem)，标题≥24px
- 媒体查询覆盖320-428px宽度
- 关键按钮≥88×88px，高对比度配色
- 输入处放置麦克风图标，支持语音输入
- 去除复杂动画，简化操作流程

### 5.2 性能要求
- 首屏加载<3秒
- 分页查询20条/页
- 核心索引：手机号唯一索引、身份类型索引、经纬度复合索引
- 支持10万级用户数据

### 5.3 视频处理
- 前端直传OSS（后端申请上传凭证）
- 限制：≤50MB，MP4/MOV格式
- 前端清除EXIF元数据
- 后端压缩：720p，码率2Mbps，时长≤5分钟
- 视频存储OSS，数据库存URL

### 5.4 安全要求
- 手机号AES加密存储，phone_hash(SHA256)索引查询
- 接口返回脱敏：手机号138****1234，姓名张**
- 小程序端脱敏，后台管理员可看完整数据（需权限）
- 敏感操作（导出/批量删除）二次确认+操作日志
- 管理员接口可选IP白名单
- 所有API默认拒绝，显式授权

### 5.5 兼容性
- 兼容主流微信版本
- 兼容iOS和Android系统

---

## 六、约束与假设

### 6.1 约束
- 后端：Java 8 / Spring Boot 1.5.9 / MyBatis
- 数据库：MySQL
- 小程序：微信原生开发
- 短信：阿里云短信API
- 视频存储：阿里云OSS

### 6.2 假设
- 初期用户规模：1000-5000，峰值10万
- 日均招工发布：50-200条
- 日均报名短信：100-500条
- 政府管理员：5-10人

---

## 七、风险清单

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 微信手机号授权拒绝率高 | 用户无法注册 | 中 | 后台手动绑定兜底 |
| 农村网络不稳定 | 视频上传失败 | 高 | 断点续传+压缩 |
| 虚假招工信息 | 平台信誉受损 | 中 | 关键词标记+人工复核+举报+强制下架 |
| 短信成本超预算 | 运营成本增加 | 低 | 月均500元预算控制 |
| 中老年用户不会操作 | 用户流失 | 中 | 适老化设计+语音输入 |
| 数据导入格式不统一 | 导入失败 | 中 | 模板下载+预览校验 |
| 手机号泄露 | 隐私风险 | 低 | AES加密+脱敏+授权机制+EXIF清除 |
| OSS费用超预期 | 成本增加 | 低 | 视频≤50MB/5分钟限制 |

---

## 八、优先级总览

### P0（MVP核心，必须实现）
- 微信登录+身份路由+兜底绑定
- 果农：今日行情、找工人、发布招工（免审核+关键词标记）、找客商、我的名片（含视频/照片）
- 工人：找活推荐、报名通知、状态管理（自动恢复+信用机制）
- 客商：货源筛选、联系授权（7天有效期）
- 后台：角色管理、数据导入（硬编码映射+预览）、名片审核、待复核列表、行情管理、数据大屏（宏观概览+撮合指标）

### P1（应该实现）
- 果农：招工记录、买农资
- 工人：工作记录、我的信息
- 客商：收购偏好
- 农资：店铺信息维护
- 后台：操作日志、短信配置、用户信息修正、招工巡查、流量指标、产业地图、报表导出

### P2（可以延后）
- 关于我们
- 举报处理
- 可配置字段映射
- 在线下单
- 双向匹配