技术架构设计

1. 技术架构总览图

1.1 整体架构图

快速理解：上层用户/设备 → 中层服务端 → 下层基础设施与第三方，一图掌握全貌。

1.2 系统上下文图

1.3 容器图

2. 标准化技术栈与版本锁定

2.1 技术栈总览

层级	技术选型	版本	用途
儿女端 App	UniApp + Vue3 + TypeScript	^3.4	iOS/Android 双端编译，包名 `health.reflekt.app`
老人端 App	原生 Android（Java + Kotlin）	—	Luma 智能音箱固件，包名 `health.reflekt.luma`
管理后台	Vue3 + TypeScript + ElementPlus	^3.5	PC Web，最小宽度 1024px
后端框架	Dromara RuoYi-Vue-Plus（Spring Boot 3）	^5.5	业务接口，包名 `health.reflekt.api`
Java 版本	Amazon Corretto	17	LTS 版本，部署镜像 `amazoncorretto:17`
数据库	Amazon RDS PostgreSQL	14+	主数据存储，Multi-AZ 部署
缓存	Amazon ElastiCache Redis	7.2+	会话缓存、设备心跳、分布式锁
消息队列	Amazon MQ（RabbitMQ）	—	MQTT 协议，雷达设备接入
对象存储	Amazon S3	—	语音留言、雷达存档、TTS 音频
容器编排	Amazon EKS	1.29+	托管 Kubernetes 集群
AI 能力	OpenAI（GPT-4o + TTS + Whisper）	Latest	语音对话、TTS 合成
短信/语音	Twilio	—	SMS 告警、红色预警语音直拨
iOS 推送	Apple APNs	—	Family App iOS 端推送
Android 推送	Google FCM	—	Family App Android 端推送
监控日志	Amazon CloudWatch + AWS X-Ray	—	全链路可观测，TraceID 串联

2.2 后端核心框架特性（RuoYi-Vue-Plus）

特性	说明
多租户	租户数据隔离，以家庭为单位的独立数据空间
数据权限	基于角色/部门的数据过滤，业务代码无感知
数据加密	MyBatis 拦截器自动加解密，支持 AES-256
分布式缓存	Redisson 实现分布式锁、限流、延迟队列
插件架构	模块化插拔，便于按需扩展
代码生成	BO/VO/Mapper/Service/Controller 全链路生成
WebSocket	支持 Token 鉴权与分布式集群消息同步
对象存储	统一 OSS 抽象层，底层使用 Amazon S3
API 认证	Sa-Token，JWT Token，会话超时 2 小时

3. 服务模块划分

3.1 服务职责总览

服务	服务名	核心职责	部署服务名	调用协议
设备接入服务	D1	三大硬件统一接入，协议转换，设备心跳监控	`reflekt-health-device-access`	MQTT/HTTP/WebSocket
家属端管理服务	D2	家庭CRUD、提醒关怀、语音留言、AI对话代理	`reflekt-health-family-api`	REST API
运营管理服务	D3	设备监控、告警处理、审计日志、配置管理	`reflekt-health-admin-api`	REST API
AI大脑服务	D4	跌倒判断、AI对话、TTS调度、主动问候	`reflekt-health-ai-brain`	内部调用
通知告警服务	D5	告警规则引擎、三级分发、升级链路、推送短信	`reflekt-health-notification`	内部调用

3.2 服务间依赖关系

调用方 \ 被调用方	D1 设备接入	D2 家属端	D3 运营管理	D4 AI大脑	D5 通知告警
Family App	—	REST API	—	—	—
Luma App	HTTP/WebSocket	—	—	—	—
Admin	—	—	REST API	—	—
D1 设备接入	—	—	设备状态同步	转发跌倒事件	—
D2 家属端	—	—	—	转发提醒请求	—
D4 AI大脑	—	—	—	—	触发告警
D5 通知告警	—	—	—	—	—
毫米波雷达	MQTT	—	—	—	—
智能手表	HTTP	—	—	—	—

