# 医院物业SaaS管理后台 — 项目技术要求

> 版本：v1.1  
> 定位：内部团队开发标准，所有开发人员必须严格按照此标准执行  
> 日期：2026-04-16

---

## 一、技术栈选型与版本要求

### 1.1 后端技术栈

| 技术 | 版本要求 | 用途 |
|------|----------|------|
| Java | 17+ | 开发语言 |
| Spring Boot | 3.x | 应用框架 |
| MariaDB | 10.6+ | 主数据库（主从复制读写分离） |
| Redis | 7.x | 缓存（权限/字典/菜单）、分布式锁 |
| MyBatis-Plus | 3.5+ | ORM框架 |
| Spring Security | 6.x | 认证与授权 |
| JWT (jjwt) | 0.12+ | Token生成与校验 |
| 腾讯云COS SDK | 最新稳定版 | 文件存储 |
| ShedLock | 5.x+ | 分布式定时任务锁 |

### 1.2 前端Web技术栈

| 技术 | 版本要求 | 用途 |
|------|----------|------|
| Vue | 3.x | 前端框架 |
| TypeScript | 5.x | 类型安全 |
| Vite | 5.x | 构建工具 |
| Pinia | 2.x | 状态管理 |
| Vue Router | 4.x | 路由管理 |
| Element Plus | 最新稳定版 | UI组件库 |
| Axios | 1.x | HTTP客户端 |
| ECharts | 5.x | 图表可视化 |

### 1.3 微信小程序技术栈

| 技术 | 版本要求 | 用途 |
|------|----------|------|
| uni-app | 3.x | 跨端框架（Vue 3模式） |
| uni-ui | 最新稳定版 | UI组件库 |
| uni-ble | 兼容最新版 | 蓝牙低功耗(BLE)插件 |

### 1.4 基础设施

| 技术 | 用途 |
|------|------|
| Docker + Docker Compose | 私有云容器化部署 |
| Nginx | 反向代理 + 静态资源 |
| Jenkins / GitLab CI | CI/CD流水线 |
| Git | 版本管理 |

---

## 二、架构设计要求

### 2.1 整体架构

```
┌─────────────────────────────────────────────────┐
│                  客户端层                          │
│    Vue3 Web管理后台    │    uni-app微信小程序       │
└───────────┬───────────┴───────────┬──────────────┘
            │        HTTPS          │
┌───────────▼───────────────────────▼──────────────┐
│                  网关层                            │
│              Nginx 反向代理                        │
└───────────┬──────────────────────────────────────┘
            │
┌───────────▼──────────────────────────────────────┐
│                  应用层                            │
│        Spring Boot 单体应用（模块化 IModulePlugin）  │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐   │
│  │报修  │ │巡检  │ │保洁  │ │考勤  │ │合同  │... │
│  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘   │
│     └────────┴────────┴────────┴────────┘        │
│              Spring Event 模块间通信               │
└───────────┬──────────────────────────────────────┘
            │
┌───────────▼──────────────────────────────────────┐
│                  数据层                            │
│  MariaDB主库 ──复制──▶ MariaDB从库（读写分离）      │
│  Redis 缓存（权限/字典/菜单）                      │
│  腾讯云COS（照片/附件/合同文件）                    │
└──────────────────────────────────────────────────┘
```

### 2.2 多租户方案

- **隔离方式**：共享数据库 + 行级隔离（`tenant_id`字段）
- **实现方式**：MyBatis-Plus `TenantLineInnerInterceptor` 自动注入 `tenant_id` 条件
- **租户识别**：从JWT Token中提取 `tenant_id`，无需前端传递
- **超管例外**：超级管理员操作不受租户隔离限制

### 2.3 模块化架构

