# 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 命令类标准结构 ```java @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