3.3 服务部署架构

4. 设备接入架构

4.1 三设备接入方式

设备	协议	方向	接入服务	数据内容
Luma 智能音箱	HTTP + WebSocket	双向	D1 设备接入服务	状态上报、语音对话、指令接收
毫米波雷达	MQTT（Amazon MQ）	上行	D1 设备接入服务	跌倒事件、存在感数据
智能手表	HTTP	双向	D1 设备接入服务	心率/血氧/步数/睡眠；实时测量指令

4.2 MQTT 接入（雷达）

MQTT Topic 规范：

设备上报：/sys/{productKey}/{deviceName}/thing/event/property/post
云端下发：/sys/{productKey}/{deviceName}/thing/service/property/set

消息格式：

{
  "deviceId": "radar_001",
  "timestamp": 1713600000000,
  "eventType": "fall_detected",
  "data": {
    "fallConfidence": 0.92,
    "inRoom": true,
    "distance": 1.8,
    "angle": 30,
    "height": 0.5
  }
}

4.3 HTTP 接入（手表）

API 限流：埃微手表 API 限流 10 次/小时/设备。后端实现指数退避重试，超限后记录并降级。

4.4 WebSocket 接入（音箱）

5. 数据模型设计

5.1 核心实体

实体	表名	说明
FAMILY	`ref_family`	家庭，租户隔离核心单位
ELDER	`ref_elder`	被照护老人档案
CAREGIVER	`ref_caregiver`	照护人（家属），含手机号（加密）
DEVICE	`ref_device`	设备，含类型/luma/radar/watch
DEVICE_EVENT	`ref_device_event`	设备事件（跌倒/心跳/健康/SOS）
ALERT	`ref_alert`	告警，含级别/状态/证据包
ESCALATION	`ref_escalation`	升级链路记录
NOTIFICATION	`ref_notification`	通知下发记录
REMINDER	`ref_reminder`	提醒计划
REMINDER_LOG	`ref_reminder_log`	提醒执行日志
MEMORY	`ref_memory`	情感陪聊记忆话题

5.2 数据库选型与配置

配置项	值
引擎	Amazon RDS for PostgreSQL 14+
部署	Multi-AZ（主备双活，自动故障切换）
字符集	UTF-8
时区	UTC
连接池	HikariCP，最大 20 连接/服务实例
加密	敏感字段 AES-256（MyBatis 拦截器自动加解密）
备份	RDS 自动备份，保留 7 天 + 手动快照
只读副本	1 个，用于 Admin 复杂查询

5.3 缓存策略

缓存Key	TTL	说明
`device:heartbeat:{deviceId}`	5 min	设备最后心跳时间
`family:status:{familyId}`	30s	家庭当前六状态
`session:{token}`	2h	用户会话，JWT
`alert:escalation:{alertId}`	90s	升级链路状态锁

6. 依赖安装命令（Agent 可直接执行）

6.1 后端（API 服务）

# 克隆仓库
git clone https://git.yuyi.tech/chengyisoft/reflekt-health-api.git
cd reflekt-health-api

# 环境准备
sdk install java 17.0.10-tem         # 或使用 amazoncorretto:17 Docker 镜像
sdk install maven 3.9.6

# 本地开发（IDE 导入）
# 导入方式：IDEA/Eclipse 导入 Maven 项目
# 运行：mvn spring-boot:run 或直接运行 Application 主类

