# 鱼测云分润管理系统需求规格说明书

## 1. 文档说明

### 1.1 编写目的
本文档基于当前代码仓库 `profit-sharing-management-master` 的后端实现，对系统业务范围、角色权限、核心流程、功能需求和非功能需求进行还原和整理，用于：

- 帮助快速理解项目覆盖的业务域
- 作为后续需求澄清、系统改造和前后端联调的基础文档
- 为补齐前端、测试用例、实施手册提供输入

### 1.2 编写依据
本文档主要依据以下内容整理：

- `fishery-admin` 中的业务控制器
- `fishery-core` 中的领域模型、服务实现、SQL 映射
- `fishery-system` 中的登录、用户、权限能力
- `fishery-quartz` 中的定时任务
- `application.yml` 与 `application-dev.yml` 中的运行配置

### 1.3 说明与边界

- 当前仓库主要是后端工程，未包含完整前端页面源码，因此界面交互以接口能力反推。
- README 为占位内容，业务口径以代码实现为准。
- 本文档区分“已明确实现的能力”和“根据实现推断的业务含义”。
- 对于角色名称、菜单文案、审批组织关系等未在代码中直接定义的内容，仅做合理归纳，不作为最终主数据标准。

## 2. 项目概述

### 2.1 系统名称

- 系统工程描述：鱼测云分润管理系统
- 运行入口名称：`fishery-admin`
- 默认访问上下文：`/equipment`

### 2.2 业务定位
该系统是一个“养殖设备管理 + 分润结算”的后台与移动端支撑系统，围绕鱼塘/池塘设备、充值订单、经销分润和提现结算展开，覆盖以下业务链路：

1. 设备接入与设备归属管理
2. 池塘与设备监测数据查询
3. 告警信息查看与控制器开关控制
4. 经销/层级用户分润比例配置
5. 充值订单自动分润计算
6. 分润记录统计、退款冲销
7. 用户提现申请与打款处理
8. 短信验证码登录与 APP 用户管理

### 2.3 总体架构
系统为多模块 Spring Boot 单体工程，采用动态数据源。

- `fishery-admin`
  说明：Web API 入口、业务控制器
- `fishery-system`
  说明：系统管理能力，如登录、用户、角色、菜单、部门、字典、日志
- `fishery-core`
  说明：分润、设备绑定、提现、监测大屏等业务核心
- `fishery-quartz`
  说明：定时任务，包括分润计算、设备绑定同步、告警码处理
- `fishery-generator`
  说明：代码生成
- `fishery-demo`
  说明：示例模块
- `fishery-common`
  说明：通用基础组件

### 2.4 数据源边界
系统至少涉及两套业务数据。

- 主数据源 `master`
  说明：本系统后台管理数据，如 `sys_*`、`basic_*`
- 辅助数据源 `test`
  说明：外部设备/订单/APP 用户数据，如 `aqu_user`、`aqu_device`、`aqu_pay_device`、`aqu_message_warn`
- 另有 `taos` 数据源配置
  说明：已配置 TDengine 连接，当前在本仓库业务代码中未见明确使用

## 3. 业务角色

### 3.1 平台管理员
负责系统级维护和业务全局管理，预期能力包括：

- 系统用户、角色、部门、菜单管理
- 分润基础规则维护
- 用户分润档案维护
- 设备绑定关系维护
- 分润记录全量查询、导出、退款处理
- 提现记录审核与打款处理
- 告警电话维护
- APP 用户管理

### 3.2 业务管理者
根据代码中的数据权限判断，部分角色可按部门或经销体系查看数据，预期能力包括：

- 查看本部门或本经销体系下的设备绑定
- 查看分润记录报表
- 查询提现记录
- 维护下级用户相关业务数据

说明：代码中通过角色 ID 和部门树控制数据范围，但未直接给出正式角色名称。

### 3.3 分润用户
即参与分润结算的业务用户，预期能力包括：

- 查看本人分润记录
- 查看本人提现记录
- 维护本人分润档案和收款信息
- 提交提现申请

### 3.4 APP 用户/养殖端用户
该类用户来自 `aqu_user`，预期能力包括：

- 通过手机号验证码或密码登录
- 查看塘口与设备
- 查看监测历史数据和告警
- 控制控制器设备开关

## 4. 业务范围

