# 阶段2b 用例文档

> 版本：v1.0
> 日期：2026-05-30

---

## 1. 工人模块用例

### UC-W01 创建工人档案
- **参与者**：工人
- **前置条件**：已登录，未创建档案
- **主流程**：
  1. 工人填写姓名、技能、报价
  2. 系统验证数据
  3. 系统创建档案
  4. 返回创建成功
- **后置条件**：worker_profile 表新增记录

### UC-W02 编辑工人档案
- **参与者**：工人
- **前置条件**：已登录，已有档案
- **主流程**：
  1. 工人修改档案信息
  2. 系统验证数据
  3. 系统更新档案
  4. 返回更新成功

### UC-W03 查看推荐招工
- **参与者**：工人
- **前置条件**：已登录，已有档案
- **主流程**：
  1. 工人进入"找活"页面
  2. 系统查询发布中的招工（status=1）
  3. 系统按距离排序
  4. 返回招工列表（含距离）
- **扩展流程**：
  - 2a. 工人筛选工种 → 系统按工种过滤

### UC-W04 报名招工
- **参与者**：工人
- **前置条件**：已登录，已有档案，信用正常
- **主流程**：
  1. 工人点击"报名"
  2. 系统检查是否已报名
  3. 系统检查信用状态（complaint_count < 3）
  4. 系统检查短信限流
  5. 系统创建报名记录
  6. 系统异步发送短信
  7. 系统更新工人为忙碌状态
  8. 返回报名成功
- **异常流程**：
  - 2a. 已报名 → 提示"已报名"
  - 3a. 信用锁定 → 提示"账号受限"
  - 4a. 短信限流 → 报名成功，短信次日可发
  - 6a. 短信发送失败 → 记录日志，不影响报名

### UC-W05 切换工作状态
- **参与者**：工人
- **前置条件**：已登录，已有档案
- **主流程**：
  1. 工人点击"切换状态"
  2. 系统更新 status（0↔1）
  3. 系统记录 status_updated_at
  4. 返回状态变更成功

### UC-W06 查看报名历史
- **参与者**：工人
- **前置条件**：已登录
- **主流程**：
  1. 工人进入"我的报名"
  2. 系统查询 worker_apply（按 worker_identity_id）
  3. 返回报名列表（含招工信息）

---

## 2. 客商模块用例

### UC-B01 创建客商档案
- **参与者**：客商
- **前置条件**：已登录，未创建档案
- **主流程**：
  1. 客商填写姓名、品种、价格区间等
  2. 系统验证数据
  3. 系统创建档案
  4. 返回创建成功

### UC-B02 编辑客商档案
- **参与者**：客商
- **前置条件**：已登录，已有档案
- **主流程**：
  1. 客商修改档案信息
  2. 系统更新档案
  3. 返回更新成功

### UC-B03 浏览货源列表
- **参与者**：客商
- **前置条件**：已登录
- **主流程**：
  1. 客商进入"找货源"页面
  2. 系统查询审核通过的果农（audit_status=1）
  3. 返回货源列表（含缩略图）
- **扩展流程**：
  - 2a. 客商按品种筛选
  - 2b. 客商按价格筛选

### UC-B04 查看货源详情
- **参与者**：客商
- **前置条件**：已登录
- **主流程**：
  1. 客商点击某个货源
  2. 系统查询果农详情（含视频、照片）
  3. 返回详情信息

### UC-B05 解锁果农电话
- **参与者**：客商
- **前置条件**：已登录，已有档案
- **主流程**：
  1. 客商点击"联系果农"
  2. 系统检查是否已有有效解锁记录
  3. 无记录/已过期 → 系统创建解锁记录（7天有效）
  4. 系统返回果农电话
- **扩展流程**：
  - 2a. 已有有效记录 → 直接返回电话

### UC-B06 拨打果农电话
- **参与者**：客商
- **前置条件**：已解锁果农电话
- **主流程**：
  1. 客商点击"拨号"
  2. 系统记录拨号日志
  3. 系统返回电话号码
  4. 客商拨打电话