# Docker 构建
mvn clean package -DskipTests
docker build -t reflekt-health-api:latest .
docker run -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e AMAZON_MQ_ENDPOINT=${AMAZON_MQ_ENDPOINT} \
  -e AMAZON_MQ_USERNAME=${AMAZON_MQ_USERNAME} \
  -e AMAZON_MQ_PASSWORD=${AMAZON_MQ_PASSWORD} \
  -e TWILIO_ACCOUNT_SID=${TWILIO_ACCOUNT_SID} \
  -e TWILIO_AUTH_TOKEN=${TWILIO_AUTH_TOKEN} \
  -e TWILIO_PHONE_NUMBER=${TWILIO_PHONE_NUMBER} \
  -e OPENAI_API_KEY=${OPENAI_API_KEY} \
  -e AWS_S3_BUCKET=${AWS_S3_BUCKET} \
  -e AWS_REGION=${AWS_REGION} \
  -e AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} \
  -e AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} \
  reflekt-health-api:latest

6.2 儿女端（Family App）

# 克隆仓库
git clone https://git.yuyi.tech/chengyisoft/reflekt-health-app.git
cd reflekt-health-app

# 安装依赖（pnpm 优先，npm 次之）
pnpm install
# npm install

# 开发调试
pnpm dev:h5          # H5 预览
pnpm dev:ios         # iOS 开发版（需 macOS + Xcode）
pnpm dev:android     # Android 开发版

# 生产构建
pnpm build:app-ios      # iOS .ipa
pnpm build:app-android  # Android .apk / .aab

6.3 老人端（Luma App）

# 克隆仓库
git clone https://git.yuyi.tech/chengyisoft/reflekt-health-luma.git
cd reflekt-health-luma

# Android Studio 打开项目
# Gradle Sync → Build → 运行到音箱设备

# 固件构建（CI/CD）
./gradlew assembleRelease

6.4 管理后台（Admin）

# 克隆仓库
git clone https://git.yuyi.tech/chengyisoft/reflekt-health-admin.git
cd reflekt-health-admin

pnpm install

# 开发调试
pnpm dev

# 生产构建
pnpm build:admin
# 输出目录: dist/admin/

7. 环境变量清单

7.1 必需环境变量

变量名	说明	敏感	示例
`AMAZON_MQ_ENDPOINT`	Amazon MQ 接入点	否	`b-xxxx.mq.us-east-1.amazonaws.com:5672`
`AMAZON_MQ_USERNAME`	Amazon MQ 用户名	否	`admin`
`AMAZON_MQ_PASSWORD`	Amazon MQ 密码	是	`********`
`TWILIO_ACCOUNT_SID`	Twilio Account SID	否	`ACxxxxxxxx`
`TWILIO_AUTH_TOKEN`	Twilio Auth Token	是	`********`
`TWILIO_PHONE_NUMBER`	Twilio 发号电话号码	否	`+1234567890`
`OPENAI_API_KEY`	OpenAI API Key	是	`sk-********`
`AWS_S3_BUCKET`	S3 Bucket 名称	否	`reflekt-health-assets`
`AWS_REGION`	AWS Region	否	`us-east-1`
`AWS_ACCESS_KEY_ID`	AWS AccessKey	是	`AKIA********`
`AWS_SECRET_ACCESS_KEY`	AWS SecretKey	是	`********`
`APNS_KEY_ID`	APNs Key ID	否	`XXXXXXXXXX`
`APNS_TEAM_ID`	APNs Team ID	否	`YYYYYYYYYY`
`APNS_KEY_PATH`	APNs .p8 证书路径	是	`/secrets/apns.p8`
`FCM_SERVER_KEY`	Firebase Cloud Messaging Server Key	是	`********`
`EWATRIS_API_ENDPOINT`	埃微手表 API 端点	否	`https://api.ewatris.com`

7.2 服务发现与环境隔离

环境	标识	说明
开发环境	`dev`	本地 Docker Compose 启动
预发布环境	`staging`	AWS EKS staging 集群
生产环境	`prod`	AWS EKS production 集群

8. 关键设计决策

