soft/技术文档.md

HealthManager 健康管理平台 — 超级详细技术文档

适用对象：小白开发者 / 新加入项目的同学 文档目标：看懂每一个文件是干什么的，代码在做什么，为什么要这样写

---

目录

1. 项目总览
2. 架构设计：什么是"整洁架构"
3. 后端 — Domain 领域层
4. 后端 — Application 应用层
5. 后端 — Infrastructure 基础设施层
6. 后端 — WebApi 接口层
7. 病人端前端 (frontend-patient)
8. 医生端前端 (frontend-doctor)
9. 数据库表结构
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

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 对应一张数据库表

   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 健康管理平台