### 4.1 已覆盖业务域

- 系统管理
- APP/短信登录
- 池塘与设备监测
- 设备绑定
- 分润规则管理
- 用户分润档案管理
- 分润记录管理
- 提现管理
- 退款冲销
- 告警电话管理
- 定时任务管理

### 4.2 明显未完成或实现不完整的业务

- 语音告警电话的自动拨号任务仅有占位逻辑，未完成实际拨打
- 前端页面与交互细节未随仓库提供
- 部分 XML 映射文件存在错配痕迹，说明代码仍有整理空间

## 5. 核心业务对象

### 5.1 分润基础规则 `basic_profit_sharing`

- 等级名称 `name`
- 等级编码 `code`
- 测氧仪分润比例 `omRatio`
- 控制器分润比例 `controlRatio`

用途：定义分润级别或档位的基础比例。

### 5.2 用户分润档案 `basic_profit_sharing_user`

- 关联用户 `userId`
- 分润级别 `sharingCode`
- 测氧仪比例 `omRatio`
- 控制器比例 `controlRatio`
- 公司名称 `company`
- 开户行 `bank`
- 银行卡号 `bankNumber`
- 收款人姓名 `name`

用途：存储参与分润的用户档案和收款信息。

### 5.3 用户设备绑定 `basic_user_bind_info`

- 绑定用户 `userId`
- 设备编号 `deviceName`
- 产品 Key `productKey`
- IoT 唯一标识 `iotId`
- 设备类型 `type`
- 绑定时间 `bindTime`
- 分润状态 `profitStatus`
- 关联 APP 用户信息

用途：建立后台分润用户与业务设备之间的归属关系。

### 5.4 分润记录 `basic_profit_sharing_record`

- 分润用户 `userId`
- 分润金额 `amount`
- 来源 `fromWay`
- 标题 `title`
- 原始订单号 `orderNo`
- 设备编号 `deviceName`
- 分润状态 `status`
- 提现状态 `withdrawalStatus`
- 打款状态 `paymentStatus`
- 驳回原因 `paymentReason`
- 关联提现单 `withdrawId`

用途：记录每一笔可分配收益及其后续结算状态。

### 5.5 提现记录 `basic_user_withdraw`

- 提现用户 `userId`
- 标题 `title`
- 申请时间 `withdrawTime`
- 提现总额 `totalAmount`
- 收款信息 `bank`、`bankNumber`、`name`
- 实际打款金额 `paymentAmount`
- 打款状态 `paymentStatus`
- 打款时间 `paymentTime`

用途：记录按批次发起的提现申请和财务打款结果。

### 5.6 外部设备与订单对象

- `aqu_user`
  说明：APP 用户
- `aqu_pond`
  说明：池塘/塘口
- `aqu_device`
  说明：设备主表
- `aqu_device_data_history`
  说明：设备历史监测数据
- `aqu_device_switch`
  说明：控制器开关
- `aqu_message_warn`
  说明：告警消息
- `aqu_pay_device`
  说明：设备充值或付费明细，是分润计算的直接来源

## 6. 功能需求

### 6.1 系统管理
系统应提供标准后台管理能力，包括：

- 用户管理
- 角色管理
- 部门管理
- 岗位管理
- 菜单管理
- 字典管理
- 参数配置
- 公告管理
- 在线用户管理
- 登录日志与操作日志
- 定时任务管理
- 缓存查看
- 服务监控
- 文件上传下载

说明：以上能力来自 `fishery-system` 与 `fishery-quartz` 通用模块。

### 6.2 登录与认证

#### 6.2.1 后台登录
系统应支持后台账号密码登录，并具备：

- 图形验证码校验
- JWT Token 签发
- 登录日志记录
- 登录错误重试限制

#### 6.2.2 APP/短信登录
系统应支持 `/sms/**` 匿名访问的移动端登录能力，包括：

- 手机号获取短信验证码
- 手机号 + 验证码登录
- 手机号/用户名 + 密码登录
- APP Token 签发

补充说明：

- APP 用户既可能来自本系统 `sys_user`，也可能来自外部 `aqu_user`
- 代码中预留了微信 `openid`、手机号换取能力，但当前接口未形成完整微信登录闭环

### 6.3 池塘与设备监测
系统应支持移动端或大屏使用者按本人数据范围查看养殖场景信息。