- **核心接口**：`IModulePlugin`（详见 `05-接口规范.md`）
- **模块注册**：系统启动时自动扫描并注册所有 `IModulePlugin` 实现类
- **模块通信**：Spring `ApplicationEvent` + `ApplicationEventPublisher`
- **模块隔离**：各模块独立目录结构，禁止跨模块直接调用Service，必须通过Event解耦
- **租户级控制**：支持按租户启用/禁用特定模块（`sys_tenant_module` 表）

### 2.4 前后端分离

- Web端与后端通过RESTful API通信
- 小程序端与后端通过同一套API通信
- 前端路由由后端权限接口动态驱动
- 统一JWT认证，Web端存localStorage，小程序端存本地Storage

### 2.5 读写分离方案

- **实现方式**：MariaDB主从复制 + MyBatis-Plus动态数据源切换
- **路由规则**：
  - 写操作（INSERT/UPDATE/DELETE）→ 主库
  - 读操作（SELECT）→ 从库
- **注解标记**：自定义 `@ReadOnly` 注解标记读操作，AOP切面切换数据源
- **容错机制**：从库不可用时自动降级到主库读取，超时阈值3秒
- **配置要求**：在 `application.yml` 中分别配置 `spring.datasource.master` 和 `spring.datasource.slave` 两套数据源连接地址

---

## 三、去中间件方案

**不引入RocketMQ/Kafka等消息中间件**，采用以下Spring Boot内置机制替代：

### 3.1 权限变更实时通知

- **替代方案**：Redis Pub/Sub + Spring Event
- **实现细节**：
  1. 权限变更时，通过 Redis Pub/Sub 发布变更消息 `PUBLISH permission:changed <version>`
  2. 各服务实例订阅 `permission:changed` 频道，收到消息后触发 Spring Event
  3. 监听器刷新本地权限缓存
- **优势**：毫秒级延迟，零数据库压力，复用已有 Redis 实例
- **降级策略**：Redis 连接断开时，权限缓存 TTL(2小时)到期后自动刷新
- **实现要点**：
  1. 权限变更时通过 `StringRedisTemplate.convertAndSend()` 发布消息到 `permission:changed` 频道
  2. 各实例 `MessageListener` 订阅该频道，收到消息后发布 Spring Event
  3. `@EventListener` 监听事件并刷新本地权限缓存

### 3.2 异步任务处理

- **替代方案**：Spring `@Async` + 自定义线程池
- **线程池配置要求**：
  - 核心线程数：CPU核心数（默认4）
  - 最大线程数：CPU核心数×2（默认8）
  - 队列容量：1000
  - 线程空闲时间：60秒
  - 拒绝策略：CallerRunsPolicy（调用者线程执行）
- **适用场景**：报表导出、消息推送、日志异步写入、图片处理
- **持久化保障**：关键任务必须先落库再异步执行，避免线程池丢失任务

### 3.3 模块间事件通信

- **替代方案**：Spring `ApplicationEvent` + `ApplicationEventPublisher`
- **进程内通信**：直接使用Spring Event，事件定义在共享API模块中
- **跨实例通信**：Redis Pub/Sub 广播事件（与权限通知同一机制）
- **预定义事件**：

  | 事件类型 | 来源模块 | 消费方 |
  |----------|----------|--------|
  | ORDER_COMPLETED | repair | evaluation(触发评价) |
  | INSPECTION_ABNORMAL | inspection | repair(生成报修) |
  | CLEANING_TIMEOUT | cleaning | notification(推送预警) |
  | BEACON_OFFLINE | device | notification(推送预警) |
  | PERMISSION_CHANGED | permission | 各模块(刷新缓存) |

### 3.4 定时任务

- **替代方案**：Spring `@Scheduled` + 数据库分布式锁
- **分布式锁实现**：ShedLock 或数据库行锁（`SELECT ... FOR UPDATE`）
- **适用场景**：巡检任务自动生成、保洁超时预警、合同到期提醒、Beacon心跳检测
- **实现要点**：定时方法加 `@Scheduled` 注解声明cron表达式，配合 `@ShedLock` 注解声明锁名称、最少/最多持有时间，确保多实例部署时同一时刻仅一个实例执行

