总体设计图.md
36.8 KB
HC小区管理系统 - 总体设计图
一、系统概览
HC小区管理系统（MicroCommunity）是一套面向物业企业的SaaS平台，覆盖物业管理全场景： 房产 → 业主 → 缴费 → 报修 → 巡检 → 停车 → 门禁 → 道闸 → 监控 → 工作流 → 问卷 → 公告
二、系统模块全景图
┌───────────────────────────────────────────────────────────────────────────────────────┐
│ HC小区管理系统 │
│ MicroCommunity v1.0 │
├───────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │
│ │ 前端应用层 │ │ 网关接入层 │ │
│ │ ┌──────────┐ ┌──────────┐ │ │ ┌───────────────────────────┐ │ │
│ │ │ PC管理后台│ │ 业主手机端│ │ │ │ service-api (网关) │ │ │
│ │ │ Vue/React│ │ 微信小程序│ │ │ │ • 统一入口 • 认证鉴权 │ │ │
│ │ └──────────┘ └──────────┘ │ │ │ • 路由分发 • API文档 │ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │ │ • WebSocket • 文件上传 │ │ │
│ │ │ 物业手机端│ │ 第三方对接│ │ │ └───────────────────────────┘ │ │
│ │ │ App │ │ API/Web │ │ │ │ │
│ │ └──────────┘ └──────────┘ │ │ 服务注册: service-eureka │ │
│ └─────────────────────────────────┘ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ 核心业务服务层 (12个微服务) │ │
│ ├─────────────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ service-user │ │service- │ │ service-fee │ │service-order │ │ │
│ │ │ 用户服务 │ │community │ │ 费用服务 │ │ 订单服务 │ │ │
│ │ │ │ │ 社区服务 │ │ │ │ │ │ │
│ │ │ • 登录认证 │ │ • 小区管理 │ │ • 费用配置 │ │ • 订单受理 │ │ │
│ │ │ • 业主管理 │ │ • 楼栋/单元 │ │ • 收费管理 │ │ • 事务协调 │ │ │
│ │ │ • 组织架构 │ │ • 房间管理 │ │ • 抄表管理 │ │ • 数据总线 │ │ │
│ │ │ • 权限角色 │ │ • 停车位 │ │ • 收据管理 │ │ • 异步处理 │ │ │
│ │ │ • 菜单管理 │ │ • 访客管理 │ │ • 月租车 │ │ • 事件监听 │ │ │
│ │ │ • 员工管理 │ │ • 巡检管理 │ │ • 退费管理 │ │ │ │ │
│ │ │ • 车辆管理 │ │ • 报修管理 │ │ • 临时停车费 │ │ 所有写操作 │ │ │
│ │ │ │ │ • 活动管理 │ │ │ │ 的事务协调 │ │ │
│ │ │ 26个命令模块 │ │ 10+功能模块 │ │ 23个命令模块 │ │ │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ service-acct │ │ service-store │ │service-common │ │ service-oa │ │ │
│ │ │ 账户服务 │ │ 商户服务 │ │ 通用服务 │ │ OA服务 │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ • 账户管理 │ │ • 店铺管理 │ │ • 广告管理 │ │ • 工作池管理 │ │ │
│ │ │ • 支付处理 │ │ • 资源库存 │ │ • 门禁密钥 │ │ • 任务分配 │ │ │
│ │ │ • 积分系统 │ │ • 采购管理 │ │ • 充电设备 │ │ • 工作类型 │ │ │
│ │ │ • 优惠券 │ │ • 排班管理 │ │ • 工作流引擎 │ │ • 周期任务 │ │ │
│ │ │ • 发票管理 │ │ • 预约管理 │ │ • 文件管理 │ │ • 事件处理 │ │ │
│ │ │ • 在线支付 │ │ • 投诉处理 │ │ • 消息推送 │ │ │ │ │
│ │ │ │ │ • 合同管理 │ │ • 打印机管理 │ │ │ │ │
│ │ │ 20个命令模块 │ │ 29个业务领域 │ │ 35个命令接口 │ │ │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │service-report │ │ service-job │ │ service-dev │ │ service-scm │ │ │
│ │ │ 报表服务 │ │ 任务服务 │ │ 开发服务 │ │ 供应链服务 │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ • 费用统计 │ │ • 数据导出 │ │ • 缓存管理 │ │ • 供应商管理 │ │ │
│ │ │ • 欠费统计 │ │ • 物联网设备 │ │ • 系统监控 │ │ • 采购订单 │ │ │
│ │ │ • 自定义报表 │ │ • 商城服务 │ │ • 代码生成 │ │ • 库存管理 │ │ │
│ │ │ • 费用月度统计 │ │ • 打印服务 │ │ │ │ │ │ │
│ │ │ • 社区数据统计 │ │ • 任务调度 │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ 86个命令接口 │ │ 34个命令接口 │ │ │ │ │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ 基础框架层 (5个核心模块) │ │
│ ├─────────────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ java110-core │ │ java110-bean │ │ java110- │ │ │
│ │ │ 核心框架模块 │ │ 数据实体模块 │ │ interface │ │ │
│ │ │ │ │ │ │ Feign接口模块 │ │ │
│ │ │ • @Java110Cmd │ │ • DTO (数据传输) │ │ │ │
│ │ │ • @Java110Trans │ │ • PO (持久化) │ │ • 584个Feign │ │ │
│ │ │ actional │ │ • VO (视图) │ │ 客户端接口 │ │ │
│ │ │ • AOP切面 │ │ • ResultVo统一 │ │ • 服务间RPC调用 │ │ │
│ │ │ • Redis缓存 │ │ 响应封装 │ │ • Feign配置 │ │ │
│ │ │ • 事件机制 │ │ │ │ • 错误解码器 │ │ │
│ │ │ • 代理工厂 │ │ 100+ DTO子包 │ │ │ │ │
│ │ │ • 链路追踪 │ │ 86+ PO子包 │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ java110-db │ │ java110-utils │ │ │
│ │ │ 数据库模块 │ │ 工具类库 │ │ │
│ │ │ │ │ │ │ │
│ │ │ • MyBatis映射 │ │ • 通用工具函数 │ │ │
│ │ │ • 数据源配置 │ │ • 日期/字符串处理 │ │ │
│ │ │ │ │ • 加密/解密 │ │ │
│ │ └─────────────────┘ └─────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ java110-doc │ │ │
│ │ │ API文档模块 │ │ │
│ │ │ │ │ │
│ │ │ • 11个自定义注解 │ │ │
│ │ │ • 文档自动生成 │ │ │
│ │ │ • 可视化UI界面 │ │ │
│ │ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ 基础设施层 │ │
│ ├─────────────────────────────────────────────────────────────────────────────────┤ │
│ │ MySQL 8.0 │ Redis 缓存 │ FTP/OSS文件存储 │ Eureka注册 │ Quartz调度 │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────┘
三、核心业务流程设计
3.1 用户请求处理流程
客户端 (PC/手机/第三方)
│
│ POST /app/{serviceCode}
│ Header: JWT Token
│ Body: {reqData: {...}}
│
▼
┌──────────────────────┐
│ service-api 网关 │
│ AppController │──── JwtFilter: Token校验（白名单免检）
│ 解析 serviceCode │──── 白名单: 登录、注册、支付回调、文件下载、微信接口
│ 提取 reqData │
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ 权限验证 │
│ IPrivilegeSMO │──── 校验用户是否有该 serviceCode 的调用权限
└──────┬───────────────┘
│ 通过
▼
┌──────────────────────┐
│ 服务路由 │
│ IApiSMO │──── serviceCode 格式: "模块.操作"
│ 解析 serviceCode │ 例: "fee.payFee" → service-fee
│ Feign 远程调用 │ "user.saveUser" → service-user
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ 命令匹配与执行 │
│ @Java110Cmd 注解 │
│ serviceCode 映射 │──── PayFeeCmd.validate() → 参数校验
│ 到具体命令类 │──── PayFeeCmd.doCmd() → 执行业务逻辑
│ │ @Java110Transactional → 事务控制
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ 统一响应返回 │
│ ResultVo │──── {code: 0, msg: "成功", data: {...}}
│ JSON格式 │
└──────────────────────┘
3.2 费用收缴流程
┌─────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 管理员/系统│────►│ 创建费用项 │────►│ 生成费用账单 │────►│ 推送缴费通知 │
│ │ │ feeConfig │ │ fee.saveRoom │ │ 短信/微信推送 │
│ │ │ 设置收费标准 │ │ CreateFee │ │ │
└─────────┘ └──────────────┘ └──────────────┘ └──────┬───────┘
│
▼
┌─────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 完成缴费 │◄────│ 记录缴费记录 │◄────│ 支付平台回调 │◄────│ 业主选择支付 │
│ 更新账单 │ │ payFeeDetail │ │ 微信/支付宝 │ │ • 微信支付 │
│ 状态 │ │ │ │ 支付成功通知 │ │ • 预存账户 │
└─────────┘ └──────────────┘ └──────────────┘ │ • 优惠券 │
└──────────────┘
3.3 报修处理流程
业主提交报修 物业派单 维修处理 业主评价
│ │ │ │
▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ 填写报修│────►│ 审核派单│────►│ 上门维修│────►│ 评价反馈│
│ 拍照上传│ │ 指派员工│ │ 更新进度│ │ 星级评分│
│ saveRepair│ │ 工单流转│ │ 维修完成│ │ replyApp│
│ │ │ │ │ │ │ raise │
└────────┘ └────────┘ └────────┘ └────────┘
四、数据库设计概要
┌────────────────┐
│ community (小区) │
│ 小区基本信息 │
└───────┬────────┘
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ floor (楼栋) │ │parking_area │ │ activities │
│ │ │ (停车场区域) │ │ (社区活动) │
└──────┬───────┘ └──────┬────────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ unit (单元) │ │parking_space │
│ │ │ (停车位) │
└──────┬───────┘ └──────┬────────┘
│ │
▼ │
┌──────────────┐ │
│ room (房屋) │ │
└──────┬───────┘ │
│ │
▼ ▼
┌──────────────────────────────────────────┐
│ owner (业主) - 关联房屋或车位 │
│ 业主信息、车辆信息、家庭成员 │
└──────────────┬───────────────────────────┘
│
┌────────────┼────────────┬─────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
│fee (费用)│ │repair │ │complaint│ │car (车辆) │
│ 费用记录 │ │ (报修) │ │ (投诉) │ │ 车辆信息 │
└─────────┘ └─────────┘ └─────────┘ └──────────┘
用户体系:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ user (用户) │────►│ role (角色) │────►│privilege │
│ 员工/管理员 │ │ 角色-权限关联│ │ (权限) │
└──────┬──────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐ ┌─────────────┐
│ org (组织) │ │ store (店铺)│
│ 组织架构 │ │ 物业公司 │
└─────────────┘ └─────────────┘
五、命令驱动架构设计
5.1 设计理念
传统MVC架构: 命令驱动架构:
┌──────────┐ ┌──────────────────────────────┐
│Controller│ │ 统一入口: POST /app/{serviceCode}
│ ↓ │ │ {reqData: ...} │
│ Service │ ← 业务膨胀 │ ↓ │
│ ↓ │ │ @Java110Cmd 命令自动发现 │
│ DAO │ │ ↓ │
└──────────┘ │ serviceCode → 命令类映射 │
│ ↓ │
核心优势: │ validate() → 参数校验 │
✓ 统一入口 (一个API处理所有请求) │ doCmd() → 业务处理 │
✓ 自动发现 (注解扫描命令类) │ @Java110Transactional │
✓ 高内聚 (每个命令类单一职责) │ ↓ │
✓ 易扩展 (新增业务只需加命令类) │ ResultVo 统一返回 │
└──────────────────────────────┘
5.2 服务编码规范
serviceCode 格式: {模块名}.{操作名}
示例:
user.saveUser → 用户模块.保存用户
fee.payFee → 费用模块.缴费
community.saveCommunity → 社区模块.创建小区
payment.unifiedPayment → 支付模块.统一支付
visit.saveVisit → 访客模块.创建访客
repair.listRepairEvent → 报修模块.查询报修事件
所有 serviceCode 通过 @Java110Cmd(serviceCode = "xxx") 注解声明
5.3 命令类标准结构
@Java110Cmd(serviceCode = "fee.payFee") // 服务编码注解
public class PayFeeCmd extends Cmd { // 继承命令基类
@Override
public void validate(CmdEvent event, // 参数校验
ICmdDataFlowContext ctx,
JSONObject reqJson) {
// 校验必填字段、参数格式
Assert.hasKey(reqJson, "feeId", "费用ID不能为空");
Assert.hasKey(reqJson, "communityId", "小区ID不能为空");
}
@Override
@Java110Transactional // 事务管理
public void doCmd(CmdEvent event, // 业务处理
ICmdDataFlowContext ctx,
JSONObject reqJson) {
// 执行业务逻辑
// 1. 查询费用信息
// 2. 创建支付订单
// 3. 调用支付接口
// 4. 更新费用状态
}
}
六、外部集成设计
┌───────────────────────────────────────────────────────────┐
│ HC小区管理系统 │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │微信支付 │ │支付宝 │ │银联支付 │ │短信服务 │ │
│ │支付/小程序│ │支付 │ │支付 │ │通知/营销 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴────────────┴────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ 支付适配器工厂 │ │
│ │ PaymentFactory │ │
│ │ • 微信支付适配器 │ │
│ │ • 支付宝适配器 │ │
│ │ • 银联支付适配器 │ │
│ └─────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 物联网设备集成 (IoT) │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │
│ │ │门禁设备│ │道闸设备│ │充电桩 │ │计量表 │ │ │
│ │ │(海康/大华│ │(车牌识别│ │(充电管理│ │(水/电/气│ │ │
│ │ │ 等) │ │ 等) │ │ 等) │ │ 等) │ │ │
│ │ └────────┘ └────────┘ └────────┘ └────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 文件存储服务 │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ FTP服务器 │ │ 阿里云OSS │ │ │
│ │ │ 本地存储 │ │ 云端存储 │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────┘
七、部署架构设计
┌───────────────────────────────────────────────────────────────────┐
│ 生产环境部署 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Nginx 反向代理 │ │
│ │ (SSL终端 / 负载均衡 / 静态资源) │ │
│ └────────────┬────────────────────────────────┬───────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────┐ ┌────────────────────────┐ │
│ │ service-api (网关) │ │ service-api (网关) │ │
│ │ Port: 8008 │ │ Port: 8009 │ │
│ └───────────┬────────────┘ └───────────┬────────────┘ │
│ │ │ │
│ └─────────────┬───────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ service-eureka (服务注册中心) │ │
│ │ 支持集群部署 / 心跳检测 / 服务列表 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │service- │ │service- │ │service- │ │
│ │user:xxxx │ │fee:xxxx │ │community:xxxx │ │
│ │ (集群2节点)│ │ (集群2节点)│ │ (集群2节点) │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ MySQL │ │ Redis │ │ FTP/OSS │ │
│ │ (主从) │ │ (集群) │ │ 文件存储 │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└───────────────────────────────────────────────────────────────────┘
八、系统设计原则与亮点
| 设计原则 | 实现方式 |
|---|---|
| 统一入口 | service-api 网关作为所有请求的唯一入口 |
| 命令驱动 | @Java110Cmd 注解实现 serviceCode → 命令类的自动映射 |
| 高内聚低耦合 | 每个命令类负责单一业务，模块间通过 Feign 接口通信 |
| 事务一致性 | @Java110Transactional 注解支持分布式事务管理 |
| 数据安全 | DTO/PO/VO 三层对象分离，VO过滤敏感字段（如密码），防止数据泄露 |
| 双模式部署 | 支持 Spring Boot 单体（开发/小型）和 Spring Cloud 微服务（生产/大型） |
| 接口文档自动化 | 11个自定义注解自动生成 API 文档，可视化界面可在线测试 |
| 支付可扩展 | 支付适配器工厂模式，新增支付渠道只需加适配器，无需修改业务代码 |
| 物联网集成 | 统一IoT设备协议，支持门禁、道闸、充电桩、计量表等多种设备 |
| 灵活配置 | 支持多环境配置 (dev/test/prod)，通过 profile 切换 |
文档版本: v1.0
生成日期: 2026年
项目地址: https://gitee.com/wuxw7/MicroCommunity