账权平台 — 项目说明书

1项目概述

账权平台是一套面向农业产业链的 多租户 SaaS 综合管理平台，涵盖智慧农业、产品溯源、自助过磅、AI 智能助手等核心业务域。平台采用前后端分离架构，后端基于 Spring Boot + MyBatis Plus，前端基于 Vue 2 + Element UI，通过多租户动态数据源实现企业级数据隔离。

62

后端 Controller

85+

前端页面

10+

业务模块

85+

Mapper 接口

项目组成

子项目	技术栈	说明	端口
saas-service	Java 11 / Spring Boot 2.2.1	后端服务，提供全部 REST API	`7777`(生产) / `8202`(开发)
saas-web	Vue 2.7 / Element UI 2.15	前端管理控制台	`8201`(开发)

核心业务域

智慧农业

园区/地块/作物管理、灌溉计划、水肥一体机、电磁阀控制、农事计划、投入品管理、设备数据上报、摄像头监控

产品溯源

溯源码生成与绑定、码货关联、采收/加工/质检全链条、仓储出入库、物流追踪、溯源大屏

自助过磅

车辆/司机/IC卡管理、北斗卡借还追踪、称重票据、报警规则、过磅工作台、小票打印

AI Agent 平台

多厂商 LLM 配置、Agent 编排、Groovy 动态工具、Function Calling、技能注入、多轮对话、调用审计

多租户 SaaS

企业认证、套餐配额管理、角色权限体系、SSO 单点登录、AccessToken 开放平台

伙伴云集成

伙伴云低代码平台深度对接、表结构同步、数据 CRUD 代理、SSO 登录、AMIS 页面配置

2系统架构

整体架构图

浏览器 / 移动端 / 外部系统

▼

Nginx 反向代理

▼

saas-web
Vue 2 + Element UI

saas-service
Spring Boot REST API

▼

MySQL
cloud (主库)

MySQL
user (租户库)

Redis
DB7 / DB9

阿里云 OSS
文件存储

▼

阿里云 DashScope
LLM API

伙伴云 OpenAPI
低代码平台

萤石云 API
视频监控

阿里云 ASR
语音识别

n8n
工作流引擎

技术栈总览

类别	后端 (saas-service)	前端 (saas-web)
核心框架	Spring Boot 2.2.1 / Java 11	Vue 2.7.14
路由/状态	—	Vue Router 3.5 / Vuex 3.1
ORM / 数据	MyBatis Plus 3.5.7 + 动态数据源 3.6.1	—
UI 组件	—	Element UI 2.15.13
缓存	Redis + Redisson 3.35.0	localStorage
HTTP	Spring MVC	Axios 0.18.1
对象存储	阿里云 OSS SDK 3.17.4	—
LLM / AI	DashScope (OpenAI 兼容) + Groovy 3.0.19	Monaco Editor / marked / highlight.js
WebSocket	Spring WebSocket + Java-WebSocket	原生 WebSocket (ASR)
工具库	Hutool 5.8.16 / Lombok / Apache POI	ECharts 5.4 / 高德地图 / WangEditor
构建工具	Maven	Vue CLI 4.4.4 / Webpack

3后端服务 (saas-service)

3.1 基本信息

GroupId / ArtifactId	`cn.apes / saas-service`
版本	1.0.0-SNAPSHOT
主启动类	`cn.apes.CloudApplication`（启用 @EnableAsync / @EnableScheduling）
根包	`cn.apes.cloud`
生产端口	7777
开发端口	8202

3.2 包结构

