soft/backend/技术文档-后端.md

HealthManager 后端 — 技术文档

适用对象：小白开发者 / 新加入项目的同学 涵盖：项目总览、整洁架构、Domain/Application/Infrastructure/WebApi 四层、数据库、FAQ

---

目录

1. 项目总览
2. 架构设计：什么是整洁架构
3. Domain 领域层
4. Application 应用层
5. Infrastructure 基础设施层
6. WebApi 接口层
7. 数据库表结构
8. 常见问题 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 兼容的对象存储	存储图片（报告照片、头像等）

1.3 项目文件结构

backend/
├── HealthManager.slnx              ← 解决方案文件
├── src/
│   ├── HealthManager.Domain/       ← 领域层（实体 + 接口）
│   ├── HealthManager.Application/  ← 应用层（服务 + DTO）
│   ├── HealthManager.Infrastructure/← 基础设施层（数据库 + JWT）
│   └── HealthManager.WebApi/       ← Web API 层（控制器 + 启动）
├── start-dev.bat                   ← 一键启动脚本
└── 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 定义的接口

2.2 每一层的职责

层	能做什么	不能做什么
Domain	定义实体、定义接口	不写具体逻辑、不访问数据库
Application	写业务逻辑、定义 DTO	不直接访问 HTTP 请求、不直接操作数据库
Infrastructure	实现接口、操作数据库、生成 JWT	不处理 HTTP 请求
WebApi	接收 HTTP 请求、控制权限、返回响应	不写业务逻辑、不直接操作数据库

---

3. Domain 领域层

这是最核心的一层，定义了"数据长什么样"。就像一个房子的地基。

3.1 接口 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 层不应该知道具体是怎么实现的。所以 Domain 定义接口，Infrastructure 去实现。

3.2 实体类一览

每种实体对应数据库中的一张表。

实体文件	对应表	用途
User.cs	Users	用户（患者+医生），通过 Role 字段区分
RefreshToken.cs	RefreshTokens	JWT 刷新令牌
Device.cs	Devices	智能设备绑定
HealthRecord.cs	HealthRecords	健康测量数据（血压/心率/血糖等），Value 用 JSON 存储
DietRecord.cs	DietRecords	饮食记录
ExerciseRecord.cs	ExerciseRecords	运动记录
Medication.cs	Medications	药物方案
MedicationRecord.cs	MedicationRecords	服药打卡记录
Consultation.cs	Consultations	医患咨询会话
ConsultationMessage.cs	ConsultationMessages	咨询消息
QuickReplyTemplate.cs	QuickReplyTemplates	医生快捷回复模板
Report.cs	Reports	检查报告
ReportItem.cs	ReportItems	报告中的检查项目
FollowUp.cs	FollowUps	随访计划
Notification.cs	Notifications	通知

3.3 关键实体详解

User（用户表）

患者和医生共用一张 Users 表，通过 Role 字段区分：

• 患者独有字段：MedicalHistory, StentDate, StentType, HeightCm, WeightKg
• 医生独有字段：Department, Title, Specialty, Introduction, IsAvailable
• 公共字段：Id, Phone, PasswordHash, Name, Gender, Birthday, CreatedAt
• 软删除：IsDeleted + DeletedAt

HealthRecord（健康记录）

属性	类型	说明
Type	string	blood_pressure, heart_rate, blood_sugar, spo2, weight, steps
Value	JsonDocument	关键设计：不同测量存不同 JSON 格式。血压 {systolic, diastolic, pulse}，心率 {value}
Unit	string	单位：mmHg, bpm, mmol/L, %, kg, 步
Source	string	来源：manual（手动）, device（设备）, doctor（医生）

Medication（药物）

属性	类型	说明
DrugName	string	药物名称
Dosage	string	剂量，如 "100mg"
Frequency	string	频率，如 "每日1次"
TimeSlots	List<string>	服药时间点，如 ["08:00", "20:00"]，存为 PostgreSQL text[]
Status	string	active / completed / stopped

Report（报告）

属性	类型	说明
Category	string	血液检查 / 心电图 / 影像学 / 尿液检查
ImageUrls	List<string>	报告图片地址列表
Status	string	pending（待审核）→ interpreting（解读中）→ completed（已完成）
RiskLevel	string?	normal / attention / abnormal

