AI-Health/docs/backend_architecture_evolution.md

后端架构演进方案

日期：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：

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 抽象，避免过度设计。第一阶段采用：

Endpoint -> Application Service -> AppDbContext

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

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

Application Service -> Repository / UnitOfWork -> AppDbContext

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

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

5. 生产者-消费者管道

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

适合管道的任务：

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

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

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

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

6. 第一阶段落地范围

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

6.1 报告模块目标

从当前：

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

演进为：

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 结构：

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 写入确认机制已完成第一阶段落地：

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。
• 上传、列表、详情、删除、查看原图、分析失败状态保持可用。
• 后端编译通过，前端报告页分析通过。