# 后端架构演进方案

日期：2026-06-18

## 1. 背景

当前项目已经具备 `Health.Domain`、`Health.Application`、`Health.Infrastructure`、`Health.WebApi` 的分层目录，但实际业务逻辑主要仍写在 `Health.WebApi/Endpoints` 中。多数接口直接注入 `AppDbContext`，在 Endpoint 内完成查询、权限判断、状态流转和 `SaveChanges`。

这种方式适合早期快速验证，但随着患者端健康管理、AI 分析、报告、饮食、用药、运动、医生端等业务增长，会带来几个问题：

- 业务规则分散在 Endpoint、AI Agent Handler、后台服务中。
- 同一个业务动作可能被普通接口和 AI 工具重复实现。
- 权限和资源归属校验容易遗漏。
- 异步任务目前存在 `Task.Run` 形式，不便于限流、重试和统一管理。
- Application 层没有真正承接业务用例，后续测试和维护成本会升高。

技术目标是按 DDD 思路逐步演进：让 Endpoint 成为接口适配层，业务流程进入 Application Service，外部能力和数据访问由 Infrastructure 支撑，耗时任务通过生产者-消费者管道处理。

## 2. 当前业务边界

### 2.1 当前核心患者端闭环

以下业务都需要继续做扎实：

1. AI 健康管家聊天
2. 健康指标记录与趋势：血压、心率、血糖、血氧、体重
3. 报告上传与 AI 预解读
4. 饮食拍照分析与保存
5. 用药管理与打卡
6. 运动计划

### 2.2 医生端当前策略

医生端可以做代码整理和权限边界收拢，但不作为当前核心业务闭环：

- 医患实时聊天：暂时搁置，后续接入互联网医院后再完善。
- 医生审核报告：暂时不是当前真实流程，患者端报告以 AI 预解读为主；界面可显示“医生审核中/待审核”一类状态。
- 医生工作台：保留现有页面和基础接口，不主动扩大功能范围，重构时以不影响当前项目运行为目标。

### 2.3 AI 写入规则

统一业务规则：

- AI 纯查询、解释、建议可以直接回复。
- AI 只要要写入用户健康相关数据，必须先让用户确认。
- 需要确认的写入包括但不限于：健康指标、用药计划、运动计划、健康档案修改。
- 饮食记录当前在饮食分析结果页由用户主动保存，保留该方式。

## 3. 目标架构

目标不是创建一个巨大的全能 Service，而是按业务模块拆分 Application Service：

```text
Health.WebApi
  Endpoints
  Hubs
  BackgroundServices

Health.Application
  Auth
  Users
  HealthRecords
  Medications
  Diet
  Reports
  Exercise
  Consultations
  Doctors
  Ai
  Common

Health.Domain
  Entities
  Enums
  DomainRules

Health.Infrastructure
  Data
  AI
  Services
  Storage
```

职责边界：

- `WebApi`：接收 HTTP/SignalR 请求，解析参数，返回响应。
- `Application`：承接业务用例、状态流转、权限校验、任务入队。
- `Domain`：保存核心实体、枚举和稳定业务规则。
- `Infrastructure`：EF Core、AI 客户端、短信、文件存储、推送、未来互联网医院适配。

## 4. 数据库读写收拢方式

短期先不强制引入 Repository 抽象，避免过度设计。第一阶段采用：

```text
Endpoint -> Application Service -> AppDbContext
```

也就是说，数据库读写先统一进入对应业务 Service，而不是继续散落在 Endpoint 中。

后续如果业务复杂度继续提升，再考虑：

```text
Application Service -> Repository / UnitOfWork -> AppDbContext
```

第一阶段优先收拢这些模块：

1. `ReportService`
2. `DietService`
3. `MedicationService`
4. `ExerciseService`
5. `HealthRecordService`
6. `ConsultationService`

## 5. 生产者-消费者管道

不是所有业务都需要管道。同步、快速、必须立即返回的操作仍走普通 Service。

适合管道的任务：

- 报告 AI 分析
- 饮食图片识别
- 处方图片识别
- 用药提醒推送
- 健康周报生成
- 后期互联网医院数据同步

当前阶段采用 .NET 内置 `Channel<T>` + `BackgroundService`：

```text
业务 Service = 生产者
Channel<TJob> = 内存任务队列
BackgroundService = 消费者
AI/推送/外部服务 = 实际执行器
```