---

4. Application 应用层

这一层写所有的业务逻辑。

4.1 DTO（数据传输对象）

DTO = Data Transfer Object。用于前后端之间传输数据，而不是直接把数据库实体暴露给前端。

文件	包含的 DTO
DTOs/AuthDtos.cs	LoginRequest, RegisterRequest, SendSmsRequest, AuthResponse, UserProfileResponse, UpdateProfileRequest
DTOs/ConsultationDtos.cs	ConsultationCreateRequest, SendMessageRequest 等
DTOs/FollowUpDtos.cs	FollowUpCreateRequest, FollowUpUpdateRequest, FollowUpResponse
DTOs/HealthDtos.cs	HealthRecordCreateRequest, HealthRecordResponse, HealthStatsResponse
DTOs/MedicationDtos.cs	MedicationCreateRequest, MedicationResponse, AdherenceResponse
DTOs/ReportDtos.cs	ReportUploadRequest, ReportInterpretRequest, ReportResponse

4.2 服务类

每个服务类负责一个业务领域的所有逻辑。通过构造函数注入 AppDbContext。

服务文件	负责领域	核心方法
AuthService.cs	用户认证	GetUserByPhone, SaveRefreshToken, RevokeRefreshToken, HashPassword
HealthService.cs	健康数据	GetRecords, GetLatest, AddRecord, GetStats（含趋势计算）
MedicationService.cs	药物管理	GetUserMedications, Add, MarkTaken, GetAdherenceRate
ConsultationService.cs	在线问诊	GetDoctors, Start, SendMessage, GetMessages
PatientService.cs	患者管理（医生用）	GetPatients（支持搜索分页）, GetPatientDetail
ReportService.cs	报告管理	Upload, GetPatientReports, GetAllReports, Interpret
FollowUpService.cs	随访管理	Add, GetPatientFollowUps, GetDoctorFollowUps, Update
NotificationService.cs	通知	GetUserNotifications, GetUnreadCount, MarkAsRead, Create

关键方法详解

HealthService.GetStatsAsync：计算每种健康类型的统计值

• 查最近 7 天记录算周平均 → 和前面 7 天比较 → 判断趋势（上升 >3%、下降 <3%、稳定）
• 查全部记录算月平均
• 支持的类型：blood_pressure, heart_rate, blood_sugar, spo2, weight, steps

MedicationService.GetAdherenceRateAsync：计算依从率

• 依从率 = 实际服用次数 / 总应有次数 × 100%
• 30 天内按药物 TimeSlots 数量算总应服药次数

MedicationService.MarkTakenAsync：标记已服药

• 先查今天该时间点是否已有记录（幂等，防止重复打卡）
• 有则更新，无则新建

---

5. Infrastructure 基础设施层

这一层和"外部世界"打交道：数据库、JWT 加密等具体技术实现。

5.1 Data/AppDbContext.cs — 数据库上下文

整个项目中最重要的基础设施文件，EF Core 的"总管家"。

做了什么：

1. 定义 15 个 DbSet：每个 DbSet 对应一张数据库表
2. 在 OnModelCreating 中配置：
   • JSON 列：HealthRecord.Value → PostgreSQL jsonb 类型
   • 数组列：List<string> → PostgreSQL text[] 类型
   • 索引：Phone（唯一）、Role、UserId+Type、Status、ScheduledAt 等
   • 外键关系：用户→健康记录、用户→药物、咨询→消息 等

5.2 Data/DataSeeder.cs — 种子数据

在数据库首次创建时自动插入演示数据：

数据	数量	说明
患者	2 个	张明（男，60岁，PCI术后）、李芳（女，53岁，PCI术后）
医生	2 个	王建国（主任医师）、陈雪梅（副主任医师）
健康记录	~93 条	患者1 的 31 天血压+心率+体重数据
药物	4 种	阿司匹林、替格瑞洛、瑞舒伐他汀、美托洛尔
服药记录	~50 条	8 天服药情况，约 90% 依从率
咨询	1 个	张明咨询王建国
消息	4 条	完整医患对话
通知	4 条	用药提醒、复查提醒等

