核心数据流

数据流以 Flutter API client 发起请求，FastAPI router 做鉴权和参数校验，use case 或 service 编排业务，repository 负责表读写。Chat 和处方链路会额外进入 RAG / LLM，但用户业务数据仍通过 PostgreSQL 持久化。

总流向

移动端页面Flutter App

请求与接口API clients / routers

业务编排use cases / services

↴

业务持久化repositories / RDS

AI 知识链路RAG / LLM / knowledge_chunks

用户档案数据流

Step	Component	DB touchpoints	说明
登录/注册	auth.py、AuthService、UserRepository	users、sms_verifications、login_logs	手机号、验证码、密码哈希和登录审计。
更新基础资料	user.py、UserService.update_basic_info	users、update_logs	更新姓名、性别、出生日期、头像等字段，并写变更日志。
更新健康指标	UserService.update_health_metrics	user_profiles、update_logs	更新身高、体重、血压、肿瘤类型、治疗阶段、诊断日期等字段。
疾病/手术史	DiseaseRepository、OperationRepository	user_diseases、user_operations、update_logs	新增、更新、软删除用户病史和手术史。
完整档案读取	UserService.get_complete_profile	users、user_profiles、user_diseases、user_operations	为 profile 页面、Chat/RAG 上下文和处方生成提供基础用户画像。

Assessment / Safety 数据流

评估提交/api/assessment/*

规则处理assessment / safety engine

评估快照user_health_profiles

↴

档案上下文user_profiles

安全事件safety_incidents

关联对话dialogue_logs

Flow	DB touchpoints	说明
安全筛查	user_health_profiles.safety_check_data、risk_level	保存筛查 payload、风险等级和有效期相关结果。
完整评估	user_health_profiles.assessment_data、user_profiles.assessment_context	保存 canonical assessment payload，并供 Chat/RAG 与处方链路读取。
安全事件	safety_incidents、可关联 dialogue_logs	记录高风险内容、事件类型、处理动作和解决状态。

Chat / RAG 数据流

flowchart LR
  Chat["消息入口\nPOST /api/chat/message"]
  Safety["安全前置\nSafetyFilter"]
  Context["上下文准备\nsession / history / profile"]
  RAG["知识生成\nRAG runtime / LLM"]
  Store["结果持久化\nchat_sessions / dialogue_logs"]
  Knowledge["知识检索\nknowledge_chunks"]

  Chat --> Safety
  Safety --> Context
  Context --> RAG
  RAG --> Knowledge
  RAG --> Store

Step	DB touchpoints	说明
会话准备	chat_sessions	无 session 时创建新会话；已有 session 时验证用户归属并更新时间。
历史注入	dialogue_logs	读取当前 session 最近消息，格式化后注入 RAG/LLM。
用户上下文	users、user_profiles、user_diseases	提供年龄、性别、治疗阶段、肿瘤类型、疾病史等上下文。
知识检索	knowledge_chunks	按 query embedding、rag_schema、record_type 等条件取 evidence。
结果持久化	dialogue_logs	保存用户输入、AI 响应、RAG context、confidence、safety flags 和幂等键。

处方生成数据流

flowchart LR
  Request["处方请求\nPOST /api/prescription/generate"]
  Profile["读取档案\ncomplete profile"]
  Generate["处方生成\nLLM prompt / fallback"]
  Scheme["处方落库\nsport_schemes"]
  ChatCard["对话卡片\ndialogue_logs"]

  Request --> Profile
  Profile --> Generate
  Generate --> Scheme
  Generate --> ChatCard

Step	DB touchpoints	说明
档案读取	users、user_profiles、user_diseases、user_operations	生成处方前读取用户基础画像和健康档案。
RAG 检索	knowledge_chunks	取运动推荐、禁忌、治疗阶段等 evidence。
处方落库	sport_schemes	写入 sportscheme canonical payload、起止日期、审核状态和 demo 标记。
Chat 卡片	dialogue_logs	有 session 时写入处方卡片消息，供 Chat 页面展示和跳转。

运动执行数据流

flowchart LR
  SportAPI["运动接口\n/api/sport/*"]
  Service["运动服务\nSportService"]
  Logs["运动记录\nsport_logs"]
  Schemes["处方方案\nsport_schemes"]
  Profile["用户档案\nuser_profiles"]

  SportAPI --> Service
  Service --> Logs
  Service --> Schemes
  Service --> Profile

Flow	DB touchpoints	说明
创建运动记录	sport_logs	创建进行中或已完成运动；进行中记录会先检查同用户未完成记录。
完成与反馈	sport_logs	更新 sport_end、cal、iffinish、sport_feedback。
历史/日历	sport_logs	按用户、ifdel=false、日期范围或开始时间读取。
运动统计	sport_logs、user_profiles	汇总次数、热量、时长；热量计算可读取体重。
方案列表	sport_schemes	按用户读取处方列表和活跃方案。

陪伴与首页健康概览数据流

Flow	DB touchpoints	说明
虚拟陪练状态	virtual_companion	初始化、更新情绪、外观和位置配置。
健康概览	users、user_profiles、sport_logs	由 companion API 组合用户档案与运动统计。
入口边界	HealthOverviewScreen 代码与路由保留，但当前不作为可达入口	数据链路存在，文档不把隐藏入口写成当前可达页面。

审计与排查数据流

表	写入来源	排查用途
login_logs	登录流程	登录成功率、失败原因、设备来源。
update_logs	用户资料、疾病史、手术史、头像更新	用户资料变更追踪。
data_migration_log	数据迁移脚本	迁移批次状态与错误摘要。
dialogue_logs_archive	对话归档流程	冷数据归档批次、归档原因、历史记录追踪。
system_configs	系统配置管理	feature flag 或运行配置排查。

来源锚点

• API routers: apps/backend_service/app/api/auth.py、user.py、chat.py、prescription.py、sport.py、assessment.py、safety.py、companion.py
• Use cases: apps/backend_service/app/use_cases/chat/send_message.py、prescription/generate_prescription.py、assessment/
• Services: apps/backend_service/app/services/user_service.py、sport_service.py、prescription_service.py
• Repositories: apps/backend_service/app/repositories/
• RAG: apps/backend_service/app/core/rag_engine.py、apps/backend_service/app/core/rag/knowledge_chunk_search.py
• Flutter clients: apps/flutter_app/lib/api/