cn.apes.cloud
├── config/            # 配置类（12个）：RedissonConfig, OssConfig, DataSourceConfig...
├── controller/        # REST 控制器（62个）
│   └── traceability/  # 溯源模块控制器（9个）
├── domain/            # 数据模型层
│   ├── entity/        # 核心实体（43个）
│   ├── dto/           # 数据传输对象（35个）
│   ├── vo/            # 视图对象（5个）
│   ├── huoban/        # 伙伴云数据模型（11个）
│   ├── traceability/  # 溯源数据模型（22个）
│   └── weight/        # 称重数据模型（13个）
├── filter/            # AccessToken 鉴权过滤器
├── groovy/            # Groovy 脚本执行引擎
│   ├── GroovyExecutorService.java    # 编译+缓存+执行
│   ├── GroovyToolExecutor.java       # 工具接口
│   └── JsonSchemaValidator.java      # 入参校验
├── mapper/            # MyBatis Mapper（85个）
│   └── traceability/  # 溯源 Mapper（20个）
├── service/           # 业务逻辑层
│   ├── impl/          # 服务实现（90个）
│   │   └── huoban/    # 伙伴云服务（6个）
├── task/              # 定时任务（摄像头抓图）
├── util/              # 工具类
└── websocket/         # ASR 语音识别 WebSocket 代理

3.3 数据源配置

采用 baomidou dynamic-datasource 实现多数据源动态切换，通过自定义 @TenantSource 注解 + AOP 切面，根据请求头 X-Tenant-ID 自动切换数据源。

数据源	目标数据库	用途
`cloud`（主库）	MySQL 192.168.1.161:3306/cloud	平台核心数据（用户、企业、权限、LLM 配置等）
`user`（租户库）	MySQL 192.168.1.161:3306/user	租户业务数据（溯源、农业、称重等）
`huoban`	伙伴云 MySQL	直连伙伴云数据库（数据同步/CRUD）

多租户切换原理：请求头 X-Tenant-ID 值为 user/zx/plant 时，DataSourceHeaderAspect 切面自动调用 DynamicDataSourceContextHolder.push() 切换到对应数据源。默认使用 user 数据源。

3.4 核心配置类

配置类	功能
RedissonConfiguration	Redisson 客户端，DB7（主业务）+ DB9（辅助），JsonJackson 编解码
OssConfiguration	阿里云 OSS，桶 `zq-cloud`，区域 `oss-cn-beijing`
DataSourceHeaderAspect	多租户数据源切换 AOP 切面
AccessTokenFilterConfig	AccessToken 外部 API 鉴权过滤器注册
WebSocketConfig	ASR 语音识别 WebSocket 端点 `/asr/ws`

3.5 定时任务

摄像头定时抓图 (CameraCaptureTask)

每小时执行一次，遍历所有摄像头调用萤石云 API 抓图，记录成功/失败统计日志。

4前端应用 (saas-web)

4.1 基本信息

项目名称	saas-web（账权平台）
框架	Vue 2.7.14 + Vue Router 3.5.2 (History 模式) + Vuex 3.1.0
UI 组件库	Element UI 2.15.13（中文语言包）
构建工具	Vue CLI 4.4.4 + Webpack + Sass
开发端口	8201（host: 0.0.0.0）
输出目录	saas-web

4.2 目录结构

src/
├── main.js                 # 应用入口
├── App.vue                 # 根组件
├── api/                    # API 接口层（35个文件）
├── assets/                 # 静态资源
├── components/             # 公共组件（面包屑/标签页/AI助手/大屏组件等）
├── config/                 # 全局配置
├── layout/                 # 布局（TopHeader + Sidebar + TagsView）
├── router/                 # 路由配置（静态路由 + 动态路由注册）
├── store/                  # Vuex（user / settings / tagsView）
├── styles/                 # 全局样式（SCSS 变量/Mixin/Element UI 覆盖）
├── utils/                  # 工具函数（16个文件）
└── views/                  # 页面视图（85+文件，41个子目录）

4.3 布局架构

layout/index.vue（主布局容器）

▼

TopHeader
Logo + 应用Tab + 用户菜单

▼

Sidebar
三级树形菜单

el-main
TagsView + keep-alive

▼

router-view（页面内容）

iframeView（内嵌页面）

独立大屏页面（noLayout: true）不使用主布局，可脱离侧栏/顶栏独立访问，支持通过 URL Token 参数从外部系统直接跳转。包括：智慧农业大屏、武鸣沃柑大脑、溯源大屏。

