apes-Authon-history/docs/saas-service深度分析报告.md

saas-service 项目源代码深度分析报告

一、项目基本信息

项目属性	值
GroupId	cn.apes
ArtifactId	saas-service
版本	1.0.0-SNAPSHOT
描述	账权用户服务
Java 版本	11
Spring Boot 版本	2.2.1.RELEASE
MyBatis Plus 版本	3.5.7
动态数据源版本	dynamic-datasource-spring-boot-starter 3.6.1
Redisson 版本	3.35.0
主启动类	cn.apes.CloudApplication
项目路径	/tmp/project-analysis/service-master

主启动类代码

文件路径: src/main/java/cn/apes/CloudApplication.java

@EnableAsync
@SpringBootApplication
@EnableScheduling
public class CloudApplication {
    public static void main(String[] args) {
        SpringApplication.run(CloudApplication.class, args);
    }
}

启动类启用了三个关键注解：@EnableAsync（异步任务）、@SpringBootApplication（Spring Boot 自动配置）、@EnableScheduling（定时任务）。

---

二、完整包结构

项目根包为 cn.apes.cloud，目录结构如下：

cn.apes.cloud
  |-- config/              # 配置类（12个文件）
  |-- controller/          # REST 控制器（62个文件）
  |   |-- traceability/    # 溯源模块控制器（9个文件）
  |-- domain/              # 数据模型层
  |   |-- entity/          # 核心实体类（43个文件）
  |   |-- dto/             # 数据传输对象（约35个文件）
  |   |-- vo/              # 视图对象（5个文件）
  |   |-- huoban/          # 伙伴云数据模型（11个文件）
  |   |-- traceability/    # 溯源数据模型（22个文件）
  |   |-- weight/          # 称重数据模型（13个文件）
  |-- filter/              # 过滤器（1个文件）
  |-- groovy/              # Groovy 脚本执行引擎（3个文件）
  |-- mapper/              # MyBatis Mapper 接口（约85个文件）
  |   |-- traceability/    # 溯源 Mapper（20个文件）
  |-- service/             # 业务逻辑层
  |   |-- impl/            # 服务实现类（约90个文件）
  |   |   |-- huoban/      # 伙伴云服务实现（6个文件）
  |-- task/                # 定时任务（1个文件）
  |-- util/                # 工具类（2个文件）
  |-- websocket/           # WebSocket 处理器（1个文件）

---

三、主要模块和功能划分

项目是一个大型 SaaS 多租户后端服务，包含以下核心业务模块：

1. 用户与企业认证模块

• 用户注册/登录（密码登录、微信小程序登录）
• 企业认证（提交/审核/重新提交）
• 多企业切换
• SSO 单点登录配置
• AccessToken 外部 API 鉴权

2. 权限管理模块

• 菜单管理（多应用菜单树）
• 权限管理（按应用分组）
• 角色管理（角色 CRUD、角色权限分配）
• 成员角色管理（按企业维度）
• 套餐权限控制

3. LLM/AI 模块（核心特色）

• LLM 厂商配置（LlmProviderConfig）：支持多厂商 API Key、BaseUrl 配置
• LLM 模型配置（LlmModelConfig）：模型列表管理，支持 chat/embedding/image 类型
• Agent 配置（LlmAgentConfig）：System Prompt、User Prompt、输出类型（text/json/markdown）
• 多轮对话（LlmChatController/LlmChatServiceImpl）：支持 Function Calling 工具调用循环
• Groovy 工具执行（GroovyExecutorService）：动态编译执行 Groovy 脚本作为 LLM 工具
• Skill 技能系统（AiSkill）：将技能内容注入 System Prompt
• 对话管理（LlmConversation/LlmConversationMessage）：会话持久化、消息历史
• 调用日志（LlmCallLog/LlmToolLog）：完整的调用审计和统计
• 变量替换：支持 {{variable}} 格式的提示词模板变量替换
• 多模态输入：支持图片 URL 和视频 URL 输入
• ASR 语音识别（AsrWebSocketHandler）：WebSocket 代理阿里云实时语音转文字

4. 伙伴云（HuoBan）集成模块

• 伙伴云 API 代理（表结构同步、数据 CRUD、文件上传）
• 伙伴云 SSO 登录
• AMIS 低代码页面配置
• 伙伴云 V2 API 集成

