# 阶段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 报名+短信通知流程
1. 工人POST报名请求
2. 检查信用状态（complaint_count < 3）
3. 检查短信限流（每天每对工人-果农最多1条）
4. 插入worker_apply记录
5. 更新worker_profile.status = 0（忙碌）
6. 异步发送短信通知
7. 返回报名结果

### 6.2 联系授权流程
1. 客商POST解锁请求
2. 检查是否已有有效解锁记录（未过期）
3. 有记录：直接返回电话
4. 无记录：插入phone_unlock_record（7天有效期）
5. 返回电话

---

## 7. 安全设计

### 7.1 认证授权
- 所有/api/wx/*接口需要JWT认证
- userId从JWT解析，通过@RequestAttribute注入
- 数据查询带user_identity_id过滤

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

---

## 8. 性能设计

### 8.1 数据库优化
- 招工查询：经纬度复合索引
- 报名查询：worker_identity_id索引
- 授权查询：buyer+grower复合索引

### 8.2 异步处理
- 短信发送异步化（@Async）
- 视频压缩异步化（已有）

---

## 9. 接口统计

| 模块 | 接口数 |
|------|--------|
| 工人模块 | 6 |
| 客商模块 | 7 |
| 农资模块 | 2 |
| 后台管理 | 2 |
| **总计** | **17** |

**验收标准**：新增接口 >= 15 → 达标