单服务器和当前用户规模下，内存队列足够作为第一阶段方案。后续如果出现多实例部署、任务不能丢、重试次数和死信队列等要求，再迁移到 Redis Stream、RabbitMQ 或 Hangfire。

## 6. 第一阶段落地范围

先从报告模块落地，因为它同时具备上传、AI、异步、状态流转、失败重试等典型场景。

### 6.1 报告模块目标

从当前：

```text
ReportEndpoints -> AppDbContext + Task.Run + AI 调用
```

演进为：

```text
ReportEndpoints
  -> ReportService
      -> 保存文件
      -> 创建报告
      -> 标记状态
      -> 入队 ReportAnalysisJob

ReportAnalysisWorker
  -> 消费 ReportAnalysisQueue
  -> 调用 ReportAnalysisService / AI Analyzer
  -> 更新报告状态
```

### 6.2 报告模块要保持的业务行为

- 上传只支持报告图片。
- 上传成功后状态为 `Analyzing`。
- AI 成功后进入 `PendingDoctor`，患者端展示 AI 预解读。
- AI 失败后进入 `AnalysisFailed`，不生成假摘要、假指标。
- 患者端可以查看原始报告图片。
- 医生审核不是当前核心闭环，状态可保留但不扩大功能。

## 7. 当前已落地进展

截至 2026-06-18，第一轮服务化已经完成以下模块：

1. `ReportService`：报告上传、图片校验、报告创建、重新分析、删除、AI 分析状态流转进入服务层；报告分析通过 `ReportAnalysisQueue` + `ReportAnalysisWorker` 异步消费。
2. `HealthRecordService`：健康指标列表、创建、更新、删除、最新值、趋势查询、异常判断进入服务层；AI 记数据工具复用同一套创建逻辑。
3. `ExerciseService`：运动计划创建、列表、详情、删除、打卡、AI 创建/查询/打卡进入服务层。
4. `MedicationService`：用药列表、创建、更新、删除、今日服药确认、按剂量打卡、提醒查询、AI 创建/查询/确认进入服务层。
5. `DietService`：饮食记录列表、保存、删除、热量/评分更新进入服务层。

其中以下模块已经继续演进为更严格的 Application Service + Repository 结构：

```text
Endpoint
  -> Health.Application.*Service
      -> Health.Application.I*Repository
          -> Health.Infrastructure.Ef*Repository
              -> AppDbContext
```

已完成：

1. `HealthRecordService` + `IHealthRecordRepository` + `EfHealthRecordRepository`
2. `ExerciseService` + `IExerciseRepository` + `EfExerciseRepository`
3. `DietService` + `IDietRepository` + `EfDietRepository`
4. `MedicationService` + `IMedicationRepository` + `EfMedicationRepository`
5. `ReportService` + `IReportRepository` + `EfReportRepository` + `IReportFileStorage` + `LocalReportFileStorage`

报告模块中，`ReportAnalysisQueue` 和 `ReportAnalysisService` 仍属于 Infrastructure：前者是内存队列适配，后者需要调用 AI 客户端并通过 `IReportRepository` 更新报告状态，不再直接依赖 `AppDbContext`。

AI 写入确认机制已完成第一阶段落地：

```text
AI 写入工具调用
  -> 创建 10 分钟有效的 PendingAiWriteCommand
  -> 前端展示确认卡片，此时不写数据库
  -> 用户点击确认
  -> POST /api/ai/confirm-write/{commandId}
  -> 校验当前用户和一次性命令
  -> 执行对应 Application Service 写入
```

- 健康指标、创建/确认用药、创建/打卡运动、AI 修改健康档案均进入待确认流程。
- 纯查询工具继续直接执行。
- 命令只能由所属用户执行一次；执行失败时会恢复命令供用户重试，过期或服务重启后自动失效。
- AI 待确认命令已迁移到数据库表 `AiWriteCommands`，领取命令、业务写入和完成状态在同一事务内执行，避免重复写入。
- 报告分析任务已迁移到数据库表 `ReportAnalysisTasks`，支持服务重启恢复、原子领取、失败重试和最终失败状态。
- 项目当前仍使用 `EnsureCreated` 管理原有表；新增 `DatabaseSchemaMigrator` 和 `__AppSchemaMigrations` 版本表，为已有本地数据库安全补充基础设施表。

患者端其他业务收拢进展：