5. 溯源（Traceability）模块

• 溯源码管理（生成任务、码列表、绑定/解绑/作废/启用）
• 码货绑定（批量导入、未绑定码查询）
• 父子码关联
• 赋码审计
• 废码异常处理
• 产品分类管理
• 土地管理
• 采收批次
• 加工记录
• 质量检测
• 资质管理
• 证书管理
• 仓库管理（入库/出库/库位平面图/库存）
• 物流追踪
• 反馈管理
• 召回管理
• 溯源追踪配置

6. 智慧农业（Fei）模块

• 园区信息管理（FeiParkInfo）
• 地块信息管理（PlotInfo）
• 作物信息管理（FeiCrop）
• 作物物候期管理（FeiCropPhenology）
• 农事计划管理（FeiFarmPlan）
• 施肥配方管理（FeiFertilizationFormula）
• 灌溉计划管理（FeiIrrigationPlan）
• 灌溉计划执行记录（FeiIrrigationPlanExec）
• 电磁阀管理（FeiSolenoidValve）
• 电磁阀操作日志（FeiSolenoidValveLog）
• 投入品管理（FeiInputMaterial）
• 投入品库存日志（FeiInputMaterialStockLog）
• 水肥一体机设备管理（FeiFertigationDevice）
• 母液罐管理（FeiMotherTank）
• 加药操作和日志（FeiDosingLog）
• 市场设备管理（FeiMarketDevice）
• 设备数据上报（FeiDeviceDataReport）
• 摄像头管理（CameraInfo）
• 摄像头抓图（萤石云集成）

7. 称重（Weight）模块

• 车辆记录管理
• 称重设备管理
• 司机管理
• IC 卡管理
• 北斗卡管理（借用/归还/追踪记录）
• 称重票据管理（一次称重/二次称重/编辑/打印）
• 票据日志
• 报警规则管理（报警条件、报警记录）
• 客户 UI 配置

8. 套餐与配额管理模块

• 套餐方案管理（SysPackagePlan）
• 套餐权限配置（SysPackagePlanPermission）
• 套餐配额配置（SysPackagePlanQuota）
• 客户套餐管理（CustomerPackage）
• 配额增减（CustomerPackageController）
• 配额变更日志
• 套餐延期申请与审核
• 系统配额定义（SysQuota）

9. 组织管理模块

• 组织树管理（SysOrganization）

10. 开放平台模块

• OpenController：通过 open-key 鉴权的开放接口
• 溯源追踪配置查询
• 配额扣减

11. 其他模块

• 文件上传（阿里云 OSS）
• 外链管理（ExtLink）
• 操作日志（SysOperationLog）
• 健康检查（ActuatorController）

---

四、所有 Controller 及其 API 端点列表

用户与企业认证

Controller	路径前缀	主要端点
UserController	/user	POST /saveUserInfo, POST /pageUser, POST /loginPwd, POST /register, POST /resetPwd, GET /getCurrentUser, POST /editPwd, GET /getUserByPhone, GET /getCustomerUser, POST /selectCustomer, GET /getMyCustomers, POST /editProfile, POST /customer/editCurrent, GET /customer/getCurrent, POST /certifyEnterprise, GET /getPendingCustomer, POST /recertifyEnterprise
CustomerController	/customer	POST /pageCustomer, GET /getCustomerDetail, GET /addUser, GET /delUser, POST /employee/page, GET /employee/detail, POST /employee/update, POST /saveCustomer, POST /deleteCustomer, GET /getMyApps, GET /getCustomerApps, POST /addCustomerApp, POST /removeCustomerApp, GET /getAllApps, GET /getSSOConfig, POST /saveSSOConfig, POST /updateCustomerStatus, POST /auditCertification, POST /syncTenantsToHuoban
AccessTokenController	/sysAccessToken	POST /create, POST /page, POST /revoke, POST /enable, POST /regenerate, POST /delete
CommonController	/common	POST /upload, POST /upload1, POST /saveSsoConfig, GET /getSsoConfig, GET /code2Session, GET /huobanWebLogin, GET /uiConfig/getByCustomer

权限管理