4.4 动态路由系统

前端路由分为静态路由（登录/注册/认证等）和动态路由两部分。动态路由通过 menuApi.handleMenu() 根据后端返回的菜单数据动态注册：

menuType	类型	路由前缀	加载方式
1	普通页面	`/common/{menuPath}`	动态 import vuePath 组件
2	伙伴云内嵌	`/common/huoban/{id}`	加载 huoban/index 组件
3	支付页面	`/common/payment/{id}`	加载 payment/index 组件
4	Web 内嵌	`/common/web/{id}`	加载 web/index 组件

4.5 Vuex 状态管理

模块	核心 State	说明
user	loginUser, menuList, currentCustomer, huobanToken, appList, currentApp, allAppMenus	用户登录态、企业信息、菜单树、多应用切换
settings	sidebarCollapsed	侧栏折叠状态
tagsView	visitedViews, cachedViews	标签页管理，支持 localStorage 持久化

4.6 第三方库

ECharts 5.4

数据可视化图表，用于大屏和报表

高德地图

园区地图标注、物流轨迹追踪

Monaco Editor

VS Code 内核代码编辑器，支持 Java/Groovy/JSON/SQL 语法高亮

WangEditor

富文本编辑器，用于内容编辑

html2canvas

网页截图，用于大屏导出

marked + highlight.js

Markdown 渲染 + 代码高亮，用于 AI 对话展示

qrcodejs2

二维码生成，用于溯源码

萤石云 SDK

视频监控实时流播放

5核心功能模块

5.1 用户与企业认证

用户注册/登录：密码登录 + 微信小程序登录（code2Session）
企业认证：提交营业执照 → 平台审核 → 认证通过/驳回 → 重新提交
多企业切换：一个用户可关联多个企业，支持切换当前企业
SSO 单点登录：支持企业配置 SSO，对接伙伴云 SSO 登录
AccessToken：外部 API 鉴权令牌，支持 IP 白名单、过期时间、启用/停用

5.2 智慧农业（飞翼）

园区 & 地块管理：园区信息 CRUD、地块信息管理（坐标、面积、作物关联）
作物管理：作物信息、物候期管理（生长期阶段定义）
农事计划：施肥/灌溉/采收计划制定与执行跟踪
灌溉系统：灌溉计划管理、定时执行、执行记录、电磁阀远程控制
水肥一体机：设备管理、母液罐配置、加药操作、加药日志、设备布局可视化
投入品管理：肥料/农药等投入品库存管理、出入库日志
设备数据上报：传感器数据采集（温湿度、土壤等）
摄像头监控：萤石云摄像头管理、定时抓图、抓图日志
可视化大屏：园区数据可视化大屏，含地图、图表、设备状态

5.3 产品溯源

溯源码管理：批量生成、码列表查询、绑定/解绑/作废/启用
码货绑定：批量导入绑定、未绑定码查询、父子码关联
全链条追溯：土地 → 采收 → 加工 → 质检 → 入库 → 出库 → 物流 → 反馈/召回
资质与证书：企业资质管理、产品合格证生成
仓储管理：入库/出库记录、库存查询、库位平面图
溯源大屏：冷库温湿度、利用率、分级图表、采收进度、物流轨迹地图
H5 溯源页：消费者扫码查看产品全链条溯源信息

5.4 自助过磅

称重票据：一次称重 / 二次称重 / 编辑 / 打印全流程
车辆 & 司机管理：车辆记录、司机信息、IC 卡管理
北斗卡管理：借用 / 归还 / 追踪记录、报警规则与报警记录
过磅工作台：自助过磅操作界面
小票打印：独立打印页面，支持热敏打印机

5.5 套餐与配额管理

套餐方案：定义套餐包含的应用、权限、配额
客户套餐：为客户分配套餐，管理配额增减
配额管理：系统配额定义（如溯源码数量、AI 调用次数等）
套餐延期：延期申请 → 审核 → 生效
配额变更日志：完整记录配额增减历史

5.6 伙伴云集成

