# 阶段一需求规格 — 基础设施与用户体系

> 基于 requirements-specification.md 提取
> 阶段一功能点：20 个

---

## 一、阶段范围

阶段一聚焦**基础设施搭建**和**用户体系建设**，为后续业务功能提供底层支撑。

### 功能模块

| 模块 | 功能点数 | 优先级 |
|------|---------|--------|
| 系统管理（角色/权限/字典/日志） | 6 | P0 |
| 用户注册与认证 | 8 | P0 |
| 首页与行情展示 | 4 | P0 |
| 审核基础框架 | 2 | P1 |

**总计**: 20 个功能点

---

## 二、功能需求

### 2.1 系统管理模块

#### 2.1.1 角色管理（P0）
- **功能**: 系统预置角色（果农/工人/客商/农资商/超级管理员/数据录入员/审核员/运维人员）
- **角色属性**: 角色名称、角色编码、权限列表、状态
- **操作**: 查看角色列表、查看角色详情、分配权限
- **约束**: 系统预置角色不可删除，仅可修改权限配置

#### 2.1.2 账号管理（P0）
- **功能**: 后台管理员账号的增删改查
- **账号属性**: 用户名、密码（BCrypt加密）、姓名、手机号、角色、状态
- **操作**: 创建账号、编辑账号、启用/禁用、重置密码
- **约束**: 
  - 用户名唯一
  - 手机号唯一
  - 密码强度：≥8位，含大小写字母和数字
  - 禁用后不可登录

#### 2.1.3 权限管理（P0）
- **功能**: 基于 RBAC 的权限控制
- **权限模型**: 用户 → 角色 → 权限（菜单+按钮）
- **菜单结构**: 
  - 系统管理（角色管理、账号管理、字典管理、操作日志）
  - 用户管理（果农管理、工人管理、客商管理、农资商管理）
  - 内容审核（招工审核、货源审核、投诉处理）
  - 数据统计（数据大屏、报表导出）
- **约束**: 
  - 默认拒绝，显式授权
  - 超级管理员拥有全部权限
  - 权限变更实时生效

#### 2.1.4 字典管理（P1）
- **功能**: 系统字典数据的维护
- **字典类型**: 
  - 苹果品种（红富士/嘎啦/花牛/秦冠/其他）
  - 工种类型（采摘/套袋/搬运/装卸/其他）
  - 农资种类（化肥/果袋/反光膜/选果机/农药）
  - 行政区划（洒渔镇下辖村）
  - 审核状态（待审/已通过/被驳回）
  - 用户状态（正常/禁用/锁定）
- **操作**: 查看字典列表、新增字典项、编辑字典项、删除字典项
- **约束**: 
  - 字典编码唯一
  - 系统内置字典不可删除
  - 字典变更记录操作日志

#### 2.1.5 操作日志（P1）
- **功能**: 记录管理员的操作行为
- **日志内容**: 操作人、操作时间、操作类型、操作模块、操作内容、IP地址、操作结果
- **操作**: 查看日志列表、按条件筛选、导出日志
- **约束**: 
  - 日志只增不删
  - 保留期限：≥180天
  - 敏感操作（删除、权限变更）必须记录

#### 2.1.6 数据字典初始化（P0）
- **功能**: 系统初始化时导入基础字典数据
- **数据内容**: 
  - 苹果品种：红富士、嘎啦、花牛、秦冠、青苹果、其他
  - 工种类型：采摘、套袋、搬运、装卸、修剪、其他
  - 农资种类：化肥、果袋、反光膜、选果机、农药、其他
  - 行政区划：洒渔镇下辖村（需实际数据）
- **约束**: 初始化数据不可删除，仅可扩展

---

### 2.2 用户注册与认证

#### 2.2.1 微信登录（P0）
- **流程**: 
  1. 小程序端调用 `wx.login()` 获取 code
  2. 后端用 code 换取 openid
  3. 查询 openid 是否已绑定用户
  4. 已绑定 → 签发 JWT token
  5. 未绑定 → 返回提示"未找到信息，请联系村委会"
- **Token 结构**: 
  - payload: userId, identityId, identityType, exp
  - 有效期: 24小时
- **约束**: 
  - 一个 openid 绑定一个用户
  - Token 过期后需重新登录
  - 登录日志记录

#### 2.2.2 后台登录（P0）
- **流程**: 
  1. 输入用户名+密码
  2. 验证用户名存在
  3. 验证密码正确（BCrypt）
  4. 验证账号状态（非禁用）
  5. 签发 JWT token
- **Token 结构**: 
  - payload: userId, username, roleId, exp
  - 有效期: 8小时
- **约束**: 
  - 连续5次密码错误锁定30分钟
  - 登录日志记录
  - 支持退出登录（Token 黑名单）

#### 2.2.3 身份路由（P0）
- **功能**: 根据用户身份数量决定跳转逻辑
- **规则**: 
  - 0个身份 → 提示"未找到信息，请联系村委会"
  - 1个身份 → 直接进入对应首页
  - N个身份 → 身份选择页（大卡片列表，≥120px高度）
- **约束**: 
  - 身份选择后记录到 Token
  - 支持切换身份（重新选择）