Controller	路径前缀	主要端点
PermissionController	/permission	GET /currentMenus, GET /getAppMenus, GET /getMyPermissionCodes, GET /getPackageAppMenus, POST /saveMenu, GET /getAllMenu, POST /savePermission, GET /getAllPermission, GET /getPlanPermissionTree, POST /deletePermission, POST /deleteMenu, POST /getAllRole, POST /getAllRoleByAppName, POST /saveRole, POST /deleteRole, POST /setRolePermission, GET /getRolePermission, POST /setMemberRole, GET /getMemberAvailableRoles, GET /getMemberAssignedRoles, POST /setMemberRolesByCustomer, GET /getHuoBanUrl, GET /getHuobanToken, GET /getMenu, GET /getPaymentMenu, GET /changePaymentGroup
AppController	/app	POST /pageApp, POST /saveApp, POST /deleteApp, POST /getAppDetail
SysOrganizationController	/organization	POST /page, GET /tree, GET /detail, POST /add, POST /update, POST /delete, GET /listAll

LLM/AI 模块

Controller	路径前缀	主要端点
LlmChatController	/llmChat	POST /start（开始新对话）, POST /continue（继续多轮对话）
LlmAgentConfigController	/llmAgent	POST /page, POST /add, POST /update, POST /delete, POST /toggleStatus, GET /detail/{id}, POST /debug, POST /call/{agentId}
LlmProviderConfigController	/llmProvider	POST /page, POST /add, POST /update, POST /delete, POST /toggleStatus, GET /list
LlmModelConfigController	/llmModel	POST /page, POST /add, POST /update, POST /delete, POST /toggleStatus, GET /list
LlmConversationController	/llmConversation	POST /add, GET /detail/{id}, GET /listByAgent, POST /close, POST /delete, POST /addMessage, GET /messages, POST /deleteMessage
LlmAgentToolController	/llmAgentTool	GET /listByAgent, GET /listByTool, POST /add, POST /delete, POST /deleteByAgent, POST /batchAdd
LlmAgentSkillController	/llmAgentSkill	GET /listByAgent, GET /listBySkill, POST /add, POST /delete, POST /deleteByAgent, POST /batchAdd
LlmToolController	/llmTool	GET /page, GET /detail, POST /add, POST /update, POST /delete
GroovyToolExecuteController	/llmTool	POST /execute（执行 Groovy 工具脚本）, POST /clearCache
LlmToolLogController	/llmToolLog	GET /page, GET /detail, POST /add, POST /update, POST /delete
LlmCallLogController	/llmCallLog	POST /page, GET /detail/{id}, POST /delete, POST /batchDelete, POST /statistics
AiController	/ai	POST /Quotation（AI 报价单识别）
AiSkillController	/aiSkill	GET /page, GET /detail, POST /add, POST /update, POST /delete

伙伴云集成

Controller	路径前缀	主要端点
HuobanController	/huoban	GET /syncTables, GET /syncTableConfig, GET /syncAll, POST /huobanTableList, POST /huobanTableInfo, POST /huobanColumnList, POST /huobanColumnSave, GET /spaceList, POST /data, POST /create, POST /update, POST /upsert, GET /detail, POST /ids, POST /uploadFIle, POST /getFiles, GET /getSpaceUsers, POST /huobanDoc
Huoban2Controller	/huoban2	GET /syncTables, GET /syncTableConfig, GET /syncAll, POST /saveTableName, POST /huobanTableList, POST /huobanTableInfo, POST /huobanColumnList, POST /huobanColumnSave, GET /spaceList, POST /data, POST /dataOne, POST /upsetOne, POST /create, POST /update, POST /upsert, GET /detail, GET /webDetail, GET /del, POST /bulkDel, POST /ids, POST /uploadFIle, POST /getFiles, GET /getSpaceUsers, POST /webData, POST /webCreate, GET /webDel, POST /webCreateTable, GET /webLogin, GET /getAutomation, POST /automationButton, POST /automationCall, POST /searchUser, GET /batchInvite, POST /updateSpaceMemberGroup, GET /getSpaceMembers, GET /searchSpaceMember, GET /getSpaceGroups, POST /inviteAndAddToGroup

溯源模块

