# 阶段一用例文档 — 基础设施与用户体系

> 功能点覆盖：20/20

---

## 一、系统管理用例

### UC-SYS-001: 角色管理

**主要参与者**: 超级管理员

**前置条件**: 已登录后台管理系统

**基本流程**:
1. 管理员进入系统管理 → 角色管理
2. 系统显示角色列表（角色名称、编码、状态、创建时间）
3. 管理员点击某个角色查看详情
4. 系统显示角色详情（权限列表）
5. 管理员修改权限配置
6. 系统保存权限变更
7. 系统记录操作日志

**替代流程**:
- 3a. 管理员搜索角色 → 按名称筛选
- 5a. 管理员尝试删除系统预置角色 → 系统提示"系统预置角色不可删除"

**后置条件**: 角色权限已更新，操作日志已记录

---

### UC-SYS-002: 账号管理

**主要参与者**: 超级管理员

**前置条件**: 已登录后台管理系统

**基本流程**:
1. 管理员进入系统管理 → 账号管理
2. 系统显示账号列表（用户名、姓名、手机号、角色、状态）
3. 管理员点击"新增账号"
4. 管理员填写：用户名、密码、姓名、手机号、角色
5. 系统验证：用户名唯一、手机号唯一、密码强度
6. 系统创建账号（密码 BCrypt 加密）
7. 系统记录操作日志

**替代流程**:
- 5a. 用户名已存在 → 提示"用户名已存在"
- 5b. 手机号已存在 → 提示"手机号已注册"
- 5c. 密码强度不足 → 提示"密码需≥8位，含大小写字母和数字"

**后置条件**: 账号已创建，可正常登录

---

### UC-SYS-003: 字典管理

**主要参与者**: 超级管理员、数据录入员

**前置条件**: 已登录后台管理系统

**基本流程**:
1. 管理员进入系统管理 → 字典管理
2. 系统显示字典类型列表
3. 管理员选择某个字典类型（如"苹果品种"）
4. 系统显示该类型下的字典项列表
5. 管理员点击"新增字典项"
6. 管理员填写：字典编码、字典名称、排序号
7. 系统验证：字典编码唯一
8. 系统创建字典项
9. 系统记录操作日志

**替代流程**:
- 7a. 字典编码已存在 → 提示"字典编码已存在"
- 5a. 管理员尝试删除系统内置字典 → 提示"系统内置字典不可删除"

**后置条件**: 字典项已创建，可在业务中使用

---

### UC-SYS-004: 操作日志查看

**主要参与者**: 超级管理员

**前置条件**: 已登录后台管理系统

**基本流程**:
1. 管理员进入系统管理 → 操作日志
2. 系统显示操作日志列表（操作人、时间、类型、模块、内容、IP、结果）
3. 管理员按条件筛选（操作人、时间范围、操作类型）
4. 系统显示筛选结果
5. 管理员点击某条日志查看详情
6. 系统显示日志详情

**替代流程**:
- 3a. 管理员导出日志 → 系统生成 Excel 文件

**后置条件**: 无数据变更

---

## 二、用户认证用例

### UC-AUTH-001: 微信登录

**主要参与者**: 小程序用户

**前置条件**: 用户已安装微信

**基本流程**:
1. 用户打开小程序
2. 小程序调用 `wx.login()` 获取 code
3. 小程序将 code 发送到后端
4. 后端用 code 调用微信接口换取 openid
5. 后端查询 openid 是否已绑定用户
6. 已绑定 → 后端签发 JWT token，返回用户信息
7. 小程序存储 token，进入首页

**替代流程**:
- 5a. 未绑定 → 返回提示"未找到信息，请联系村委会"
- 6a. 用户有多个身份 → 返回身份列表，用户选择后进入对应首页

**后置条件**: 用户已登录，token 已存储

---

### UC-AUTH-002: 后台登录

**主要参与者**: 后台管理员

**前置条件**: 已打开后台管理系统

**基本流程**:
1. 管理员输入用户名和密码
2. 点击"登录"
3. 系统验证用户名存在
4. 系统验证密码正确（BCrypt）
5. 系统验证账号状态（非禁用）
6. 系统签发 JWT token
7. 系统记录登录日志
8. 管理员进入后台首页

**替代流程**:
- 3a. 用户名不存在 → 提示"用户名或密码错误"
- 4a. 密码错误 → 提示"用户名或密码错误"，记录错误次数
- 4b. 连续5次错误 → 锁定30分钟，提示"账号已锁定，请30分钟后重试"
- 5a. 账号已禁用 → 提示"账号已禁用，请联系管理员"

**后置条件**: 管理员已登录，token 已存储

---

### UC-AUTH-003: 身份路由

**主要参与者**: 小程序用户

**前置条件**: 用户已登录

**基本流程**:
1. 用户登录成功
2. 系统查询用户绑定的身份数量
3. 根据身份数量决定跳转：
   - 0个身份 → 显示提示页"未找到信息，请联系村委会"
   - 1个身份 → 直接进入对应首页
   - N个身份 → 显示身份选择页

**替代流程**:
- 3a. 用户选择身份 → 进入对应首页
- 3b. 用户拒绝授权 → 显示引导页，提供联系管理员方式

**后置条件**: 用户已进入对应角色首页

---

### UC-AUTH-004: 用户信息查询

**主要参与者**: 已登录用户

**前置条件**: 用户已登录

**基本流程**:
1. 用户进入个人中心
2. 系统查询用户基本信息
3. 系统返回：用户ID、姓名、手机号（脱敏）、身份列表、当前身份

