feat: 后端架构重构 — Endpoint→Service→Repository分层 + AI确认机制 + 异步任务持久化
- 核心业务拆分为 Endpoint → Application Service → Repository 三层 - AI写入操作必须用户确认后才写库(确认卡片机制) - 报告/饮食/用药分析改为持久化任务队列(原子领取/重试/重启恢复) - 运动计划修复: 连续真实日期替代周模板 - 用药提醒去重 + 通知Outbox预留 - 认证收拢到AuthService, 管理员收拢到AdminService - AI会话加用户归属校验防串号 - 提示词调整为患者视角 - 开发假数据已关闭 - 21/21测试通过, 0警告0错误
This commit is contained in:
MingNian
@@ -371,7 +371,186 @@ var conversation = await db.Conversations
|
||||
5. 医生端做成真正可用的工作台：患者筛选、风险排序、随访提醒。
|
||||
6. 报告、饮食、用药、运动做长期趋势关联。
|
||||
|
||||
## 11. 总体建议
|
||||
## 11. 第二轮深挖补充
|
||||
|
||||
这一轮额外对已有 `docs/BUG_REVIEW.md`、后端端点、AI Agent handler、SignalR、Flutter provider 生命周期、饮食/蓝牙/问诊页面做了交叉检查。需要注意：旧 bug 文档中有一些问题已经被修复或情况已经变化，本节以当前代码为准。
|
||||
|
||||
### 11.1 已确认仍然存在的高风险问题
|
||||
|
||||
| 优先级 | 位置 | 当前问题 | 风险说明 | 修复方向 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| P0 | `backend/src/Health.WebApi/Endpoints/auth_endpoints.cs` | `/api/auth/send-sms` 仍返回 `devCode` | 任何客户端都能拿到验证码，短信验证等同失效 | 只在 Development 返回；生产环境完全移除 |
|
||||
| P0 | `health_app/lib/pages/auth/login_page.dart` | 前端拿到 `devCode` 后自动填入验证码 | 把后端安全问题固化成产品行为 | 删除自动填充；开发环境可用 debug banner 或日志 |
|
||||
| P0 | `backend/src/Health.WebApi/Endpoints/ai_chat_endpoints.cs` | SSE token 走 query，且 fallback 用 `ReadJwtToken` 解析 | query token 会进日志；`ReadJwtToken` 不验证签名 | SSE 改标准鉴权，或先换一次性 stream ticket |
|
||||
| P0 | `backend/src/Health.WebApi/Endpoints/ai_chat_endpoints.cs` | 创建/续写 AI 会话时 `FindAsync(conversationId)` 未校验 `UserId` | 可能跨用户写入/读取会话 | `FirstOrDefaultAsync(c => c.Id == id && c.UserId == userId)` |
|
||||
| P0 | `backend/src/Health.WebApi/Hubs/ConsultationHub.cs` | SignalR Hub 没有鉴权，入组只靠 `consultationId` | 任意连接可加入任意问诊房间 | `MapHub().RequireAuthorization()`，Join 前校验用户或医生权限 |
|
||||
| P0 | `backend/src/Health.WebApi/Hubs/ConsultationHub.cs` | `SendMessage` 按传入 `senderType` 和 `consultationId` 写库 | 客户端可冒充 Doctor/User，向任意会话发消息 | senderType 从 Claims/角色推导，不信任客户端 |
|
||||
| P0 | `backend/src/Health.WebApi/Endpoints/consultation_endpoints.cs` | 患者发消息只查会话存在，未校验会话属于当前用户 | 用户 A 可向用户 B 的问诊发 HTTP 消息 | 查询加 `c.UserId == userId` |
|
||||
| P0 | `backend/src/Health.WebApi/Endpoints/exercise_endpoints.cs` | `/items/{itemId}/checkin` 只 `FindAsync(itemId)` | 用户可打卡/取消他人的运动计划项 | Include Plan 后校验 `Plan.UserId` |
|
||||
| P0 | `backend/src/Health.Infrastructure/AI/AgentHandlers/exercise_agent_handler.cs` | AI 运动 checkin 只按 itemId 操作 | 通过 AI 工具也可越权打卡 | 查询 item 时联表校验当前 userId |
|
||||
| P0 | `backend/src/Health.Infrastructure/AI/AgentHandlers/medication_agent_handler.cs` | AI 用药 confirm 直接写 `MedicationLog`，不验证药品归属 | 可给他人药品写入服药记录 | 先查 `Medication.Id == medId && UserId == userId` |
|
||||
| P1 | `backend/src/Health.WebApi/Endpoints/medication_endpoints.cs` | `/medications/{id}/confirm` 查 existing log 未限制 `UserId`，也未先确认药品归属 | 可能误删/写入不属于当前用户药品的日志 | 先查药品归属，再按 `MedicationId + UserId` 查日志 |
|
||||
| P1 | `backend/src/Health.WebApi/Endpoints/doctor_endpoints.cs` | 医生端已鉴权，但患者详情/报告/随访操作多处只按 id 查询 | 医生可能访问或修改非自己负责患者的数据 | 所有医生端资源都按医生关联患者过滤 |
|
||||
| P1 | `backend/src/Health.WebApi/Endpoints/file_endpoints.cs` | 上传缺少大小、类型、内容校验，且返回结构与前端不匹配 | 恶意文件/超大文件风险，前端图片上传链路失败 | 加限制、白名单、URL 返回和访问控制 |
|
||||
| P1 | `health_app/lib/pages/diet/diet_capture_page.dart` | `_fieldCtrls` 缓存 controller，但页面没有 dispose | 多次进入饮食分析页会泄漏 TextEditingController | 在 State `dispose()` 中遍历释放 |
|
||||
| P1 | `health_app/lib/providers/consultation_provider.dart` | Hub/轮询 stop 需要手动调用，provider 自身没有自动释放 | 离开页面后可能继续 SignalR 或 5 秒轮询 | Notifier build 中注册 `ref.onDispose(stop)` |
|
||||
| P1 | `health_app/lib/providers/chat_provider.dart` | SSE `_subscription` 和 timer 没看到 provider dispose 释放 | 聊天流中断/页面销毁后可能残留监听 | 注册 `ref.onDispose`，切换会话时取消旧流 |
|
||||
| P1 | `backend/src/Health.WebApi/Program.cs` | `MapHub("/hubs/consultation")` 未 RequireAuthorization | 即使 API 鉴权，实时通道仍裸露 | Hub 映射处加鉴权并处理 token 传递 |
|
||||
|
||||
### 11.2 旧问题中已经变化或需要修正的判断
|
||||
|
||||
这些点在旧 `BUG_REVIEW.md` 里出现过，但当前代码已经不是原始状态，后续不要按旧结论机械修：
|
||||
|
||||
- `doctor_endpoints.cs` 不是“零授权”了：当前已有 `.RequireAuthorization()` 和医生角色过滤。真正问题是医生端数据授权粒度不够，部分详情/报告/随访接口没有限制到当前医生负责的患者。
|
||||
- `open_ai_compatible_client.cs` 的 Vision content 当前已经是 `Content = contentParts`，不是把多模态数组序列化成字符串。旧的 VLM 序列化 bug 看起来已修复。
|
||||
- `diet_agent_handler.cs` 和 `consultation_agent_handler.cs` 当前没有声明未实现工具，而是主动缩减为档案/记录查询。问题应描述为“AI Agent 能力和首页胶囊/欢迎卡片承诺不一致”，不是“声明工具但未实现”。
|
||||
- `cleanup_service.cs` 当前已经先删 ConversationMessages 再删 Conversations，旧的 FK 删除顺序问题已修。
|
||||
- `device_scan_page.dart` 当前 `dispose()` 已取消 scan/read/connection 订阅，不能继续作为确定泄漏 bug。仍建议检查 `OmronBleService` 的全局 provider 生命周期和断线重连边界。
|
||||
- `widget_test.dart` 中 `primary == primaryLight` 的错误断言已经改掉，目前测试更大的问题是覆盖面太浅。
|
||||
|
||||
### 11.3 后端授权边界需要系统性重查
|
||||
|
||||
项目里很多接口已经 `.RequireAuthorization()`，但“已登录”不等于“有权操作这个资源”。建议建立统一规则：
|
||||
|
||||
| 资源 | 当前风险 | 应该怎么查 |
|
||||
| --- | --- | --- |
|
||||
| AI Conversation | 续写时未绑定 `UserId` | `Conversation.Id == id && Conversation.UserId == currentUserId` |
|
||||
| Consultation HTTP | POST message 未绑定 `UserId` | `Consultation.Id == id && Consultation.UserId == currentUserId` |
|
||||
| Consultation Hub | 入组/发消息无服务端权限判断 | Join 和 SendMessage 都查用户或医生是否有权进入该 consultation |
|
||||
| ExercisePlanItem | checkin 只按 itemId | `ExercisePlanItem.Id == itemId && Item.Plan.UserId == currentUserId` |
|
||||
| Medication confirm | 部分确认接口未先校验药品归属 | `Medication.Id == id && Medication.UserId == currentUserId` |
|
||||
| Doctor patient detail | 医生按任意 patient id 查详情 | `User.Id == patientId && User.DoctorId == currentDoctorId` |
|
||||
| Doctor report review | 医生按任意 report id 审阅 | `Report.User.DoctorId == currentDoctorId` |
|
||||
| Doctor follow-up update/delete | 医生按任意 followUp id 操作 | `FollowUp.User.DoctorId == currentDoctorId` 或 `DoctorName/DoctorId` 绑定 |
|
||||
|
||||
建议在后端加一层可复用 helper，例如：
|
||||
|
||||
```csharp
|
||||
static IQueryable<User> ScopePatientsToDoctor(AppDbContext db, Guid doctorId) =>
|
||||
db.Users.Where(u => u.Role == "User" && u.DoctorId == doctorId);
|
||||
```
|
||||
|
||||
所有医生端接口都从这个 scope 派生，不要每个 endpoint 手写判断。
|
||||
|
||||
### 11.4 API 语义和错误码问题
|
||||
|
||||
现在不少接口用 HTTP 200 包业务错误码，比如 401/403/404/400 都包成 `{ code, message }`。这种风格可以保留，但要注意两个问题：
|
||||
|
||||
- 对认证授权失败，HTTP 状态码最好仍返回 401/403，方便客户端、网关、日志系统识别。
|
||||
- 业务错误码需要统一枚举，否则前端只能靠字符串判断。
|
||||
|
||||
建议定义统一错误码：
|
||||
|
||||
- `0` 成功
|
||||
- `40001` 参数错误
|
||||
- `40002` 登录过期
|
||||
- `40003` 无权限
|
||||
- `40004` 资源不存在
|
||||
- `40005` 业务状态冲突
|
||||
- `50000` 服务端异常
|
||||
|
||||
并让 `ExceptionMiddleware` 只处理意外异常，业务错误由 endpoint 明确返回。
|
||||
|
||||
### 11.5 数据模型和索引补充
|
||||
|
||||
当前 `AppDbContext` 已经配置了不少索引和枚举转换，比旧报告里“完全没有 FK/索引”的描述更好。但仍建议补：
|
||||
|
||||
- `RefreshToken(Token)` 唯一或普通索引：刷新 token 查询会频繁发生。
|
||||
- `RefreshToken(UserId, IsRevoked, ExpiresAt)`：便于清理和会话管理。
|
||||
- `Report(UserId, CreatedAt)`：报告列表按用户和时间查询。
|
||||
- `FollowUp(UserId, ScheduledAt)`：随访日历、医生待办会用到。
|
||||
- `DeviceToken(UserId)`：推送服务上线后需要。
|
||||
- `Consultation(UserId, CreatedAt)` 和 `Consultation(Status, CreatedAt)`：患者历史和医生待办都会用到。
|
||||
|
||||
另外，核心关系建议显式配置删除行为，尤其是 User 删除时关联 Consultation、Report、Conversation、MedicationLog 的级联或手动删除策略。
|
||||
|
||||
### 11.6 AI Agent 产品能力不一致
|
||||
|
||||
现在首页上有多个 agent/胶囊入口，但后端能力不完全一致：
|
||||
|
||||
- 饮食 Agent 当前只保留健康档案查询，真正饮食识别在专门图片接口。
|
||||
- 问诊 Agent 当前只保留健康记录和档案查询，转医生走专门问诊流程。
|
||||
- 用药/运动 Agent 有创建、查询、确认能力，但确认工具存在所有权校验问题。
|
||||
- 通用 Agent 如果聚合多个工具，需要明确“哪些动作会写数据，哪些只是查询”。
|
||||
|
||||
建议 UI 文案和后端能力统一：
|
||||
|
||||
- 欢迎卡片不要暗示当前 agent 能完成它实际上做不到的写操作。
|
||||
- 会写入健康数据、药品、运动计划、档案的 AI 动作，必须有确认卡片。
|
||||
- AI 工具调用结果应返回结构化状态，前端不要只靠自然语言判断成功。
|
||||
|
||||
### 11.7 前端状态和生命周期问题
|
||||
|
||||
前端现在能跑起来，但长期运行会有状态残留风险：
|
||||
|
||||
- `ConsultationChatNotifier` 里 Hub 和轮询 timer 需要自动释放。建议 `build()` 中调用 `ref.onDispose(stop)`。
|
||||
- `ChatNotifier` 的 SSE 订阅、流式响应 timer 需要在 provider 销毁、切换 agent、重新发送时取消。
|
||||
- 饮食页 `_fieldCtrls` 需要 `dispose()`，否则每次识别食物后 controller 累积。
|
||||
- 多个 `FutureProvider` 没有 `autoDispose`，页面级数据会缓存很久。健康最新值、药品提醒、当前运动计划这类数据建议明确刷新策略。
|
||||
- 很多页面删除后只本地 `_load()`，没有 `ref.invalidate(...)`，跨页面缓存可能不同步。
|
||||
|
||||
### 11.8 UI 深层问题：不是再加渐变，而是建立层级
|
||||
|
||||
最近 UI 调整集中在侧边栏、欢迎卡片、饮食页、设置页、个人信息页等。颜色已经比最初丰富，但仍需要注意：
|
||||
|
||||
- 颜色角色要固定：蓝色用于主行动/健康状态，橙色用于饮食，紫色用于报告，绿色用于记录/恢复，青色用于设备或运动，浅红用于提醒/风险。
|
||||
- 欢迎卡片和胶囊按钮的图标必须同语义、同线宽、同背景形状。用户已经多次指出“不只是颜色一样，图标内容也要一样”，这说明视觉一致性比单个渐变更重要。
|
||||
- 健康仪表盘应优先展示数字、单位、状态、更新时间。图标可以弱化，避免抢数字层级。
|
||||
- 设置页不应只是按钮列表，应分为账号、安全、通知、设备、隐私、关于。
|
||||
- 个人信息页应像正式档案：基础信息、医疗信息、健康偏好、绑定医生、账号安全分区展示。
|
||||
- 功能入口两行三列是合理的，但每个入口不要堆摘要，图标 + 名称 + 必要状态即可。
|
||||
|
||||
### 11.9 功能缺口再细化
|
||||
|
||||
| 模块 | 当前缺口 | 建议 |
|
||||
| --- | --- | --- |
|
||||
| 饮食记录 | 已有识别和保存，但历史记录编辑能力弱 | 支持编辑食物、份量、热量、餐次；支持从历史复制 |
|
||||
| 报告管理 | 上传后异步 AI 分析，但失败/处理中状态不够细 | 增加 pending/analyzing/failed/retry 状态和轮询刷新 |
|
||||
| 问诊 | 患者端创建即新会话，历史问诊入口弱 | 增加问诊历史、继续问诊、关闭问诊、评价医生 |
|
||||
| 用药 | 提醒后台只记录日志，未实际推送 | 接入推送，支持漏服/补服/跳过原因 |
|
||||
| 运动 | 有计划和打卡，但计划解释和详情不足 | 计划详情页、运动禁忌、完成趋势 |
|
||||
| 健康日历 | 汇总用药/运动/随访，但和打卡状态联动有限 | 日历上直接展示已完成、未完成、逾期 |
|
||||
| 医生端 | 已有工作台，但患者范围和流程需加强 | 风险患者排序、未读消息、待审报告、随访待办 |
|
||||
| 管理员端 | 医生管理已有基础 | 增加操作审计、禁用账号、数据统计 |
|
||||
|
||||
### 11.10 更细的整改顺序
|
||||
|
||||
第一批必须先修安全：
|
||||
|
||||
1. 移除生产 `devCode` 和前端自动填充。
|
||||
2. 修 SSE 认证，不再解析未验证 JWT。
|
||||
3. AI conversation 按用户归属查询。
|
||||
4. Consultation Hub 加鉴权、入组校验、senderType 服务端判定。
|
||||
5. Consultation HTTP 发消息校验当前用户。
|
||||
6. Exercise/Medication 的普通接口和 AI 工具都补所有权校验。
|
||||
7. 医生端详情、报告、随访接口限制到当前医生负责患者。
|
||||
|
||||
第二批修接口契约和稳定性：
|
||||
|
||||
1. 文件上传返回 `{ id, name, size, url, contentType }`。
|
||||
2. 前端 `uploadFile` 兼容后端 envelope 和 list 返回，失败要提示。
|
||||
3. 饮食页 controller dispose。
|
||||
4. Chat/Consultation provider 注册 `ref.onDispose`。
|
||||
5. 后端补上传大小/类型限制。
|
||||
6. 关闭生产 body 日志。
|
||||
|
||||
第三批做 UI 体系：
|
||||
|
||||
1. 把颜色、渐变、圆角、阴影、图标背景抽成设计 token。
|
||||
2. 侧边栏、个人信息、设置、饮食分析页按同一设计语言重做。
|
||||
3. 首页欢迎卡片和胶囊入口统一图标语义。
|
||||
4. 健康仪表盘增加更新时间、单位、状态文字。
|
||||
5. 对中老年用户做字号、对比度、触控面积检查。
|
||||
|
||||
第四批补测试：
|
||||
|
||||
1. 后端加越权测试：用户 A 不能操作用户 B 的 conversation/consultation/exercise/medication。
|
||||
2. 加短信验证码生产环境不返回测试。
|
||||
3. 加 SignalR Hub 入组权限测试。
|
||||
4. 加文件上传类型/大小测试。
|
||||
5. Flutter 加饮食保存、问诊连接释放、上传失败 UI 的 widget/provider 测试。
|
||||
|
||||
## 12. 总体建议
|
||||
|
||||
这个项目最有价值的方向是“围绕患者长期健康数据做 AI 辅助管理”，不是简单堆功能入口。接下来建议把项目重心从“页面多”转为“核心闭环扎实”：
|
||||
|
||||
@@ -383,4 +562,3 @@ var conversation = await db.Conversations
|
||||
- 安全和隐私经得起真实使用。
|
||||
|
||||
UI 上不要继续单页单独调色，应该先统一设计体系，再逐步替换页面。工程上先修安全和接口契约，再做大面积美化。这样项目会从“原型功能很多”变成“真正像一个可信赖的健康产品”。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user