#### 2.2.4 用户信息查询（P0）
- **功能**: 查询当前登录用户的基本信息
- **返回**: 用户ID、姓名、手机号（脱敏）、身份列表、当前身份
- **约束**: 
  - 手机号脱敏显示（138****8888）
  - 仅返回当前身份相关的信息

#### 2.2.5 用户状态管理（P0）
- **功能**: 管理员管理用户账号状态
- **状态**: 正常、禁用、锁定
- **操作**: 
  - 启用：恢复正常状态
  - 禁用：禁止登录和业务操作
  - 锁定：因投诉等原因锁定，需人工解锁
- **约束**: 
  - 状态变更记录操作日志
  - 锁定需注明原因

#### 2.2.6 手机号加密存储（P0）
- **功能**: 用户手机号 AES 加密存储
- **方案**: 
  - 明文手机号 → AES 加密 → 存储
  - 明文手机号 → SHA256 → phone_hash（唯一索引）
  - 查询时通过 phone_hash 匹配
- **约束**: 
  - AES 密钥配置在 application.properties
  - phone_hash 唯一索引
  - 接口返回时脱敏显示

#### 2.2.7 身份绑定（P0）
- **功能**: 管理员为用户绑定身份
- **身份类型**: 果农、工人、客商、农资商
- **绑定信息**: 
  - 果农：果园地址、苹果品种、产量
  - 工人：工种、技能、报价
  - 客商：公司名称、收购品种、收购量
  - 农资商：店铺名称、主营产品
- **约束**: 
  - 一个用户可绑定多个身份
  - 每个身份独立管理
  - 身份信息变更需审核

#### 2.2.8 管理员创建用户（P0）
- **功能**: 后台管理员创建用户账号
- **流程**: 
  1. 填写用户基本信息（姓名、手机号）
  2. 选择身份类型
  3. 填写身份详细信息
  4. 创建成功后通知用户（短信）
- **约束**: 
  - 手机号唯一
  - 创建后需用户首次登录激活
  - 记录操作日志

---

### 2.3 首页与行情展示

#### 2.3.1 果农首页（P0）
- **布局**: 
  - 顶部：问候语"早安，[姓名]！" + 当地实时天气
  - 中部：今日行情（苹果品种收购价格区间，涨价红/降价绿色块）
  - 底部：金刚区（4个核心入口：找工人、找客商、买农资、发布需求）
- **数据来源**: 
  - 行情数据：market_price 表
  - 天气数据：第三方 API（可选）
- **约束**: 
  - 行情数据每日更新
  - 展示更新时间

#### 2.3.2 工人首页（P0）
- **布局**: 
  - 顶部：推荐招工（工种匹配+距离排序）
  - 中部：附近招工卡片列表
  - 底部：我的报名、个人档案
- **数据来源**: recruit_info 表
- **约束**: 
  - 按距离排序
  - 展示工种、价格、天数、人数、果农姓名、距离

#### 2.3.3 客商首页（P0）
- **布局**: 
  - 顶部：今日行情
  - 中部：货源推荐（品种匹配+产量排序）
  - 底部：我的联系、收藏
- **数据来源**: grower_profile 表、market_price 表
- **约束**: 
  - 按品种匹配推荐
  - 展示品种、产量、预期价格、果园地址

#### 2.3.4 农资商首页（P1）
- **布局**: 
  - 顶部：店铺概览
  - 中部：商品管理入口
  - 底部：订单管理、店铺设置
- **数据来源**: supplier_shop 表
- **约束**: 
  - 展示店铺基本信息
  - 快捷入口

---

### 2.4 审核基础框架

#### 2.4.1 审核流程（P0）
- **功能**: 通用审核流程框架
- **审核对象**: 果农档案、工人档案、客商档案、招工信息、货源信息
- **审核状态**: 待审、已通过、被驳回
- **审核操作**: 
  - 通过：更新状态为已通过
  - 驳回：更新状态为被驳回，填写驳回原因
- **约束**: 
  - 审核记录操作日志
  - 驳回需注明原因
  - 审核 SLA：≤24小时提醒，48小时升级

#### 2.4.2 审核列表（P1）
- **功能**: 审核员查看待审核列表
- **筛选**: 审核类型、状态、时间范围
- **排序**: 按提交时间倒序
- **约束**: 
  - 仅审核员和超级管理员可访问
  - 展示待审核数量

---

## 三、非功能需求

### 3.1 性能需求
- 接口响应时间：≤500ms（95%请求）
- 并发用户数：≥100
- 数据库连接池：最大连接数 20

### 3.2 安全需求
- 手机号 AES 加密存储
- 密码 BCrypt 加密
- JWT Token 认证
- RBAC 权限控制
- 接口防重放攻击
- SQL 注入防护（MyBatis #{}）

### 3.3 可用性需求
- 系统可用性：≥99%
- 数据备份：每日全量备份
- 故障恢复：≤4小时

### 3.4 兼容性需求
- 微信小程序：基础库 ≥2.0
- 后台管理：Chrome/Firefox/Edge 最新版
- 适老化：正文≥18px(rem)、按钮≥88×88px