决策点	选择	理由
多租户隔离	以家庭为隔离单位	家庭是 Reflekt 最小业务单元，跨家庭访问严格禁止
设备接入架构	统一接入服务 D1，协议转换	三种异构设备（MQTT/HTTP/WebSocket）统一封装为内部模型
AI 服务定位	独立 D4 服务，不嵌入业务服务	AI 对话/TTS/跌倒判断为计算密集型，独立扩缩容
消息队列选型	Amazon MQ（RabbitMQ）	雷达设备仅支持 MQTT 协议，Amazon MQ 原生支持 MQTT over TLS
缓存策略	Redis 缓存心跳 + 会话，DB 存永久状态	心跳高频写入不适合 DB，Redis 提供毫秒级读写
文件存储	Amazon S3	语音留言/TTS 音频/雷达存档，需持久化存储与 CDN 分发
移动推送	APNs + FCM 双通道	iOS/Android 双平台各选最优方案，互为备份
告警升级	D5 独立服务，Redisson 分布式锁	升级链路跨越多服务，需原子性和一致性保证
WebSocket	Sa-Token Token 鉴权，分布式集群同步	Luma 设备需长连接，支持指令下发与事件上报
API 认证	Sa-Token + JWT，2 小时会话超时	成熟国产框架，与 RuoYi-Vue-Plus 深度集成
数据加密	MyBatis 拦截器自动加解密	联系方式/疾病史等字段零感知加密，业务代码无侵入
视频通话	MVP 不做（改为音频通话）	MVP 聚焦核心告警链路，WebRTC 复杂度高，延期至 v1.1

9. 全链路数据流

10. 非功能性需求摘要

维度	指标	目标值
性能	API 查询响应时间 P95	< 200ms
性能	API 写入响应时间 P95	< 500ms
性能	红色预警端到端延迟	< 5 分钟
性能	设备心跳上报成功率	≥ 99.5%
性能	峰值吞吐量	≥ 100 TPS
可用性	系统 SLA	99.9%
可用性	故障恢复时间 RTO	< 30 分钟
可用性	数据恢复点 RPO	< 5 分钟
安全	传输加密	TLS 1.2+（HTTPS/WSS）
安全	敏感字段加密	AES-256
安全	认证机制	JWT Token，2 小时超时
安全	数据隔离	以家庭为单位的租户隔离
合规	HIPAA 合规	100% 满足
合规	日志保留期	≥ 12 个月
适老化	Luma App 字号最小值	≥ 18pt
适老化	Family App 字号最小值	≥ 16pt
适老化	核心操作步骤	≤ 3 步

11. 风险与已知约束

风险ID	风险描述	影响	缓解措施
RISK-01	Amazon MQ 单连接心跳 60s，低于雷达心跳设计	设备频繁标记离线	设备端本地离线缓存，断连补发
RISK-02	埃微 API 限流 10 次/小时/设备	心率数据实时性受限	后端下发实时测量指令触发主动上报
RISK-03	Twilio SMS 限流 10 条/日/手机号	红色预警无法 100% 送达	推送 + 直拨双通道降级，直拨优先穿透
RISK-04	OpenAI 配额 GPT-4o + TTS 共用	高并发场景相互挤压	优先级调度，配额监控预警
RISK-05	APNs / FCM 证书/API Key 过期	移动端通知失效	证书到期预警，短信通道兜底
RISK-06	红色预警端到端 < 5 分钟	任一环节延迟累积即超时	全链路延迟监控，SLA 告警

12. 项目目录结构

reflekt-health-api/               # 后端 API 服务
├── reflekt-api/                  # RuoYi-Vue-Plus 主模块
│   ├── reflekt-system/           # 系统模块（用户/角色/菜单）
│   ├── reflekt-generator/        # 代码生成模块
│   └── ...
├── src/main/java/health/reflekt/
│   ├── controller/               # REST Controller 层
│   ├── service/                  # 业务逻辑层
│   │   ├── device/               # 设备接入（D1）
│   │   ├── family/               # 家属端服务（D2）
│   │   ├── admin/                # 运营管理服务（D3）
│   │   ├── ai/                   # AI 大脑服务（D4）
│   │   └── notification/         # 通知告警服务（D5）
│   ├── mq/                       # MQ 消费者
│   │   └── radar/                # 雷达 MQTT 消费者
│   ├── domain/                   # 实体类
│   ├── mapper/                   # MyBatis Mapper
│   └── common/                   # 通用工具类
├── pom.xml
└── Dockerfile

