435af55c4a
Backend: .NET 10 + PostgreSQL + EF Core + JWT + SignalR Frontend patient: React 19 + TypeScript + Vite (mobile H5) Frontend doctor: React 19 + TypeScript + Vite (desktop web)
1518 lines
62 KiB
Markdown
1518 lines
62 KiB
Markdown
# HealthManager 健康管理平台 — 超级详细技术文档
|
||
|
||
> **适用对象**：小白开发者 / 新加入项目的同学
|
||
> **文档目标**：看懂每一个文件是干什么的，代码在做什么，为什么要这样写
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目总览](#1-项目总览)
|
||
2. [架构设计：什么是"整洁架构"](#2-架构设计什么是整洁架构)
|
||
3. [后端 — Domain 领域层](#3-后端--domain-领域层)
|
||
4. [后端 — Application 应用层](#4-后端--application-应用层)
|
||
5. [后端 — Infrastructure 基础设施层](#5-后端--infrastructure-基础设施层)
|
||
6. [后端 — WebApi 接口层](#6-后端--webapi-接口层)
|
||
7. [病人端前端 (frontend-patient)](#7-病人端前端-frontend-patient)
|
||
8. [医生端前端 (frontend-doctor)](#8-医生端前端-frontend-doctor)
|
||
9. [数据库表结构](#9-数据库表结构)
|
||
10. [常见问题 FAQ](#10-常见问题-faq)
|
||
|
||
---
|
||
|
||
## 1. 项目总览
|
||
|
||
### 1.1 这是什么项目？
|
||
|
||
**HealthManager** 是一个**面向心血管术后患者的健康管理平台**。它有两个前端和一个后端：
|
||
|
||
| 部分 | 技术 | 谁用 | 干什么 |
|
||
|------|------|------|--------|
|
||
| **后端 API** | .NET 10 + PostgreSQL | 为两个前端提供数据 | 用户认证、健康数据存储、用药管理、在线问诊、报告解读、随访管理 |
|
||
| **病人 H5 前端** | React 19 + TypeScript + Vite | 术后患者 | 在手机上记录血压/心率/用药，咨询医生，查看报告 |
|
||
| **医生 PC 前端** | React 19 + TypeScript + Vite | 心血管医生 | 在电脑上管理患者、回复咨询、解读报告、安排随访 |
|
||
|
||
### 1.2 涉及的技术
|
||
|
||
| 技术 | 是什么 | 在本项目中的用途 |
|
||
|------|--------|------------------|
|
||
| **.NET 10** | 微软的后端开发框架 | 写 API 接口，处理业务逻辑 |
|
||
| **C#** | .NET 的编程语言 | 所有后端代码都用 C# 写 |
|
||
| **Entity Framework Core (EF Core)** | .NET 的数据库操作框架 | 用 C# 对象操作数据库，不用手写 SQL |
|
||
| **PostgreSQL** | 开源关系型数据库 | 存储用户、健康数据、药物、咨询等所有数据 |
|
||
| **Npgsql** | PostgreSQL 的 .NET 驱动 | 让 EF Core 能连接和操作 PostgreSQL |
|
||
| **JWT (JSON Web Token)** | 一种身份验证令牌 | 用户登录后，凭令牌访问 API，不用每次输密码 |
|
||
| **SignalR** | 微软的实时通信框架 | 实现医生和患者之间的实时聊天 |
|
||
| **Swagger** | API 文档工具 | 自动生成 API 文档页面，可以直接在浏览器里测试接口 |
|
||
| **MinIO** | S3 兼容的对象存储 | 存储图片（报告照片、头像等） |
|
||
| **Redis** | 内存缓存数据库 | 缓存常用数据，加速访问 |
|
||
| **React** | Facebook 出的前端框架 | 构建用户界面，组件化开发 |
|
||
| **TypeScript** | JavaScript 的超集，加了类型系统 | 让前端代码更安全、更好维护 |
|
||
| **Vite** | 新一代前端构建工具 | 开发时热更新快，打包也快 |
|
||
| **Zustand** | 轻量级状态管理库 | 管理登录状态、用户信息等全局数据 |
|
||
| **React Router** | React 路由库 | 实现页面跳转，URL 和页面组件对应 |
|
||
| **ECharts** | 百度出品的数据可视化库 | 画趋势图、饼图，展示健康数据变化 |
|
||
|
||
### 1.3 项目文件结构
|
||
|
||
```
|
||
D:\APP\
|
||
├── backend\ ← 后端 .NET 项目
|
||
│ ├── HealthManager.slnx ← 解决方案文件（管理多个项目）
|
||
│ ├── start-dev.bat ← 一键启动脚本
|
||
│ └── src\
|
||
│ ├── HealthManager.Domain\ ← 领域层（实体 + 接口）
|
||
│ ├── HealthManager.Application\← 应用层（服务 + DTO）
|
||
│ ├── HealthManager.Infrastructure\← 基础设施层（数据库 + JWT）
|
||
│ └── HealthManager.WebApi\ ← Web API 层（控制器 + 启动）
|
||
├── frontend-patient\ ← 病人 H5 前端
|
||
│ └── src\
|
||
│ ├── pages\ ← 页面组件
|
||
│ ├── services\ ← API 调用函数
|
||
│ ├── stores\ ← 状态管理
|
||
│ ├── components\ ← 公共组件
|
||
│ ├── types\ ← 类型定义
|
||
│ ├── utils\ ← 工具函数
|
||
│ └── router\ ← 路由配置
|
||
├── frontend-doctor\ ← 医生 PC 前端
|
||
│ └── src\
|
||
│ ├── pages\ ← 页面组件
|
||
│ ├── services\ ← API 调用函数
|
||
│ ├── stores\ ← 状态管理
|
||
│ ├── types\ ← 类型定义
|
||
│ └── router\ ← 路由配置
|
||
└── data\ ← 数据目录
|
||
├── pgdata\ ← PostgreSQL 数据文件
|
||
└── minio\ ← MinIO 文件存储
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 架构设计：什么是"整洁架构"
|
||
|
||
### 2.1 为什么分成四层？
|
||
|
||
传统的写法是把所有代码写在一起（比如把数据库查询、业务逻辑、API 接口写在一个文件里）。这样写久了会越来越乱，改一个地方可能影响其他功能。
|
||
|
||
**整洁架构（Clean Architecture）** 的核心思想是：**把代码按照职责分成不同的层，内层的代码不依赖外层的代码**。
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ WebApi (接口层) │ ← 接收 HTTP 请求，返回 JSON
|
||
│ 接收请求 → 调用服务 → 返回结果 │
|
||
├──────────────────────────────────────────┤
|
||
│ Application (应用层) │ ← 业务逻辑、数据转换
|
||
│ 具体的业务操作：登录、查健康数据等 │
|
||
├──────────────────────────────────────────┤
|
||
│ Domain (领域层) │ ← 核心：定义"什么是用户"、"什么是健康记录"
|
||
│ 实体类（User、HealthRecord...）+ 接口 │
|
||
├──────────────────────────────────────────┤
|
||
│ Infrastructure (基础设施层) │ ← 和外部系统打交道
|
||
│ 数据库操作、JWT 生成、发邮件等 │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
**依赖方向**：WebApi → Application → Domain ← Infrastructure
|
||
|
||
- 所有层都依赖 Domain（因为 Domain 定了"数据长什么样"）
|
||
- Infrastructure 实现了 Domain 定义的接口（比如 `IJwtProvider`）
|
||
|
||
### 2.2 每一层的职责
|
||
|
||
| 层 | 能做什么 | 不能做什么 |
|
||
|----|----------|-----------|
|
||
| **Domain** | 定义实体、定义接口 | 不写具体逻辑、不访问数据库 |
|
||
| **Application** | 写业务逻辑、定义 DTO | 不直接访问 HTTP 请求、不直接操作数据库 |
|
||
| **Infrastructure** | 实现接口、操作数据库、生成 JWT | 不处理 HTTP 请求 |
|
||
| **WebApi** | 接收 HTTP 请求、控制权限、返回响应 | 不写业务逻辑、不直接操作数据库 |
|
||
|
||
---
|
||
|
||
## 3. 后端 — Domain 领域层
|
||
|
||
> 这是最核心的一层，定义了"数据长什么样"。就像一个房子的地基。
|
||
|
||
### 3.1 项目文件 `HealthManager.Domain.csproj`
|
||
|
||
这是 .NET 项目的配置文件，告诉编译器：
|
||
- 这是一个类库项目（不是可运行的程序）
|
||
- 使用 .NET 10
|
||
- 引用了哪些 NuGet 包（这里没有额外依赖，是最纯净的）
|
||
|
||
### 3.2 接口 `Interfaces/IJwtProvider.cs`
|
||
|
||
```csharp
|
||
namespace HealthManager.Domain.Interfaces;
|
||
|
||
public interface IJwtProvider
|
||
{
|
||
string GenerateAccessToken(Guid userId, string name, string role);
|
||
string GenerateRefreshToken();
|
||
}
|
||
```
|
||
|
||
**这是干什么的？** 定义了一个"契约"——任何实现这个接口的类，必须提供两个方法：
|
||
- `GenerateAccessToken`：生成访问令牌（30分钟有效，用完后要用刷新令牌换新的）
|
||
- `GenerateRefreshToken`：生成刷新令牌（长期有效，用来换新的访问令牌）
|
||
|
||
**为什么放在 Domain 层？** 因为 Application 层需要使用这个功能，但 Application 层不应该知道具体是怎么实现的（可能是 JWT，也可能是其他方式）。所以 Domain 定义接口，Infrastructure 去实现。
|
||
|
||
### 3.3 实体类
|
||
|
||
实体类 = 数据库表的 C# 映射。每个实体对应数据库中的一张表，类的属性对应表的列。
|
||
|
||
---
|
||
|
||
#### `Entities/User.cs` — 用户表
|
||
|
||
**对应数据库表**：`Users`
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 唯一标识，全局不重复的 ID（不用自增数字，避免暴露用户量） |
|
||
| Role | string | 角色：`"patient"`（患者）、`"doctor"`（医生）、`"admin"`（管理员） |
|
||
| Phone | string | 手机号，用于登录（相当于用户名） |
|
||
| PasswordHash | string | 密码的 SHA256 哈希值，不存明文 |
|
||
| Name | string | 真实姓名 |
|
||
| AvatarUrl | string? | 头像图片地址（可空） |
|
||
| Gender | string? | 性别 |
|
||
| Birthday | DateOnly? | 出生日期 |
|
||
| HeightCm | decimal? | 身高（厘米） |
|
||
| WeightKg | decimal? | 体重（公斤） |
|
||
| MedicalHistory | List\<string\>? | 病史列表，如 `["高血压", "冠心病"]`，在数据库存为数组 |
|
||
| StentDate | DateOnly? | 支架植入日期（患者特有） |
|
||
| StentType | string? | 支架类型（患者特有） |
|
||
| Department | string? | 科室（医生特有） |
|
||
| Title | string? | 职称，如 `"主任医师"`（医生特有） |
|
||
| Specialty | List\<string\>? | 擅长领域列表（医生特有） |
|
||
| Introduction | string? | 医生简介（医生特有） |
|
||
| IsAvailable | bool | 是否可接诊（医生特有） |
|
||
| CreatedAt | DateTime | 账号创建时间 |
|
||
| UpdatedAt | DateTime | 最后更新时间 |
|
||
| IsDeleted | bool | 软删除标记（不真删数据） |
|
||
| DeletedAt | DateTime? | 删除时间 |
|
||
|
||
**设计特点**：患者和医生共用一张 `Users` 表，通过 `Role` 字段区分。患者独有的字段（如病史、支架日期）对医生为空；医生独有的字段（如科室、职称）对患者为空。这叫"单表继承"模式。
|
||
|
||
**导航属性**：User 还包含多个"一对多"关系，表示一个用户可以有多个健康记录、多种药物等。
|
||
|
||
---
|
||
|
||
#### `Entities/RefreshToken.cs` — 刷新令牌表
|
||
|
||
**对应数据库表**：`RefreshTokens`
|
||
|
||
**干什么的？** 用户登录后，后端发两个令牌：
|
||
- **Access Token**：短期有效（30分钟），用于访问 API
|
||
- **Refresh Token**：长期有效（7天），用于在 Access Token 过期后换新的
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| UserId | Guid | 属于哪个用户 |
|
||
| Token | string | 令牌字符串（唯一的） |
|
||
| ExpiresAt | DateTime | 过期时间 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
| RevokedAt | DateTime? | 吊销时间（如果被吊销了就不能再用了） |
|
||
|
||
---
|
||
|
||
#### `Entities/Device.cs` — 设备表
|
||
|
||
**对应数据库表**：`Devices`
|
||
|
||
**干什么的？** 患者可以绑定智能设备（血压计、手环等），设备数据自动同步。
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| UserId | Guid? | 绑定的用户（可空，未绑定时为空） |
|
||
| Name | string | 设备名称，如 `"欧姆龙血压计"` |
|
||
| Type | string | 设备类型：血压计、手环、血糖仪、体重秤 |
|
||
| MacAddress | string? | MAC 地址 |
|
||
| SerialNumber | string? | 序列号 |
|
||
| IsBound | bool | 是否已绑定用户 |
|
||
| BoundAt | DateTime? | 绑定时间 |
|
||
| LastSyncAt | DateTime? | 最后同步时间 |
|
||
| BatteryLevel | int? | 电量百分比 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/HealthRecord.cs` — 健康记录表
|
||
|
||
**对应数据库表**：`HealthRecords`
|
||
|
||
**干什么的？** 存储用户的健康测量数据（血压、心率、血糖、血氧、体重、步数）。
|
||
|
||
**属性说明**：
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| UserId | Guid | 属于哪个用户 |
|
||
| Type | string | 类型：`blood_pressure`(血压)、`heart_rate`(心率)、`blood_sugar`(血糖)、`spo2`(血氧)、`weight`(体重)、`steps`(步数) |
|
||
| Value | JsonDocument | **关键设计**：不同测量的数据格式不一样。血压是 `{systolic:120, diastolic:80, pulse:72}`，心率是 `{value:72}`。用 JSON 列存储，灵活适应不同格式 |
|
||
| Unit | string | 单位：`mmHg`、`bpm`、`mmol/L`、`%`、`kg`、`步` |
|
||
| RecordedAt | DateTime | 测量时间 |
|
||
| Source | string | 数据来源：`manual`（手动输入）、`device`（设备同步）、`doctor`（医生录入） |
|
||
| Notes | string? | 备注 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
**为什么 Value 用 JSON 而不是分别建列？** 因为不同测量类型的数据结构不同。如果每种类型建一张表，会有很多表。JSON 列让数据库结构简单，同时保持灵活性。
|
||
|
||
---
|
||
|
||
#### `Entities/DietRecord.cs` — 饮食记录表
|
||
|
||
**对应数据库表**：`DietRecords`
|
||
|
||
**干什么的？** 记录患者的饮食情况。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| UserId | Guid | 属于哪个用户 |
|
||
| MealType | string | 餐类型：`breakfast`、`lunch`、`dinner`、`snack` |
|
||
| FoodName | string | 食物名称 |
|
||
| Portion | string? | 份量描述 |
|
||
| Calories | int? | 卡路里估算 |
|
||
| Notes | string? | 备注 |
|
||
| RecordedAt | DateOnly | 记录日期 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/ExerciseRecord.cs` — 运动记录表
|
||
|
||
**对应数据库表**：`ExerciseRecords`
|
||
|
||
**干什么的？** 记录患者的运动情况。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| UserId | Guid | 属于哪个用户 |
|
||
| ExerciseType | string | 运动类型：`步行`、`慢跑`、`游泳`、`骑行` |
|
||
| DurationMin | int | 运动时长（分钟） |
|
||
| Intensity | string? | 强度：`low`、`moderate`、`high` |
|
||
| CaloriesBurned | int? | 消耗卡路里 |
|
||
| Notes | string? | 备注 |
|
||
| RecordedAt | DateOnly | 记录日期 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/Medication.cs` — 药物表
|
||
|
||
**对应数据库表**：`Medications`
|
||
|
||
**干什么的？** 存储医生为患者开的药。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| UserId | Guid | 患者 ID |
|
||
| DoctorId | Guid? | 开药医生 ID |
|
||
| DrugName | string | 药物名称，如 `"阿司匹林肠溶片"` |
|
||
| Dosage | string | 剂量，如 `"100mg"` |
|
||
| Frequency | string | 频率，如 `"每日1次"` |
|
||
| TimeSlots | List\<string\> | 服药时间点列表，如 `["08:00", "20:00"]`，存为数组 |
|
||
| StartDate | DateOnly | 开始日期 |
|
||
| EndDate | DateOnly? | 结束日期（为空表示长期服用） |
|
||
| Notes | string? | 备注（如注意事项） |
|
||
| Status | string | 状态：`active`（服用中）、`completed`（已结束）、`stopped`（已停用） |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
| UpdatedAt | DateTime | 更新时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/MedicationRecord.cs` — 服药记录表
|
||
|
||
**对应数据库表**：`MedicationRecords`
|
||
|
||
**干什么的？** 记录每一次服药情况（吃了还是没吃）。用来计算"依从率"（有没有按时吃药）。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| MedicationId | Guid | 属于哪个药物 |
|
||
| UserId | Guid | 患者 ID |
|
||
| TimeSlot | string | 哪个时间点，如 `"08:00"` |
|
||
| TakenAt | DateTime? | 实际服药时间（为空表示没吃） |
|
||
| IsTaken | bool | 是否已服用 |
|
||
| SkippedReason | string? | 未服用的原因，如 `"忘记"` |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/Consultation.cs` — 咨询表
|
||
|
||
**对应数据库表**：`Consultations`
|
||
|
||
**干什么的？** 存储一次医患在线咨询会话。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| PatientId | Guid | 患者 ID |
|
||
| DoctorId | Guid | 医生 ID |
|
||
| Subject | string? | 咨询主题 |
|
||
| Status | string | 状态：`active`（进行中）、`closed`（已结束） |
|
||
| StartedAt | DateTime | 开始时间 |
|
||
| ClosedAt | DateTime? | 关闭时间 |
|
||
| ClosedBy | Guid? | 谁关闭的 |
|
||
| Summary | string? | 总结 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/ConsultationMessage.cs` — 咨询消息表
|
||
|
||
**对应数据库表**：`ConsultationMessages`
|
||
|
||
**干什么的？** 存储咨询中的每一条消息。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| ConsultationId | Guid | 属于哪个咨询 |
|
||
| SenderId | Guid | 发送者 ID |
|
||
| SenderRole | string | 发送者角色：`patient`、`doctor`、`system` |
|
||
| ContentType | string | 内容类型：`text`、`image`、`file`、`template` |
|
||
| Content | string | 消息正文 |
|
||
| ImageUrl | string? | 图片地址 |
|
||
| FileUrl | string? | 文件地址 |
|
||
| IsRead | bool | 对方是否已读 |
|
||
| CreatedAt | DateTime | 发送时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/QuickReplyTemplate.cs` — 快捷回复模板表
|
||
|
||
**对应数据库表**：`QuickReplyTemplates`
|
||
|
||
**干什么的？** 医生可以设置常用回复模板，问诊时一键发送，提高效率。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| DoctorId | Guid | 医生 ID |
|
||
| Title | string | 模板标题 |
|
||
| Content | string | 模板内容 |
|
||
| Category | string? | 分类 |
|
||
| SortOrder | int | 排序 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/Report.cs` — 报告表
|
||
|
||
**对应数据库表**：`Reports`
|
||
|
||
**干什么的？** 患者上传的检查报告（化验单、心电图等），由医生审核解读。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| PatientId | Guid | 患者 ID |
|
||
| DoctorId | Guid? | 解读医生 ID |
|
||
| Title | string | 报告标题 |
|
||
| Category | string | 类别：`血液检查`、`心电图`、`影像学`、`尿液检查` |
|
||
| ImageUrls | List\<string\> | 报告图片地址列表，存为数组 |
|
||
| Status | string | 状态：`pending`（待审核）、`interpreting`（解读中）、`completed`（已完成） |
|
||
| RiskLevel | string? | 风险等级：`normal`、`attention`、`abnormal` |
|
||
| Summary | string? | 解读总结 |
|
||
| Suggestions | string? | 医生建议 |
|
||
| UploadedBy | Guid | 上传者 ID |
|
||
| UploadedAt | DateTime | 上传时间 |
|
||
| CompletedAt | DateTime? | 完成时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/ReportItem.cs` — 报告项目表
|
||
|
||
**对应数据库表**：`ReportItems`
|
||
|
||
**干什么的？** 一份报告包含多个检查项目（比如一份化验单有10项指标）。每个项目存一条。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| ReportId | Guid | 属于哪个报告 |
|
||
| ItemName | string | 项目名称，如 `"低密度脂蛋白胆固醇"` |
|
||
| ResultValue | string | 检查结果，如 `"3.2"` |
|
||
| Unit | string? | 单位，如 `"mmol/L"` |
|
||
| ReferenceRange | string? | 正常参考范围，如 `"<3.4"` |
|
||
| IsAbnormal | bool | 是否异常 |
|
||
| SortOrder | int | 排序 |
|
||
|
||
---
|
||
|
||
#### `Entities/FollowUp.cs` — 随访表
|
||
|
||
**对应数据库表**：`FollowUps`
|
||
|
||
**干什么的？** 安排患者复查/随访计划。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| PatientId | Guid | 患者 ID |
|
||
| DoctorId | Guid? | 医生 ID |
|
||
| Title | string | 随访主题 |
|
||
| Description | string? | 描述 |
|
||
| ScheduledAt | DateTime | 计划时间 |
|
||
| Status | string | 状态：`upcoming`（将到来）、`completed`（已完成）、`cancelled`（已取消）、`rescheduled`（已改期） |
|
||
| Notes | string? | 备注 |
|
||
| ReminderEnabled | bool | 是否开启提醒 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
| UpdatedAt | DateTime | 更新时间 |
|
||
|
||
---
|
||
|
||
#### `Entities/Notification.cs` — 通知表
|
||
|
||
**对应数据库表**：`Notifications`
|
||
|
||
**干什么的？** 各类推送通知。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | Guid | 主键 |
|
||
| UserId | Guid | 接收者 ID |
|
||
| Type | string | 类型：`medication`、`followup`、`consultation`、`report`、`system` |
|
||
| Title | string | 标题 |
|
||
| Content | string | 内容 |
|
||
| RelatedId | Guid? | 关联的业务 ID（比如关联的咨询 ID） |
|
||
| IsRead | bool | 是否已读 |
|
||
| ReadAt | DateTime? | 阅读时间 |
|
||
| CreatedAt | DateTime | 创建时间 |
|
||
|
||
---
|
||
|
||
## 4. 后端 — Application 应用层
|
||
|
||
> 这一层写所有的**业务逻辑**。它不操作数据库（通过 DbContext 操作），不接收 HTTP 请求（由 WebApi 层接收并调用它）。
|
||
|
||
### 4.1 DTO（数据传输对象）
|
||
|
||
DTO = Data Transfer Object。它是"前端和后端之间传输数据用的对象"。
|
||
|
||
**为什么要用 DTO 而不是直接把实体类（Entity）返回给前端？**
|
||
1. **安全**：实体类可能包含密码哈希等敏感数据，DTO 可以过滤掉
|
||
2. **灵活**：前端需要的数据格式可能和数据库结构不一样，DTO 可以自由组合
|
||
3. **解耦**：数据库结构变了，只要调整 DTO 转换逻辑，前端不受影响
|
||
|
||
---
|
||
|
||
#### `DTOs/AuthDtos.cs` — 认证相关 DTO
|
||
|
||
| DTO | 作用 |
|
||
|-----|------|
|
||
| `LoginRequest` | 前端发来的登录请求：`{ phone, smsCode }` |
|
||
| `RegisterRequest` | 前端发来的注册请求：`{ phone, smsCode, name }` |
|
||
| `SendSmsRequest` | 发验证码请求：`{ phone }` |
|
||
| `AuthResponse` | 登录成功后返回：`{ userId, name, role, accessToken, refreshToken }` |
|
||
| `UserProfileResponse` | 用户完整资料（患者和医生字段都有） |
|
||
| `UpdateProfileRequest` | 更新个人资料的请求 |
|
||
|
||
---
|
||
|
||
#### `DTOs/ConsultationDtos.cs` — 咨询相关 DTO
|
||
|
||
| DTO | 作用 |
|
||
|-----|------|
|
||
| `ConsultationCreateRequest` | 创建咨询：`{ doctorId, subject }` |
|
||
| `ConsultationResponse` | 咨询详情 |
|
||
| `SendMessageRequest` | 发送消息：`{ content, contentType, imageUrl }` |
|
||
| `MessageResponse` | 消息详情 |
|
||
|
||
---
|
||
|
||
#### `DTOs/FollowUpDtos.cs` — 随访相关 DTO
|
||
|
||
| DTO | 作用 |
|
||
|-----|------|
|
||
| `FollowUpCreateRequest` | 创建随访：`{ title, description, scheduledAt, reminderEnabled }` |
|
||
| `FollowUpUpdateRequest` | 更新随访（所有字段都可空，只更新提供的字段） |
|
||
| `FollowUpResponse` | 随访详情 |
|
||
|
||
---
|
||
|
||
#### `DTOs/HealthDtos.cs` — 健康记录相关 DTO
|
||
|
||
| DTO | 作用 |
|
||
|-----|------|
|
||
| `HealthRecordCreateRequest` | 添加健康记录：`{ type, valueJson, unit, recordedAt, notes }` |
|
||
| `HealthRecordResponse` | 单条健康记录 |
|
||
| `HealthStatsResponse` | 聚合统计：最新值 + 周平均 + 月平均 + 趋势（上升/下降/稳定） |
|
||
|
||
---
|
||
|
||
#### `DTOs/MedicationDtos.cs` — 药物相关 DTO
|
||
|
||
| DTO | 作用 |
|
||
|-----|------|
|
||
| `MedicationCreateRequest` | 添加药物：`{ drugName, dosage, frequency, timeSlots, startDate, endDate, notes }` |
|
||
| `MedicationResponse` | 药物详情 |
|
||
| `MedicationRecordResponse` | 服药记录 |
|
||
| `AdherenceResponse` | 依从率：`{ rate(%), takenDays, totalDays }` |
|
||
|
||
---
|
||
|
||
#### `DTOs/ReportDtos.cs` — 报告相关 DTO
|
||
|
||
| DTO | 作用 |
|
||
|-----|------|
|
||
| `ReportUploadRequest` | 上传报告：`{ title, category, imageUrls }` |
|
||
| `ReportInterpretRequest` | 医生解读报告：`{ summary, items, riskLevel, suggestions }` |
|
||
| `ReportResponse` | 报告详情（含解读结果） |
|
||
| `ReportItemDto` | 单个检查项目 |
|
||
|
||
---
|
||
|
||
### 4.2 服务类
|
||
|
||
每个服务类负责一个业务领域的所有逻辑。它们通过构造函数注入 `AppDbContext`（数据库）和需要的其他服务。
|
||
|
||
---
|
||
|
||
#### `Services/AuthService.cs` — 认证服务
|
||
|
||
**负责**：用户登录、注册、Token 刷新、获取资料、更新资料。
|
||
|
||
**主要方法做的事**：
|
||
- **登录**：根据手机号找用户 → 验证密码（演示版跳过） → 生成 JWT 令牌对 → 保存刷新令牌到数据库 → 返回令牌和用户信息
|
||
- **注册**：检查手机号是否已注册 → 创建新用户 → 生成令牌对 → 保存 → 返回
|
||
- **刷新令牌**：找到数据库中的刷新令牌 → 检查是否过期/被吊销 → 生成新令牌对 → 吊销旧令牌 → 保存新令牌
|
||
- **获取资料**：根据用户 ID 查找用户 → 映射成 UserProfileResponse 返回
|
||
- **更新资料**：找到用户 → 更新可修改的字段 → 保存
|
||
|
||
---
|
||
|
||
#### `Services/HealthService.cs` — 健康数据服务
|
||
|
||
**负责**：健康记录的增删查、统计计算。
|
||
|
||
**主要方法做的事**：
|
||
- **获取记录列表**：支持按类型（血压/心率等）、按天数筛选，也可以医生查看指定患者的记录
|
||
- **获取最新记录**：查某类型最新的一条
|
||
- **添加记录**：验证 JSON 格式 → 创建 HealthRecord → 保存
|
||
- **获取统计**：这是最复杂的方法。查出每种类型的所有记录 → 计算最新值、7天平均、30天平均 → 比较趋势（上升/下降/稳定）
|
||
|
||
---
|
||
|
||
#### `Services/MedicationService.cs` — 药物管理服务
|
||
|
||
**负责**：药物的增删查、服药打卡、依从率计算。
|
||
|
||
**主要方法做的事**：
|
||
- **列出药物**：查出用户的所有药物，支持医生查看指定患者的
|
||
- **添加药物**：创建新药物 → 为所有时间段生成服药记录（预生成未来几天的记录）
|
||
- **获取详情**：根据 ID 查询单条药物
|
||
- **获取服药记录**：查某药物的所有服药记录
|
||
- **标记已服用**：用户点"已服药" → 更新对应时间和时间点的服药记录为已服用
|
||
- **计算依从率**：已服用次数 / 总需服用次数 × 100%
|
||
|
||
---
|
||
|
||
#### `Services/ConsultationService.cs` — 咨询问诊服务
|
||
|
||
**负责**：列出医生、创建咨询、收发消息。
|
||
|
||
**主要方法做的事**：
|
||
- **列出可用医生**：查出所有 `Role=doctor` 且 `IsAvailable=true` 的用户
|
||
- **创建咨询**：患者选择医生 → 检查是否已有活跃咨询（有的话复用） → 创建新 Consultation
|
||
- **获取咨询列表**：患者看自己的，医生看分配给自己的
|
||
- **发送消息**：创建 ConsultationMessage → 保存 → 通过 SignalR 实时推送给对方
|
||
- **获取消息**：查某咨询的所有消息，按时间排序
|
||
|
||
---
|
||
|
||
#### `Services/PatientService.cs` — 患者管理服务（医生用）
|
||
|
||
**负责**：医生查看患者列表和详情。
|
||
|
||
**主要方法做的事**：
|
||
- **患者列表**：查出所有 `Role=patient` 的用户，支持按姓名/手机号搜索，支持分页
|
||
- **患者详情**：根据 ID 查出患者完整资料
|
||
|
||
---
|
||
|
||
#### `Services/ReportService.cs` — 报告管理服务
|
||
|
||
**负责**：报告的增删查、医生解读。
|
||
|
||
**主要方法做的事**：
|
||
- **上传报告**：患者上传检查报告图片 → 创建 Report 记录（状态为 pending）
|
||
- **列出报告**：患者看自己的，医生可看所有或筛选特定患者
|
||
- **待审核列表**：列出所有状态为 pending 的报告（医生用）
|
||
- **报告详情**：查询单条报告及其所有 ReportItem
|
||
- **解读报告**：医生提交解读 → 保存总结、风险等级、建议 → 创建所有 ReportItem → 更新报告状态为 completed
|
||
|
||
---
|
||
|
||
#### `Services/FollowUpService.cs` — 随访管理服务
|
||
|
||
**负责**：随访计划的增删改查。
|
||
|
||
**主要方法做的事**：
|
||
- **创建随访**：患者或医生创建随访计划
|
||
- **列出随访**：患者看自己的，医生看分配给自己的
|
||
- **更新随访**：医生修改随访信息（改时间、改状态、加备注）
|
||
|
||
---
|
||
|
||
#### `Services/NotificationService.cs` — 通知服务
|
||
|
||
**负责**：通知的查询、已读标记、创建。
|
||
|
||
**主要方法做的事**：
|
||
- **列出通知**：查出用户所有通知，按时间倒序
|
||
- **未读计数**：统计 `IsRead=false` 的通知数量
|
||
- **标记已读**：单条或全部标为已读
|
||
- **创建通知**：其他服务调用此方法创建通知（如"医生回复了你的咨询"）
|
||
|
||
---
|
||
|
||
## 5. 后端 — Infrastructure 基础设施层
|
||
|
||
> 这一层和"外部世界"打交道：数据库、JWT 加密等具体技术实现。
|
||
|
||
### 5.1 `Data/AppDbContext.cs` — 数据库上下文
|
||
|
||
**这是整个项目中最重要的基础设施文件**。它是 EF Core 的"总管家"。
|
||
|
||
**做了什么**：
|
||
1. **定义 15 个 DbSet**：每个 DbSet 对应一张数据库表
|
||
```csharp
|
||
public DbSet<User> Users => Set<User>();
|
||
public DbSet<HealthRecord> HealthRecords => Set<HealthRecord>();
|
||
// ... 共 15 个
|
||
```
|
||
|
||
2. **在 `OnModelCreating` 中配置表结构**：
|
||
- **JSON 列映射**：HealthRecord.Value 类型是 `JsonDocument`，配置为 PostgreSQL 的 `jsonb` 类型
|
||
- **数组列映射**：`List<string>` 类型的属性（如 MedicalHistory、TimeSlots、Specialty）映射为 PostgreSQL 的 `text[]` 类型
|
||
- **索引配置**：为常查询的列创建数据库索引（加速查询）
|
||
- `Users.Phone` 建唯一索引（手机号不能重复）
|
||
- `Users.Role` 建普通索引（经常按角色查询）
|
||
- `HealthRecords.UserId + Type` 建复合索引（"查某用户的血压数据"这种查询）
|
||
- `Consultations.Status` 建索引（查活跃的咨询）
|
||
- 等等...
|
||
- **软删除过滤器**：User 有 `IsDeleted` 标记，配置全局过滤器自动排除已删除的用户
|
||
|
||
---
|
||
|
||
### 5.2 `Data/DataSeeder.cs` — 种子数据
|
||
|
||
**干什么的？** 在数据库首次创建时，自动插入演示数据，方便开发和测试。
|
||
|
||
**插入了什么数据**：
|
||
|
||
| 数据 | 数量 | 说明 |
|
||
|------|------|------|
|
||
| **患者** | 2个 | 张明（男，60岁，高血压+冠心病+PCI术后）、李芳（女，53岁，高血脂+冠心病+PCI术后） |
|
||
| **医生** | 2个 | 王建国（主任医师，心血管内科）、陈雪梅（副主任医师，心血管内科） |
|
||
| **健康记录** | 31天×3条/天 ≈ 93条 | 患者1的血压、心率、体重数据（有随机波动） |
|
||
| **药物** | 4种 | 阿司匹林、替格瑞洛、瑞舒伐他汀、美托洛尔 |
|
||
| **服药记录** | 4药×8天×1~2次/天 ≈ 50条 | 近8天的服药情况，约90%依从率 |
|
||
| **咨询** | 1个 | 张明咨询王建国关于术后复查 |
|
||
| **咨询消息** | 4条 | 一次完整的医患对话 |
|
||
| **通知** | 4条 | 用药提醒、复查提醒、医生回复、健康提示 |
|
||
|
||
**关键技术点**：
|
||
- 所有演示密码都是 `demo123`，使用 SHA256 哈希存储
|
||
- 使用固定随机种子 `new Random(42)`，每次生成的数据一样
|
||
- 时间戳使用 `DateTimeKind.Utc`，因为 PostgreSQL 的 `timestamp with time zone` 要求 UTC 时间
|
||
- 健康数据的 Value 使用 `JsonDocument.Parse()` 创建 JSON 格式
|
||
|
||
---
|
||
|
||
### 5.3 `Services/JwtProvider.cs` — JWT 令牌提供者
|
||
|
||
**干什么的？** 实现了 Domain 层定义的 `IJwtProvider` 接口，生成 JWT 令牌。
|
||
|
||
**两个方法**：
|
||
|
||
1. **`GenerateAccessToken`**：生成访问令牌
|
||
- 从配置文件读取密钥（`appsettings.json` 的 `Jwt:Secret`）
|
||
- 把用户 ID、姓名、角色打包进令牌的"负载"（Claims）
|
||
- 使用 HMAC-SHA256 算法签名
|
||
- 设置 30 分钟过期
|
||
- 返回签好名的 JWT 字符串
|
||
|
||
2. **`GenerateRefreshToken`**：生成刷新令牌
|
||
- 使用加密安全的随机数生成器产生 64 字节随机数据
|
||
- 转成 Base64 字符串返回（就是一个随机字符串，不包含任何信息）
|
||
|
||
**JWT 是怎么工作的？** 可以理解为"盖了章的通行证"：
|
||
- 服务器签发令牌时"盖章"（用密钥签名）
|
||
- 客户端每次请求带着令牌
|
||
- 服务器验证"章"是真的 → 放行
|
||
- 如果令牌过期了 → 拒绝，客户端用刷新令牌换新的
|
||
|
||
---
|
||
|
||
## 6. 后端 — WebApi 接口层
|
||
|
||
> 这是最外层，直接接收 HTTP 请求，返回 JSON 响应。
|
||
|
||
### 6.1 `Program.cs` — 应用程序入口
|
||
|
||
**这是整个后端启动的唯一入口文件**。它配置了应用运行所需的一切。
|
||
|
||
**主要做的事（按顺序）**：
|
||
|
||
1. **创建 WebApplication**：初始化 .NET 应用
|
||
2. **注册服务（依赖注入）**：
|
||
- 注册 `AppDbContext`：告诉 EF Core 用 PostgreSQL，连接字符串从配置文件读
|
||
- 注册 JWT 认证：配置验证规则（密钥、签发者、过期时间等）
|
||
- 注册 Swagger：配置 API 文档，支持 JWT 认证测试
|
||
- 注册 SignalR：配置实时通信
|
||
- 注册 CORS：允许前端跨域访问（开发阶段允许所有来源）
|
||
- 注册业务服务：`AuthService`、`HealthService` 等，让控制器能使用
|
||
- 注册 `IJwtProvider` → `JwtProvider`：告诉框架"当需要 IJwtProvider 时，用 JwtProvider"
|
||
3. **配置中间件管道**：
|
||
- 异常处理 → CORS → 认证 → 授权 → 映射控制器 → 映射 SignalR Hub
|
||
4. **初始化数据库**：
|
||
- 确保数据库和表已创建（`EnsureCreatedAsync`）
|
||
- 调用 `DataSeeder.SeedAsync()` 插入演示数据
|
||
5. **启动应用**：开始监听 HTTP 请求
|
||
|
||
---
|
||
|
||
### 6.2 控制器
|
||
|
||
控制器 = 处理 HTTP 请求的"接待员"。每个控制器负责一组相关的 API。
|
||
|
||
---
|
||
|
||
#### `Controllers/AuthController.cs` — 认证接口
|
||
|
||
**路由前缀**：`api/auth`
|
||
|
||
| 端点 | 方法 | 认证 | 做什么 |
|
||
|------|------|------|--------|
|
||
| `POST /api/auth/send-sms` | 公开 | ✗ | 模拟发送短信验证码（演示版直接返回成功） |
|
||
| `POST /api/auth/login` | 公开 | ✗ | 手机号+验证码登录，返回 JWT 令牌对 |
|
||
| `POST /api/auth/register` | 公开 | ✗ | 注册新患者账号 |
|
||
| `POST /api/auth/refresh` | 公开 | ✗ | 用刷新令牌换新的访问令牌对 |
|
||
| `GET /api/auth/me` | 需登录 | ✓ | 获取当前登录用户的完整资料 |
|
||
| `PUT /api/auth/me` | 需登录 | ✓ | 更新当前用户的个人资料 |
|
||
|
||
**细节**：登录接口接收 `{ phone, smsCode }`，验证码固定为 `1234`（演示版）。成功后返回 `{ userId, name, role, accessToken, refreshToken }`。
|
||
|
||
---
|
||
|
||
#### `Controllers/HealthController.cs` — 健康数据接口
|
||
|
||
**路由前缀**：`api/health-records`
|
||
|
||
| 端点 | 方法 | 认证 | 做什么 |
|
||
|------|------|------|--------|
|
||
| `GET /api/health-records` | 需登录 | ✓ | 查询健康记录，可按类型和天数筛选 |
|
||
| `GET /api/health-records/stats` | 需登录 | ✓ | 获取所有类型的统计（最新值、周/月平均、趋势） |
|
||
| `GET /api/health-records/latest/{type}` | 需登录 | ✓ | 获取某类型最新一条记录 |
|
||
| `POST /api/health-records` | 需登录 | ✓ | 添加一条健康记录 |
|
||
|
||
**细节**：查询支持 `?type=blood_pressure&days=30` 参数。医生可以加 `?patientId=xxx` 查看指定患者的数据。
|
||
|
||
---
|
||
|
||
#### `Controllers/MedicationController.cs` — 药物管理接口
|
||
|
||
**路由前缀**：`api/medications`
|
||
|
||
| 端点 | 方法 | 认证 | 做什么 |
|
||
|------|------|------|--------|
|
||
| `GET /api/medications` | 需登录 | ✓ | 列出所有药物 |
|
||
| `POST /api/medications` | 需登录 | ✓ | 添加新药物 |
|
||
| `GET /api/medications/{id}` | 需登录 | ✓ | 获取药物详情 |
|
||
| `GET /api/medications/{id}/records` | 需登录 | ✓ | 获取该药物的所有服药记录 |
|
||
| `POST /api/medications/{id}/take` | 需登录 | ✓ | 标记某时间点已服药 |
|
||
| `GET /api/medications/{id}/adherence` | 需登录 | ✓ | 获取该药物的依从率 |
|
||
|
||
**细节**：`take` 接口接收 `{ timeSlot: "08:00" }`，在相应的时间点记录服药。
|
||
|
||
---
|
||
|
||
#### `Controllers/ConsultationController.cs` — 在线问诊接口
|
||
|
||
**路由前缀**：`api/consultations`
|
||
|
||
| 端点 | 方法 | 认证 | 做什么 |
|
||
|------|------|------|--------|
|
||
| `GET /api/consultations/doctors` | 需登录 | ✓ | 列出可接诊的医生 |
|
||
| `GET /api/consultations` | 需登录 | ✓ | 列出我的咨询（患者看自己的，医生看分配给自己的） |
|
||
| `POST /api/consultations` | 需登录 | ✓ | 发起新咨询 |
|
||
| `GET /api/consultations/{id}/messages` | 需登录 | ✓ | 获取咨询的所有消息 |
|
||
| `POST /api/consultations/{id}/messages` | 需登录 | ✓ | 发送消息 |
|
||
|
||
---
|
||
|
||
#### `Controllers/ReportController.cs` — 报告管理接口
|
||
|
||
**路由前缀**：`api/reports`
|
||
|
||
| 端点 | 方法 | 认证 | 权限 | 做什么 |
|
||
|------|------|------|------|--------|
|
||
| `GET /api/reports` | 需登录 | ✓ | — | 列出报告 |
|
||
| `GET /api/reports/pending` | 需登录 | ✓ | 仅医生 | 列出待审核的报告 |
|
||
| `GET /api/reports/{id}` | 需登录 | ✓ | — | 获取报告详情 |
|
||
| `POST /api/reports` | 需登录 | ✓ | — | 上传报告 |
|
||
| `POST /api/reports/{id}/interpret` | 需登录 | ✓ | 仅医生 | 医生提交解读 |
|
||
|
||
---
|
||
|
||
#### `Controllers/FollowUpController.cs` — 随访管理接口
|
||
|
||
**路由前缀**：`api/follow-ups`
|
||
|
||
| 端点 | 方法 | 认证 | 权限 | 做什么 |
|
||
|------|------|------|------|--------|
|
||
| `GET /api/follow-ups` | 需登录 | ✓ | — | 列出随访计划 |
|
||
| `GET /api/follow-ups/{id}` | 需登录 | ✓ | — | 获取随访详情 |
|
||
| `POST /api/follow-ups` | 需登录 | ✓ | — | 创建随访 |
|
||
| `PUT /api/follow-ups/{id}` | 需登录 | ✓ | 仅医生 | 更新随访 |
|
||
|
||
---
|
||
|
||
#### `Controllers/PatientController.cs` — 患者管理接口（医生专用）
|
||
|
||
**路由前缀**：`api/patients`
|
||
|
||
| 端点 | 方法 | 认证 | 权限 | 做什么 |
|
||
|------|------|------|------|--------|
|
||
| `GET /api/patients` | 需登录 | ✓ | 仅医生 | 列出患者（支持搜索和分页） |
|
||
| `GET /api/patients/{id}` | 需登录 | ✓ | 仅医生 | 获取患者详情 |
|
||
|
||
---
|
||
|
||
#### `Controllers/NotificationController.cs` — 通知接口
|
||
|
||
**路由前缀**：`api/notifications`
|
||
|
||
| 端点 | 方法 | 认证 | 做什么 |
|
||
|------|------|------|--------|
|
||
| `GET /api/notifications` | 需登录 | ✓ | 列出所有通知 |
|
||
| `GET /api/notifications/unread-count` | 需登录 | ✓ | 获取未读数量 |
|
||
| `PUT /api/notifications/{id}/read` | 需登录 | ✓ | 标记单条已读 |
|
||
| `PUT /api/notifications/read-all` | 需登录 | ✓ | 全部标记已读 |
|
||
|
||
---
|
||
|
||
### 6.3 `Hubs/ChatHub.cs` — SignalR 实时聊天枢纽
|
||
|
||
**干什么的？** 实现医生和患者的实时消息推送。
|
||
|
||
**技术原理**：
|
||
- 传统 HTTP：客户端问 → 服务器答（一问一答，服务器不能主动推送）
|
||
- SignalR：建立 WebSocket 长连接 → 服务器可以随时推消息给客户端
|
||
|
||
**主要方法**：
|
||
- `JoinConsultation(consultationId)`：加入一个咨询的"聊天室"
|
||
- `LeaveConsultation(consultationId)`：离开聊天室
|
||
- `SendMessage(consultationId, content)`：发送消息 → 广播给聊天室内的其他人
|
||
|
||
**流程**：
|
||
1. 患者发消息 → `SendMessage` → 保存到数据库 → 广播给医生
|
||
2. 医生收到实时通知 → 可以在聊天页面看到新消息
|
||
|
||
---
|
||
|
||
### 6.4 配置文件
|
||
|
||
#### `appsettings.json` — 主配置文件
|
||
|
||
包含：
|
||
- **PostgreSQL 连接字符串**：`Host=localhost;Port=5432;Database=HealthManager;Username=postgres;Password=postgres123`
|
||
- **JWT 配置**：密钥、签发者、受众、过期时间
|
||
- **Redis 连接字符串**
|
||
- **MinIO 连接字符串**
|
||
|
||
#### `appsettings.Development.json` — 开发环境配置
|
||
|
||
覆盖主配置中的某些值，仅在开发环境生效。
|
||
|
||
#### `Properties/launchSettings.json` — 启动配置
|
||
|
||
定义 Visual Studio / `dotnet run` 启动时的行为：
|
||
- 使用 `http://localhost:5000` 地址
|
||
- 环境设为 Development
|
||
- 自动打开 Swagger 页面
|
||
|
||
---
|
||
|
||
## 7. 病人端前端 (frontend-patient)
|
||
|
||
> 移动端 H5 应用，患者用手机浏览器打开。
|
||
|
||
### 7.1 技术选型
|
||
|
||
| 库 | 版本 | 做什么 |
|
||
|----|------|--------|
|
||
| React | 19 | UI 框架 |
|
||
| TypeScript | 6 | 类型安全 |
|
||
| Vite | 8 | 构建工具 |
|
||
| Zustand | 5 | 状态管理 |
|
||
| React Router | 7 | 路由 |
|
||
| ECharts | 6 | 图表 |
|
||
| Framer Motion | 12 | 动画 |
|
||
| dayjs | 2 | 日期处理 |
|
||
|
||
### 7.2 文件结构说明
|
||
|
||
```
|
||
src/
|
||
├── main.tsx ← React 应用入口，把 App 组件挂到页面上
|
||
├── App.tsx ← 根组件，渲染路由
|
||
├── router/ ← 路由配置
|
||
│ ├── index.tsx ← 定义所有 URL 和页面的映射关系
|
||
│ └── AuthGuard.tsx ← 路由守卫：没登录就跳转到登录页
|
||
├── stores/ ← 状态管理
|
||
│ ├── auth.store.ts ← 认证状态：用户信息、令牌、登录/登出
|
||
│ └── notification.store.ts ← 通知状态：通知列表、未读数
|
||
├── services/ ← API 调用
|
||
│ ├── 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/ ← TypeScript 类型定义
|
||
│ ├── 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 ← 日期、数字格式化
|
||
│ ├── storage.ts ← localStorage 封装
|
||
│ ├── validator.ts ← 输入验证（手机号、验证码格式）
|
||
│ └── constants.ts ← 常量（测量类型、导航项、健康贴士、运动推荐等）
|
||
├── hooks/ ← 自定义 Hooks
|
||
│ ├── useAuth.ts ← 获取认证状态的便捷 Hook
|
||
│ └── useCountdown.ts ← 短信验证码倒计时
|
||
├── components/ ← 公共组件
|
||
│ ├── common/ ← 通用 UI 组件
|
||
│ │ ├── Button.tsx ← 按钮（主按钮/次按钮/文字按钮，加载中状态）
|
||
│ │ ├── Card.tsx ← 卡片容器
|
||
│ │ ├── Badge.tsx ← 角标（红点/数字）
|
||
│ │ ├── Input.tsx ← 输入框（带标签和错误提示）
|
||
│ │ ├── Toast.tsx ← 轻提示（成功/失败，自动消失）
|
||
│ │ └── Empty.tsx ← 空状态占位
|
||
│ ├── layout/ ← 布局组件
|
||
│ │ ├── AppLayout.tsx ← 主布局：TabBar + 内容区
|
||
│ │ ├── StackLayout.tsx ← 子页面布局：返回按钮 + 内容区（无 TabBar）
|
||
│ │ ├── TabBar.tsx ← 底部导航栏（首页/健康/服务/我的）
|
||
│ │ └── PageHeader.tsx ← 页面标题栏（带返回按钮）
|
||
│ └── charts/ ← 图表组件
|
||
│ ├── LineChart.tsx ← 折线图（展示趋势）
|
||
│ ├── BarChart.tsx ← 柱状图
|
||
│ └── PieChart.tsx ← 饼图（展示依从率等）
|
||
├── pages/ ← 页面组件
|
||
│ ├── auth/ ← 认证页面
|
||
│ │ ├── LoginPage.tsx ← 登录页
|
||
│ │ └── RegisterPage.tsx ← 注册页
|
||
│ ├── home/ ← 首页
|
||
│ │ ├── HomePage.tsx ← 仪表盘首页
|
||
│ │ └── DeviceBindingPage.tsx ← 设备绑定页
|
||
│ ├── health/ ← 健康模块
|
||
│ │ ├── HealthHubPage.tsx ← 健康中心入口
|
||
│ │ ├── HealthRecordListPage.tsx ← 健康记录列表
|
||
│ │ ├── ManualEntryPage.tsx ← 手动输入健康数据
|
||
│ │ ├── TrendChartPage.tsx ← 趋势图
|
||
│ │ └── HealthCalendarPage.tsx ← 健康日历
|
||
│ ├── medication/ ← 用药模块
|
||
│ │ ├── MedicationListPage.tsx ← 药物列表
|
||
│ │ ├── MedicationEditPage.tsx ← 添加/编辑药物
|
||
│ │ └── MedicationDetailPage.tsx ← 药物详情（含依从率饼图）
|
||
│ ├── services/ ← 服务模块
|
||
│ │ ├── ServicesHubPage.tsx ← 服务中心
|
||
│ │ ├── DoctorListPage.tsx ← 医生列表
|
||
│ │ ├── ChatPage.tsx ← 在线问诊聊天
|
||
│ │ ├── ReportListPage.tsx ← 报告列表
|
||
│ │ ├── ReportUploadPage.tsx ← 上传报告
|
||
│ │ ├── ReportDetailPage.tsx ← 报告详情
|
||
│ │ ├── FollowUpListPage.tsx ← 随访列表
|
||
│ │ └── FollowUpEditPage.tsx ← 添加/编辑随访
|
||
│ ├── exercise-diet/ ← 运动饮食模块
|
||
│ │ └── ExerciseDietPage.tsx ← 运动/饮食记录和推荐
|
||
│ ├── profile/ ← 个人中心
|
||
│ │ ├── ProfilePage.tsx ← 个人资料页
|
||
│ │ ├── SettingsPage.tsx ← 设置页
|
||
│ │ └── staticPages.tsx ← 静态页面（通知设置、隐私政策、关于）
|
||
│ └── notifications/ ← 通知
|
||
│ └── NotificationListPage.tsx ← 通知列表
|
||
└── mock/ ← 假数据（开发用，部分已被真实 API 替代）
|
||
├── index.ts ← Mock 工具（延迟模拟、ID 生成）
|
||
├── users.ts ← 假用户数据
|
||
├── health-records.ts ← 假健康数据
|
||
├── medications.ts ← 假药物数据
|
||
├── devices.ts ← 假设备数据
|
||
├── consultations.ts ← 假咨询数据
|
||
├── followups.ts ← 假随访数据
|
||
├── reports.ts ← 假报告数据
|
||
├── notifications.ts ← 假通知数据
|
||
└── exercise-diet.ts ← 假运动饮食数据
|
||
```
|
||
|
||
### 7.3 关键文件详细说明
|
||
|
||
---
|
||
|
||
#### `services/api-client.ts` — HTTP 请求客户端
|
||
|
||
**干什么的？** 所有前端 API 调用的基础。封装了原生的 `fetch` 函数。
|
||
|
||
**核心逻辑**：
|
||
1. 每次请求自动从 localStorage 读取 JWT 令牌，加到请求头的 `Authorization: Bearer xxx`
|
||
2. 发送 HTTP 请求到 `http://localhost:5000`
|
||
3. 如果服务器返回 401（未认证），自动清除本地缓存（令牌过期，需要重新登录）
|
||
4. 把服务器返回的 JSON 统一包装成 `{ code, data, message }` 格式
|
||
5. 如果服务器返回错误，抛出异常
|
||
|
||
**四个方法**：`get`、`post`、`put`、`del`，对应 HTTP 的 GET、POST、PUT、DELETE。
|
||
|
||
---
|
||
|
||
#### `stores/auth.store.ts` — 认证状态管理
|
||
|
||
**干什么的？** 管理"用户是否登录"这个核心状态。
|
||
|
||
**状态数据**：
|
||
- `user`：当前用户信息（姓名、手机号、角色等）
|
||
- `token`：JWT 访问令牌
|
||
- `isAuthenticated`：是否已登录（根据 token 是否存在判断）
|
||
|
||
**操作方法**：
|
||
- `login(phone, code)`：调登录 API → 保存令牌和用户信息
|
||
- `register(phone, code, name)`：调注册 API → 保存令牌和用户信息
|
||
- `logout()`：清除所有数据，回到登录页
|
||
- `updateProfile(data)`：更新用户资料
|
||
|
||
**持久化**：使用 Zustand 的 `persist` 中间件，数据自动存到 localStorage 的 `hrt_auth` 键。即使刷新页面或关闭浏览器，登录状态也不会丢。
|
||
|
||
---
|
||
|
||
#### `router/index.tsx` — 路由配置
|
||
|
||
**干什么的？** 定义了"哪个 URL 显示哪个页面组件"。
|
||
|
||
**路由分为三类**：
|
||
|
||
1. **公开路由**（不需要登录）：
|
||
- `/login` → 登录页
|
||
- `/register` → 注册页
|
||
|
||
2. **Tab 路由**（需要登录，底部有导航栏）：
|
||
- `/home` → 首页仪表盘
|
||
- `/health` → 健康中心
|
||
- `/services` → 服务中心
|
||
- `/profile` → 个人中心
|
||
|
||
3. **Stack 路由**（需要登录，无底部导航栏，有返回按钮）：
|
||
- `/health/records` → 健康记录列表
|
||
- `/health/records/add` → 手动录入
|
||
- `/health/trends/:type` → 趋势图
|
||
- `/services/consultation` → 医生列表
|
||
- `/services/consultation/chat/:doctorId` → 聊天
|
||
- ... 等等
|
||
|
||
**AuthGuard 组件**：包裹在需要登录的路由外面。如果用户没登录访问这些页面，自动跳转到 `/login`。
|
||
|
||
---
|
||
|
||
#### 各页面说明
|
||
|
||
##### 登录页 `pages/auth/LoginPage.tsx`
|
||
- 输入手机号 + 短信验证码
|
||
- 点击"获取验证码"按钮触发 60 秒倒计时
|
||
- 输入框中自动填充演示账号手机号 `13800138000`
|
||
- 验证码任意输入（演示版不验证）
|
||
- 登录成功后跳到首页
|
||
|
||
##### 首页 `pages/home/HomePage.tsx`
|
||
- **健康概览卡片**：显示最新血压和心率数据
|
||
- **快捷操作按钮**（6个）：录入健康数据、用药打卡、在线问诊、查看报告、运动饮食、我的随访
|
||
- **健康小贴士**：随机展示一条心血管健康建议
|
||
- **通知角标**：右上角铃铛图标，有未读通知时显示红点
|
||
|
||
##### 健康中心 `pages/health/HealthHubPage.tsx`
|
||
- 6 种测量类型的卡片：血压、心率、血糖、血氧、体重、步数
|
||
- 点击任一卡片进入该类别的记录列表
|
||
- 底部链接：健康日历、用药管理、运动饮食
|
||
|
||
##### 手动录入 `pages/health/ManualEntryPage.tsx`
|
||
- 根据测量类型显示不同的输入表单
|
||
- 血压：收缩压 + 舒张压 + 心率，三个输入框
|
||
- 其他类型：单个数值输入框
|
||
- 日期和时间选择器
|
||
|
||
##### 趋势图 `pages/health/TrendChartPage.tsx`
|
||
- 使用 ECharts 折线图
|
||
- 可选择 7天 / 14天 / 30天 / 90天 范围
|
||
- 血压类型同时显示收缩压和舒张压两条线
|
||
- 收缩压有 140 的红色警戒线
|
||
|
||
##### 药物列表 `pages/medication/MedicationListPage.tsx`
|
||
- 分"服用中"和"已结束"两个标签页
|
||
- 每种药显示名称、剂量、服药时间
|
||
- 右下角浮动按钮，点击添加新药
|
||
|
||
##### 药物详情 `pages/medication/MedicationDetailPage.tsx`
|
||
- 药物完整信息：名称、剂量、频率、时间点、开始日期、注意事项
|
||
- 依从率饼图：绿色=已服用，灰色=未服用
|
||
- 近30天服药日历视图
|
||
|
||
##### 医生列表 `pages/services/DoctorListPage.tsx`
|
||
- 按科室筛选（全部/心血管内科/心外科等）
|
||
- 每个医生卡片：头像、姓名、职称、科室、擅长领域、简介
|
||
- 点击进入聊天页面
|
||
|
||
##### 聊天页 `pages/services/ChatPage.tsx`
|
||
- 对话气泡界面
|
||
- 患者消息靠右（绿色气泡），医生消息靠左（白色气泡）
|
||
- 底部输入框 + 发送按钮
|
||
- 新消息自动滚到底部
|
||
|
||
##### 报告列表 `pages/services/ReportListPage.tsx`
|
||
- 分"全部/待审核/已解读"三个标签
|
||
- 每项显示标题、类别、状态、上传时间
|
||
- 点击查看详情
|
||
|
||
##### 报告详情 `pages/services/ReportDetailPage.tsx`
|
||
- 报告基本信息
|
||
- 如果有解读结果，显示风险等级、总结、各检查项目、医生建议
|
||
|
||
##### 个人中心 `pages/profile/ProfilePage.tsx`
|
||
- 用户头像、姓名、手机号
|
||
- 身体数据展示（身高、体重、病史）
|
||
- 菜单列表：用药管理、我的通知、设备绑定、设置、关于
|
||
- 退出登录按钮
|
||
|
||
---
|
||
|
||
### 7.4 状态管理方案
|
||
|
||
病人端有两个 Zustand Store：
|
||
|
||
| Store | 存储键 | 持久化 | 内容 |
|
||
|-------|--------|--------|------|
|
||
| `auth.store` | `hrt_auth` | ✓ localStorage | user, token, isAuthenticated |
|
||
| `notification.store` | — | ✗ 内存 | notifications[], unreadCount, loading |
|
||
|
||
**为什么通知不持久化？** 通知数据变化频繁，每次打开应用重新从服务器获取最新的即可。
|
||
|
||
---
|
||
|
||
## 8. 医生端前端 (frontend-doctor)
|
||
|
||
> PC 端 Web 应用，医生在电脑浏览器中使用。
|
||
|
||
### 8.1 文件结构
|
||
|
||
```
|
||
src/
|
||
├── main.tsx ← 应用入口
|
||
├── App.tsx ← 根组件
|
||
├── router/
|
||
│ ├── index.tsx ← 路由配置（定义 URL 和页面映射）
|
||
│ └── AuthGuard.tsx ← 路由守卫
|
||
├── stores/
|
||
│ └── auth.store.ts ← 认证状态（唯一的状态管理）
|
||
├── services/
|
||
│ └── api-client.ts ← HTTP 客户端（封装 fetch）
|
||
├── types/
|
||
│ └── index.ts ← 所有类型定义
|
||
├── components/
|
||
│ └── layout/
|
||
│ └── DoctorLayout.tsx ← 主布局：侧边栏 + 内容区
|
||
└── pages/
|
||
├── auth/
|
||
│ └── LoginPage.tsx ← 登录页
|
||
├── dashboard/
|
||
│ └── DashboardPage.tsx ← 工作台首页
|
||
├── patients/
|
||
│ ├── PatientListPage.tsx ← 患者列表
|
||
│ └── PatientDetailPage.tsx ← 患者详情
|
||
├── consultations/
|
||
│ ├── ConsultationListPage.tsx ← 咨询列表
|
||
│ └── ChatPage.tsx ← 聊天页
|
||
├── reports/
|
||
│ ├── ReportListPage.tsx ← 报告列表
|
||
│ └── ReportDetailPage.tsx ← 报告解读
|
||
├── followups/
|
||
│ ├── FollowUpListPage.tsx ← 随访列表
|
||
│ └── FollowUpEditPage.tsx ← 创建/编辑随访
|
||
└── settings/
|
||
└── ProfilePage.tsx ← 个人资料设置
|
||
```
|
||
|
||
### 8.2 关键文件详细说明
|
||
|
||
---
|
||
|
||
#### `components/layout/DoctorLayout.tsx` — 主布局
|
||
|
||
**干什么的？** 医生端所有页面的"壳"。左边是固定的侧边栏，右边是页面内容。
|
||
|
||
**侧边栏内容**：
|
||
- **Logo/标题**："健康管理平台"
|
||
- **导航菜单**（5项）：
|
||
- 📊 工作台 → `/dashboard`
|
||
- 👥 患者管理 → `/patients`
|
||
- 💬 在线问诊 → `/consultations`
|
||
- 📋 报告审核 → `/reports`
|
||
- 📅 随访管理 → `/follow-ups`
|
||
- **底部个人信息**：医生名字、科室、职称
|
||
- **退出登录按钮**
|
||
|
||
**技术细节**：左侧侧边栏宽度 220px，深色背景（`#1a1a2e`）。右侧内容区用 React Router 的 `<Outlet />` 渲染子路由页面。使用 `NavLink` 组件高亮当前活跃的菜单项。
|
||
|
||
---
|
||
|
||
#### `stores/auth.store.ts` — 认证状态
|
||
|
||
**和病人端的区别**：
|
||
- 存储键是 `doc_auth`（不是 `hrt_auth`）
|
||
- 登录后**验证角色必须是 `doctor`**，如果患者尝试登录医生端会报错"仅限医生账号登录"
|
||
- 登录成功后额外调一次 `GET /api/auth/me` 获取医生完整资料（科室、职称等）
|
||
|
||
---
|
||
|
||
#### `router/index.tsx` — 路由配置
|
||
|
||
| 路由 | 页面 | 说明 |
|
||
|------|------|------|
|
||
| `/login` | LoginPage | 登录（公开，无需认证） |
|
||
| `/` | → 重定向到 `/dashboard` | — |
|
||
| `/dashboard` | DashboardPage | 工作台首页 |
|
||
| `/patients` | PatientListPage | 患者列表 |
|
||
| `/patients/:id` | PatientDetailPage | 患者详情 + 健康数据 |
|
||
| `/consultations` | ConsultationListPage | 咨询列表 |
|
||
| `/consultations/:id` | ChatPage | 聊天页 |
|
||
| `/reports` | ReportListPage | 报告列表 |
|
||
| `/reports/:id` | ReportDetailPage | 报告详情 + 解读 |
|
||
| `/follow-ups` | FollowUpListPage | 随访列表 |
|
||
| `/follow-ups/:id/edit` | FollowUpEditPage | 新建/编辑随访 |
|
||
| `/profile` | ProfilePage | 个人设置 |
|
||
|
||
所有路由（除 `/login`）都包裹在 `<AuthGuard>` + `<DoctorLayout>` 中，确保必须登录才能访问。
|
||
|
||
---
|
||
|
||
#### 各页面详细说明
|
||
|
||
##### 登录页 `pages/auth/LoginPage.tsx`
|
||
- 自动填充演示医生账号手机号 `13700137000`
|
||
- 输入验证码（任意输入即可，演示版不验证）
|
||
- 成功后跳到工作台
|
||
|
||
##### 工作台 `pages/dashboard/DashboardPage.tsx`
|
||
- 顶部：问候语 + 医生姓名
|
||
- **4 个统计卡片**（一排显示）：
|
||
- 患者总数
|
||
- 活跃咨询数
|
||
- 待审核报告数
|
||
- 今日随访数
|
||
- **快捷操作区域**：查看患者、查看咨询、审核报告、管理随访
|
||
- **今日任务列表**：列出当天的随访安排
|
||
|
||
##### 患者列表 `pages/patients/PatientListPage.tsx`
|
||
- 表格展示：姓名、手机号、性别、病史、支架日期
|
||
- 顶部搜索框，支持按姓名或手机号过滤
|
||
- 点击"查看详情"进入患者详情页
|
||
|
||
##### 患者详情 `pages/patients/PatientDetailPage.tsx`
|
||
- **基本信息区**：姓名、手机号、性别、出生日期、身高体重
|
||
- **病史区**：疾病列表、支架日期、支架类型
|
||
- **健康数据区**：最近30天的血压、心率、血糖等数据卡片，显示最新值和趋势
|
||
|
||
##### 咨询列表 `pages/consultations/ConsultationListPage.tsx`
|
||
- 显示分配给当前医生的所有咨询
|
||
- 每条：患者姓名、咨询主题、状态标签（进行中/已结束）、开始时间
|
||
- 点击进入聊天页
|
||
|
||
##### 聊天页 `pages/consultations/ChatPage.tsx`
|
||
- 和病人端类似的对话界面
|
||
- 医生消息靠右（蓝色气泡），患者消息靠左（白色气泡）
|
||
- 输入框 + 发送按钮，也支持 Enter 键发送
|
||
- 发送后自动滚到底部
|
||
|
||
##### 报告列表 `pages/reports/ReportListPage.tsx`
|
||
- 表格展示：患者姓名、报告标题、类别、状态（待审核/已完成）、上传日期、操作
|
||
- 点击"查看"进入报告详情
|
||
|
||
##### 报告详情 + 解读 `pages/reports/ReportDetailPage.tsx`
|
||
- 上半部分：报告的基本信息（标题、类别、状态、上传时间）
|
||
- 如果有上传的图片链接，显示链接
|
||
- 下半部分：**解读表单**
|
||
- 解读结果文本框
|
||
- 提交后报告状态变为"已完成"
|
||
|
||
##### 随访列表 `pages/followups/FollowUpListPage.tsx`
|
||
- 每条随访显示：标题、患者姓名、计划时间、状态（待随访/已完成/已错过）
|
||
- 右上角"+ 新建随访"按钮
|
||
- 每条旁边有"编辑"按钮
|
||
|
||
##### 新建/编辑随访 `pages/followups/FollowUpEditPage.tsx`
|
||
- 如果路由参数 `:id` 为 `"new"`：创建新随访（POST）
|
||
- 否则：编辑已有随访（PUT），先预填现有数据
|
||
- 表单字段：标题、患者（下拉选择）、计划时间、备注
|
||
- 保存后跳转回随访列表
|
||
|
||
##### 个人设置 `pages/settings/ProfilePage.tsx`
|
||
- 预填当前医生的姓名、手机号（不可修改）、科室、职称、简介
|
||
- 修改后保存，同时更新本地缓存
|
||
|
||
---
|
||
|
||
### 8.3 状态管理
|
||
|
||
医生端只有一个 Zustand Store（`auth.store`），比病人端更简单。因为医生端的核心需求是"管理数据"，不像患者端有通知等高频变化的状态。
|
||
|
||
### 8.4 样式方案
|
||
|
||
医生端使用**内联样式（inline style）**，每个组件直接在 JSX 中写 `style={{...}}`。这样做的好处是：
|
||
- 样式和组件紧密绑定，不会出现样式冲突
|
||
- 不需要额外的 CSS 文件
|
||
- 适合组件数量不多的项目
|
||
|
||
全局基础样式在 `src/index.css` 中定义（CSS 变量、字体、基础布局）。
|
||
|
||
---
|
||
|
||
## 9. 数据库表结构
|
||
|
||
### 9.1 所有表一览
|
||
|
||
| 表名 | 用途 | 主要查询场景 |
|
||
|------|------|-------------|
|
||
| `Users` | 用户（患者+医生+管理员） | 按手机号查、按角色查、按姓名搜索 |
|
||
| `RefreshTokens` | JWT 刷新令牌 | 按令牌字符串查、按用户查 |
|
||
| `Devices` | 智能设备 | 按用户查绑定的设备 |
|
||
| `HealthRecords` | 健康测量数据 | 按用户+类型查、按时间范围查、取最新值 |
|
||
| `DietRecords` | 饮食记录 | 按用户+日期查 |
|
||
| `ExerciseRecords` | 运动记录 | 按用户+日期查 |
|
||
| `Medications` | 药物方案 | 按用户查、按状态查、按医生查 |
|
||
| `MedicationRecords` | 服药记录 | 按药物查、按用户+时间查 |
|
||
| `Consultations` | 咨询会话 | 按患者查、按医生查、按状态查 |
|
||
| `ConsultationMessages` | 咨询消息 | 按咨询查、按发送者查 |
|
||
| `QuickReplyTemplates` | 快捷回复模板 | 按医生查 |
|
||
| `Reports` | 检查报告 | 按患者查、按医生查、按状态查 |
|
||
| `ReportItems` | 报告检查项 | 按报告查 |
|
||
| `FollowUps` | 随访计划 | 按患者查、按医生查、按计划时间查 |
|
||
| `Notifications` | 通知 | 按用户查、按已读/未读查 |
|
||
|
||
### 9.2 重要索引
|
||
|
||
数据库索引就像书的目录，能大幅加速查询。
|
||
|
||
| 表 | 索引 | 加速的查询 |
|
||
|----|------|-----------|
|
||
| `Users` | Phone (唯一索引) | 登录时按手机号查找用户 |
|
||
| `Users` | Role | 列出所有医生/患者 |
|
||
| `HealthRecords` | UserId + Type | 查某人的血压数据 |
|
||
| `HealthRecords` | RecordedAt | 按时间排序/筛选 |
|
||
| `Medications` | UserId | 查某人的药物 |
|
||
| `Medications` | Status | 查活跃的药物 |
|
||
| `MedicationRecords` | UserId + CreatedAt | 查最近的服药记录 |
|
||
| `Consultations` | Status | 查活跃的咨询 |
|
||
| `Consultations` | PatientId, DoctorId | 查某人参与的咨询 |
|
||
| `Reports` | Status | 查待审核的报告 |
|
||
| `FollowUps` | ScheduledAt | 按预约时间排序 |
|
||
| `Notifications` | UserId + IsRead | 查某人的未读通知 |
|
||
| `RefreshTokens` | Token (唯一) | 刷新令牌时查找 |
|
||
|
||
### 9.3 特殊数据类型
|
||
|
||
PostgreSQL 有一些 MySQL 没有的特殊类型，本项目充分利用了它们：
|
||
|
||
| PostgreSQL 类型 | 对应 C# 类型 | 使用场景 |
|
||
|-----------------|-------------|---------|
|
||
| `uuid` | `Guid` | 所有主键 |
|
||
| `jsonb` | `JsonDocument` | HealthRecord.Value（灵活存储不同格式的测量数据） |
|
||
| `text[]` | `List<string>` | MedicalHistory、TimeSlots、Specialty、ImageUrls |
|
||
| `timestamp with time zone` | `DateTime` (UTC) | 所有时间戳字段 |
|
||
| `date` | `DateOnly` | 出生日期、开始日期、记录日期 |
|
||
|
||
---
|
||
|
||
## 10. 常见问题 FAQ
|
||
|
||
### Q1: 为什么所有 ID 都用 Guid 而不是自增数字？
|
||
|
||
- **安全**：自增 ID 会暴露数据量（用户可以猜 ID 访问别人的数据）
|
||
- **分布式友好**：如果将来要多台服务器，Guid 不会冲突
|
||
- **前端可以预生成**：不需要等数据库返回 ID
|
||
|
||
### Q2: 为什么患者和医生放在同一张 Users 表？
|
||
|
||
- 简化设计：登录逻辑完全一样
|
||
- 通过 `Role` 字段区分权限
|
||
- 用"不用的字段留空"的方式处理差异（患者字段对医生为空，反之亦然）
|
||
|
||
### Q3: JWT 令牌过期了怎么办？
|
||
|
||
Access Token 有效期只有 30 分钟。过期后，前端自动用 Refresh Token 去换新的 Access Token。如果 Refresh Token 也过期了（7天后），用户需要重新登录。
|
||
|
||
### Q4: 健康数据的 Value 为什么用 JSON？
|
||
|
||
不同测量类型数据结构不同：
|
||
- 血压：`{systolic: 120, diastolic: 80, pulse: 72}`
|
||
- 心率：`{value: 72}`
|
||
- 步数：`{value: 8500}`
|
||
|
||
如果每种类型建一张表，维护成本高。JSON 列提供灵活性，同时 PostgreSQL 的 jsonb 类型支持索引和查询。
|
||
|
||
### Q5: 前端怎么和后端通信？
|
||
|
||
前端通过 HTTP 请求和后端通信，具体流程：
|
||
1. 前端 `api-client.ts` 封装了 `fetch` 函数
|
||
2. 每次请求自动带上 JWT 令牌（在请求头 `Authorization: Bearer xxx`）
|
||
3. 后端 `[Authorize]` 属性检查令牌是否有效
|
||
4. 如果令牌过期（401），前端自动清除登录状态
|
||
|
||
### Q6: 如何启动整个项目？
|
||
|
||
1. **启动基础设施**：运行 `D:\APP\start-dev.bat`
|
||
- 启动 PostgreSQL、Redis、MinIO
|
||
- 启动后端 API（端口 5000）
|
||
2. **启动病人前端**：`cd frontend-patient && npm run dev`（端口 5173）
|
||
3. **启动医生前端**：`cd frontend-doctor && npm run dev`（端口 5174）
|
||
|
||
### Q7: 数据库在哪里？
|
||
|
||
PostgreSQL 数据文件在 `D:\APP\data\pgdata\`。数据库名 `HealthManager`，用户名 `postgres`，密码 `postgres123`。
|
||
|
||
### Q8: 如果数据库出问题了怎么重置？
|
||
|
||
1. 停止后端
|
||
2. 连接到 PostgreSQL 删除数据库：`DROP DATABASE "HealthManager";`
|
||
3. 重启后端，EF Core 会自动重建数据库和表，DataSeeder 会重新插入演示数据
|
||
|
||
---
|
||
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-05-20
|
||
> 适用项目：HealthManager 健康管理平台
|