---

## 四、安全要求

### 4.1 认证方案

| 场景 | 认证方式 | Token管理 |
|------|----------|-----------|
| Web端登录 | 用户名+密码 → JWT | localStorage存储，2小时过期 |
| 小程序登录 | 微信openid静默登录 → JWT | 本地Storage存储，2小时过期 |
| 小程序首次使用 | 微信授权openid + 手机号绑定 | 自动创建账号 |

**JWT载荷标准字段**：

| 字段 | 说明 |
|------|------|
| sub | 用户ID |
| tid | 租户ID |
| utype | 用户类型 |
| hid | 医院ID |
| pid | 物业公司ID |
| sid | 员工ID |
| iat | 签发时间 |
| exp | 过期时间 |

### 4.2 四级权限体系

权限按 **功能菜单 → 页面 → 功能点 → 动作** 四级树形结构划分：

- **7种动作类型**：查看(view)、新增(create)、编辑(update)、删除(delete)、审批(approve)、导出(export)、分配(assign)
- **权限编码规范**：`{module}:{page}:{action}`，如 `repair:list:create`
- **自动同步**：新模块通过 `IModulePlugin.getPermissionDefinitions()` 自动注册到权限配置表
- **实时生效**：权限变更后毫秒级生效（Redis Pub/Sub），无需重新登录

### 4.3 数据权限（行级隔离）

| 角色 | 数据范围 | 实现方式 |
|------|----------|----------|
| 超级管理员 | 全局所有数据 | 不注入tenant_id条件 |
| 医院账号 | 本医院+关联物业公司数据 | 注入hospital_id条件，只读 |
| 物业公司管理员 | 绑定医院数据 | 注入tenant_id + hospital_id条件 |
| 主管 | 本班组数据 | 注入team_id条件 |
| 员工 | 仅本人数据 | 注入staff_id条件 |

**实现方式**：MyBatis-Plus拦截器自动注入SQL条件，禁止手动拼接数据权限条件。

### 4.4 蓝牙策略配置

蓝牙打卡/巡检/拍照是否强制要求连接，由物业公司配置、医院账号审核：

- **配置方**：物业公司管理员
- **审核方**：医院账号
- **配置项**：各场景是否强制蓝牙连接

| 场景 | 配置项 | 强制蓝牙时的行为 | 非强制蓝牙时的行为 |
|------|--------|-----------------|-------------------|
| 巡检打卡 | `inspection_check_in` | 必须连接Beacon打卡，失败进补录 | 可手动打卡(check_type=MANUAL) |
| 巡检拍照 | `inspection_photo` | 必须在蓝牙连接下拍照 | 可自由拍照 |
| 保洁打卡 | `cleaning_check_in` | 必须连接Beacon打卡，失败进补录 | 可手动打卡(check_type=MANUAL) |
| 保洁拍照 | `cleaning_photo` | 必须在蓝牙连接下拍照 | 可自由拍照 |
| 考勤打卡 | `attendance_check` | 必须连接Beacon打卡，失败提交异常申诉 | 可手动打卡(check_type=MANUAL) |

- **数据标记**：所有打卡记录区分 `check_type`（BLUETOOTH/MANUAL），后台列表和统计报表明确显示
- **降级逻辑**：
  - 非强制蓝牙场景：蓝牙失败可直接手动打卡
  - 强制蓝牙场景：蓝牙失败进入补录模式，需主管审核
- **审核流程**：物业公司提交配置 → 医院账号审核通过后生效 → 审核拒绝则维持原配置

### 4.5 审计日志