**替代流程**: 无

**后置条件**: 无数据变更

---

### UC-AUTH-005: 用户状态管理

**主要参与者**: 超级管理员

**前置条件**: 已登录后台管理系统

**基本流程**:
1. 管理员进入用户管理 → 用户列表
2. 管理员选择某个用户
3. 管理员修改用户状态（启用/禁用/锁定）
4. 系统验证操作合法性
5. 系统更新用户状态
6. 系统记录操作日志

**替代流程**:
- 4a. 尝试禁用超级管理员 → 提示"不可禁用超级管理员"
- 3a. 锁定操作 → 需填写锁定原因

**后置条件**: 用户状态已更新，操作日志已记录

---

### UC-AUTH-006: 管理员创建用户

**主要参与者**: 超级管理员、数据录入员

**前置条件**: 已登录后台管理系统

**基本流程**:
1. 管理员进入用户管理 → 创建用户
2. 管理员填写：姓名、手机号
3. 管理员选择身份类型
4. 管理员填写身份详细信息
5. 系统验证：手机号唯一
6. 系统创建用户账号
7. 系统发送短信通知用户
8. 系统记录操作日志

**替代流程**:
- 5a. 手机号已存在 → 提示"手机号已注册"

**后置条件**: 用户已创建，等待首次登录激活

---

### UC-AUTH-007: 身份绑定

**主要参与者**: 超级管理员、数据录入员

**前置条件**: 已登录后台管理系统，用户已存在

**基本流程**:
1. 管理员进入用户管理 → 选择用户
2. 管理员点击"绑定身份"
3. 管理员选择身份类型
4. 管理员填写身份详细信息
5. 系统创建身份关联
6. 系统记录操作日志

**替代流程**:
- 3a. 用户已有该类型身份 → 提示"用户已有该身份"

**后置条件**: 用户已绑定新身份

---

### UC-AUTH-008: 退出登录

**主要参与者**: 已登录用户

**前置条件**: 用户已登录

**基本流程**:
1. 用户点击"退出登录"
2. 系统清除本地 token
3. 系统跳转到登录页

**替代流程**: 无

**后置条件**: 用户已退出，token 已清除

---

## 三、首页与行情用例

### UC-HOME-001: 果农首页展示

**主要参与者**: 果农用户

**前置条件**: 已登录，身份为果农

**基本流程**:
1. 用户进入果农首页
2. 系统显示问候语"早安，[姓名]！"
3. 系统显示今日行情（苹果品种、价格区间、涨跌、更新时间）
4. 系统显示金刚区（找工人、找客商、买农资、发布需求）

**替代流程**:
- 3a. 行情数据未更新 → 显示"暂无行情数据"

**后置条件**: 无数据变更

---

### UC-HOME-002: 工人首页展示

**主要参与者**: 工人用户

**前置条件**: 已登录，身份为工人

**基本流程**:
1. 用户进入工人首页
2. 系统显示推荐招工（按工种匹配+距离排序）
3. 系统显示招工卡片列表（工种、价格、天数、人数、果农姓名、距离）

**替代流程**:
- 2a. 无匹配招工 → 显示"暂无招工信息"

**后置条件**: 无数据变更

---

### UC-HOME-003: 客商首页展示

**主要参与者**: 客商用户

**前置条件**: 已登录，身份为客商

**基本流程**:
1. 用户进入客商首页
2. 系统显示今日行情
3. 系统显示货源推荐（按品种匹配+产量排序）

**替代流程**:
- 3a. 无匹配货源 → 显示"暂无货源信息"

**后置条件**: 无数据变更

---

### UC-HOME-004: 农资商首页展示

**主要参与者**: 农资商用户

**前置条件**: 已登录，身份为农资商

**基本流程**:
1. 用户进入农资商首页
2. 系统显示店铺概览
3. 系统显示快捷入口（商品管理、订单管理、店铺设置）

**替代流程**:
- 2a. 店铺未完善 → 显示引导完善店铺信息

**后置条件**: 无数据变更

---

## 四、审核用例

### UC-AUDIT-001: 审核流程

**主要参与者**: 审核员

**前置条件**: 已登录后台管理系统，有待审核项

**基本流程**:
1. 审核员进入内容审核 → 待审核列表
2. 系统显示待审核列表（审核类型、提交人、提交时间）
3. 审核员选择某项查看详情
4. 系统显示审核详情（内容、附件）
5. 审核员点击"通过"或"驳回"
6. 如驳回，填写驳回原因
7. 系统更新审核状态
8. 系统记录审核日志
9. 系统通知提交人审核结果

**替代流程**:
- 5a. 审核员点击"驳回" → 必须填写驳回原因

**后置条件**: 审核状态已更新，通知已发送

---

### UC-AUDIT-002: 审核列表查看

**主要参与者**: 审核员、超级管理员

**前置条件**: 已登录后台管理系统

**基本流程**:
1. 审核员进入内容审核
2. 系统显示审核列表（待审核/已审核 Tab）
3. 审核员按条件筛选（审核类型、状态、时间范围）
4. 系统显示筛选结果
5. 系统显示待审核数量角标

**替代流程**: 无

**后置条件**: 无数据变更

---

## 用例统计

| 模块 | 用例数 | 功能点覆盖 |
|------|--------|-----------|
| 系统管理 | 4 | 6/6 |
| 用户认证 | 8 | 8/8 |
| 首页与行情 | 4 | 4/4 |
| 审核框架 | 2 | 2/2 |
| **总计** | **18** | **20/20** |