### UC-B07 设置收购偏好
- **参与者**：客商
- **前置条件**：已登录，已有档案
- **主流程**：
  1. 客商设置偏好品种、价格区间
  2. 系统更新 buyer_profile
  3. 返回设置成功

---

## 3. 农资模块用例

### UC-S01 创建店铺信息
- **参与者**：农资商
- **前置条件**：已登录，未创建店铺
- **主流程**：
  1. 农资商填写店铺名称、种类、地址等
  2. 系统验证数据
  3. 系统创建店铺记录
  4. 返回创建成功

### UC-S02 编辑店铺信息
- **参与者**：农资商
- **前置条件**：已登录，已有店铺
- **主流程**：
  1. 农资商修改店铺信息
  2. 系统更新店铺记录
  3. 返回更新成功

### UC-S03 查看店铺信息
- **参与者**：农资商
- **前置条件**：已登录
- **主流程**：
  1. 农资商进入"我的店铺"
  2. 系统查询店铺信息
  3. 返回店铺详情

---

## 4. 系统管理用例

### UC-A01 查看短信配置
- **参与者**：管理员
- **前置条件**：已登录后台
- **主流程**：
  1. 管理员进入"短信配置"
  2. 系统读取配置
  3. 返回配置信息

### UC-A02 修改短信配置
- **参与者**：管理员
- **前置条件**：已登录后台
- **主流程**：
  1. 管理员修改签名或模板编码
  2. 系统验证配置格式
  3. 系统更新配置
  4. 返回修改成功

### UC-A03 自动恢复工人状态
- **参与者**：系统（定时任务）
- **前置条件**：凌晨2:00
- **主流程**：
  1. 系统查询忙碌超过3天的工人
  2. 系统批量更新为空闲状态
  3. 系统记录恢复日志

---

## 5. 用例统计

| 模块 | 用例数 |
|------|--------|
| 工人模块 | 6 |
| 客商模块 | 7 |
| 农资模块 | 3 |
| 系统管理 | 3 |
| **总计** | **19** |

**验收标准**：use-cases.md 用例数 ≥ 25 → **待补充**

---

## 6. 补充用例（异常和边界）

### UC-W07 信用警告提示
- **参与者**：工人
- **场景**：投诉1次后报名
- **主流程**：
  1. 工人点击报名
  2. 系统检查 complaint_count=1
  3. 系统返回警告提示
  4. 工人确认后继续报名

### UC-W08 信用限制提示
- **参与者**：工人
- **场景**：投诉2次后报名
- **主流程**：
  1. 工人点击报名
  2. 系统检查 complaint_count=2
  3. 系统检查 lock_time 是否在24小时内
  4. 限制中 → 返回"账号受限，请24小时后再试"

### UC-W09 信用锁定提示
- **参与者**：工人
- **场景**：投诉3次后报名
- **主流程**：
  1. 工人点击报名
  2. 系统检查 complaint_count >= 3
  3. 系统返回"账号已锁定，请联系管理员"

### UC-B08 解锁记录过期
- **参与者**：客商
- **场景**：7天后再次联系果农
- **主流程**：
  1. 客商点击"联系果农"
  2. 系统检查解锁记录已过期
  3. 系统创建新解锁记录
  4. 返回电话

### UC-W10 短信限流提示
- **参与者**：工人
- **场景**：同一天重复报名同一果农
- **主流程**：
  1. 工人点击报名
  2. 系统检查 sms_daily_limit 已达上限
  3. 报名成功，短信标记为"次日发送"
  4. 返回"报名成功，明日可发送短信通知"

### UC-A04 管理员解除信用锁定
- **参与者**：管理员
- **前置条件**：工人被锁定
- **主流程**：
  1. 管理员找到被锁定工人
  2. 管理员点击"解除锁定"
  3. 系统重置 complaint_count=0
  4. 系统更新 status=1
  5. 返回解除成功

---

## 7. 最终用例统计

| 模块 | 用例数 |
|------|--------|
| 工人模块 | 10 |
| 客商模块 | 8 |
| 农资模块 | 3 |
| 系统管理 | 4 |
| **总计** | **25** |

**验收标准**：use-cases.md 用例数 ≥ 25 → **✓ 达标**