540 lines
21 KiB
Markdown
540 lines
21 KiB
Markdown
# 安智伴 · 家人连线台（Web 监护端）
|
||
|
||
> 本项目与 [dh_aigc_android](https://github.com/user/dh_aigc_android)（Android AI 数字人陪护终端）配合使用，共同构成完整的"AI 数字人 + 家庭远程关怀"解决方案。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [需求分析](#需求分析)
|
||
- [设计思路](#设计思路)
|
||
- [技术架构](#技术架构)
|
||
- [数据库设计](#数据库设计)
|
||
- [页面与功能](#页面与功能)
|
||
- [API 接口](#api-接口)
|
||
- [全链路数据流](#全链路数据流)
|
||
- [推送通知系统](#推送通知系统)
|
||
- [身份验证](#身份验证)
|
||
- [开发与部署](#开发与部署)
|
||
|
||
---
|
||
|
||
## 需求分析
|
||
|
||
### 背景
|
||
|
||
配合 Android 端 AI 数字人陪护应用，家属需要一个便捷的远程监护面板来：
|
||
- 了解老人是否在使用设备、与 AI 聊了什么
|
||
- 主动发送关怀留言，由数字人口播转达
|
||
- 接收老人通过 AI 口述的回复留言
|
||
- 获得实时推送通知，不遗漏重要消息
|
||
|
||
### 核心需求
|
||
|
||
| 需求维度 | 描述 |
|
||
|---------|------|
|
||
| **双向留言** | 家属发送留言 → 数字人口播给老人；老人口述 → AI 转录 → 家属在此查看 |
|
||
| **使用监测** | 查看老人设备的使用频率、AI 对话次数、最后在线时间 |
|
||
| **设备绑定** | 支持扫码或手动输入设备码绑定老人设备，一个家属可绑定多台设备 |
|
||
| **推送提醒** | 收到新留言时浏览器推送通知（PWA + Web Push） |
|
||
| **多端登录** | 同一家属账号可在多个浏览器/设备登录 |
|
||
| **面向家属的友好界面** | 暖色调、生活化文案，避免技术化的配置面板 |
|
||
|
||
### 用户角色
|
||
|
||
| 角色 | 使用场景 |
|
||
|------|---------|
|
||
| **家属**（本 Web 端） | 登录后查看老人动态、发送留言、管理设备绑定、接收推送 |
|
||
| **老人**（Android 端） | 不直接使用本系统，通过 AI 数字人间接交互 |
|
||
| **设备**（Android 端自动上报） | 自动注册、上报使用事件和对话数据 |
|
||
|
||
---
|
||
|
||
## 设计思路
|
||
|
||
### 1. 以留言为核心的关怀模式
|
||
|
||
不同于即时通讯工具，本系统采用"留言板"模式：
|
||
- 家属写留言 → 等老人下次与 AI 对话时口播转达
|
||
- 老人对 AI 说"帮我给儿子捎个话" → AI 通过工具调用存入数据库 → 家属收到推送
|
||
|
||
这种异步模式契合老人的使用习惯，无需老人学习操作手机。
|
||
|
||
### 2. 设备即桥梁
|
||
|
||
- Android 设备是唯一的数据桥梁，通过 UUID 标识
|
||
- 家属通过扫码或输入设备码绑定设备
|
||
- 所有消息和事件都关联到设备维度
|
||
|
||
### 3. PWA 优先
|
||
|
||
- 支持"安装到桌面"，像原生 App 一样使用
|
||
- Service Worker 处理推送通知
|
||
- 即使浏览器关闭也能收到消息提醒
|
||
|
||
### 4. 温暖的视觉语言
|
||
|
||
- 暖色系纸质质感（`--paper: #f4ece0`、`--copper: #c76733`、`--olive: #76845e`）
|
||
- 生活化文案（"写好并送出"而非"提交"）
|
||
- 面向不一定技术精通的家属用户
|
||
|
||
---
|
||
|
||
## 技术架构
|
||
|
||
### 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| **框架** | Next.js 16 (App Router, Server Components) |
|
||
| **前端** | React 19 + TypeScript 5 |
|
||
| **样式** | Tailwind CSS 4 + CSS 变量暖色系统 |
|
||
| **ORM** | Prisma 7 + PrismaPg 适配器 |
|
||
| **数据库** | PostgreSQL |
|
||
| **推送** | Web Push API + VAPID 密钥 |
|
||
| **认证** | Session-based (HttpOnly Cookie + bcryptjs) |
|
||
| **PWA** | Service Worker + Web App Manifest |
|
||
| **扫码** | qr-scanner (浏览器端摄像头扫码) |
|
||
|
||
### 系统架构图
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 家属浏览器 (PWA) │
|
||
│ │
|
||
│ ┌─────────────────┐ ┌─────────────┐ ┌────────────────────┐ │
|
||
│ │ 设备管理 │ │ 留言板 │ │ 陪伴动态 │ │
|
||
│ │ (扫码绑定/列表) │ │ (双向消息) │ │ (使用/对话/工具) │ │
|
||
│ └────────┬────────┘ └──────┬──────┘ └─────────┬──────────┘ │
|
||
│ │ │ │ │
|
||
│ ┌────────▼──────────────────▼────────────────────▼──────────┐ │
|
||
│ │ Service Worker (Web Push) │ │
|
||
│ └───────────────────────────┬───────────────────────────────┘ │
|
||
└──────────────────────────────┼───────────────────────────────────┘
|
||
│ HTTPS
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ Next.js Server │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||
│ │ API Routes │ │
|
||
│ │ /api/account/* 认证 (登录/注册/登出) │ │
|
||
│ │ /api/family/* 家属操作 (发留言/绑定/别名/解绑) │ │
|
||
│ │ /api/device/* 设备上报 (注册/消息/事件/对话/工具) │ │
|
||
│ │ /api/push/* 推送管理 (订阅/退订/测试) │ │
|
||
│ └────────────────────────────┬───────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────────────────▼───────────────────────────────┐ │
|
||
│ │ Prisma ORM │ │
|
||
│ └────────────────────────────┬───────────────────────────────┘ │
|
||
└───────────────────────────────┼──────────────────────────────────┘
|
||
│
|
||
┌───────────▼───────────┐
|
||
│ PostgreSQL │
|
||
│ │
|
||
│ CaregiverAccount │
|
||
│ CaregiverSession │
|
||
│ ElderDevice │
|
||
│ DeviceBinding │
|
||
│ FamilyMessage │
|
||
│ ConversationTurn │
|
||
│ UsageEvent │
|
||
│ ToolCallLog │
|
||
│ PushSubscription │
|
||
└───────────────────────┘
|
||
```
|
||
|
||
### 与 Android 端的通信
|
||
|
||
```
|
||
┌──────────────────┐ ┌──────────────────┐
|
||
│ Android 设备端 │ │ Next.js 云端 │
|
||
│ │ │ │
|
||
│ FamilyBridge │ ──────→ │ /api/device/* │
|
||
│ Service │ HTTPS │ │
|
||
│ │ │ • register │
|
||
│ • 设备注册 │ ──────→ │ • messages │
|
||
│ • 拉取留言 │ ←────── │ • messages/read │
|
||
│ • 标记已读 │ ──────→ │ • usage │
|
||
│ • 上报事件 │ ──────→ │ • conversations │
|
||
│ • 上传对话 │ ──────→ │ • tool-call │
|
||
│ • 工具调用记录 │ ──────→ │ │
|
||
└──────────────────┘ └──────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库设计
|
||
|
||
### ER 关系
|
||
|
||
```
|
||
CaregiverAccount ──1:N──→ CaregiverSession (多设备登录)
|
||
CaregiverAccount ──1:N──→ DeviceBinding (绑定多台设备)
|
||
CaregiverAccount ──1:N──→ FamilyMessage (发出的留言)
|
||
CaregiverAccount ──1:N──→ PushSubscription (推送端点)
|
||
|
||
ElderDevice ──1:N──→ DeviceBinding (被多个家属绑定)
|
||
ElderDevice ──1:N──→ FamilyMessage (关联的留言)
|
||
ElderDevice ──1:N──→ ConversationTurn (对话记录)
|
||
ElderDevice ──1:N──→ UsageEvent (使用事件)
|
||
ElderDevice ──1:N──→ ToolCallLog (工具调用日志)
|
||
```
|
||
|
||
### 核心数据模型
|
||
|
||
#### CaregiverAccount（家属账号）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | Int (PK) | 自增主键 |
|
||
| username | String (unique) | 账户名，3-24 位 |
|
||
| passwordHash | String | bcrypt 密码哈希 |
|
||
| nickname | String? | 昵称 |
|
||
|
||
#### ElderDevice（老人设备）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | Int (PK) | 自增主键 |
|
||
| deviceUuid | String (unique) | UUID 格式设备号 |
|
||
| displayName | String? | 设备显示名 |
|
||
| appVersion | String? | 应用版本号 |
|
||
| lastSeenAt | DateTime | 最后在线时间 |
|
||
|
||
#### DeviceBinding（设备绑定）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| caregiverId + elderDeviceId | 复合唯一键 | 多对多桥接 |
|
||
| alias | String? | 自定义别名（≤24 字） |
|
||
|
||
#### FamilyMessage（双向留言）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| publicId | Int (auto-increment) | 公开 ID，用于 URL |
|
||
| content | String | 留言内容 |
|
||
| direction | Enum | `ELDER_TO_FAMILY` / `FAMILY_TO_ELDER` |
|
||
| importance | Enum | `LOW` / `NORMAL` / `HIGH` / `URGENT` |
|
||
| status | Enum | `PENDING` / `DELIVERED` / `READ` |
|
||
|
||
#### UsageEvent（使用事件）
|
||
|
||
事件类型：`APP_OPEN` · `SETTINGS_OPENED` · `AI_SESSION_STARTED` · `AI_SESSION_ENDED` · `CAMERA_ENABLED` · `CAMERA_DISABLED` · `TOOL_CALLED`
|
||
|
||
#### ConversationTurn（对话轮次）
|
||
|
||
角色：`USER`（老人语音）· `ASSISTANT`（AI 回复）· `TOOL`（工具调用）
|
||
|
||
#### ToolCallLog（工具调用日志）
|
||
|
||
记录 AI 对话中触发的工具调用，包括工具名、参数 JSON、执行结果、状态。
|
||
|
||
### 迁移历史
|
||
|
||
| 版本 | 时间 | 内容 |
|
||
|------|------|------|
|
||
| v1 | 2026-04-17 01:50 | 初始表结构 + 枚举类型 |
|
||
| v2 | 2026-04-17 04:09 | 添加 publicId + PushSubscription 表 |
|
||
| v3 | 2026-04-17 04:51 | 账号认证系统 + 多设备会话 |
|
||
| v4 | 2026-04-17 07:00 | 设备绑定别名功能 |
|
||
|
||
---
|
||
|
||
## 页面与功能
|
||
|
||
### 页面结构
|
||
|
||
```
|
||
/login → 登录 / 注册
|
||
/ → 首页概览 (KPI 卡片 + 导航)
|
||
/devices → 设备列表 (绑定新设备 + 快速统计)
|
||
/devices/[uuid] → 设备详情 (发送留言 + 收到留言 + 活动记录)
|
||
/messages → 留言板 (双列：老人留言 / 我的问候)
|
||
/messages/[id] → 留言详情
|
||
/activity → 陪伴动态 (使用记录 + 聊天记录 + 智能服务)
|
||
/scan → 扫码绑定 (QR Scanner)
|
||
/settings → 设置 (PWA 安装 + 推送管理)
|
||
/bind → 绑定结果页
|
||
```
|
||
|
||
### 首页 `/`
|
||
|
||
- 4 个 KPI 卡片：已绑设备数、新留言数、待查看数、对话总数
|
||
- 4 个功能导航卡片：留言板、设备管理、陪伴动态、设置
|
||
- 无设备时显示引导流程
|
||
- 最近消息预览
|
||
|
||
### 设备管理 `/devices`
|
||
|
||
- 手动粘贴设备码绑定
|
||
- 设备卡片：在线状态、留言数、对话数、智能服务调用数
|
||
- 最新动态预览
|
||
|
||
### 设备详情 `/devices/[uuid]`
|
||
|
||
- KPI 指标（新留言、待查看、最后在线、绑定链接）
|
||
- 设备管理（别名修改、解绑）
|
||
- 发送留言表单（4 个优先级）
|
||
- 最近收到的留言列表
|
||
- 最近活动记录
|
||
- 已发送的问候
|
||
- 最近对话片段
|
||
|
||
### 留言板 `/messages`
|
||
|
||
- 双列分组：左侧"长辈的留言"（含未读计数）、右侧"我发出的问候"（含待查看计数）
|
||
- 每条显示：公开 ID、方向标签、设备名、优先级、状态、时间戳
|
||
|
||
### 陪伴动态 `/activity`
|
||
|
||
- 三列展示：使用记录、聊天记录、智能服务
|
||
- 趋势可视化图表
|
||
|
||
### 扫码绑定 `/scan`
|
||
|
||
- 浏览器摄像头 QR 扫描
|
||
- 自动摄像头授权检测
|
||
- 失败降级提示手动输入
|
||
|
||
---
|
||
|
||
## API 接口
|
||
|
||
### 账号管理 `/api/account/`
|
||
|
||
| 路由 | 方法 | 功能 |
|
||
|------|------|------|
|
||
| `/login` | POST | 登录（username + password → 设置 Session Cookie） |
|
||
| `/register` | POST | 注册（创建账号 + 自动登录） |
|
||
| `/logout` | POST | 登出（清除 Cookie + 删除 Session） |
|
||
|
||
### 家属操作 `/api/family/`
|
||
|
||
| 路由 | 方法 | 功能 |
|
||
|------|------|------|
|
||
| `/messages` | POST | 发送留言给老人（创建 FamilyMessage + 触发 Web Push） |
|
||
| `/device-binding` | PATCH | 修改设备别名 |
|
||
| `/device-binding` | DELETE | 解绑设备 |
|
||
| `/bind` | POST | 绑定新设备 |
|
||
| `/session` | GET | 会话验证 + 重定向 |
|
||
|
||
### 设备上报 `/api/device/`
|
||
|
||
| 路由 | 方法 | 功能 | 认证方式 |
|
||
|------|------|------|---------|
|
||
| `/register` | POST | 设备注册/更新 | deviceUuid 验证 |
|
||
| `/messages` | GET | 拉取待发送消息 | deviceUuid 查询参数 |
|
||
| `/messages/read` | POST | 标记消息已读 | deviceUuid 验证 |
|
||
| `/conversations` | POST | 记录对话内容 | deviceUuid 验证 |
|
||
| `/usage` | POST | 上报使用事件 | deviceUuid 验证 |
|
||
| `/tool-call` | POST | 记录工具调用 | deviceUuid 验证 |
|
||
|
||
### 推送管理 `/api/push/`
|
||
|
||
| 路由 | 方法 | 功能 |
|
||
|------|------|------|
|
||
| `/subscribe` | POST | 订阅推送通知（需登录） |
|
||
| `/unsubscribe` | POST | 取消订阅 |
|
||
| `/test` | POST | 发送测试推送 |
|
||
|
||
---
|
||
|
||
## 全链路数据流
|
||
|
||
### 1. 设备绑定流程
|
||
|
||
```
|
||
老人设备首次启动 → POST /api/device/register → 获得 deviceUuid + bindUrl
|
||
→ 设备屏幕展示二维码（编码 bindUrl）
|
||
→ 家属打开 /scan 页面 → 浏览器摄像头扫码
|
||
→ 解析出 /bind?deviceUuid=xxx
|
||
→ 未登录 → 重定向 /login?redirectTo=/bind?deviceUuid=xxx
|
||
→ 已登录 → 调用 POST /api/family/bind
|
||
→ 检查/创建 ElderDevice → 创建 DeviceBinding → 迁移遗留数据
|
||
→ 绑定成功页
|
||
```
|
||
|
||
### 2. 家属发送留言 → 老人收到
|
||
|
||
```
|
||
家属在 /devices/[uuid] 填写留言 → POST /api/family/messages
|
||
→ 创建 FamilyMessage (FAMILY_TO_ELDER, PENDING)
|
||
→ 触发 sendIncomingMessagePush() → 向所有订阅端点发送 Web Push
|
||
→ 家属收到浏览器通知确认
|
||
|
||
→ (稍后) 老人设备启动 AI 对话
|
||
→ FamilyBridgeService → GET /api/device/messages
|
||
→ 返回未读消息 (summaryText + messages[])
|
||
→ 注入 AI 系统 Prompt → AI 在第一轮回复中主动口播转达
|
||
→ 设备端 → POST /api/device/messages/read → 标记已读
|
||
```
|
||
|
||
### 3. 老人口述留言 → 家属收到
|
||
|
||
```
|
||
老人对 AI 说 "帮我给女儿说一声我今天去公园了"
|
||
→ Qwen 识别意图 → 触发 leave_message_for_family 工具
|
||
→ FamilyBridgeService → POST /api/device/conversations
|
||
→ 创建 FamilyMessage (ELDER_TO_FAMILY)
|
||
→ 触发 Web Push → 家属浏览器通知
|
||
→ 家属打开 /messages 查看
|
||
```
|
||
|
||
### 4. 使用监测
|
||
|
||
```
|
||
设备事件 (APP_OPEN / AI_SESSION_STARTED / ...)
|
||
→ POST /api/device/usage → 存入 UsageEvent
|
||
→ 家属访问 /activity → Server Component 查询最近事件
|
||
→ 渲染使用趋势图 + 对话记录 + 工具调用日志
|
||
```
|
||
|
||
---
|
||
|
||
## 推送通知系统
|
||
|
||
### 架构
|
||
|
||
```
|
||
家属浏览器
|
||
├── 注册 Service Worker (/sw.js)
|
||
├── PushManager.subscribe(VAPID 公钥) → 获取 PushSubscription
|
||
├── POST /api/push/subscribe → 存入数据库
|
||
└── 收到推送 → showNotification() → 点击 → 打开对应页面
|
||
|
||
服务端 (新消息触发时)
|
||
├── 查询目标设备所有已绑定家属的 PushSubscription
|
||
├── 循环调用 webpush.sendNotification()
|
||
└── 处理 410 Gone → 清理失效端点
|
||
```
|
||
|
||
### Service Worker 功能
|
||
|
||
- **push 事件**：解析 JSON → 调用 `showNotification()`，显示标题、内容、图标
|
||
- **notificationclick 事件**：打开或聚焦到目标 URL，支持已打开窗口的导航
|
||
- **去重**：使用 `tag: "digital-human-message"` 合并同类通知
|
||
|
||
---
|
||
|
||
## 身份验证
|
||
|
||
### 家属端（Session-based）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Cookie 名 | `dh-caregiver-session` |
|
||
| 属性 | HttpOnly + Secure (生产) + SameSite=Lax |
|
||
| 有效期 | 365 天 |
|
||
| 密码哈希 | bcryptjs |
|
||
| 多设备 | 每次登录创建独立 Session，支持多端在线 |
|
||
|
||
### 设备端（UUID 隐式验证）
|
||
|
||
设备通过 `deviceUuid` 参数标识身份，依赖 UUID 的不可猜测性。无需额外认证令牌。
|
||
|
||
---
|
||
|
||
## 开发与部署
|
||
|
||
### 环境变量
|
||
|
||
```env
|
||
DATABASE_URL=postgresql://... # PostgreSQL 连接串
|
||
NEXT_PUBLIC_VAPID_PUBLIC_KEY=... # Web Push 公钥（客户端）
|
||
VAPID_PRIVATE_KEY=... # Web Push 私钥（服务端）
|
||
VAPID_SUBJECT=mailto:admin@example.com # 推送发送者标识
|
||
```
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 数据库迁移
|
||
npx prisma migrate dev
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
访问 [http://localhost:3000](http://localhost:3000) 。
|
||
|
||
### 数据库管理
|
||
|
||
```bash
|
||
# 查看数据库
|
||
npx prisma studio
|
||
|
||
# 生成 Prisma Client
|
||
npx prisma generate
|
||
|
||
# 创建新迁移
|
||
npx prisma migrate dev --name <migration-name>
|
||
```
|
||
|
||
### 生产部署
|
||
|
||
```bash
|
||
# 构建
|
||
npm run build
|
||
|
||
# 启动
|
||
npm start
|
||
```
|
||
|
||
支持部署到 Vercel、Docker 或任何 Node.js 环境。
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
digital-human-monitor-v2/
|
||
├── app/ # Next.js App Router
|
||
│ ├── layout.tsx # 根布局 (认证状态 + 导航)
|
||
│ ├── page.tsx # 首页概览
|
||
│ ├── globals.css # 全局样式 (暖色系变量)
|
||
│ ├── manifest.ts # PWA Manifest
|
||
│ ├── api/ # API 路由
|
||
│ │ ├── account/ # 登录/注册/登出
|
||
│ │ ├── device/ # 设备上报接口
|
||
│ │ ├── family/ # 家属操作接口
|
||
│ │ └── push/ # 推送管理
|
||
│ ├── activity/ # 陪伴动态页
|
||
│ ├── bind/ # 绑定结果页
|
||
│ ├── devices/ # 设备管理
|
||
│ │ └── [deviceUuid]/ # 设备详情
|
||
│ ├── login/ # 登录/注册页
|
||
│ ├── messages/ # 留言板
|
||
│ │ └── [messageId]/ # 留言详情
|
||
│ ├── scan/ # 扫码绑定
|
||
│ └── settings/ # 设置页
|
||
├── components/ # 可复用 UI 组件
|
||
├── lib/ # 业务逻辑库
|
||
│ ├── prisma.ts # Prisma 客户端单例
|
||
│ ├── session.ts # Session 管理
|
||
│ ├── page-auth.ts # 页面级认证守卫
|
||
│ ├── push.ts # Web Push 发送逻辑
|
||
│ ├── caregiver-panel.ts # 家属面板数据聚合
|
||
│ ├── monitor-data.ts # 监测数据查询
|
||
│ └── panel-format.ts # 面板格式化工具
|
||
├── prisma/
|
||
│ ├── schema.prisma # 数据库 Schema
|
||
│ └── migrations/ # 迁移文件
|
||
├── public/
|
||
│ ├── sw.js # Service Worker
|
||
│ └── pwa/ # PWA 图标资源
|
||
└── scripts/
|
||
└── generate-icons.mjs # 图标生成脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 关联项目
|
||
|
||
| 项目 | 角色 | 仓库 |
|
||
|------|------|------|
|
||
| **digital-human-monitor-v2**（本项目） | 家属端：远程监护 Web 面板 + 消息管理 + 推送通知 | 当前仓库 |
|
||
| **dh_aigc_android** | 老人端：AI 数字人陪护 + 设备行为上报 | [dh_aigc_android](../dh_aigc_android/) |
|