Controller	路径前缀	主要端点
TraceCodeController	/trace/code	POST /task/page, GET /task/detail, POST /task/add, POST /task/generateBatchCode, POST /task/update, POST /task/delete, POST /task/generate, POST /list/page, GET /list/detail, POST /list/bind, POST /list/unbind, POST /list/void, POST /list/enable, POST /bind/page, GET /bind/detail, POST /bind/add, POST /bind/batchImport, POST /bind/unboundList, POST /bind/unbind, POST /relation/page, GET /relation/detail, POST /relation/add, POST /relation/delete, POST /audit/page, GET /audit/detail, POST /exception/page, GET /exception/detail, POST /exception/add, POST /exception/handle, POST /exception/delete
TraceCategoryController	/trace/category	分类管理 CRUD
TraceProcessController	/trace/process	加工记录 CRUD
TraceQualityController	/trace/quality	质量检测 CRUD
TraceWarehouseController	/trace/warehouse	仓库入出库 CRUD
TraceCommonController	/trace/common	溯源公共接口
TraceHarvestController	/trace/harvest	采收批次 CRUD
TraceLandController	/trace/land	土地管理 CRUD
TraceWarehouseFloorPlanController	/trace/warehouseFloorPlan	库位平面图 CRUD

智慧农业模块

Controller	路径前缀	主要端点
FeiParkInfoController	/park	GET /page, GET /detail, POST /add, POST /update, POST /delete, GET /list
PlotInfoController	/fei/plot	POST /page, POST /detail, POST /add, POST /update, POST /delete
FeiCropController	/fei/crop	POST /page, GET /detail, POST /add, POST /update, POST /delete, GET /list
FeiCropPhenologyController	/fei/cropPhenology	物候期 CRUD
FeiFarmPlanController	/fei/farmPlan	农事计划 CRUD
FeiFertilizationFormulaController	/fei/fertilizationFormula	施肥配方 CRUD
FeiIrrigationPlanController	/irrigation/plan	GET /page, GET /detail, POST /add, POST /update, POST /delete, POST /toggle, GET /listByPark
FeiIrrigationPlanExecController	/irrigation/planExec	灌溉执行记录 CRUD
FeiSolenoidValveController	/fei/solenoidValve	电磁阀 CRUD
FeiSolenoidValveLogController	/fei/solenoidValveLog	电磁阀日志 CRUD
FeiInputMaterialController	/fei/inputMaterial	投入品 CRUD
FeiInputMaterialStockLogController	/fei/inputMaterialStockLog	投入品库存日志 CRUD
FeiFertigationDeviceController	/fertigation-device	GET /page, GET /detail, POST /add, POST /update, POST /delete, POST /dosing, POST /save-layout, GET /dosing-log, GET /dosing-log/all, GET /today-logs
FeiMarketDeviceController	/fei/marketDevice	市场设备 CRUD
FeiDeviceDataReportController	/fei/deviceDataReport	设备数据上报 CRUD
CameraInfoController	/cameraInfo	GET /page, GET /detail, POST /add, POST /update, POST /delete, POST /capture
CameraCaptureLogController	/cameraCaptureLog	抓图日志 CRUD

称重模块