- **记录范围**：所有写操作（CREATE/UPDATE/DELETE/APPROVE/ASSIGN/EXPORT）自动记录
- **实现方式**：AOP切面统一处理，业务代码无感知
- **记录内容**：操作人、时间、IP、模块、操作类型、变更前后数据快照
- **权限变更日志**：单独记录，展示变更前后权限对比
- **数据补录日志**：单独记录，标记补录原因和审核状态
- **日志保留**：至少保留1年，支持导出

### 4.6 通用安全要求

| 安全项 | 要求 |
|--------|------|
| SQL注入防护 | 必须使用MyBatis-Plus参数化查询，禁止拼接SQL |
| XSS防护 | 所有用户输入必须HTML转义后存储，前端渲染使用v-text而非v-html |
| 密码存储 | BCrypt加密，禁止明文存储 |
| 敏感数据 | 手机号脱敏显示（138****1234），身份证号如需存储需AES加密 |
| 接口鉴权 | 所有API必须声明权限要求（除公开接口外） |
| 跨域控制 | Nginx配置白名单域名，禁止 `Access-Control-Allow-Origin: *` |
| 请求限流 | Redis令牌桶限流，API默认100次/分钟/用户 |

---

## 五、性能要求

### 5.1 响应时间基线

| 指标 | 要求 | 测量方式 |
|------|------|----------|
| API平均响应时间 | < 300ms | 服务端P50 |
| API P99响应时间 | < 500ms | 服务端P99 |
| 列表查询（含分页） | < 500ms | 端到端 |
| 报表生成（单月数据） | < 5s | 端到端 |
| 蓝牙扫描超时 | 3秒 | 客户端 |
| 蓝牙连接建立 | < 3秒 | 客户端 |

### 5.2 并发与容量

- 单实例支持100 QPS
- 支持水平扩展（无状态设计，Session存Redis）
- 数据库连接池：HikariCP，最大连接数 = CPU核心数 * 2 + 1
- Redis连接池：Lettuce，最大连接数 = CPU核心数 * 2

### 5.3 缓存策略

| 缓存对象 | 过期策略 | 刷新机制 |
|----------|----------|----------|
| 用户权限集 | 2小时TTL | 权限变更时实时刷新（毫秒级，Redis Pub/Sub） |
| 字典数据 | 24小时TTL | 字典变更时手动/自动刷新 |
| 菜单配置 | 24小时TTL | 菜单变更时手动/自动刷新 |
| 业务数据 | 按需懒加载 | 不缓存，实时查询 |

### 5.4 蓝牙交互可靠性

| 指标 | 要求 |
|------|------|
| 连接判定 | **不判断距离，只要成功连接蓝牙设备即可打卡** |
| 信号阈值 | RSSI > -70dBm（可配置，仅用于判定是否能建立连接） |
| 扫描超时 | 3秒 |
| 重试次数 | 3次 |
| 补录降级 | 蓝牙失败后必须提供补录/手动打卡入口 |
| 心跳检测 | Beacon每5分钟上报心跳，超15分钟标记OFFLINE |

---

## 六、数据库备份与恢复

### 6.1 备份策略

| 备份类型 | 频率 | 工具 | 保留时间 |
|----------|------|------|----------|
| 全量备份 | 每日凌晨2:00 | mysqldump --single-transaction | 30天 |
| 增量备份 | 每4小时 | MariaDB binlog | 7天 |
| 异地备份 | 每日 | rsync/scp到备份服务器 | 30天 |

### 6.2 备份存储

- **主存储**：私有云本地磁盘（独立磁盘，与数据盘分离）
- **异地存储**：异地备份服务器（不同机房或不同物理机）
- **备份文件命名**：`hospital_mgmt_full_YYYYMMDD_HHmmss.sql.gz`、`hospital_mgmt_incr_YYYYMMDD_HHmmss.binlog.gz`

### 6.3 恢复方案