#### 6.3.1 塘口查询
系统应支持查询当前用户所属塘口列表。

输入：

- 当前登录用户

输出：

- 塘口 ID
- 塘口名称

#### 6.3.2 设备列表查询
系统应支持按塘口和设备类型查询设备。

筛选条件：

- 用户 ID
- 塘口 ID 列表
- 设备类型

输出内容至少包括：

- 设备编号
- 设备名称
- 设备类型
- 当前监测值
- 在线状态
- 告警参数
- 控制器开关信息

#### 6.3.3 设备历史数据查询
系统应支持查询设备历史趋势数据。

能力包括：

- 单设备历史曲线查询
- 多设备历史对比查询
- 按最近 N 天统计
- 30 分钟粒度聚合

监测指标包括：

- 溶氧
- 温度
- 饱和度
- pH
- 盐度

#### 6.3.4 告警信息查询
系统应支持：

- 查询当前用户告警列表
- 按设备查询告警列表
- 返回告警总数用于分页

#### 6.3.5 控制器开关控制
系统应支持控制器设备开关下发。

输入：

- `iotId`
- 开关序号 `index`
- 开关目标状态 `0/1`

输出：

- 下发是否成功

### 6.4 APP 用户管理
系统应支持对外部 `aqu_user` 用户进行后台管理。

功能包括：

- APP 用户列表查询
- 修改是否开通大屏权限 `hasScreen`
- 修改用户标题 `title`

### 6.5 设备绑定管理
系统应支持维护后台分润用户与设备的绑定关系。

#### 6.5.1 绑定列表查询
系统应支持查询绑定列表，并依据权限限制数据范围。

筛选条件至少包括：

- 用户
- 设备编号
- 设备类型
- APP 用户手机号

#### 6.5.2 绑定详情查询
系统应支持查看绑定详情，并补充外部业务库中的设备归属信息。

#### 6.5.3 新增绑定
系统应支持新增用户设备绑定，规则包括：

- 若未传用户，则默认绑定到当前登录人
- 若按用户 ID 指定绑定对象，应自动回填用户名
- 同一设备编号不可重复绑定
- 若外部业务库可查到该设备，应合并其业务侧设备信息

#### 6.5.4 修改与删除绑定
系统应支持修改和删除绑定关系。

#### 6.5.5 设备数据补充查询
围绕绑定设备，系统应支持：

- 查询设备监测数据及历史数据
- 查询控制器信息
- 查询告警信息

### 6.6 分润基础规则管理
系统应支持维护基础分润档位。

功能包括：

- 分润规则列表查询
- 分润规则详情查询
- 新增分润规则
- 修改分润规则
- 删除分润规则
- 导出分润规则

规则属性包括：

- 等级名称
- 等级编码
- 测氧设备比例
- 控制器比例

### 6.7 用户分润档案管理
系统应支持维护分润用户档案及其收款信息。

功能包括：

- 分润档案列表查询
- 分润档案详情查询
- 新增分润档案
- 修改分润档案
- 删除分润档案
- 导出分润档案

业务规则包括：

1. 档案主键与用户 ID 对齐。
2. 若用户修改的是本人档案，可直接处理。
3. 若用户修改他人档案，需要具备管理员权限。
4. 用户档案不存在时，不允许直接修改，需先新增。
5. 分润比例需通过层级校验。

#### 6.7.1 分润比例校验规则
系统应校验同一条用户链路上的累计比例不超过 100%。

- 测氧设备比例累计不得超过 100%
- 控制器比例累计不得超过 100%

说明：

- 系统会沿 `sys_user.parent_id` 向上累加上级比例
- 超出比例时，应阻止保存

### 6.8 分润计算与分润记录管理

#### 6.8.1 分润记录查询
系统应支持分润记录列表查询、详情查询和导出。

查询维度至少包括：

- 用户
- 来源
- 分润状态
- 设备编号
- 打款状态
- 提现单号
- 时间区间
- 电话号码

#### 6.8.2 分润报表
系统应支持统计报表接口，输出至少包括：

- 分润总额 `total`
- 已分润金额 `fr`
- 已提现金额 `tx`

统计维度包括：

- 时间范围
- 用户范围
- 部门范围

