# 阶段2b 需求规格说明书

> 版本：v1.0
> 日期：2026-05-30
> 阶段：Phase 2b — 工人+客商+农资功能
> 功能点：13个

---

## 1. 功能点总览

| 编号 | 模块 | 功能点 | 优先级 |
|------|------|--------|--------|
| F2b-01 | 工人 | 工人档案管理 | P0 |
| F2b-02 | 工人 | 找活推荐（工种匹配+距离排序） | P0 |
| F2b-03 | 工人 | 报名+短信通知 | P0 |
| F2b-04 | 工人 | 状态管理（空闲/忙碌） | P0 |
| F2b-05 | 工人 | 信用机制（投诉递进处罚） | P1 |
| F2b-06 | 客商 | 客商档案管理 | P0 |
| F2b-07 | 客商 | 货源列表（品种/价格筛选） | P0 |
| F2b-08 | 客商 | 货源详情（含视频/照片） | P0 |
| F2b-09 | 客商 | 联系授权（解锁电话7天有效） | P0 |
| F2b-10 | 客商 | 收购偏好设置 | P1 |
| F2b-11 | 农资 | 店铺信息管理 | P0 |
| F2b-12 | 系统 | 短信配置管理 | P1 |
| F2b-13 | 系统 | 3天自动恢复定时任务 | P1 |

---

## 2. 工人模块

### F2b-01 工人档案管理

**描述**：工人可创建/编辑个人档案，包含姓名、技能、报价等信息。

**数据项**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | VARCHAR(50) | 是 | 姓名 |
| skills | VARCHAR(100) | 否 | 技能（JSON数组，如["采摘工","分拣工"]）|
| price | DECIMAL(8,2) | 否 | 报价 |
| price_unit | VARCHAR(10) | 否 | 计价单位：DAY/PIECE |
| status | TINYINT | 自动 | 0忙碌/1空闲，默认1 |

**业务规则**：
- 首次填写自动创建档案
- 技能从字典表 WORK_TYPE 选取
- 报价可为空（面议）

---

### F2b-02 找活推荐

**描述**：工人查看附近招工信息，按距离和工种匹配排序。

**筛选条件**：
| 条件 | 说明 |
|------|------|
| 工种 | 按工人技能匹配（skills 包含 work_types） |
| 距离 | 按工人位置到招工位置的距离排序 |
| 状态 | 仅显示 status=1（发布中）的招工 |

**排序规则**：
1. 工种完全匹配优先
2. 距离近优先（Haversine公式）
3. 发布时间新优先

**返回数据**：
- 招工信息（工种、价格、人数、地点）
- 距离（公里）
- 果农姓名

---

### F2b-03 报名+短信通知

**描述**：工人对招工信息报名，系统自动发送短信通知果农。

**流程**：
```
工人点击报名
→ 检查是否已报名（worker_apply表）
→ 检查信用状态（complaint_count < 3）
→ 检查短信限流（sms_daily_limit，同一工人对同一果农每天≤1条）
→ INSERT worker_apply
→ 发送短信（阿里云API，异步）
→ 更新 worker_profile.status = 0（忙碌）
→ 返回报名结果
```

**短信内容**：
```
【洒渔用工】[工人姓名]([工种])对您的招工感兴趣，联系电话：[电话]
```

**防骚扰规则**：
- 同一工人每天对同一果农最多1条短信
- 通过 sms_daily_limit 表控制
- 跨天（自然日）自动重置

**异常处理**：
- 短信发送失败：记录日志，不阻断报名
- 短信服务不可用：报名仍成功，标记 sms_sent=0

---

### F2b-04 状态管理

**描述**：工人可手动切换工作状态。

**状态值**：
| 值 | 含义 | 触发方式 |
|----|------|----------|
| 0 | 忙碌 | 报名时自动/手动切换 |
| 1 | 空闲 | 手动切换/3天自动恢复 |

**业务规则**：
- 报名时自动切换为忙碌
- 工人可手动切换为空闲
- 3天无操作自动恢复为空闲（定时任务）
- 状态变更记录 status_updated_at

---

### F2b-05 信用机制

**描述**：基于投诉次数的递进处罚机制。

**处罚规则**：
| 投诉次数 | 处罚 |
|----------|------|
| 1次 | 警告（可继续使用） |
| 2次 | 限制报名24小时 |
| 3次 | 状态锁定，需管理员解除 |

**业务规则**：
- complaint_count 由管理员处理投诉时累加
- 限制报名：检查 lock_time 是否在24小时内
- 状态锁定：status=-1，管理员可手动解除
- 管理员解除后重置 complaint_count=0

---

## 3. 客商模块

### F2b-06 客商档案管理

**描述**：客商可创建/编辑收购档案。

**数据项**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | VARCHAR(50) | 是 | 姓名/公司名 |
| varieties | VARCHAR(200) | 否 | 收购品种（JSON数组）|
| price_range | VARCHAR(50) | 否 | 价格区间（如"3.0-4.5元/斤"）|
| total_amount | DECIMAL(10,2) | 否 | 收购总量（斤）|
| standards | VARCHAR(200) | 否 | 收购标准 |
| address | VARCHAR(200) | 否 | 收购点地址 |

---

