# Ether 物业信息化平台 - 实现方案文档

> 本文档基于需求规格说明书、技术规范说明书和领域模型详细设计整理而成
> 创建日期: 2026-02-05
> 版本: v1.0

---

## 📋 系统概述

Ether 物业信息化平台是一个 **B端（管理端）+ G端（政府端）+ C端（客户端）** 的三端一体化物业管理系统，核心目标是实现"数据一网统管，业务一键闭环"。

### 建设范围
- **本期重点**: 全面覆盖B端内部管理流程，包括空间基础数据、综合工单体系、设施设备全生命周期管理、财务计费与收缴中心
- **协同范围**: 对接外部停车系统、支付网关及政府监管接口

---

## 🏗️ 一、系统架构设计

### 1.1 整体架构（微服务 + DDD）

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              前端层 (Presentation)                           │
├─────────────────┬─────────────────┬─────────────────┬───────────────────────┤
│   B端PC管理后台  │  B端PDA移动作业  │   C端小程序      │    G端政府监管        │
│  Vue3 + AntdVue │ Uni-app + Antd  │   微信小程序     │    Web门户            │
│                 │    Mobile       │                 │                       │
└─────────────────┴─────────────────┴─────────────────┴───────────────────────┘
                                       │
┌─────────────────────────────────────────────────────────────────────────────┐
│                           API网关层 (Gateway)                                │
│              Spring Cloud Gateway + JWT认证 + 限流 + 签名验证                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
┌─────────────────────────────────────────────────────────────────────────────┐
│                          核心业务服务层 (Core Services)                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │  空间主数据  │ │  运营调度    │ │  设施设备    │ │  财务计费    │           │
│  │   Domain    │ │   Domain    │ │   Domain    │ │   Domain    │           │
│  │   (4.1)     │ │   (4.2)     │ │   (4.3)     │ │   (4.4)     │           │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                           │
│  │  权限与账户  │ │  审批流程    │ │  集成中心    │                           │
│  │   Domain    │ │   Domain    │ │   Domain    │                           │
│  │   (4.5)     │ │   (4.7)     │ │   (4.6)     │                           │
│  └─────────────┘ └─────────────┘ └─────────────┘                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
┌─────────────────────────────────────────────────────────────────────────────┐
│                          基础设施层 (Infrastructure)                         │
│  PostgreSQL 15+  │  Redis  │  RabbitMQ  │  MinIO  │  Elasticsearch         │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 1.2 领域驱动设计（DDD）六大领域

| 领域 | 职责 | 核心聚合根 |
|------|------|-----------|
| **空间与主数据领域** (4.1) | 物理数字孪生底座 | SpaceNode, PropertyBinding |
| **运营调度领域** (4.2) | 工单、巡检、排班、访客 | WorkOrder, InspectionTask |
| **设施设备领域** (4.3) | 资产台账、维保计划 | Equipment, MaintenancePlan |
| **财务计费领域** (4.4) | 账单、支付、退款 | FinancialBill, RefundOrder |
| **权限与账户领域** (4.5) | RBAC、访客凭证、项目隔离 | Account, VisitorCredential |
| **集成中心领域** (4.6) | 外部系统适配、IoT网关 | IntegrationLog, ProtocolAdapter |

---

## 💻 二、技术栈与开发语言

### 2.1 后端技术栈（Java）

| 技术/框架 | 版本 | 用途 |
|-----------|------|------|
| **Java** | 17+ (LTS) | 开发语言 |
| **Spring Boot** | 3.2.x | 基础框架 |
| **Spring Cloud Alibaba** | 2023.x | 微服务治理（Nacos, Sentinel, Seata） |
| **Spring Data JPA** | 3.2.x | ORM框架 |
| **QueryDSL** | 5.x | 类型安全查询 |
| **PostgreSQL Driver** | 42.7.x | 数据库驱动 |
| **PostGIS** | 3.4+ | 空间数据库扩展 |
| **Redis** | 7.x | 缓存 + 分布式锁 |
| **Redisson** | 3.25+ | Redis客户端 |
| **RabbitMQ** | 3.12+ | 消息队列 |
| **MinIO** | 2024.x | 对象存储 |
| **JWT (jjwt)** | 0.12.x | 身份认证 |
| **MapStruct** | 1.5.x | DTO映射 |
| **Lombok** | 1.18.x | 代码简化 |
| **Hibernate Validator** | 8.x | 参数校验 |
| **Swagger/OpenAPI** | 2.3.x | API文档 |

### 2.2 前端技术栈

