qdintc/fishery_dms

Fork 0

Files

tianyongbao 2fad08ebb3 feat: 鱼测云经销商管理后台，代码提交。

2026-04-09 01:48:22 +08:00

20 KiB

Raw Permalink Blame History

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

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 业务定位

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

设备接入与设备归属管理
池塘与设备监测数据查询
告警信息查看与控制器开关控制
经销/层级用户分润比例配置
充值订单自动分润计算
分润记录统计、退款冲销
用户提现申请与打款处理
短信验证码登录与 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 用户分润档案管理

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

功能包括：

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

业务规则包括：

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

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

处理逻辑：

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

分润公式：

分润金额 = 支付金额 × 分润比例 / 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 用户提现申请

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

规则包括：

仅可提取本人记录。
仅可提取未提现的分润记录。
当前实现中，仅允许提取生成时间早于当前 30 天的分润记录。
用户必须先维护完整收款信息。
提现申请成功后，应生成一张提现单。
被纳入本次提现的分润记录应回填 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 分润准备流程

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

7.2 充值分润流程

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

7.3 提现流程

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

7.4 设备监测流程

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

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. 结论

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

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

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

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

20 KiB Raw Permalink Blame History Unescape Escape

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

1. 文档说明

1.1 编写目的

1.2 编写依据

1.3 说明与边界

2. 项目概述

2.1 系统名称

2.2 业务定位

2.3 总体架构

2.4 数据源边界

3. 业务角色

3.1 平台管理员

3.2 业务管理者

3.3 分润用户

3.4 APP 用户/养殖端用户

4. 业务范围

4.1 已覆盖业务域

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

5. 核心业务对象

5.1 分润基础规则 basic_profit_sharing

5.2 用户分润档案 basic_profit_sharing_user

5.3 用户设备绑定 basic_user_bind_info

5.4 分润记录 basic_profit_sharing_record

5.5 提现记录 basic_user_withdraw

5.6 外部设备与订单对象

6. 功能需求

6.1 系统管理

6.2 登录与认证

6.2.1 后台登录

6.2.2 APP/短信登录

6.3 池塘与设备监测

6.3.1 塘口查询

6.3.2 设备列表查询

6.3.3 设备历史数据查询

6.3.4 告警信息查询

6.3.5 控制器开关控制

6.4 APP 用户管理

6.5 设备绑定管理

6.5.1 绑定列表查询

6.5.2 绑定详情查询

6.5.3 新增绑定

6.5.4 修改与删除绑定

6.5.5 设备数据补充查询

6.6 分润基础规则管理

6.7 用户分润档案管理

6.7.1 分润比例校验规则

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

6.8.1 分润记录查询

6.8.2 分润报表

6.8.3 自动分润计算

6.8.4 分润记录状态流转

6.8.5 退款处理

6.9 提现管理

6.9.1 提现记录查询

6.9.2 用户提现申请

6.9.3 打款处理

6.10 告警电话管理

6.11 定时任务

6.11.1 分润计算任务 profitTask

6.11.2 设备绑定同步任务

6.11.3 告警码处理任务 WarnCodeTask

6.11.4 语音拨号任务 CellTask

7. 关键业务流程

7.1 分润准备流程

7.2 充值分润流程

7.3 提现流程

7.4 设备监测流程

8. 业务规则

8.1 数据权限规则

8.2 分润比例规则

8.3 设备类型规则

8.4 提现规则

8.5 退款规则

9. 接口与模块清单

9.1 业务接口模块

9.2 通用后台模块

10. 非功能需求

10.1 技术要求

10.2 性能要求

20 KiB

Raw Permalink Blame History

5.1 分润基础规则 `basic_profit_sharing`

5.2 用户分润档案 `basic_profit_sharing_user`

5.3 用户设备绑定 `basic_user_bind_info`

5.4 分润记录 `basic_profit_sharing_record`

5.5 提现记录 `basic_user_withdraw`

6.11.1 分润计算任务 `profitTask`

6.11.3 告警码处理任务 `WarnCodeTask`

6.11.4 语音拨号任务 `CellTask`