reflekt-health-app/               # Family App 儿女端（UniApp）
├── src/
│   ├── pages/                    # 页面
│   │   ├── auth/                 # 认证模块
│   │   ├── home/                 # 首页 Hub
│   │   ├── devices/               # 设备管理
│   │   ├── messages/              # 消息中心
│   │   └── profile/             # 个人设置
│   ├── static/ui/fap/           # UI 预览文件
│   ├── services/                 # API 封装
│   ├── store/                    # 状态管理（Pinia）
│   └── utils/                   # 工具函数
├── manifest.json
└── package.json

reflekt-health-luma/              # Luma App 老人端（原生 Android）
├── app/src/main/
│   ├── java/health/reflekt/luma/
│   │   ├── service/             # Android Service
│   │   ├── receiver/            # 广播接收器
│   │   └── ui/                  # Activity / Fragment
│   └── res/
│       ├── layout/              # 布局文件
│       ├── values/               # 资源值
│       └── raw/                 # 音频资源
└── build.gradle

reflekt-health-admin/             # Admin 管理后台
├── src/
│   ├── views/                   # 页面视图
│   ├── api/                     # API 调用封装
│   ├── store/                   # 状态管理
│   └── router/                  # 路由配置
├── package.json
└── vite.config.ts

本文档由 Reflekt Health 产品团队维护，最后更新于 2026-04-21。

1. 技术架构总览图​

1.1 整体架构图​

1.2 系统上下文图​

1.3 容器图​

2. 标准化技术栈与版本锁定​

2.1 技术栈总览​

2.2 后端核心框架特性（RuoYi-Vue-Plus）​

3. 服务模块划分​

3.1 服务职责总览​

3.2 服务间依赖关系​

3.3 服务部署架构​

4. 设备接入架构​

4.1 三设备接入方式​

4.2 MQTT 接入（雷达）​

4.3 HTTP 接入（手表）​

4.4 WebSocket 接入（音箱）​

5. 数据模型设计​

5.1 核心实体​

5.2 数据库选型与配置​

5.3 缓存策略​

6. 依赖安装命令（Agent 可直接执行）​

6.1 后端（API 服务）​

6.2 儿女端（Family App）​

6.3 老人端（Luma App）​

6.4 管理后台（Admin）​

7. 环境变量清单​

7.1 必需环境变量​

7.2 服务发现与环境隔离​

8. 关键设计决策​

9. 全链路数据流​

10. 非功能性需求摘要​

11. 风险与已知约束​

12. 项目目录结构​

1. 技术架构总览图

1.1 整体架构图

1.2 系统上下文图

1.3 容器图

2. 标准化技术栈与版本锁定

2.1 技术栈总览

2.2 后端核心框架特性（RuoYi-Vue-Plus）

3. 服务模块划分

3.1 服务职责总览

3.2 服务间依赖关系

3.3 服务部署架构

4. 设备接入架构

4.1 三设备接入方式

4.2 MQTT 接入（雷达）

4.3 HTTP 接入（手表）

4.4 WebSocket 接入（音箱）

5. 数据模型设计

5.1 核心实体

5.2 数据库选型与配置

5.3 缓存策略

6. 依赖安装命令（Agent 可直接执行）

6.1 后端（API 服务）

6.2 儿女端（Family App）

6.3 老人端（Luma App）

6.4 管理后台（Admin）

7. 环境变量清单

7.1 必需环境变量

7.2 服务发现与环境隔离

8. 关键设计决策

9. 全链路数据流

10. 非功能性需求摘要

11. 风险与已知约束

12. 项目目录结构