init: apes-Authon-history — 剥离历史与源码分析归档

- docs/: 源码分析报告、代码深度解析、项目说明书、独立服务化方案 - backend/: 账权模块提取说明（提取原则、文件清单、耦合度验证） - frontend/: 前端剥离方案、剥离历史与说明、框架修改详情
2026-08-09 13:04:04 +08:00
commit 9cbb1f7695
9 changed files with 4639 additions and 0 deletions
@@ -0,0 +1,627 @@
+# 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`
+
+```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`（伙伴云库）
+
+**配置文件中的多租户配置**：
+
+```yaml
+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`
+
+```yaml
+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. **项目目录结构** — 前后端完整目录树