双模式集成：直连伙伴云 MySQL（@DS("huoban")）+ 伙伴云 OpenAPI 代理
表结构同步：自动同步伙伴云表格结构到本地配置
数据 CRUD 代理：通过平台 API 操作伙伴云表格数据
SSO 登录：平台 Token → 伙伴云 Token 免密登录
AMIS 低代码：支持 AMIS 页面配置和动态渲染
自动化按钮：伙伴云自动化工作流触发

6LLM / AI Agent 平台

平台内置完整的 LLM Agent 管理引擎，支持多厂商模型配置、Agent 编排、Groovy 动态工具、Function Calling 多轮对话、技能注入和全链路审计。

6.1 架构层次

Agent 配置 (LlmAgentConfig)
System Prompt / User Prompt / Output Type

▼

厂商配置
LlmProviderConfig

模型配置
LlmModelConfig

关联工具
LlmAgentTool → LlmTool

关联技能
LlmAgentSkill → AiSkill

▼

LLM 调用 (DashScope OpenAI 兼容 API)
多轮对话 + Function Calling（最多10轮）

▼

GroovyExecutorService
动态编译执行工具脚本

LlmConversationMessage
消息持久化

▼

LlmCallLog
调用日志审计

LlmToolLog
工具执行日志

6.2 核心能力

多厂商模型配置

支持配置多个 LLM 厂商（API Key、BaseUrl），每个厂商下可配置多个模型（chat/embedding/image），支持视觉模型

Function Calling

自动检测 LLM 返回的 tool_calls，执行对应 Groovy 工具脚本，将结果回传给 LLM 继续推理，最多 10 轮防止死循环

Groovy 动态工具

使用 GroovyClassLoader 动态编译脚本，编译结果缓存（ConcurrentHashMap），支持 JSON Schema 入参校验，无需重启即可添加新工具

技能系统

AiSkill 技能内容注入 System Prompt，为 Agent 提供领域知识，一个 Agent 可关联多个技能

多轮对话

LlmConversation 会话管理 + LlmConversationMessage 消息持久化，支持 system/user/assistant/tool_call/tool_result 多种消息类型

提示词模板

支持 {{variable}} 格式的变量替换，通过 userParams 传入动态参数

多模态输入

支持图片 URL（image_url）和视频 URL（video_url）输入，兼容视觉理解模型

输出类型控制

支持 text / json / markdown 三种输出格式，通过 response_format 控制

全链路审计

LlmCallLog 记录每次调用的 Token 用量、耗时、状态；LlmToolLog 记录工具执行的输入/输出/耗时/错误

ASR 语音识别

WebSocket 代理阿里云实时 ASR（fun-asr-realtime），PCM 16kHz 音频流式传输，前端实时显示转写结果

6.3 前端 AI 页面

页面	路径	功能
智能对话	`/ai/chat`	多轮对话界面，支持图片/视频上传、Markdown 渲染
Agent 配置	`/system/agent`	Agent CRUD、工具/技能关联、调试
模型管理	`/system/model`	厂商/模型配置
工具管理	`/system/tool`	Groovy 工具脚本编辑（Monaco Editor）+ 执行测试
技能管理	`/system/skill`	AI 技能 CRUD
对话历史	`/ai/conversation`	会话列表 + 消息详情
调用日志	`/system/callLog`	LLM 调用日志查询 + 统计

7多租户与权限体系

7.1 多租户架构

实现方式：基于 baomidou dynamic-datasource + 自定义 @TenantSource 注解 + AOP 切面，通过 HTTP 请求头 X-Tenant-ID 实现透明数据源切换。

租户标识	数据源	说明
`user`（默认）	user 数据库	标准租户业务数据
`zx`	zx 数据库	专线租户
`plant`	plant 数据库	种植租户

7.2 权限体系

套餐 (PackagePlan)

→

应用 (App)

▼

菜单 (Menu)

→

权限 (Permission)

▼

角色 (Role)

→

成员 (Member)

