9750b443
 王彪总
fix(config): 更新配置...
|
1
|
# HC项目管理系统 - 总体设计图
|
|
88e030b7
王彪总
init project
|
2
3
4
|
## 一、系统概览
|
|
9750b443
王彪总
fix(config): 更新配置...
|
5
|
HC项目管理系统（MicroCommunity）是一套面向物业企业的SaaS平台，覆盖物业管理全场景：
|
|
88e030b7
王彪总
init project
|
6
7
8
9
10
11
12
13
|
**房产 → 业主 → 缴费 → 报修 → 巡检 → 停车 → 门禁 → 道闸 → 监控 → 工作流 → 问卷 → 公告**
---
## 二、系统模块全景图
```
┌───────────────────────────────────────────────────────────────────────────────────────┐
|
|
9750b443
王彪总
fix(config): 更新配置...
|
14
|
│ HC项目管理系统 │
|
|
88e030b7
王彪总
init project
|
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
|
│ MicroCommunity v1.0 │
├───────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │
│ │ 前端应用层 │ │ 网关接入层 │ │
│ │ ┌──────────┐ ┌──────────┐ │ │ ┌───────────────────────────┐ │ │
│ │ │ PC管理后台│ │ 业主手机端│ │ │ │ service-api (网关) │ │ │
│ │ │ Vue/React│ │ 微信小程序│ │ │ │ • 统一入口 • 认证鉴权 │ │ │
│ │ └──────────┘ └──────────┘ │ │ │ • 路由分发 • API文档 │ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │ │ • WebSocket • 文件上传 │ │ │
│ │ │ 物业手机端│ │ 第三方对接│ │ │ └───────────────────────────┘ │ │
│ │ │ App │ │ API/Web │ │ │ │ │
│ │ └──────────┘ └──────────┘ │ │ 服务注册: service-eureka │ │
│ └─────────────────────────────────┘ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ 核心业务服务层 (12个微服务) │ │
│ ├─────────────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ service-user │ │service- │ │ service-fee │ │service-order │ │ │
│ │ │ 用户服务 │ │community │ │ 费用服务 │ │ 订单服务 │ │ │
│ │ │ │ │ 社区服务 │ │ │ │ │ │ │
|
|
9750b443
王彪总
fix(config): 更新配置...
|
38
|
│ │ │ • 登录认证 │ │ • 项目管理 │ │ • 费用配置 │ │ • 订单受理 │ │ │
|
|
88e030b7
王彪总
init project
|
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
│ │ │ • 业主管理 │ │ • 楼栋/单元 │ │ • 收费管理 │ │ • 事务协调 │ │ │
│ │ │ • 组织架构 │ │ • 房间管理 │ │ • 抄表管理 │ │ • 数据总线 │ │ │
│ │ │ • 权限角色 │ │ • 停车位 │ │ • 收据管理 │ │ • 异步处理 │ │ │
│ │ │ • 菜单管理 │ │ • 访客管理 │ │ • 月租车 │ │ • 事件监听 │ │ │
│ │ │ • 员工管理 │ │ • 巡检管理 │ │ • 退费管理 │ │ │ │ │
│ │ │ • 车辆管理 │ │ • 报修管理 │ │ • 临时停车费 │ │ 所有写操作 │ │ │
│ │ │ │ │ • 活动管理 │ │ │ │ 的事务协调 │ │ │
│ │ │ 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 │
└────────┘ └────────┘ └────────┘ └────────┘
```
---
## 四、数据库设计概要
```
┌────────────────┐
|
|
9750b443
王彪总
fix(config): 更新配置...
|
213
214
|
│ community (项目) │
│ 项目基本信息 │
|
|
88e030b7
王彪总
init project
|
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
└───────┬────────┘
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 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 → 费用模块.缴费
|
|
9750b443
王彪总
fix(config): 更新配置...
|
295
|
community.saveCommunity → 社区模块.创建项目
|
|
88e030b7
王彪总
init project
|
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
|
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不能为空");
|
|
9750b443
王彪总
fix(config): 更新配置...
|
315
|
Assert.hasKey(reqJson, "communityId", "项目ID不能为空");
|
|
88e030b7
王彪总
init project
|
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
}
@Override
@Java110Transactional // 事务管理
public void doCmd(CmdEvent event, // 业务处理
ICmdDataFlowContext ctx,
JSONObject reqJson) {
// 执行业务逻辑
// 1. 查询费用信息
// 2. 创建支付订单
// 3. 调用支付接口
// 4. 更新费用状态
}
}
```
---
## 六、外部集成设计
```
┌───────────────────────────────────────────────────────────┐
|
|
9750b443
王彪总
fix(config): 更新配置...
|
338
|
│ HC项目管理系统 │
|
|
88e030b7
王彪总
init project
|
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
|
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │微信支付 │ │支付宝 │ │银联支付 │ │短信服务 │ │
│ │支付/小程序│ │支付 │ │支付 │ │通知/营销 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴────────────┴────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ 支付适配器工厂 │ │
│ │ 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
|
