阶段2b 架构设计文档
版本：v1.0
日期：2026-05-30
阶段：Phase 2b — 工人+客商+农资功能
1. 架构概览
1.1 分层架构
Controller 层 (/api/wx/*, /api/admin/*)
↓
Service 层 (业务逻辑)
↓
Mapper 层 (MyBatis XML)
↓
数据库层 (MySQL)
1.2 新增模块
| 模块 |
说明 |
优先级 |
| WorkerModule |
工人端（推荐、报名、状态、信用） |
P0 |
| BuyerModule |
客商端（货源、授权、偏好） |
P0 |
| SupplierModule |
农资端（店铺） |
P0 |
| SmsModule |
短信服务（配置、发送、限流） |
P1 |
2. 数据模型设计
2.1 新增表
worker_apply（报名表）
- id: BIGINT AUTO_INCREMENT PRIMARY KEY
- worker_identity_id: BIGINT NOT NULL
- recruit_id: BIGINT NOT NULL
- farmer_identity_id: BIGINT NOT NULL
- sms_sent: TINYINT DEFAULT 0
- apply_time: DATETIME DEFAULT CURRENT_TIMESTAMP
phone_unlock_record（联系授权表）
- id: BIGINT AUTO_INCREMENT PRIMARY KEY
- buyer_identity_id: BIGINT NOT NULL
- grower_identity_id: BIGINT NOT NULL
- batch_id: BIGINT
- unlock_time: DATETIME DEFAULT CURRENT_TIMESTAMP
- expire_time: DATETIME NOT NULL
sms_daily_limit（短信限流表）
- id: BIGINT AUTO_INCREMENT PRIMARY KEY
- worker_identity_id: BIGINT NOT NULL
- farmer_identity_id: BIGINT NOT NULL
- sms_date: DATE NOT NULL
- sms_count: INT DEFAULT 0
- UNIQUE KEY (worker_identity_id, farmer_identity_id, sms_date)
2.2 现有表扩展
worker_profile 扩展字段
- lock_time: DATETIME (锁定时间)
buyer_profile 扩展字段
- preferred_varieties: VARCHAR(200) (偏好品种JSON)
- min_quantity: DECIMAL(10,2) (最小收购量)
3. 接口设计
3.1 工人模块接口（6个）
| 接口 |
方法 |
说明 |
| /api/wx/worker/profile |
GET |
获取工人档案 |
| /api/wx/worker/profile |
PUT |
创建/更新工人档案 |
| /api/wx/worker/recommend |
GET |
推荐招工列表 |
| /api/wx/worker/apply |
POST |
报名招工 |
| /api/wx/worker/status |
PUT |
切换工作状态 |
| /api/wx/worker/applies |
GET |
报名历史 |
3.2 客商模块接口（7个）
| 接口 |
方法 |
说明 |
| /api/wx/buyer/profile |
GET |
获取客商档案 |
| /api/wx/buyer/profile |
PUT |
创建/更新客商档案 |
| /api/wx/buyer/goods |
GET |
货源列表 |
| /api/wx/buyer/goods/{id} |
GET |
货源详情 |
| /api/wx/buyer/unlock |
POST |
解锁果农电话 |
| /api/wx/buyer/preferences |
GET |
获取收购偏好 |
| /api/wx/buyer/preferences |
PUT |
更新收购偏好 |
3.3 农资模块接口（2个）
| 接口 |
方法 |
说明 |
| /api/wx/supplier/shop |
GET |
获取店铺信息 |
| /api/wx/supplier/shop |
PUT |
创建/更新店铺信息 |
3.4 后台管理接口（2个）
| 接口 |
方法 |
说明 |
| /api/admin/sms/config |
GET |
获取短信配置 |
| /api/admin/sms/config |
PUT |
更新短信配置 |
4. 服务层设计
4.1 WorkerRecommendService
- getRecommendList(workerIdentityId, workType, page, pageSize): 推荐招工列表
4.2 WorkerApplyService
- apply(workerIdentityId, recruitId): 报名招工
- getApplyList(workerIdentityId, page, pageSize): 报名历史
4.3 WorkerStatusService
- updateStatus(workerIdentityId, status): 切换状态
- autoRecoverStatus(): 自动恢复（定时任务）
4.4 CreditService
- checkCredit(workerIdentityId): 检查信用状态
- addComplaint(workerIdentityId): 增加投诉计数
- unlock(workerIdentityId): 解除锁定
4.5 BuyerGoodsService
- getGoodsList(variety, priceMin, priceMax, page, pageSize): 货源列表
- getGoodsDetail(growerId): 货源详情
4.6 PhoneUnlockService
- unlockPhone(buyerIdentityId, growerIdentityId): 解锁电话
- isUnlocked(buyerIdentityId, growerIdentityId): 检查是否已解锁
4.7 SmsService
- sendApplyNotification(workerIdentityId, farmerIdentityId, recruitId): 发送报名通知
- checkDailyLimit(workerIdentityId, farmerIdentityId): 检查短信限流
4.8 SupplierShopService
- getShop(userIdentityId): 获取店铺信息
- saveShop(userIdentityId, shopData): 创建/更新店铺
5. Mapper层设计
5.1 新增Mapper
| Mapper |
表 |
方法 |
| WorkerApplyMapper |
worker_apply |
insert, selectByWorkerId, selectByRecruitId |
| PhoneUnlockMapper |
phone_unlock_record |
insert, selectValid, selectByBuyerAndGrower |
| SmsDailyLimitMapper |
sms_daily_limit |
insert, update, selectByWorkerAndFarmer |
5.2 现有Mapper扩展
| Mapper |
新增方法 |
| RecruitInfoMapper |
selectForRecommend |
| WorkerProfileMapper |
updateStatus, updateComplaintCount |
| BuyerProfileMapper |
updatePreferences |
6. 流程设计
6.1 报名+短信通知流程
- 工人POST报名请求
- 检查信用状态（complaint_count < 3）
- 检查短信限流（每天每对工人-果农最多1条）
- 插入worker_apply记录
- 更新worker_profile.status = 0（忙碌）
- 异步发送短信通知
- 返回报名结果
6.2 联系授权流程
- 客商POST解锁请求
- 检查是否已有有效解锁记录（未过期）
- 有记录：直接返回电话
- 无记录：插入phone_unlock_record（7天有效期）
- 返回电话
7. 安全设计
7.1 认证授权
7.2 数据安全
- 手机号通过拨号接口获取（记录日志）
- 联系授权7天过期
- 短信限流防骚扰
8. 性能设计
8.1 数据库优化
- 招工查询：经纬度复合索引
- 报名查询：worker_identity_id索引
- 授权查询：buyer+grower复合索引
8.2 异步处理
9. 接口统计
| 模块 |
接口数 |
| 工人模块 |
6 |
| 客商模块 |
7 |
| 农资模块 |
2 |
| 后台管理 |
2 |
| 总计 |
17 |
验收标准：新增接口 >= 15 → 达标