1. `HealthArchiveService` + `IHealthArchiveRepository`：健康档案页面、AI 查询和确认写入统一执行。
2. `AiConversationService` + `IAiConversationRepository`：会话创建、消息保存、历史列表和删除统一执行。
3. `PatientContextService`：统一组合健康档案、近期指标和当前用药。
4. `UserService` + `IUserRepository`：个人资料和账号注销统一执行；账号数据清理使用事务。
5. `CalendarService` + `ICalendarRepository`：聚合用药、运动、随访日历。

生产者/消费者管道现状：

- 报告分析：数据库持久化任务 + `ReportAnalysisWorker`。
- 饮食图片识别：任务持久化到 `DietImageAnalysisTasks`，由 `DietImageAnalysisWorker` 原子领取、失败重试和恢复处理中断任务；前端接口协议保持不变。
- 用药提醒：`MedicationReminderService` 负责扫描生产任务，任务持久化到 `MedicationReminderTasks` 并按药品/日期/时间唯一去重；`MedicationReminderWorker` 消费后写入 `NotificationOutbox`。真正的手机推送需在选定推送服务后消费 Outbox，目前不会把未发送通知标记为已推送。
- 报告、饮食和用药任务消费者均采用 1 到 5 秒的自适应空闲轮询，过期 Processing 任务每分钟恢复一次，避免每秒重复执行恢复更新。
- App 内用药提醒通过 `NotificationOutbox` + `/api/notifications/pending` 提供，患者端前台每 30 秒获取并展示，展示后回执去重；暂不接入系统级或厂商推送。
- `MaintenanceService` 每小时执行一次维护，自动删除超过 30 天的已完成/失败后台任务、通知 Outbox、过期 AI 写入命令和旧 AI 会话，不删除用户健康记录、饮食记录或用药计划。
- 登录、注册、验证码、Token 刷新和退出已收拢到 `IAuthService`；管理员医生管理和患者列表已收拢到 `IAdminService`，Endpoint 不再直接读写数据库。开发环境 `send-sms` 仍返回 `devCode` 供 Flutter 自动填入，非开发环境不返回验证码。
- AI 工具查询、确认写入和事务边界已收拢到 `IAiToolExecutionService`，AI Endpoint 不再直接持有 `AppDbContext`。
- 运动计划已从 `WeekStartDate + DayOfWeek` 周模板改为 `StartDate + EndDate + ReminderTime`，每日条目使用唯一的 `ScheduledDate`。连续 7 天、10 天或更长计划按真实日期生成，首页今日任务、健康日历、医生端只读详情和 AI 创建均使用同一日期模型。
- App 内运动提醒按每日条目的 `ScheduledDate` 和计划 `ReminderTime` 生成到 `NotificationOutbox`；已打卡和休息日不会提醒，同一每日条目只生成一次。

当前仍保留在 Endpoint 或旧 Handler 中的业务，需要后续逐步收拢：

- `ConsultationService`：医生聊天暂不作为当前核心业务，但基础权限和数据读写仍可继续服务化。
- `DoctorService` / `AdminDoctorService`：医生信息、患者列表、报告查看等目前不作为真实互联网医院流程，后续按老板和互联网医院接入方案调整。
- `CalendarService`：健康日历目前聚合运动、用药、饮食等多模块数据，适合在核心模块稳定后单独收拢。
- `User/ProfileService`：个人信息、健康档案、账号清理等可继续整理，尤其是 AI 修改健康档案前的确认规则。

## 8. 后续推广顺序

1. 报告：Application Service + 分析队列 + Worker
2. 饮食：图片识别任务队列，用户修正后保存
3. 用药：提醒扫描和推送任务解耦
4. 运动：计划创建、打卡规则收拢到 Service
5. 健康指标：记录、异常判断、趋势查询收拢到 Service
6. 问诊：互联网医院接入前只收拢基础接口，不扩大聊天功能
7. 医生端：保留基础接口，后续根据互联网医院和老板决策再完善审核/聊天工作流

## 9. 不做的事

当前阶段暂不做：

- 不一次性重构全项目。
- 不立即引入 RabbitMQ/Kafka 等重型组件。
- 不强制引入复杂 Repository 层。
- 不改变当前患者端主要交互。
- 不把医生聊天/医生审核作为当前核心业务流。

## 10. 验收标准

第一阶段完成后应满足：

- 报告 Endpoint 不再直接承载主要业务流程。
- 报告 AI 分析不再使用 `Task.Run`。
- 报告分析任务通过队列进入后台 Worker。
- 报告状态流转集中在 Application Service。
- 上传、列表、详情、删除、查看原图、分析失败状态保持可用。
- 后端编译通过，前端报告页分析通过。