#### 6.8.3 自动分润计算
系统应通过定时任务，根据外部订单数据自动生成分润记录。

计算来源：

- `aqu_pay_device`

处理逻辑：

1. 定时拉取指定时间窗口内的订单明细。
2. 按设备编号找到参与分润的用户链路。
3. 根据设备类型选择对应比例。
4. 计算分润金额并生成记录。
5. 将原订单标记为已参与分润。

分润公式：

- 分润金额 = 支付金额 × 分润比例 / 100

设备类型：

- `1`：溶氧设备
- `2`：控制器设备

#### 6.8.4 分润记录状态流转
分润记录至少应支持以下状态维度：

- 分润状态 `status`
  - `0`：待处理或已申请提现待打款
  - `1`：已生成有效分润
  - `9`：无效
- 提现状态 `withdrawalStatus`
  - `0`：未提现
  - `1`：已提现申请
- 打款状态 `paymentStatus`
  - `0`：未打款
  - `1`：已打款
  - `9`：驳回或失效

说明：以上语义基于字段注释和代码行为归纳。

#### 6.8.5 退款处理
系统应支持按订单号对分润记录进行退款冲销。

处理规则：

- 同一订单号下的所有有效分润记录均应被置为无效
- 同步记录驳回原因
- 如该分润记录已关联提现单，应同步冲减提现单剩余可打款金额

### 6.9 提现管理

#### 6.9.1 提现记录查询
系统应支持提现记录列表查询、详情查询和导出。

查询维度至少包括：

- 用户
- 标题
- 提现时间
- 昵称
- 手机号

#### 6.9.2 用户提现申请
系统应支持分润用户发起提现申请。

规则包括：

1. 仅可提取本人记录。
2. 仅可提取未提现的分润记录。
3. 当前实现中，仅允许提取生成时间早于当前 30 天的分润记录。
4. 用户必须先维护完整收款信息。
5. 提现申请成功后，应生成一张提现单。
6. 被纳入本次提现的分润记录应回填 `withdrawId`。

提现单生成内容包括：

- 提现标题
- 提现总额
- 提现时间
- 收款公司/开户行
- 收款卡号
- 收款人姓名
- 用户昵称和手机号
- 初始打款状态

#### 6.9.3 打款处理
系统应支持后台修改提现单状态，并在打款成功后更新金额。

预期规则：

- `paymentStatus = 1` 表示已打款
- 打款金额可小于总额
- 若后续发生退款或驳回，应同步冲减可打款金额

### 6.10 告警电话管理
系统应支持维护语音报警手机号。

功能包括：

- 电话列表查询
- 新增电话
- 修改电话
- 删除电话

字段包括：

- 手机号
- 是否启用

说明：定时拨号任务尚未完成。

### 6.11 定时任务

#### 6.11.1 分润计算任务 `profitTask`
系统应支持定时执行分润计算。

能力包括：

- 订单读取
- 分润链路展开
- 分润记录批量生成
- 原订单状态更新

#### 6.11.2 设备绑定同步任务
系统应支持补齐尚未关联 `device_id` 的绑定记录。

处理逻辑：

- 查询本地绑定表中缺失设备 ID 的记录
- 根据设备编号到外部业务库查找设备
- 回填设备 ID 等信息

#### 6.11.3 告警码处理任务 `WarnCodeTask`
系统应支持在设备充值成功后重置设备告警码。

#### 6.11.4 语音拨号任务 `CellTask`
当前仅有框架和号码查询逻辑，实际拨打能力未实现。

## 7. 关键业务流程

### 7.1 分润准备流程

1. 管理员创建系统用户和组织关系。
2. 管理员维护用户分润档案。
3. 管理员维护用户与设备的绑定关系。
4. 系统根据用户层级和设备归属建立可分润链路。

### 7.2 充值分润流程

1. 设备在外部业务库产生充值/支付记录。
2. 定时任务读取最近时间窗口内的支付明细。
3. 系统按设备编号匹配绑定用户及上级链路。
4. 系统按设备类型套用比例，生成分润记录。
5. 系统将支付明细标记为已分润，避免重复计算。

### 7.3 提现流程

1. 分润用户完善收款资料。
2. 用户发起提现申请。
3. 系统筛选满足条件的分润记录并汇总金额。
4. 系统生成提现单，并将分润记录关联到提现单。
5. 管理员审核并打款。
6. 若发生退款或驳回，系统同步调整金额状态。