| 指标 | 要求 |
|------|------|
| RTO（恢复时间目标） | < 2小时 |
| RPO（恢复点目标） | < 4小时（增量备份间隔） |
| 恢复方式 | 全量恢复 + binlog重放 |
| 恢复流程 | 1. 停止应用 → 2. 恢复最近全量备份 → 3. 重放binlog到故障时间点 → 4. 验证数据完整性 → 5. 启动应用 |

### 6.4 恢复演练

- **频率**：每季度一次
- **内容**：在测试环境执行完整恢复流程，验证RTO和RPO
- **记录**：演练结果记录文档，问题纳入改进计划
- **责任人**：DBA + 运维

### 6.5 备份脚本要求

- 全量备份使用 `mysqldump --single-transaction` 导出并gzip压缩
- 备份文件命名格式：`hospital_mgmt_full_YYYYMMDD_HHmmss.sql.gz`（增量：`hospital_mgmt_incr_YYYYMMDD_HHmmss.binlog.gz`）
- 自动清理30天前的全量备份文件
- 备份完成后通过 rsync 同步到异地备份服务器

---

## 七、开发与测试规范

> 开发规范、测试规范已独立为 `04-开发与测试规范.md`，本章仅保留引用。

- **后端开发规范**（代码分层、命名、数据库、模块开发、审计日志）→ 详见 `04-开发与测试规范.md` 第一章
- **前端开发规范**（Vue3组件、TypeScript、状态管理、API调用）→ 详见 `04-开发与测试规范.md` 第二章
- **小程序开发规范**（目录、蓝牙、图片上传）→ 详见 `04-开发与测试规范.md` 第三章
- **Git分支与提交规范** → 详见 `04-开发与测试规范.md` 第四章
- **前后端协作规范** → 详见 `04-开发与测试规范.md` 第五章
- **代码审查要求** → 详见 `04-开发与测试规范.md` 第六章
- **测试规范**（单元测试、集成测试、蓝牙测试、性能测试、安全测试）→ 详见 `04-开发与测试规范.md` 第七章

---

## 八、部署与运维要求

### 8.1 部署架构（私有云）

```
┌──────────────────────────────────────────┐
│               私有云服务器                  │
│                                          │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │   Nginx     │  │  Docker Compose  │   │
│  │  反向代理    │──│  ┌────────────┐  │   │
│  │  静态资源    │  │  │ Spring Boot│  │   │
│  └─────────────┘  │  │  应用容器   │  │   │
│                   │  └────────────┘  │   │
│                   │  ┌────────────┐  │   │
│                   │  │   Redis    │  │   │
│                   │  │   缓存容器  │  │   │
│                   │  └────────────┘  │   │
│                   └─────────────────┘   │
│                                          │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │ MariaDB主库  │  │  MariaDB从库     │   │
│  │  写操作      │──│  读操作          │   │
│  └─────────────┘  └─────────────────┘   │
└──────────────────────────────────────────┘
```

### 8.2 Docker Compose部署要求

部署包含以下服务容器：

| 服务 | 镜像 | 说明 |
|------|------|------|
| app | hospital-mgmt:latest | Spring Boot应用，端口8080，依赖Redis和MariaDB主库 |
| redis | redis:7-alpine | 缓存服务，持久化存储 |
| mariadb-master | mariadb:10.6 | 主库（写），持久化存储 |
| mariadb-slave | mariadb:10.6 | 从库（读），依赖主库，持久化存储 |
| nginx | nginx:alpine | 反向代理+静态资源，端口80/443，挂载自定义nginx.conf和前端dist目录 |

- **环境变量注入**：通过 `SPRING_PROFILES_ACTIVE`、`SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_SLAVE_URL`、`SPRING_REDIS_HOST` 等环境变量配置连接信息，禁止硬编码

### 8.3 小程序版本更新策略

```
小程序启动
    │
  调用 GET /system/versions/latest 获取最新版本号
    │
  与本地版本号比较
    │
  ├── 版本一致 ──▶ 正常使用
  │
  ├── 小版本更新（兼容） ──▶ 提示"发现新版本，是否更新？"
  │
  └── 大版本更新（不兼容） ──▶ 强制更新，引导前往微信更新
```

