# HealthManager 患者前端 — 技术文档

> 移动端 H5 应用，患者用手机浏览器打开。

---

## 目录

1. [技术选型](#1-技术选型)
2. [文件结构](#2-文件结构)
3. [关键文件详解](#3-关键文件详解)
4. [页面详解](#4-页面详解)
5. [状态管理](#5-状态管理)
6. [API 调用方式](#6-api-调用方式)
7. [常见问题 FAQ](#7-常见问题-faq)

---

## 1. 技术选型

| 库 | 版本 | 做什么 |
|----|------|--------|
| React | 19 | UI 框架 |
| TypeScript | 6 | 类型安全 |
| Vite | 8 | 构建工具 |
| Zustand | 5 | 状态管理 |
| React Router | 7 | 路由（页面跳转） |
| ECharts | 6 | 图表（趋势图、饼图） |
| Framer Motion | 12 | 动画 |
| dayjs | 2 | 日期处理 |

---

## 2. 文件结构

```
src/
├── main.tsx                    ← React 应用入口
├── App.tsx                     ← 根组件，渲染路由
├── router/
│   ├── index.tsx               ← URL 和页面的映射关系
│   └── AuthGuard.tsx           ← 路由守卫：没登录→跳登录页
├── stores/
│   ├── auth.store.ts           ← 认证状态：用户、令牌、登录/登出
│   └── notification.store.ts   ← 通知状态
├── services/
│   ├── api-client.ts           ← 底层 HTTP 请求（封装 fetch）
│   ├── auth.service.ts         ← 登录/注册/资料 API
│   ├── health.service.ts       ← 健康数据 API
│   ├── medication.service.ts   ← 药物 API
│   ├── consultation.service.ts ← 咨询 API
│   ├── report.service.ts       ← 报告 API
│   ├── followup.service.ts     ← 随访 API
│   ├── notification.service.ts ← 通知 API
│   ├── exercise-diet.service.ts← 运动饮食 API
│   └── device.service.ts       ← 设备 API
├── types/
│   ├── user.ts, health.ts, medication.ts, consultation.ts
│   ├── report.ts, followup.ts, notification.ts, device.ts
│   ├── calendar.ts, exercise-diet.ts
│   └── index.ts                ← 统一导出
├── utils/
│   ├── format.ts               ← 日期/数字格式化
│   ├── validator.ts            ← 手机号/验证码格式校验
│   └── constants.ts            ← 常量（测量类型、健康贴士等）
├── hooks/
│   ├── useAuth.ts              ← 获取认证状态
│   └── useCountdown.ts         ← 验证码倒计时
├── components/
│   ├── common/
│   │   ├── Button.tsx          ← 按钮（支持 loading 状态）
│   │   ├── Card.tsx            ← 卡片容器
│   │   ├── Badge.tsx           ← 角标（红点/数字）
│   │   ├── Input.tsx           ← 输入框（带标签+错误提示）
│   │   ├── Toast.tsx           ← 轻提示
│   │   └── Empty.tsx           ← 空状态占位
│   ├── layout/
│   │   ├── AppLayout.tsx       ← 主布局：TabBar + 内容区
│   │   ├── StackLayout.tsx     ← 子页面布局：返回按钮 + 内容区
│   │   ├── TabBar.tsx          ← 底部导航栏（首页/健康/服务/我的）
│   │   └── PageHeader.tsx      ← 页面标题栏
│   └── charts/
│       ├── LineChart.tsx       ← ECharts 折线图
│       ├── BarChart.tsx        ← ECharts 柱状图
│       └── PieChart.tsx        ← ECharts 饼图
└── pages/
    ├── auth/
    │   ├── LoginPage.tsx       ← 登录页
    │   └── RegisterPage.tsx    ← 注册页
    ├── home/
    │   ├── HomePage.tsx        ← 仪表盘首页
    │   └── DeviceBindingPage.tsx ← 设备绑定
    ├── health/                 ← 健康模块
    ├── medication/             ← 用药模块
    ├── services/               ← 服务模块（问诊/报告/随访）
    ├── exercise-diet/          ← 运动饮食
    ├── profile/                ← 个人中心
    └── notifications/          ← 通知
```

---

## 3. 关键文件详解

### 3.1 `services/api-client.ts` — HTTP 请求客户端

**所有前端 API 调用的基础**，封装了原生 `fetch`。

**核心逻辑**：
1. 公开接口（login/register/send-sms/refresh）**不附加** Authorization 头
2. 其他请求自动从 localStorage 读取 JWT 令牌，加到 `Authorization: Bearer xxx`
3. 发送 HTTP 请求到 `http://localhost:5000`
4. 如果返回 401（未认证）→ 清除 localStorage，跳转登录页
5. 把服务器返回的 JSON 统一包装成 `{ code, data, message }`

**四个方法**：`get`、`post`、`put`、`del`

### 3.2 `services/auth.service.ts` — 认证服务

| 函数 | 做的事 |
|------|--------|
| `login(phone, smsCode)` | 调 `POST /api/auth/login` → 返回 `{token, user}` |
| `register(phone, smsCode, name)` | 调 `POST /api/auth/register` |
| `getProfile()` | 调 `GET /api/auth/me` → 更新 localStorage 中的用户资料 |
| `updateProfile(data)` | 调 `PUT /api/auth/me` → 更新姓名/性别/身高/体重/病史 |
| `logout()` | 清除 localStorage 的 `hrt_auth` |

### 3.3 `services/health.service.ts` — 健康数据服务

| 函数 | API | 说明 |
|------|-----|------|
| `getRecords({type, startDate, endDate})` | `GET /health-records` | 查记录列表 |
| `addRecord(record)` | `POST /health-records` | 添加记录。自动把 value 转成 JSON 字符串 |
| `getLatestStats()` | `GET /health-records?days=7` | 拉取 7 天数据，客户端计算各类型的均值和趋势 |
| `getTrendData(type, days)` | `GET /health-records?type=&days=` | 趋势图数据 |

**Value 解析逻辑**：`parseValue()` 根据 type 解析 JSON：
- `blood_pressure` → `{systolic, diastolic}` 对象
- 其他类型 → `{value}` 中的数字

### 3.4 `services/medication.service.ts` — 用药服务

| 函数 | API | 说明 |
|------|-----|------|
| `getMedications()` | `GET /medications` | 药物列表 |
| `addMedication(data)` | `POST /medications` | 添加药物 |
| `markTaken(medicationId, slot)` | `POST /medications/{id}/take` | 打卡 |
| `getAdherence(medicationId)` | `GET /medications/{id}/adherence` | 依从率 |

### 3.5 `services/consultation.service.ts` — 咨询

| 函数 | API | 说明 |
|------|-----|------|
| `getDoctors()` | `GET /consultations/doctors` | 可接诊医生列表 |
| `getConsultation(doctorId)` | `GET /consultations` | 查与某医生的活跃咨询 |
| `startConsultation(doctorId)` | `POST /consultations` | 发起新咨询 |
| `sendMessage(consultationId, text)` | `POST /consultations/{id}/messages` | 发送消息 |
| `getDoctorReply(consultationId)` | `GET /consultations/{id}/messages` | 拉取最新消息，找医生的回复 |

### 3.6 `stores/auth.store.ts` — 认证状态

**状态数据**：`user`, `token`, `isAuthenticated`

**操作方法**：
- `login(phone, code)` → 调 API → 保存 token → 再拉完整用户资料
- `register(phone, code, name)` → 同上
- `logout()` → 清除所有数据
- `updateProfile(data)` → 只更新内存中的用户对象

**持久化**：Zustand `persist` 中间件 → `localStorage` 的 `hrt_auth` 键。刷新页面不丢登录状态。

### 3.7 `router/index.tsx` — 路由

分为三类：

1. **公开路由**（无需登录）：`/login`、`/register`
2. **Tab 路由**（需登录，底部导航栏）：`/home`、`/health`、`/services`、`/profile`
3. **Stack 路由**（需登录，有返回按钮）：所有子页面如 `/health/records/add`、`/services/consultation/chat/:doctorId` 等

`AuthGuard` 组件包裹在需要登录的路由外，未登录自动跳 `/login`。

---

## 4. 页面详解

### 登录页 `LoginPage.tsx`

- 输入手机号 + 短信验证码
- 点"获取验证码" → 60 秒倒计时
- 验证码任意输入（演示版）
- 成功后跳首页

### 首页 `HomePage.tsx`

- **健康概览卡片**（蓝色渐变）：最新血压 + 心率，异常值变色
- **快捷操作**（6 个）：测血压、记用药、在线问诊、报告解读、健康日历、运动饮食
- **健康小贴士**：随机展示，点击换下一条
- **通知角标**：未读通知红点

### 健康中心 `HealthHubPage.tsx`

6 种测量类型卡片 → 点击进记录列表 → 点"+ 录入" → 填数值 → 保存

### 趋势图 `TrendChartPage.tsx`

- ECharts 折线图，可选 7/14/30/90 天
- 血压同时显示收缩压+舒张压两条线，140 警戒线

### 药物管理

- **列表**：分"进行中/已结束"Tab
- **添加**：选常用药或手动输入，设剂量、频次（每日1~3次）、服药时间点
- **详情**：依从率饼图，近30天服药记录

### 在线问诊

- **医生列表**：按科室筛选 → 点医生 → 进聊天
- **聊天**：对话气泡，自动滚底
- 发送后 1.5 秒模拟医生回复（演示版）

### 报告管理

- **上传**：填标题 → 选类别 → 点虚线框选图片 → 提交
- **列表**：分状态 Tab 查看
- **详情**：查看解读结果

### 个人中心 `ProfilePage.tsx`

- 用户信息卡片（点击进入编辑）
- 身体数据展示
- 菜单：用药、通知、设备、设置、关于
- 退出登录

### 编辑资料 `EditProfilePage.tsx`

可修改：姓名、性别、生日、身高(cm)、体重(kg)、病史（顿号分隔）

---

## 5. 状态管理

| Store | 存储键 | 持久化 | 内容 |
|-------|--------|--------|------|
| `auth.store` | `hrt_auth` | ✓ localStorage | user, token, isAuthenticated |
| `notification.store` | — | ✗ 内存 | notifications[], unreadCount |

通知不持久化——每次打开应用重新从服务器拉取。

---

## 6. API 调用方式

```
前端 services → api-client.ts → fetch() → http://localhost:5000 → 后端 Controller
```

- 所有 API 请求经过 `api-client.ts` 统一处理
- 自动带 JWT 令牌（公开接口除外）
- 401 自动清除登录态并跳转登录页
- 响应统一为 `{ code, data, message }` 格式

---

## 7. 常见问题 FAQ

### Q1: 前端怎么调后端 API？

前端 `services/` 下的每个 service 文件封装了一类 API 调用。底层都通过 `api-client.ts` 发 HTTP 请求到 `http://localhost:5000`。

### Q2: 怎么测这个前端？

```bash
cd frontend-patient
npm run dev
# 浏览器打开 http://localhost:5173
# F12 → 左上角 📱 图标 → 选 iPhone 12 Pro 模拟手机
```

### Q3: 演示账号是什么？

手机号 `13800138000`，验证码随便填（1234 就行）。

### Q4: 为什么某些页面打开是空白的？

打开 F12 看 Console 有没有红色报错。最常见原因：
- 后端没启动（`ERR_CONNECTION_REFUSED`）
- 令牌过期（401 Unauthorized）→ 清 localStorage 重新登录

### Q5: 怎么改颜色/样式？

全局 CSS 变量在 `src/assets/styles/variables.css`：
- 主色 `--color-primary: #1E6BFF`
- 背景 `--color-bg: #F2F5FA`
- 改一个地方，全局生效

---

> 文档版本：v1.0 | 最后更新：2026-05-20 | 患者前端技术文档