#### B端PC管理后台
| 技术/框架 | 版本 | 用途 |
|-----------|------|------|
| **Vue** | 3.4.x | 框架 |
| **TypeScript** | 5.3+ | 开发语言 |
| **Vite** | 5.x | 构建工具 |
| **Ant Design Vue** | 4.x | UI组件库 |
| **Vue Router** | 4.x | 路由 |
| **Pinia** | 2.x | 状态管理 |
| **Axios** | 1.6.x | HTTP客户端 |
| **ECharts** | 5.x | 数据可视化 |
| **LogicFlow** | 1.2.x | 流程设计器 |

#### B端PDA移动作业端 / C端小程序
| 技术/框架 | 版本 | 用途 |
|-----------|------|------|
| **Uni-app** | 3.x | 跨端框架 |
| **Vue** | 3.x | 框架 |
| **Ant Design Mobile** | 5.x | 移动端UI |
| **uView UI** | 2.x | Uni-app组件库 |

### 2.3 数据库与中间件

| 组件 | 版本 | 用途 |
|------|------|------|
| **PostgreSQL** | 15+ | 主数据库 |
| **PostGIS** | 3.4+ | 空间数据扩展 |
| **pg_trgm** | - | 模糊搜索 |
| **ltree** | - | 树形结构 |
| **Redis** | 7.x | 缓存/会话/锁 |
| **RabbitMQ** | 3.12+ | 消息队列 |
| **MinIO** | 2024.x | 对象存储 |
| **Elasticsearch** | 8.x | 搜索引擎（可选） |

---

## 📦 三、外部资源与第三方服务

### 3.1 支付与财务

| 服务 | 类型 | 用途 |
|------|------|------|
| **微信支付** | 官方SDK | C端在线缴费 |
| **支付宝** | 官方SDK | C端在线缴费 |
| **税控接口** | 第三方 | 电子发票开具 |
| **集团财务ERP** | 内部对接 | 凭证同步 |

### 3.2 政府监管接口

| 服务 | 类型 | 用途 |
|------|------|------|
| **962121热线平台** | 政府API | 投诉工单同步 |
| **房管局监管系统** | 政府API | 异常处置、信息上报 |
| **市物业中心** | 数据共享协议 | 数据同步 |

### 3.3 IoT与硬件集成

| 服务/设备 | 类型 | 用途 |
|-----------|------|------|
| **停车系统** | 厂商API | 车牌识别、车位管理 |
| **门禁系统** | 硬件SDK | 访客通行、员工打卡 |
| **电梯监控系统** | MQTT/HTTP | 故障报警 |
| **消防IoT传感器** | MQTT | 实时监控 |
| **PDA设备** | Android SDK | 扫码、NFC、红外 |
| **NFC磁卡** | ISO 14443-A | 巡更打卡 |

### 3.4 地图与位置服务

| 服务 | 类型 | 用途 |
|------|------|------|
| **腾讯地图SDK** | 第三方 | 小程序地图展示 |
| **高德地图API** | 第三方 | Web端地图、地理编码 |
| **GPS定位服务** | 系统原生 | 打卡定位校验 |

### 3.5 消息推送与通讯

| 服务 | 类型 | 用途 |
|------|------|------|
| **企业微信API** | 第三方 | 内部通知、审批提醒 |
| **飞书API** | 第三方 | 内部通知（备选） |
| **微信订阅消息** | 官方 | C端消息推送 |
| **短信服务** | 第三方 | 验证码、告警通知 |

### 3.6 文件存储与处理

| 服务 | 类型 | 用途 |
|------|------|------|
| **MinIO** | 自建 | 文件对象存储 |
| **阿里云OSS** | 云厂商 | 备份/CDN（可选） |
| **FFmpeg** | 开源 | 视频压缩处理 |
| **ImageMagick** | 开源 | 图片压缩/水印 |

---

## 🔧 四、核心Maven依赖清单

### 4.1 父POM核心依赖

```xml
<!-- Spring Boot -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
</parent>

<!-- Spring Cloud Alibaba -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2023.0.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 4.2 各模块核心依赖

```xml
<!-- === Web & Security === -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<!-- === Database === -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.3</version>
</dependency>
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-spatial</artifactId>
</dependency>

<!-- === QueryDSL === -->
<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-jpa</artifactId>
    <version>5.1.0</version>
</dependency>
<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-apt</artifactId>
    <version>5.1.0</version>
</dependency>

<!-- === Cache & MQ === -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<dependency>
    <groupId>org.redisson</groupId>
    <artifactId>redisson-spring-boot-starter</artifactId>
    <version>3.27.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-amqp</artifactId>
</dependency>

<!-- === JWT === -->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.12.5</version>
</dependency>

<!-- === MinIO === -->
<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.9</version>
</dependency>

<!-- === Tools === -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.32</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.47</version>
</dependency>