### 8.4 缓存管理策略

| 触发方式 | 清理范围 | 说明 |
|----------|----------|------|
| 系统启动 | 全部缓存 | 启动时自动清理 |
| 权限变更 | 权限缓存 | 变更后毫秒级自动刷新（Redis Pub/Sub） |
| 手动清理 | 指定模块缓存 | 超管在"缓存管理"页面操作 |
| 系统更新 | 全部缓存 | 部署新版本后自动清理 |

### 8.5 监控与告警

| 监控项 | 告警条件 | 通知方式 |
|--------|----------|----------|
| 应用健康 | 健康检查失败 | 邮件+企业微信 |
| 数据库连接 | 连接池使用率>80% | 企业微信 |
| Redis连接 | 连接池使用率>80% | 企业微信 |
| Beacon离线 | 离线超过15分钟 | 系统内通知 |
| Beacon低电量 | 电量<20% | 系统内通知 |
| 磁盘空间 | 使用率>85% | 邮件+企业微信 |
| 备份失败 | 备份任务失败 | 邮件 |

---

## 九、接口规范

> 接口规范已独立为 `05-接口规范.md`，本章仅保留引用。

- **全局约定**（请求头、统一响应格式、错误码、查询参数）→ 详见 `05-接口规范.md` 第一章
- **认证规范**（认证方式、JWT载荷、权限编码）→ 详见 `05-接口规范.md` 第二章
- **文件上传规范** → 详见 `05-接口规范.md` 第三章
- **模块化架构规范**（IModulePlugin、模块注册、事件通信、版本升级、安全规范）→ 详见 `05-接口规范.md` 第四~八章
- **接口权限汇总** → 详见 `05-接口规范.md` 第九章

---

## 十、环境配置管理

### 10.1 环境划分

| 环境 | 用途 | 数据库 | 配置文件 |
|------|------|--------|----------|
| dev | 本地开发 | 本地MariaDB | application-dev.yml |
| test | 集成测试 | 测试MariaDB | application-test.yml |
| staging | 预发布 | 预发布MariaDB | application-staging.yml |
| prod | 生产 | 生产MariaDB主从 | application-prod.yml |

### 10.2 敏感配置管理

- 数据库密码、Redis密码、JWT密钥、腾讯云SecretKey等 **禁止硬编码**
- 使用环境变量注入：`SPRING_DATASOURCE_PASSWORD`, `JWT_SECRET`, `COS_SECRET_KEY`
- 生产环境密码定期轮换（每季度）

### 10.3 配置项清单

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `jwt.expiration` | Token过期时间（秒） | 7200 |
| `jwt.refresh-expiration` | Refresh Token过期时间（秒） | 604800 |
| `bluetooth.rssi-threshold` | 蓝牙信号阈值（dBm） | -70 |
| `bluetooth.distance-threshold` | ~~已废弃~~ 蓝牙不判断距离，连接即打卡 | — |
| `bluetooth.scan-timeout` | 蓝牙扫描超时（秒） | 3 |
| `permission.redis-channel` | 权限变更Redis频道名 | permission:changed |
| `async.pool.core-size` | 异步线程池核心线程数 | CPU核心数 |
| `async.pool.max-size` | 异步线程池最大线程数 | CPU核心数*2 |
| `upload.max-size` | 文件上传大小限制（MB） | 20 |
| `cos.bucket-name` | 腾讯云COS存储桶名称 | — |
| `backup.full-cron` | 全量备份cron | 0 2 * * ? |
| `backup.incr-interval-hours` | 增量备份间隔（小时） | 4 |

---

> **本文档为内部开发标准，所有开发人员必须严格按照此标准执行。如有疑问或需要调整，需经技术负责人审批。**