Controller	路径前缀	主要端点
WeightController	/weight	车辆记录（/vehicle/*）、设备管理（/device/*）、司机管理（/driver/*）、IC卡管理（/card/*）、北斗卡管理（/beidou/*，含借用/归还/追踪/报警）、称重票据（/ticket/*，含一次/二次称重/编辑/打印）、报警规则（/alarmRule/*）

套餐与配额管理

Controller	路径前缀	主要端点
SysPackagePlanController	/packagePlan	POST /page, POST /add, POST /update, POST /delete, POST /toggleStatus, GET /detail, GET /getPermissions, POST /savePermissions, GET /getQuotas, GET /getAllQuotas, GET /getPlanApps, GET+POST /saveQuotas
SysQuotaController	/quota	POST /page, POST /add, POST /update, POST /delete, GET /detail
CustomerPackageController	/customerPackage	GET /list, POST /add, POST /edit, POST /delete, POST /saveQuotas, GET /getQuotas, GET /myPackages, POST /overview, POST /submitExtendApply, POST /extendApplyList, POST /reviewExtendApply, POST /increaseQuota, POST /decreaseQuota, GET /quotaChangeLogs

其他

Controller	路径前缀	主要端点
OpenController	/open	GET /trackingConfig/getByCustomerId, POST /customerPackage/decreaseQuota
ExtLinkController	/extLink	GET /page, GET /detail, POST /add, POST /update, POST /delete
SysOperationLogController	/operationLog	POST /page, GET /listCustomers
TrackingConfigController	/trackingConfig	GET /list, GET /getByCustomerId, GET /current, POST /save, POST /delete, GET /customers
ActuatorController	/actuator	GET /health
WeiXin2Controller	/weixin2	（空控制器，预留）

---

五、核心业务实体

LLM/AI 相关实体

实体类	说明	关键字段
LlmProviderConfig	LLM 厂商配置	vendorCode, vendorName, baseUrl, apiKey, iconUrl, status
LlmModelConfig	LLM 模型配置	vendorCode, modelName, displayName, modelType(chat/embedding/image), supportVision, supportVideo, isEmbedding, maxTokens, maxContextTokens
LlmAgentConfig	Agent 配置	title, userPrompt, systemPrompt, providerId, modelId, outputType(text/json/markdown), supportImage, supportVideo
LlmConversation	对话会话	agentId, title, status(1活跃/0关闭), messageCount, lastActiveTime
LlmConversationMessage	对话消息	conversationId, messageType(system/user_prompt/user/assistant/tool_call/tool_result), content, toolName, toolParams, toolResult, toolStatus, model, tokens, duration
LlmCallLog	LLM 调用日志	agentId, agentTitle, modelName, systemPrompt, userPrompt, userInput, uploadedFiles, responseContent, promptTokens, completionTokens, totalTokens, durationMs, callStatus, errorMessage
LlmToolLog	工具执行日志	toolId, toolName, traceId, agentId, skillId, inputData, outputData, status, errorMsg, executorIp, duration
LlmAgentTool	Agent-工具关联	agentId, toolId
LlmAgentSkill	Agent-技能关联	agentId, skillId
AiSkill	AI 技能	skillName, skillKey, description, content, category, status

核心业务实体

实体类	说明
CustomerInfo	企业/客户信息（企业名称、类型、法人、管理员、营业执照、行业、省市等）
UserInfo	用户信息
CustomerUser	客户-用户关联
AppInfo	应用信息
CustomerPackage	客户套餐
SysPackagePlan	套餐方案
SysQuota	系统配额定义
SysMenu	菜单
SysRole	角色
SysMemberRole	成员角色关联
SysAccessToken	AccessToken（外部 API 鉴权令牌）
SysOperationLog	操作日志
SsoConfig	SSO 单点登录配置
TrackingConfig	溯源追踪配置
SysOrganization	组织架构

溯源实体（22个）

TraceCode（溯源码）、TraceCodeTask（生成任务）、TraceCodeBind（码货绑定）、TraceCodeRelation（父子码关联）、TraceCodeAudit（赋码审计）、TraceCodeException（废码异常）、TraceCategory（产品分类）、TraceProduct（产品）、TraceLand（土地）、TraceHarvestBatch（采收批次）、TraceProcessRecord（加工记录）、TraceQualityTest（质量检测）、TraceQualification（资质）、TraceCertificate（证书）、TraceWarehouseIn/TraceWarehouseInDetail（入库）、TraceWarehouseOut/TraceWarehouseOutDetail（出库）、TraceWarehouseFloorPlan（库位平面图）、TraceInventory（库存）、TraceLogistics（物流）、TraceFeedback（反馈）、TraceRecall（召回）

称重实体（13个）

WeightTicket（称重票据）、WeightTicketLog（票据日志）、WeightDevice（称重设备）、WeightDriver（司机）、WeightCard（IC卡）、WeightVehicleRecord（车辆记录）、WeightBeidouCard（北斗卡）、WeightBeidouBorrowRecord（借用记录）、WeightBeidouTrackingRecord（追踪记录）、WeightBeidouAlarmRule（报警规则）、WeightBeidouAlarmRuleCondition（报警条件）、WeightBeidouAlarmRecord（报警记录）、CustomerUiConfig（客户UI配置）

农业实体

FeiParkInfo（园区）、PlotInfo（地块）、FeiCrop（作物）、FeiCropPhenology（物候期）、FeiFarmPlan（农事计划）、FeiFertilizationFormula（施肥配方）、FeiIrrigationPlan（灌溉计划）、FeiSolenoidValve（电磁阀）、FeiSolenoidValveLog（电磁阀日志）、FeiInputMaterial（投入品）、FeiInputMaterialStockLog（投入品库存日志）、FeiFertigationDevice（水肥一体机）、FeiMotherTank（母液罐）、FeiDosingLog（加药日志）、FeiMarketDevice（市场设备）、FeiDeviceDataReport（设备数据上报）、CameraInfo（摄像头）、CameraCaptureLog（抓图日志）

---

六、技术架构特点

1. 多租户动态数据源

核心机制：基于 baomidou dynamic-datasource 实现多租户数据源隔离。

关键文件：

• src/main/java/cn/apes/cloud/config/TenantSource.java — 自定义注解
• src/main/java/cn/apes/cloud/config/DataSourceHeaderAspect.java — AOP 切面

工作原理：

1. @TenantSource 注解可标注在 Controller 类或方法上
2. DataSourceHeaderAspect 切面拦截带有 @TenantSource 的类/方法
3. 从 HTTP 请求头 X-Tenant-ID 读取租户标识
4. 支持的租户标识：user、zx、plant（默认为 user）
5. 通过 DynamicDataSourceContextHolder.push(head) 切换数据源
6. 配置了两个数据源：cloud（主库）和 huoban（伙伴云库）

配置文件中的多租户配置：

tenant:
  enabled: true
  default-tenant: user
  header-name: X-Tenant-ID
  dynamic-create: true

2. LLM 集成架构

架构层次：

Agent 配置 (LlmAgentConfig)
    |-- 厂商配置 (LlmProviderConfig) → API Key, BaseUrl
    |-- 模型配置 (LlmModelConfig) → 模型名称, 类型
    |-- 关联工具 (LlmAgentTool → LlmTool) → Groovy 脚本
    |-- 关联技能 (LlmAgentSkill → AiSkill) → 注入 System Prompt
    |
    v
LLM 调用 (DashScope OpenAI 兼容 API)
    |
    |-- 单次调用: LlmCallServiceImpl.callModel()
    |-- 多轮对话: LlmChatServiceImpl.startChat()/continueChat()
    |       |-- Function Calling 循环（最多 10 轮）
    |       |-- Groovy 工具执行: GroovyExecutorService.executeTool()
    |       |-- 消息持久化: LlmConversationMessage
    |
    v
日志审计: LlmCallLog (调用日志) + LlmToolLog (工具日志)

关键特点：

• 使用阿里云 DashScope API（OpenAI 兼容格式），endpoint: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
• 支持多厂商配置，可通过 providerId 灵活切换
• 提示词变量替换：{{variable}} 格式，通过 userParams 传入
• 多模态支持：图片 URL（image_url 类型）和视频 URL（video_url 类型）
• Function Calling：自动检测 tool_calls，执行 Groovy 工具脚本，将结果回传给 LLM
• 最大工具调用轮次限制：10 轮（防止死循环）
• 输出类型控制：text / json / markdown，支持 response_format 设置

3. Groovy 动态脚本引擎

关键文件：

• src/main/java/cn/apes/cloud/groovy/GroovyExecutorService.java
• src/main/java/cn/apes/cloud/groovy/GroovyToolExecutor.java（接口）
• src/main/java/cn/apes/cloud/groovy/JsonSchemaValidator.java

特点：

• 使用 GroovyClassLoader 动态编译 Groovy 脚本
• 编译结果缓存（ConcurrentHashMap），避免重复编译导致 Metaspace 泄漏
• 脚本必须实现 GroovyToolExecutor 接口
• 入参 JSON Schema 校验
• 完整的执行日志记录（IP、耗时、输入/输出、错误信息）
• 支持缓存清除和重新编译

4. WebSocket ASR 语音识别代理

关键文件：src/main/java/cn/apes/cloud/websocket/AsrWebSocketHandler.java

特点：

• WebSocket 端点：/asr/ws
• 代理前端与阿里云 ASR 服务的 WebSocket 通信
• 使用模型：fun-asr-realtime（实时语音转文字）
• 音频格式：PCM, 16000Hz 采样率
• 缓冲机制：在 ASR 服务返回 task-started 之前缓存音频数据
• 每个前端会话独立维护阿里云 WebSocket 连接

5. AccessToken 外部 API 鉴权

关键文件：

• src/main/java/cn/apes/cloud/filter/AccessTokenFilter.java
• src/main/java/cn/apes/cloud/config/AccessTokenFilterConfig.java

鉴权流程：

1. 过滤器以最高优先级（order=1）拦截所有请求
2. 提取 Token：优先 X-Access-Token 请求头，其次 Authorization: Bearer <token>
3. 校验 Token：通过 SysAccessTokenService.validate() 校验（含 IP 白名单检查）
4. 校验通过：将用户/企业信息写入 Redis，包装 Request 注入 token header，使 @Login AOP 能正常工作
5. 校验失败：返回 401
6. 无 Token：放行，交给后续 @Login AOP 处理
7. 记录外部系统调用日志

6. 伙伴云（HuoBan）深度集成

项目与伙伴云低代码平台深度集成：

• 两套 API 控制器（HuobanController 使用 @DS("huoban") 直连伙伴云数据库，Huoban2Controller 通过伙伴云 OpenAPI）
• 伙伴云 SSO 单点登录
• 表结构同步、数据 CRUD、文件上传
• AMIS 低代码页面配置
• 自动化按钮调用
• 空间成员管理

7. Redis 双数据库架构

关键文件：src/main/java/cn/apes/cloud/config/RedissonConfiguration.java

• redissonClient()：使用 database 7（主业务缓存）
• redissonClient9()：使用 database 9（辅助用途）
• 编解码器：JsonJacksonCodec

8. 定时任务

关键文件：src/main/java/cn/apes/cloud/task/CameraCaptureTask.java

• 摄像头定时抓图任务：每小时执行一次（@Scheduled(fixedRate = 1000 * 60 * 60)）
• 遍历所有摄像头，调用萤石云 API 进行抓图
• 记录成功/失败统计

9. 文件存储

• 阿里云 OSS 对象存储（OssConfiguration）
• 桶名：zq-cloud，区域：oss-cn-beijing
• 伙伴云文件上传代理

---

七、配置文件中的关键配置

application.yml（主配置）

文件路径: src/main/resources/application.yml

spring:
  profiles:
    active: local              # 默认激活 local 环境
  jackson:
    time-zone: GMT+8           # 东八区时区
    date-format: yyyy-MM-dd HH:mm:ss

# 多租户配置
tenant:
  enabled: true                # 启用多租户
  default-tenant: user         # 默认租户
  header-name: X-Tenant-ID     # 租户请求头名称
  dynamic-create: true         # 允许动态创建数据源

mybatis-plus:
  global-config:
    db-config:
      logic-delete-field: isDel     # 全局逻辑删除字段
      logic-delete-value: 1          # 逻辑已删除值
      logic-not-delete-value: 0      # 逻辑未删除值

application-prod.yml（生产环境）

文件路径: src/main/resources/application-prod.yml

配置项	值
服务端口	7777
Python 路径	/usr/bin/python3
工作路径	/data/services/saas-service/data
主数据源 (cloud)	MySQL 192.168.1.161:3306/cloud
伙伴云数据源 (huoban)	MySQL 192.168.1.161:3306/user
Redis	192.168.1.165:6403, database 7
文件上传限制	max-file-size: 20MB, max-request-size: 200MB
OSS	oss-cn-beijing.aliyuncs.com, bucket: zq-cloud
伙伴云 API	https://hb.zhangquyun.com/server/api
伙伴云 V2	app-id: 1000001
支付域名	https://payment.yilise.com/

application-local.yml（本地开发环境）

文件路径: src/main/resources/application-local.yml

配置项	值
服务端口	8202
主数据源	MySQL 192.168.31.201:3389/cloud
伙伴云数据源	MySQL 192.168.31.201:3389/user
Redis	192.168.31.201:7890, database 7
MyBatis 日志	StdOutImpl（控制台输出 SQL）
调试日志	TenantInterceptor=debug, dynamic.datasource=debug

---

八、docs 目录下的 API 文档

项目在 docs/ 目录下包含 15 个 Markdown 文档：

文档文件	内容
llmAgentTool-api.md	LLM Agent 工具关联 API 文档
llmAgentSkill接口文档.md	LLM Agent 技能关联 API 文档
llmConversation-api.md	LLM 对话会话管理 API 文档
llmTool接口文档.md	LLM 工具管理 API 文档
api-access-token.md	AccessToken 外部 API 鉴权文档
api-login.md	登录 API 文档
多租户使用说明.md	多租户动态数据源使用说明
账权平台对接.md	账权 SaaS 云对接文档
账权开放平台对接.md	开放平台对接文档
伙伴云低代码对接文档.md	伙伴云低代码平台对接文档
irrigation_plan_api.md	灌溉计划 API 文档
cameraInfo-api.md	摄像头信息管理 API 文档
input-material-stock-log-api-doc.md	投入品库存日志 API 文档
input-material-stock-log-test-report.md	投入品库存日志测试报告
Groovy工具脚本生成提示词.md	Groovy 工具脚本生成的 LLM 提示词

---

九、技术栈总结

类别	技术
基础框架	Spring Boot 2.2.1.RELEASE, Java 11
ORM	MyBatis Plus 3.5.7
动态数据源	baomidou dynamic-datasource 3.6.1
缓存	Redis + Redisson 3.35.0
对象存储	阿里云 OSS SDK 3.17.4
LLM/AI	阿里云 DashScope（OpenAI 兼容格式）
动态脚本	Groovy 3.0.19
WebSocket	Spring WebSocket + Java-WebSocket 1.5.3
工具库	Hutool 5.8.16, Fastjson, Lombok 1.18.36
飞书集成	oapi-sdk 2.4.6
Excel	Apache POI 4.1.2
验证	Hibernate Validator 6.1.0.Final
公共库	apes-commons 0.0.7-SNAPSHOT（自研公共库）

---

十、架构亮点总结

1. 多租户 SaaS 架构：通过自定义 @TenantSource 注解 + AOP 切面 + 动态数据源实现透明多租户隔离，支持 user、zx、plant 三个租户数据库。

2. LLM Agent 平台：完整的 LLM Agent 管理平台，支持厂商/模型/Agent 三级配置，多轮对话 + Function Calling + Groovy 工具执行 + Skill 技能注入，形成了完整的 AI Agent 工作流。

3. Groovy 动态工具引擎：通过 Groovy 脚本实现 LLM 工具的动态扩展，无需重启服务即可添加新工具，支持 JSON Schema 入参校验和编译缓存。

4. 伙伴云深度集成：既是数据源（直连伙伴云 MySQL），也是 API 代理（通过伙伴云 OpenAPI），还支持 SSO 和 AMIS 低代码页面。

5. 多模态 AI 输入：LLM 调用支持图片 URL 和视频 URL 的多模态输入，支持视觉理解模型。

6. 实时语音识别：WebSocket 代理阿里云 ASR 服务，实现前端实时语音转文字功能。

7. 全链路审计：LLM 调用日志、工具执行日志、操作日志三层审计体系，支持调用统计和错误追踪。

8. 开放平台：通过 AccessToken 机制支持外部系统安全调用，含 IP 白名单、过期时间、配额扣减等能力。

---

前端应用补充说明

说明书还包含以下 10 个章节的前端部分：

1. 项目概述 — 平台定位、核心业务域、项目组成（62 个 Controller、85+ 前端页面、10+ 业务模块）
2. 系统架构 — 整体架构图、技术栈总览（前后端对照表）
3. 后端服务 — 包结构、多数据源配置（cloud/user/huoban）、核心配置类、定时任务
4. 前端应用 — 目录结构、布局架构、动态路由系统（4 种 menuType）、Vuex 状态管理、第三方库
5. 核心功能模块 — 智慧农业、产品溯源、自助过磅、套餐配额、伙伴云集成等 6 大模块详解
6. LLM / AI Agent 平台 — 架构层次图、10 项核心能力（Function Calling、Groovy 动态工具、多轮对话、ASR 等）、前端 AI 页面
7. 多租户与权限体系 — 多租户切换原理、权限层级图、AccessToken 开放平台
8. API 接口概览 — 全部 Controller 路径前缀和核心端点、前端代理配置
9. 部署与配置 — 生产/开发环境配置对照、环境依赖
10. 项目目录结构 — 前后端完整目录树