spec.md 8.8 KB
阶段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（发布中）的招工 |
排序规则：
- 工种完全匹配优先
- 距离近优先（Haversine公式）
- 发布时间新优先
返回数据：
- 招工信息（工种、价格、人数、地点）
- 距离（公里）
- 果农姓名
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天无操作自动恢复为空闲。
逻辑：
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%)