关键技术点：

• 演示密码 demo123，SHA256 哈希存储
• 固定随机种子 new Random(42)，每次数据一致
• 所有时间必须是 UTC：new DateTime(year, month, day, hour, minute, 0, DateTimeKind.Utc)

5.3 Services/JwtProvider.cs — JWT 令牌提供者

实现了 IJwtProvider 接口：

• GenerateAccessToken：HMAC-SHA256 签名，30 分钟过期，包含 userId + name + role
• GenerateRefreshToken：加密随机数生成器产生 64 字节 → Base64 字符串

---

6. WebApi 接口层

6.1 Program.cs — 应用程序入口

整个后端启动的唯一入口。按顺序配置：

1. 注册数据库：EF Core + PostgreSQL，连接字符串从 appsettings.json 读取
2. 注册 JWT 认证：验证规则（密钥、签发者、过期时间）
3. 注册 Swagger：API 文档页面
4. 注册 SignalR：实时通信
5. 注册 CORS：允许前端跨域（开发阶段允许 localhost:5173-5175）
6. 注册业务服务：AuthService、HealthService 等
7. 配置中间件管道：CORS → 认证 → 授权 → 控制器 → SignalR Hub
8. 初始化数据库：EnsureCreatedAsync + SeedAsync

6.2 Hubs/ChatHub.cs — SignalR 实时聊天

• JoinConsultation(consultationId)：加入聊天室
• LeaveConsultation(consultationId)：离开
• SendMessage(consultationId, content)：发送消息 → 广播给聊天室所有人

6.3 API 接口完整列表

认证（AuthController）- api/auth

端点	方法	认证	说明
/send-sms	POST	公开	发送短信验证码（演示版直接返回成功）
/login	POST	公开	手机号+验证码登录 → 返回 JWT 令牌对
/register	POST	公开	注册新患者
/refresh	POST	公开	刷新令牌换新的访问令牌
/me	GET	需登录	获取当前用户完整资料
/me	PUT	需登录	更新个人资料（姓名/性别/身高/体重/病史）

健康数据（HealthController）- api/health-records

端点	方法	认证	说明
/	GET	需登录	查询记录，支持 ?type=&days=。医生可加 ?patientId=
/stats	GET	需登录	所有类型的统计（最新值+周均+月均+趋势）
/latest/{type}	GET	需登录	某类型最新一条
/	POST	需登录	添加健康记录

药物管理（MedicationController）- api/medications

端点	方法	认证	说明
/	GET	需登录	列出所有药物。医生可加 ?patientId=
/	POST	需登录	添加新药物
/{id}	GET	需登录	药物详情
/{id}/records	GET	需登录	服药记录列表
/{id}/take	POST	需登录	标记已服药 { timeSlot: "08:00" }
/{id}/adherence	GET	需登录	依从率百分比

在线问诊（ConsultationController）- api/consultations

端点	方法	认证	说明
/doctors	GET	需登录	可接诊的医生列表
/	GET	需登录	我的咨询列表
/	POST	需登录	发起新咨询
/{id}/messages	GET	需登录	咨询消息列表
/{id}/messages	POST	需登录	发送消息

报告管理（ReportController）- api/reports

端点	方法	认证	权限	说明
/	GET	需登录	—	患者看自己，医生看全部
/pending	GET	需登录	仅医生	待审核报告
/{id}	GET	需登录	—	报告详情
/	POST	需登录	—	上传报告 {title, category, imageUrls}
/{id}/interpret	POST	需登录	仅医生	提交解读 {summary, items, riskLevel, suggestions}

随访管理（FollowUpController）- api/follow-ups

端点	方法	认证	权限	说明
/	GET	需登录	—	患者看自己，医生看分配给自己
/{id}	GET	需登录	—	随访详情
/	POST	需登录	—	创建随访
/{id}	PUT	需登录	仅医生	更新随访

患者管理（PatientController）- api/patients（仅医生）

端点	方法	认证	说明
/	GET	仅医生	患者列表，支持 ?search=&page=&pageSize=
/{id}	GET	仅医生	患者详情