### F2b-07 货源列表

**描述**：客商浏览果农发布的货源信息。

**筛选条件**：
| 条件 | 说明 |
|------|------|
| 品种 | 按苹果品种筛选（如红富士） |
| 价格 | 按预期价格范围筛选 |
| 产量 | 按产量范围筛选 |
| 状态 | 仅显示审核通过的果农（audit_status=1） |

**返回数据**：
- 果农姓名
- 品种、产量、预期价格
- 果园地址
- 照片缩略图

---

### F2b-08 货源详情

**描述**：客商查看果农详细信息，包括视频和照片。

**返回数据**：
- 基本信息（同列表）
- 果园视频（video_url）
- 果园照片（photos，JSON数组）
- 经纬度（用于距离计算）

---

### F2b-09 联系授权

**描述**：客商解锁果农电话，获取7天有效联系权限。

**流程**：
```
客商点击"联系果农"
→ 检查是否已有有效解锁记录（phone_unlock_record，未过期）
→ 有记录 → 直接返回电话
→ 无记录/已过期 → INSERT phone_unlock_record（expire_time=now+7天）
→ 返回果农电话
```

**授权规则**：
- 每次解锁有效期7天
- 过期后需重新解锁
- 解锁记录关联 buyer_identity_id + grower_identity_id

---

### F2b-10 收购偏好

**描述**：客商设置收购偏好，用于个性化推荐。

**数据项**：
| 字段 | 说明 |
|------|------|
| preferred_varieties | 偏好品种 |
| price_range | 价格区间 |
| min_quantity | 最小收购量 |

**业务规则**：
- 偏好保存在 buyer_profile 表
- 后续可用于货源推荐（Phase 3）

---

## 4. 农资模块

### F2b-11 店铺信息管理

**描述**：农资商管理店铺基本信息。

**数据项**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| shop_name | VARCHAR(50) | 是 | 店铺名称 |
| owner_name | VARCHAR(50) | 否 | 店主姓名 |
| categories | VARCHAR(200) | 否 | 主营种类（JSON数组）|
| address | VARCHAR(200) | 否 | 详细地址 |
| phone | VARCHAR(20) | 否 | 联系电话 |

**业务规则**：
- 种类从字典表 SUPPLIER_CATEGORY 选取
- 每个农资商一个店铺

---

## 5. 系统模块

### F2b-12 短信配置管理

**描述**：管理员配置短信服务参数。

**配置项**：
| 配置 | 说明 |
|------|------|
| sign_name | 短信签名（如"洒渔用工"）|
| template_code.apply | 报名通知模板编码 |
| template_code.audit | 审核通知模板编码 |

**业务规则**：
- 配置存储在 application.properties
- 管理员可通过后台修改
- 修改后实时生效

---

### F2b-13 3天自动恢复定时任务

**描述**：每天凌晨检查工人状态，3天无操作自动恢复为空闲。

**逻辑**：
```sql
UPDATE worker_profile
SET status = 1, status_updated_at = NOW()
WHERE status = 0
  AND status_updated_at < DATE_SUB(NOW(), INTERVAL 3 DAY)
```

**执行规则**：
- 每天凌晨2:00执行
- 仅恢复状态为"忙碌"且超过3天的工人
- 记录恢复日志

---

## 6. 非功能需求

### 6.1 性能要求
| 指标 | 目标 |
|------|------|
| 推荐列表响应时间 | < 500ms |
| 货源列表响应时间 | < 500ms |
| 短信发送延迟 | < 3s（异步） |

### 6.2 安全要求
- 手机号通过拨号接口获取（记录日志）
- 联系授权7天过期
- 短信限流防骚扰

### 6.3 数据隔离
- 工人只能看到自己的报名记录
- 客商只能解锁自己联系过的果农
- 所有查询带 user_identity_id 过滤

---

## 7. 功能点覆盖检查

| 编号 | 功能点 | 接口覆盖 | 状态 |
|------|--------|----------|------|
| F2b-01 | 工人档案管理 | GET/PUT /api/wx/worker/profile | ✓ |
| F2b-02 | 找活推荐 | GET /api/wx/worker/recommend | ✓ |
| F2b-03 | 报名+短信通知 | POST /api/wx/worker/apply | ✓ |
| F2b-04 | 状态管理 | PUT /api/wx/worker/status | ✓ |
| F2b-05 | 信用机制 | 服务层实现 | ✓ |
| F2b-06 | 客商档案管理 | GET/PUT /api/wx/buyer/profile | ✓ |
| F2b-07 | 货源列表 | GET /api/wx/buyer/goods | ✓ |
| F2b-08 | 货源详情 | GET /api/wx/buyer/goods/{id} | ✓ |
| F2b-09 | 联系授权 | POST /api/wx/buyer/unlock | ✓ |
| F2b-10 | 收购偏好 | GET/PUT /api/wx/buyer/preferences | ✓ |
| F2b-11 | 店铺信息管理 | GET/PUT /api/wx/supplier/shop | ✓ |
| F2b-12 | 短信配置管理 | GET/PUT /api/admin/sms/config | ✓ |
| F2b-13 | 自动恢复定时任务 | @Scheduled | ✓ |

**覆盖率：13/13 (100%)**