套餐 → 应用：套餐方案定义客户可使用的应用列表和配额
应用 → 菜单/权限：每个应用有独立的菜单树和权限项
角色 → 权限：角色绑定权限项，支持按应用分组
成员 → 角色：企业成员分配角色，按企业维度管理
前端动态路由：登录后根据权限动态生成路由和菜单

7.3 AccessToken 开放平台

为外部系统提供安全的 API 调用机制：

Token 通过 X-Access-Token 或 Authorization: Bearer 传递
支持 IP 白名单限制
支持启用/停用/重新生成
校验通过后将用户/企业信息注入请求上下文
配额扣减：开放接口可扣减客户套餐配额

8API 接口概览

后端共 62 个 Controller，提供 300+ REST API 端点。所有接口前缀为 /api/user-service/（通过 Nginx 代理）。

8.1 接口模块总览

模块	主要 Controller	路径前缀	核心端点
用户认证	UserController	`/user`	loginPwd, register, getCurrentUser, selectCustomer, certifyEnterprise
用户认证	CommonController	`/common`	upload, code2Session, huobanWebLogin
客户管理	CustomerController	`/customer`	pageCustomer, saveCustomer, employee/page, auditCertification, syncTenantsToHuoban
权限管理	PermissionController	`/permission`	currentMenus, getMyPermissionCodes, saveRole, setRolePermission, setMemberRole
AccessToken	AccessTokenController	`/sysAccessToken`	create, page, revoke, regenerate
LLM / AI	LlmChatController	`/llmChat`	start（新对话）, continue（多轮对话）
	LlmAgentConfigController	`/llmAgent`	page, add, update, delete, debug, call/{id}
	LlmProviderConfigController	`/llmProvider`	page, add, update, delete, list
	LlmModelConfigController	`/llmModel`	page, add, update, delete, list
	LlmToolController + GroovyToolExecuteController	`/llmTool`	CRUD, execute（执行 Groovy 脚本）, clearCache
	LlmConversationController	`/llmConversation`	add, detail, listByAgent, messages, close, delete
	LlmCallLogController	`/llmCallLog`	page, detail, statistics, batchDelete
伙伴云	HuobanController / Huoban2Controller	`/huoban` / `/huoban2`	syncTables, data, create, update, upsert, webLogin, automationCall
溯源	TraceCodeController	`/trace/code`	task/generate, list/bind, bind/batchImport, relation/add
	TraceCategoryController	`/trace/category`	分类 CRUD
	TraceWarehouseController	`/trace/warehouse`	入库/出库 CRUD
	TraceQualityController	`/trace/quality`	质检 CRUD
智慧农业	FeiParkInfoController / PlotInfoController	`/park` / `/fei/plot`	园区/地块 CRUD
	FeiIrrigationPlanController	`/irrigation/plan`	灌溉计划 CRUD + toggle 开关
	FeiFertigationDeviceController	`/fertigation-device`	设备 CRUD, dosing（加药）, save-layout
称重	WeightController	`/weight`	ticket（磅单）, device, driver, card, beidou, alarmRule
套餐配额	CustomerPackageController	`/customerPackage`	myPackages, increaseQuota, decreaseQuota, submitExtendApply
开放平台	OpenController	`/open`	trackingConfig/getByCustomerId, customerPackage/decreaseQuota

8.2 前端 API 代理配置

代理前缀	目标	路径重写
`/api/user-service`	`http://localhost:8202`	`^/api/user-service` → `/`
`/n8n`	`https://n8n.ccoop.cc`	`^/n8n` → `""`

9部署与配置

9.1 后端部署

配置项	生产环境 (prod)	开发环境 (local)
服务端口	7777	8202
主数据源	192.168.1.161:3306/cloud	192.168.31.201:3389/cloud
伙伴云数据源	192.168.1.161:3306/user	192.168.31.201:3389/user
Redis	192.168.1.165:6403, DB7	192.168.31.201:7890, DB7
OSS	oss-cn-beijing.aliyuncs.com, bucket: zq-cloud
伙伴云 API	https://hb.zhangquyun.com/server/api
LLM API	https://dashscope.aliyuncs.com/compatible-mode/v1
文件上传限制	max-file-size: 20MB, max-request-size: 200MB
构建命令	`mvn clean package -Pprod` 或 `./publish.sh`
启动命令	`java -jar saas-service.jar --spring.profiles.active=prod`