### 7.4 设备监测流程

1. APP 用户登录。
2. 查询本人塘口列表。
3. 查询塘口下设备列表。
4. 查看实时值、历史值、告警记录。
5. 对控制器设备执行开关控制。

## 8. 业务规则

### 8.1 数据权限规则

- 普通用户默认仅能查看本人分润记录和提现记录
- 部分高权限角色可查看更大范围数据
- 设备绑定列表按用户/部门树控制查询范围

说明：具体角色编码需以生产环境主数据为准。

### 8.2 分润比例规则

- 上下级累计比例不可超过 100%
- 不同设备类型使用不同分润比例字段

### 8.3 设备类型规则

- `1` 表示溶氧监测设备
- `2` 表示控制器设备

### 8.4 提现规则

- 仅未提现记录可参与提现
- 当前实现限制为 30 天前产生的分润记录
- 未维护收款信息时不得发起提现

### 8.5 退款规则

- 退款会使相关分润记录失效
- 退款会影响提现单剩余可打款金额

## 9. 接口与模块清单

### 9.1 业务接口模块

- `/sms`
  说明：短信验证码与 APP 登录
- `/screen`
  说明：塘口、设备、历史、告警、控制
- `/basic/profitSharing`
  说明：分润基础规则
- `/basic/sharingUser`
  说明：用户分润档案
- `/basic/sharingRecord`
  说明：分润记录与报表、退款
- `/basic/userBind`
  说明：设备绑定、监测数据、控制器信息、告警
- `/basic/withdraw`
  说明：提现申请与提现记录
- `/basic/user`
  说明：APP 用户管理
- `/sys/tel`
  说明：语音报警电话

### 9.2 通用后台模块

- `/login`
- `/system/user`
- `/system/role`
- `/system/dept`
- `/system/menu`
- `/system/dict`
- `/system/config`
- `/system/notice`
- `/monitor/*`
- `/tool/gen/*`

## 10. 非功能需求

### 10.1 技术要求

- Java 8
- Spring Boot 2.5.x
- MyBatis Plus
- Redis
- JWT
- Druid 动态数据源

### 10.2 性能要求

- 常规列表查询应支持分页
- 历史数据查询需使用缓存降低数据库压力
- 设备在线状态应短时缓存
- 定时任务应具备批量处理能力

### 10.3 安全要求

- 后台接口需基于权限控制访问
- APP 登录验证码需具备有效期
- 登录行为需记录日志
- 上传下载需校验文件合法性

### 10.4 可维护性要求

- 业务模块与系统模块分层清晰
- 关键业务实体应保留创建/更新时间
- 定时任务应可配置、可查看执行日志

## 11. 当前实现中的风险与待确认事项

### 11.1 业务待确认

- 角色 ID 与业务角色名称的正式映射关系
- 控制器设备为何固定叠加 `ID = 101` 的分润档案
- 提现记录的审核流程是否应区分“申请中、审核通过、已打款、已驳回”
- 退款是否应按提现单冲减全部关联记录，而非单笔金额

### 11.2 实现待修正

- `BasicProfitSharingUserMapper.xml` 内容与文件名不匹配，疑似误复制
- 语音拨号任务尚未实现
- 若按当前代码执行，部分提现记录状态更新逻辑可能未完全落库
- 部分接口的权限注解被注释，需确认是否为正式设计
- 退款接口中的订单号非空校验逻辑疑似反向

### 11.3 文档待补充

- 前端页面原型
- 角色菜单矩阵
- 数据字典
- 完整表结构设计
- 对账和财务闭环说明

## 12. 结论
从现有代码看，该项目不是单纯的“后台管理模板”，而是面向鱼塘养殖设备场景的分润结算系统。其核心业务主线是：

1. 维护用户与设备关系
2. 采集设备与充值业务数据
3. 按层级和设备类型计算分润
4. 支持分润查询、提现和退款冲销
5. 为 APP/大屏提供设备监测、告警和控制能力

如果要继续推进项目建设，建议下一步优先补齐以下内容：

1. 角色与组织模型说明
2. 表结构与状态机说明
3. 前端页面清单
4. 提现审核与财务流程口径
5. 语音告警闭环设计