<!-- === Testing === -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>
```

---

## 📱 五、前端NPM依赖清单

### 5.1 B端PC (Vue3)

```json
{
  "dependencies": {
    "vue": "^3.4.21",
    "vue-router": "^4.3.0",
    "pinia": "^2.1.7",
    "ant-design-vue": "^4.2.0",
    "@ant-design/icons-vue": "^7.0.1",
    "axios": "^1.6.8",
    "echarts": "^5.5.0",
    "vue-echarts": "^6.6.9",
    "@logicflow/core": "^1.2.18",
    "@logicflow/extension": "^1.2.19",
    "dayjs": "^1.11.10",
    "lodash-es": "^4.17.21"
  },
  "devDependencies": {
    "typescript": "^5.4.5",
    "vite": "^5.2.8",
    "vue-tsc": "^2.0.11",
    "eslint": "^8.57.0",
    "prettier": "^3.2.5"
  }
}
```

### 5.2 移动端 (Uni-app)

```json
{
  "dependencies": {
    "vue": "^3.4.21",
    "@dcloudio/uni-app": "3.0.0-alpha-4010520240409001",
    "ant-design-mobile": "^5.35.0",
    "uview-plus": "^3.2.24"
  }
}
```

---

## 🗄️ 六、数据库设计要点

### 6.1 PostgreSQL扩展

```sql
-- 空间数据处理
CREATE EXTENSION IF NOT EXISTS "postgis";
-- 树形结构
CREATE EXTENSION IF NOT EXISTS "ltree";
-- 模糊搜索
CREATE EXTENSION IF NOT EXISTS "pg_trgm";
-- UUID生成
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
```

### 6.2 核心表结构

| 表名 | 领域 | 说明 |
|------|------|------|
| `base_space_node` | 空间主数据 | 空间节点（Ltree路径） |
| `base_room_detail` | 空间主数据 | 房产明细 |
| `base_ownership` | 空间主数据 | 权属关联 |
| `op_work_order` | 运营调度 | 综合工单 |
| `op_inspection_task` | 运营调度 | 巡检任务 |
| `op_shift_plan` | 运营调度 | 排班计划 |
| `op_attendance` | 运营调度 | 考勤记录 |
| `op_visitor_invite` | 运营调度 | 访客预约 |
| `ast_equipment` | 设施设备 | 设备台账 |
| `ast_maintenance_plan` | 设施设备 | 维保计划 |
| `fin_billing_account` | 财务计费 | 财务账户 |
| `fin_bill` | 财务计费 | 账单 |
| `fin_refund_order` | 财务计费 | 退款单 |
| `iam_account` | 权限账户 | 账户体系 |
| `hub_integration_log` | 集成中心 | 集成日志 |

---

## 🚀 七、部署架构

### 7.1 容器化部署

| 组件 | 镜像 | 说明 |
|------|------|------|
| **应用服务** | `ether-core-service:latest` | Spring Boot应用 |
| **集成中心** | `ether-hub-service:latest` | 外部对接服务 |
| **PostgreSQL** | `postgis/postgis:15-3.4` | 主数据库 |
| **Redis** | `redis:7-alpine` | 缓存 |
| **RabbitMQ** | `rabbitmq:3.12-management` | 消息队列 |
| **MinIO** | `minio/minio:latest` | 对象存储 |
| **Nginx** | `nginx:alpine` | 反向代理 |

### 7.2 Docker Compose 示例

```yaml
version: '3.8'
services:
  ether-postgres:
    image: postgis/postgis:15-3.4
    environment:
      POSTGRES_DB: ether_platform
      POSTGRES_USER: ether_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
      
  ether-redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    ports:
      - "6379:6379"
    
  ether-rabbitmq:
    image: rabbitmq:3.12-management
    environment:
      RABBITMQ_DEFAULT_USER: ether
      RABBITMQ_DEFAULT_PASS: ${MQ_PASSWORD}
    ports:
      - "5672:5672"
      - "15672:15672"
      
  ether-minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: etheradmin
      MINIO_ROOT_PASSWORD: ${MINIO_PASSWORD}
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data

volumes:
  postgres_data:
  minio_data:
```

---

## 📚 八、GitHub 参考资源

### 8.1 开源项目参考

| 项目 | 地址 | 参考价值 |
|------|------|----------|
| **pig** | https://github.com/pig-mesh/pig | Spring Cloud微服务脚手架 |
| **ruoyi-vue-pro** | https://github.com/YunaiV/ruoyi-vue-pro | 权限管理、工作流 |
| **jeecg-boot** | https://github.com/jeecgboot/jeecg-boot | 低代码平台、代码生成 |
| **eladmin** | https://github.com/elunez/eladmin | 后台管理系统 |
| **Ant Design Pro Vue** | https://github.com/vueComponent/ant-design-vue-pro | 前端模板 |

### 8.2 技术组件参考

| 组件 | 地址 |
|------|------|
| **Spring Boot** | https://github.com/spring-projects/spring-boot |
| **Spring Cloud Alibaba** | https://github.com/alibaba/spring-cloud-alibaba |
| **MapStruct** | https://github.com/mapstruct/mapstruct |
| **QueryDSL** | https://github.com/querydsl/querydsl |
| **Redisson** | https://github.com/redisson/redisson |
| **MinIO Java SDK** | https://github.com/minio/minio-java |

---

## ✅ 九、开发规范与约束

### 9.1 代码规范
- **JDK版本**: Java 17+
- **编码规范**: Alibaba Java Coding Guidelines
- **单元测试**: JUnit 5 + Mockito，覆盖率要求 > 80%
- **API文档**: OpenAPI 3.0 + Swagger UI

### 9.2 数据库规范
- **主键**: UUID v7 (使用 `gen_random_uuid()`)
- **金额字段**: `numeric(15,4)` 内部计算，`numeric(12,2)` 展示
- **JSON字段**: 使用 PostgreSQL `jsonb` 类型
- **空间字段**: 使用 `geometry(Point, 4326)`

### 9.3 安全规范
- **认证**: JWT Token，有效期2小时
- **鉴权**: RBAC模型，按钮级权限控制
- **签名**: HmacSHA256 接口签名
- **敏感数据**: 加密存储，禁止明文传输

### 9.4 项目上下文约束
- 所有API请求必须携带 `X-Project-ID` Header
- 后端必须执行 `(UserID + X-Project-ID + PermissionID)` 三位一体校验
- 禁止从用户全局Session中直接获取权限列表

---

## 📊 十、项目模块划分

```
Ether/
├── ether-common/                    # 公共模块
│   ├── ether-common-core/           # 核心工具类
│   ├── ether-common-security/       # 安全组件
│   └── ether-common-mybatis/        # 数据访问
├── ether-gateway/                   # 网关服务
├── ether-auth/                      # 认证中心
├── ether-system/                    # 系统管理
├── ether-mdm/                       # 主数据服务 (4.1)
├── ether-ops/                       # 运营调度服务 (4.2)
├── ether-asset/                     # 设施设备服务 (4.3)
├── ether-finance/                   # 财务计费服务 (4.4)
├── ether-iam/                       # 权限账户服务 (4.5)
├── ether-bpm/                       # 审批流程服务 (4.7)
├── ether-hub/                       # 集成中心服务 (4.6)
└── ether-ui/                        # 前端项目
    ├── ether-ui-admin/              # B端PC
    ├── ether-ui-mobile/             # PDA App
    └── ether-ui-mp/                 # C端小程序
```

---

## 📋 十一、核心业务闭环流程

### 11.1 工单闭环 (WorkOrderLoop)
1. 多渠道汇聚 (C端报修/IoT报警/现场发现)
2. 智能调度派单
3. 现场扫码签到
4. 处理过程上报
5. 验收评价
6. 绩效计算

### 11.2 设备故障自愈闭环 (IoT-Ops-AssetLoop)
1. IoT传感器感知异常
2. 设备状态变更为FAULT
3. 自动创建维修工单
4. 工单完成后恢复设备状态
5. 更新资产健康档案

### 11.3 访客通行闭环 (VisitorAccessLoop)
1. 业主发起预约
2. 生成动态二维码凭证
3. 下发至门禁硬件
4. 访客扫码通行
5. 实时提醒业主

### 11.4 财务调账闭环 (BPM-FinanceAdjustmentLoop)
1. 发起调账申请
2. 账单锁定
3. BPM审批流
4. 审批通过后生成审计流水
5. 财务平账

---

## 📝 十二、关键配置项

### 12.1 应用配置 (application.yml)

```yaml
spring:
  application:
    name: ether-platform
  datasource:
    url: jdbc:postgresql://localhost:5432/ether_platform
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  redis:
    host: localhost
    port: 6379
    password: ${REDIS_PASSWORD}
  rabbitmq:
    host: localhost
    port: 5672
    username: ${MQ_USERNAME}
    password: ${MQ_PASSWORD}

ether:
  security:
    jwt:
      secret: ${JWT_SECRET}
      expiration: 7200000  # 2小时
    sign:
      app-key: ${APP_KEY}
      app-secret: ${APP_SECRET}
  storage:
    minio:
      endpoint: http://localhost:9000
      access-key: ${MINIO_ACCESS_KEY}
      secret-key: ${MINIO_SECRET_KEY}
      bucket-name: ether-files
  lbs:
    valid-radius: 50  # 打卡有效半径(米)
```

---

## 🔄 文档更新记录

| 版本 | 日期 | 更新内容 | 作者 |
|------|------|----------|------|
| v1.0 | 2026-02-05 | 初始版本 | - |

---

> **注意**: 本文档基于需求规格说明书、技术规范说明书和领域模型详细设计整理，开发过程中如有需求变更，请及时更新本文档。