通知（NotificationController）- api/notifications

端点	方法	认证	说明
/	GET	需登录	通知列表
/unread-count	GET	需登录	未读数量
/{id}/read	PUT	需登录	标记已读
/read-all	PUT	需登录	全部已读

6.4 配置文件

文件	内容
appsettings.json	PostgreSQL 连接串、JWT 密钥/签发者、MinIO 连接
appsettings.Development.json	开发环境覆盖配置
Properties/launchSettings.json	启动配置：端口 5000，Development 环境，自动开 Swagger

---

7. 数据库表结构

7.1 所有表一览

表名	用途	主要查询场景
Users	用户（患者+医生+管理员）	按手机号查、按角色查、按姓名搜索
RefreshTokens	JWT 刷新令牌	按令牌字符串查、按用户查
Devices	智能设备	按用户查绑定的设备
HealthRecords	健康测量数据	按用户+类型查、按时间范围查、取最新值
DietRecords	饮食记录	按用户+日期查
ExerciseRecords	运动记录	按用户+日期查
Medications	药物方案	按用户查、按状态查、按医生查
MedicationRecords	服药记录	按药物查、按用户+时间查
Consultations	咨询会话	按患者查、按医生查、按状态查
ConsultationMessages	咨询消息	按咨询查、按发送者查
QuickReplyTemplates	快捷回复模板	按医生查
Reports	检查报告	按患者查、按状态查
ReportItems	报告检查项	按报告查
FollowUps	随访计划	按患者查、按医生查、按计划时间查
Notifications	通知	按用户查、按已读/未读查

7.2 重要索引

表	索引	加速的查询
Users	Phone (唯一)	登录时按手机号查找
Users	Role	列出所有医生/患者
HealthRecords	UserId + Type	查某人的血压数据
HealthRecords	RecordedAt	按时间排序
Medications	UserId, Status	查药物和状态
MedicationRecords	UserId + CreatedAt	查最近服药记录
Consultations	Status, PatientId, DoctorId	查活跃咨询
Reports	Status	查待审核报告
FollowUps	ScheduledAt	按预约时间排序
Notifications	UserId + IsRead	查未读通知

7.3 特殊数据类型

PostgreSQL 类型	对应 C# 类型	使用场景
uuid	Guid	所有主键
jsonb	JsonDocument	HealthRecord.Value
text[]	List<string>	MedicalHistory、TimeSlots、ImageUrls
timestamp with time zone	DateTime (UTC)	所有时间戳
date	DateOnly	出生日期、开始日期

---

8. 常见问题 FAQ

Q1: 为什么所有 ID 都用 Guid 而不是自增数字？

• 安全：自增 ID 会暴露数据量
• 分布式友好：多台服务器不会冲突
• 前端可预生成：不需要等数据库返回 ID

Q2: 为什么患者和医生放在同一张 Users 表？

• 登录逻辑完全一样，简化设计
• 通过 Role 字段区分权限
• 用"不用的字段留空"处理差异

Q3: JWT 令牌过期了怎么办？

Access Token 30 分钟过期 → 前端用 Refresh Token 换新的 Access Token。Refresh Token 7 天后也过期 → 需重新登录。

Q4: 健康数据的 Value 为什么用 JSON？

不同测量类型数据结构不同：血压 {systolic, diastolic, pulse}、心率 {value}。JSON 列提供灵活性，PostgreSQL jsonb 支持索引和查询。

Q5: 如何重置数据库？

-- 连接到 PostgreSQL
DROP DATABASE "HealthManager";

重启后端，EF Core 自动重建表，DataSeeder 自动插入演示数据。

Q6: 数据库连接信息

• 数据库名：HealthManager
• 用户名：postgres
• 密码：postgres123
• 端口：5432
• 数据目录：D:\APP\data\pgdata\

Q7: 为什么 DateTime 必须用 UTC？

PostgreSQL 的 timestamp with time zone 列类型要求传入的时间必须是 DateTimeKind.Utc。如果用 DateTimeKind.Unspecified 或 DateTimeKind.Local，Npgsql 会抛异常。解决办法：DateTime.SpecifyKind(dt, DateTimeKind.Utc)。

---

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