9.2 前端部署

配置项	值
开发启动	`npm run dev`（端口 8201）
生产构建	`npm run build:prod` → 输出到 `saas-web/` 目录
预发布构建	`npm run build:stage`
构建脚本	`./publish.sh`
部署方式	Nginx 静态文件 + 反向代理到后端

9.3 数据库

数据库引擎：MySQL 8.0+，字符集 UTF-8，时区 GMT+8
逻辑删除：全局字段 isDel（1=已删除，0=正常），MyBatis Plus 自动处理
数据库导出：db-export/cloud_full_*.sql（完整建库脚本）

9.4 环境依赖

组件	版本要求	用途
JDK	11+	后端运行时
Maven	3.6+	后端构建
Node.js	8.9+	前端构建
MySQL	8.0+	数据库
Redis	6.0+	缓存/分布式锁
Nginx	1.18+	反向代理/静态文件

10项目目录结构

10.1 后端 (service-master)

service-master/
├── pom.xml                          # Maven 配置
├── publish.sh                       # 发布脚本
├── src/
│   ├── main/
│   │   ├── java/cn/apes/
│   │   │   ├── CloudApplication.java    # 主启动类
│   │   │   └── cloud/
│   │   │       ├── config/              # 配置类（12个）
│   │   │       ├── controller/          # 控制器（62个）
│   │   │       ├── domain/              # 数据模型
│   │   │       ├── filter/              # 过滤器
│   │   │       ├── groovy/              # Groovy 引擎
│   │   │       ├── mapper/              # Mapper 接口（85个）
│   │   │       ├── service/             # 业务逻辑（90个实现类）
│   │   │       ├── task/                # 定时任务
│   │   │       ├── util/                # 工具类
│   │   │       └── websocket/           # WebSocket 处理器
│   │   └── resources/
│   │       ├── application.yml          # 主配置
│   │       ├── application-prod.yml     # 生产配置
│   │       └── application-local.yml    # 开发配置
│   └── test/                            # 测试代码
├── docs/                                # API 文档（15个）
├── sql/                                 # SQL 脚本
├── db-export/                           # 数据库导出
└── logs/                                # 日志文件

10.2 前端 (web-master)

web-master/
├── package.json                     # 依赖配置
├── vue.config.js                    # Vue CLI 配置
├── publish.sh                       # 发布脚本
├── src/
│   ├── main.js                      # 应用入口
│   ├── App.vue                      # 根组件
│   ├── api/                         # API 接口（35个文件）
│   │   └── fei/                     # 智慧农业子接口
│   ├── assets/                      # 静态资源
│   ├── components/                  # 公共组件
│   │   ├── ai/                      # AI 组件
│   │   ├── brain/                   # 大脑组件
│   │   └── tracing/screen/          # 溯源大屏组件（18个）
│   ├── config/                      # 全局配置
│   ├── layout/                      # 布局组件
│   │   └── components/              # TopHeader / Sidebar / TagsView
│   ├── router/                      # 路由配置
│   ├── store/                       # Vuex（user / settings / tagsView）
│   ├── styles/                      # 全局样式
│   ├── utils/                       # 工具函数（16个文件）
│   └── views/                       # 页面视图（85+文件）
│       ├── ai/                      # AI 对话
│       ├── customer/                # 客户管理
│       ├── fei/                     # 智慧农业
│       ├── huoban/                  # 伙伴云
│       ├── system/                  # 系统管理
│       ├── trace/                   # 溯源管理
│       ├── tracing/                 # 溯源追踪
│       └── weight/                  # 自助过磅
├── docs/                            # 文档
├── public/                          # 公共静态文件
└── logs/                            # 日志