XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
1197363ac6ea5d7f1554360bbc89eceecb4fabbb
aiot-platform-cloud/.qoder/repowiki/zh/content/业务模块设计.md

28 KiB
Raw Blame History

业务模块设计

**本文引用的文件** - [pom.xml](file://pom.xml) - [01-项目概述.md](file://docs/technical-overview/01-项目概述.md) - [02-系统架构.md](file://docs/technical-overview/02-系统架构.md) - [03-核心模块详解.md](file://docs/technical-overview/03-核心模块详解.md) - [part1-架构总览.md](file://docs/ops-architecture/part1-架构总览.md) - [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/package-info.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/package-info.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/SystemServerApplication.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/SystemServerApplication.java) - [viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/package-info.java](file://viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/package-info.java) - [viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/InfraServerApplication.java](file://viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/InfraServerApplication.java) - [viewsh-module-ops-api/src/main/java/com/viewsh/module/ops/api/package-info.java](file://viewsh-module-ops-api/src/main/java/com/viewsh/module/ops/api/package-info.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/core/lifecycle/OrderLifecycleManager.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/core/lifecycle/OrderLifecycleManager.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/service/fsm/OrderStateMachine.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/core/fsm/OrderStateMachine.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/core/dispatch/DispatchEngine.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/core/dispatch/DispatchEngine.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/service/order/OpsOrderService.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/service/order/OpsOrderService.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/dal/dataobject/workorder/OpsOrderDO.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/dal/dataobject/workorder/OpsOrderDO.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/dal/mysql/workorder/OpsOrderMapper.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/dal/mysql/workorder/OpsOrderMapper.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/service/cleanorder/CleanOrderService.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/environment/service/CleanOrderService.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/environment/domain/cleaner/CleanerDomainService.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/environment/domain/cleaner/CleanerDomainService.java) - [viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/environment/integration/consumer/CleanOrderCreateEventHandler.java](file://viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/environment/integration/consumer/CleanOrderCreateEventHandler.java) - [viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/ErpServerApplication.java](file://viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/ErpServerApplication.java) - [viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/purchase/ErpPurchaseOrderController.java](file://viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/purchase/ErpPurchaseOrderController.java) - [viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/sale/ErpSaleOrderController.java](file://viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/sale/ErpSaleOrderController.java) - [viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java](file://viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java) - [viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/purchase/ErpPurchaseOrderService.java](file://viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/purchase/ErpPurchaseOrderService.java) - [viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/sale/ErpSaleOrderService.java](file://viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/sale/ErpSaleOrderService.java) - [viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/stock/ErpStockService.java](file://viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/stock/ErpStockService.java) - [viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/CrmServerApplication.java](file://viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/CrmServerApplication.java) - [viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java](file://viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java) - [viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java](file://viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java) - [viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contract/CrmContractController.java](file://viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contract/CrmContractController.java) - [viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/customer/CrmCustomerService.java](file://viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/customer/CrmCustomerService.java) - [viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/business/CrmBusinessService.java](file://viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/business/CrmBusinessService.java) - [viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/contract/CrmContractService.java](file://viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/contract/CrmContractService.java)

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

引言

本设计文档面向AIOT平台云项目的业务模块，围绕系统管理、基础设施、运维管理、CRM、ERP等模块，系统阐述其功能设计、数据模型、接口设计、模块间集成与数据流转机制，并提供可落地的扩展性、可配置性与定制化能力说明，以及安全、权限与数据保护措施，最后给出部署、配置与维护的最佳实践。

项目结构

项目采用多模块Maven聚合结构，核心模块包括网关、系统服务、基础设施、IoT、运维（Ops）、ERP、CRM等。系统整体遵循“感知-连接-平台-应用”的物联网分层架构，业务中台与IoT中台协同，支撑多条业务线的数字化运营。

graph TB
subgraph "应用层"
UI["前端应用<br/>Admin/Vue3/UniApp"]
end
subgraph "接入层"
GW["API网关<br/>viewsh-gateway"]
IOTGW["IoT网关<br/>viewsh-module-iot-gateway"]
end
subgraph "平台层"
SYS["系统服务<br/>viewsh-module-system"]
INFRA["基础设施<br/>viewsh-module-infra"]
OPS["运维管理<br/>viewsh-module-ops"]
ERP["企业资源计划<br/>viewsh-module-erp"]
CRM["客户关系管理<br/>viewsh-module-crm"]
IOT["物联网服务<br/>viewsh-module-iot"]
end
subgraph "数据层"
MYSQL["关系型数据库<br/>MySQL/国产库"]
TD["时序数据库<br/>TDengine"]
REDIS["缓存/分布式锁<br/>Redis"]
MQ["消息队列<br/>RocketMQ"]
end
UI --> GW
GW --> SYS
GW --> INFRA
GW --> OPS
GW --> ERP
GW --> CRM
GW --> IOT
IOTGW --> IOT
SYS --> MYSQL
INFRA --> MYSQL
OPS --> MYSQL
ERP --> MYSQL
CRM --> MYSQL
IOT --> MYSQL
IOT --> TD
SYS --> REDIS
INFRA --> REDIS
OPS --> MQ
ERP --> MQ
CRM --> MQ

图表来源

章节来源

核心组件

  • 系统服务（System）：统一认证授权、RBAC权限、多租户、字典、日志、通知、短信、社交登录等。
  • 基础设施（Infra）：文件存储、定时任务、邮件/短信发送、消息生产消费等。
  • 运维管理（Ops）：工单引擎、状态机、派单引擎、队列管理、业务线（保洁/安保/工程/客服）域服务。
  • ERP：采购、销售、库存、财务、产品、仓库等模块化业务。
  • CRM：客户、商机、合同、回款等客户生命周期管理。
  • IoT：设备接入、协议处理、规则引擎、物模型与OTA升级。

章节来源

架构总览

系统采用“双网关”架构：API网关负责HTTP业务流量与安全防护；IoT网关负责TCP/MQTT/HTTP设备接入。平台层通过微服务实现业务中台与IoT中台的协同，数据层采用“冷热分离 + 时序优化”的混合存储策略。

graph TB
subgraph "接入层"
AGW["API网关<br/>Spring Cloud Gateway"]
IGW["IoT网关<br/>Netty/Vert.x"]
end
subgraph "平台层"
SYS["系统服务<br/>OAuth2/RBAC/多租户"]
OPS["运维管理<br/>工单引擎/状态机/派单"]
INFRA["基础设施<br/>文件/任务/消息"]
ERP["ERP<br/>采购/销售/库存/财务"]
CRM["CRM<br/>客户/商机/合同"]
IOT["IoT<br/>设备/规则/物模型"]
end
subgraph "数据层"
RDS["MySQL/国产库"]
TS["TDengine"]
CACHE["Redis"]
MQ["RocketMQ"]
end
AGW --> SYS
AGW --> OPS
AGW --> INFRA
AGW --> ERP
AGW --> CRM
AGW --> IOT
IGW --> IOT
SYS --> RDS
OPS --> RDS
INFRA --> RDS
ERP --> RDS
CRM --> RDS
IOT --> RDS
IOT --> TS
SYS --> CACHE
OPS --> MQ
ERP --> MQ
CRM --> MQ

图表来源

章节来源

详细组件分析

系统管理模块（System）

  • 职责边界：统一认证（OAuth2）、RBAC权限、多租户、字典、日志、通知、短信、社交登录等。
  • 接口设计：通过API包导出供其他模块调用，如用户、角色、权限、部门、字典、日志、通知、短信、社交等。
  • 数据模型：用户、角色、权限、部门、字典、登录日志、操作日志、通知、短信、社交等实体与映射。
  • 安全与权限：基于Spring Security与RBAC模型，支持数据权限范围（本人/本部门/本部门及以下等）。
  • 扩展性与定制：通过注解与配置扩展权限范围、字典项、通知模板、短信模板等。
classDiagram
class AdminUserApiImpl
class RoleApiImpl
class PermissionApiImpl
class DeptApiImpl
class DictDataApiImpl
class LoginLogApiImpl
class OperateLogApiImpl
class NotifyMessageSendApiImpl
class SmsSendApiImpl
class SocialUserApiImpl
class TenantApiImpl
class OAuth2TokenApiImpl
AdminUserApiImpl --> TenantApiImpl : "租户隔离"
RoleApiImpl --> PermissionApiImpl : "权限继承"
DeptApiImpl --> AdminUserApiImpl : "部门关联"
DictDataApiImpl --> AdminUserApiImpl : "字典上下文"
LoginLogApiImpl --> AdminUserApiImpl : "登录审计"
OperateLogApiImpl --> AdminUserApiImpl : "操作审计"
NotifyMessageSendApiImpl --> AdminUserApiImpl : "消息投递"
SmsSendApiImpl --> AdminUserApiImpl : "短信投递"
SocialUserApiImpl --> AdminUserApiImpl : "第三方登录"
OAuth2TokenApiImpl --> AdminUserApiImpl : "令牌管理"

图表来源

章节来源

基础设施模块（Infra）

  • 职责边界：文件存储（MinIO/S3适配）、分布式任务（XXL-Job）、消息生产消费（邮件/短信）、通知服务。
  • 接口设计：文件服务、定时任务、消息发送等API。
  • 数据模型：文件、任务、消息等DO与Mapper。
  • 扩展性与定制：通过工厂模式适配不同对象存储，支持预签名上传；消息通道可扩展。
classDiagram
class FileService
class TaskScheduler
class MailProducer
class SmsProducer
FileService <.. TaskScheduler : "定时清理/归档"
MailProducer <.. FileService : "附件上传"
SmsProducer <.. FileService : "验证码短信"

图表来源

章节来源

运维管理模块（Ops）

  • 职责边界：工单引擎、状态机、派单引擎、队列管理、业务线域服务（保洁/安保/工程/客服）。
  • 核心流程：工单生命周期管理（创建、派单、到达、处理、暂停/恢复、完成/取消），支持P0紧急打断与自动恢复。
  • 数据模型：工单、队列、派单记录、事件、区域、清洁员状态、清洁日志等。
  • 事件驱动：通过事件发布器解耦状态变更，监听器/处理器处理后续动作。
  • 扩展性与定制：业务线通过接口扩展核心引擎，派单策略可插拔。
sequenceDiagram
participant 用户 as "用户/系统"
participant 订单服务 as "OpsOrderService"
participant 生命周期 as "OrderLifecycleManager"
participant 状态机 as "OrderStateMachine"
participant 派单引擎 as "DispatchEngine"
participant 队列 as "OrderQueueService"
用户->>订单服务 : "创建工单"
订单服务->>生命周期 : "提交状态变更请求"
生命周期->>状态机 : "验证转换规则"
状态机-->>生命周期 : "允许/拒绝"
生命周期->>派单引擎 : "推荐执行人"
派单引擎-->>生命周期 : "派单结果"
生命周期->>队列 : "入队/更新队列状态"
队列-->>用户 : "派单完成/等待中"

图表来源

章节来源

保洁条线（环境管理）

  • 业务范围：日常/临时保洁、排班、巡检、耗材管理。
  • 核心能力：智能调度（自动派单、优先级队列、紧急插队）、保洁员状态管理、工牌语音播报、绩效统计。
  • 技术实现：清洁域服务、清洁员状态服务、清洁订单服务、事件处理器、派单策略（区域/优先级）。
flowchart TD
Start(["创建清洁工单"]) --> AutoOrManual{"定时生成/手动创建"}
AutoOrManual --> |定时| AutoGen["定时任务触发"]
AutoOrManual --> |手动| ManualCreate["巡检员创建"]
AutoGen --> Recommend["派单引擎推荐执行人"]
ManualCreate --> Recommend
Recommend --> Enqueue["加入优先级队列"]
Enqueue --> Voice["工牌语音播报"]
Voice --> Arrive["到岗打卡"]
Arrive --> Working["作业进行中"]
Working --> Pause{"是否暂停？"}
Pause --> |是| PauseTask["暂停/被打断"]
Pause --> |否| Complete["完成工单"]
PauseTask --> Resume{"是否恢复？"}
Resume --> |是| Working
Resume --> |否| Cancel["取消工单"]
Complete --> Next["自动派发下一个任务"]
Cancel --> End(["结束"])
Next --> End

图表来源

章节来源

ERP模块

  • 职责边界：采购、销售、库存、财务、产品、仓库等企业资源管理。
  • 接口设计：控制器层提供REST API，服务层封装业务逻辑，DAO层映射数据库。
  • 数据模型：采购订单、销售订单、出入库、库存、财务账户、产品、单位、供应商、客户、仓库等。
  • 扩展性与定制：模块化服务，支持新增业务单据与流程。
classDiagram
class ErpPurchaseOrderController
class ErpSaleOrderController
class ErpStockController
class ErpPurchaseOrderService
class ErpSaleOrderService
class ErpStockService
ErpPurchaseOrderController --> ErpPurchaseOrderService : "调用"
ErpSaleOrderController --> ErpSaleOrderService : "调用"
ErpStockController --> ErpStockService : "调用"

图表来源

章节来源

CRM模块

  • 职责边界：客户、商机、合同、回款等客户生命周期管理。
  • 接口设计：控制器层提供REST API，服务层封装客户、商机、合同相关业务。
  • 数据模型：客户、商机、合同、回款记录等。
  • 扩展性与定制：支持客户分级、商机阶段、合同模板等配置化。
classDiagram
class CrmCustomerController
class CrmBusinessController
class CrmContractController
class CrmCustomerService
class CrmBusinessService
class CrmContractService
CrmCustomerController --> CrmCustomerService : "调用"
CrmBusinessController --> CrmBusinessService : "调用"
CrmContractController --> CrmContractService : "调用"

图表来源

章节来源

IoT模块（补充）

  • 职责边界：设备接入（TCP/MQTT/HTTP）、协议处理（如JT808）、规则引擎、物模型与OTA升级。
  • 数据模型：设备、属性、事件、指令、规则、物模型等。
  • 扩展性与定制：协议适配器可扩展，规则表达式可配置。

章节来源

依赖分析

  • 模块内聚与耦合：System/Infra作为底座模块被其他业务模块广泛依赖；Ops/ERP/CRM相对独立，通过API与事件进行集成。
  • 外部依赖：Spring Boot、Spring Cloud Alibaba、MyBatis Plus、Redis、RocketMQ、TDengine、XXL-Job等。
  • 事件与消息：Ops/ERP/CRM通过消息队列实现异步解耦与削峰填谷。
graph LR
SYS["System"] --> OPS["Ops"]
SYS --> INFRA["Infra"]
SYS --> ERP["ERP"]
SYS --> CRM["CRM"]
SYS --> IOT["IoT"]
OPS --> MQ["RocketMQ"]
ERP --> MQ
CRM --> MQ
INFRA --> MQ
OPS --> REDIS["Redis"]
SYS --> REDIS
OPS --> MYSQL["MySQL"]
ERP --> MYSQL
CRM --> MYSQL
SYS --> MYSQL
IOT --> TD["TDengine"]

图表来源

章节来源

性能考虑

  • 读写分离与存算分离：业务数据走MySQL，设备时序数据走TDengine，热点数据走Redis。
  • 异步解耦：通过消息队列削峰填谷，降低瞬时峰值对数据库的压力。
  • 并发与连接：IoT网关采用Netty/Vert.x，支持百万级长连接与高并发。
  • 缓存策略：热点配置、令牌、在线状态等放入Redis，减少数据库压力。
  • 定时任务：XXL-Job统一调度，避免服务内定时任务分散导致的资源竞争。

故障排查指南

  • 网关层：检查API网关路由与限流配置，确认JWT解析与租户透传是否正常。
  • 认证与权限：核对RBAC权限与数据权限范围，确认租户隔离是否生效。
  • 工单状态：通过生命周期管理器与状态机验证状态转换是否符合预期，检查事件发布与监听器是否正常。
  • 消息链路：检查消息生产/消费是否成功，确认队列状态与重复消费处理。
  • 文件与任务：验证文件上传/下载路径与权限，确认定时任务执行日志与失败重试。
  • 数据一致性：关注跨服务事务与幂等设计，必要时启用分布式事务或补偿机制。

结论

本设计文档系统梳理了AIOT平台云的业务模块，明确了各模块的职责边界、数据模型、接口设计与集成方式。通过事件驱动、状态机与派单引擎，Ops模块实现了高效的工单调度与执行；System/Infra提供统一的认证、权限与基础设施能力；ERP/CRM覆盖企业资源与客户生命周期管理；IoT模块支撑设备接入与规则编排。整体架构具备良好的扩展性、可配置性与安全性，适合在多租户场景下进行规模化复制与定制化落地。

附录

  • 部署与运维最佳实践
    • 容器化部署：使用Docker Compose/Kubernetes，实现无状态服务弹性伸缩与持久化数据分离。
    • 网关与安全：开启API网关鉴权与限流，配置Sentinel与WAF，确保流量入口安全。
    • 数据备份与灾备：关系型数据定期备份，时序数据保留策略与归档策略明确。
    • 监控与可观测性：接入SkyWalking链路追踪、Prometheus指标采集与告警。
    • 配置管理：使用Nacos进行配置中心与动态路由，支持灰度发布与蓝绿部署。
  • 安全与权限
    • OAuth2与JWT令牌管理，RBAC权限模型与数据权限范围控制。
    • 多租户字段隔离与租户套餐限制，防止越权与资源滥用。
    • 敏感数据脱敏与加密传输，日志审计与操作留痕。
  • 可扩展性与定制化
    • 通过接口与策略模式扩展派单策略、事件处理器与通知模板。
    • 支持新增业务线与单据类型，保持核心引擎稳定与对外API一致。