系统架构总览

本文说明乐橙智康当前系统的整体结构、主业务闭环和运行骨架，适用于新成员接手、跨端协作、研发评审和部署排障前的整体认知建立。

结论

当前系统可以被稳定地讲成一个跨端闭环：

• Flutter App 承载页面、状态与交互
• FastAPI backend 承载 API adapter、use case 与核心服务
• PostgreSQL 承载业务数据与 RAG 数据
• RAG / LLM 承载 AI 生成与知识召回
• Nginx + fitdoc-core:8001 承载当前单一 active backend 部署拓扑

主业务闭环

用户档案profile

安全筛查safety

健康评估assessment

咨询与处方chat / prescription

↴

AI 与知识召回RAG / LLM

记录沉淀dialogue_logs / schemes

运动执行sport_logs

这个闭环是当前架构叙事的中心。后续所有模块文档，都应该能挂回这条链，而不是各自成岛。

当前系统骨架

移动端应用Flutter App

HTTP 入口Nginx / API

后端服务FastAPI

业务编排routers / use cases

↴

业务数据库PostgreSQL + pgvector

AI 知识链路RAG / LLM

静态与上传avatar / uploads

架构判断

1. 后端入口已经形成可讲述骨架

• main.py 是 thin entrypoint
• bootstrap.py 是 app composition root
• runtime.py 是运行时依赖解析入口
• api/ 承担 FastAPI adapter
• use_cases/ 承担主链编排

2. Flutter 端已经形成“入口装配 + BLoC + API client + screen/widget”的第一轮边界

• main.dart 注册主题、路由和全局 bloc
• feature BLoC 负责跨页面状态流
• screen/widget 负责渲染与事件派发

3. 当前生产部署不是逻辑双服务

• 当前 active backend 是单一 fitdoc-core:8001
• 历史 fitdoc-rag 已退出活动运行面
• 文档不应再把路径分流误写成逻辑双服务架构

这三个判断决定了后续阅读和开发的基本路径：

• 需要定位系统问题时，应先判断问题落在 Flutter、backend、数据、RAG 还是部署层。
• 需要新增功能时，应先判断它属于页面、状态、API adapter、use case 还是 runtime 装配问题。
• 需要理解生产形态时，应优先承认单一 active backend 口径，再去看更细的运维事实。

内容地图

文档	用途
边界与主链	解释 backend / frontend / data / RAG / runtime 的边界与主链装配方式
测试护栏与演进落点	解释测试为什么是架构边界，以及新增能力应落在哪里

系统边界说明

• RAG 仍然是专项边界，不适合在系统总览里被写成普通后端子模块。
• weekly_report 当前不应作为主线阻塞能力看待；HealthOverviewScreen 与 WeeklyReportScreen 的代码保留，不等于它们属于当前可达主入口。
• 这个系统已经不是“单纯的技术分层能跑单体”，但也还没有演进成完全严格的 Clean Architecture 纯形态；当前最准确的说法是“关键主链已建立 use case / runtime / test guard 边界”。

问题定位入口

现象	优先判断层	典型来源
页面入口、返回、tab 切换异常	Flutter navigation / screen	lib/main.dart、screens/、app-pages/main-flow
页面有数据但状态不对	Flutter BLoC / API client	lib/bloc/、lib/api/
请求路径、鉴权、状态码异常	FastAPI adapter	app/api/、API tests
主业务结果错误或编排缺失	use case / service	app/use_cases/、app/services/
数据缺失、历史不一致	repository / model / DB	app/repositories/、app/models/、database reference
AI 回答、处方生成、召回异常	RAG / LLM boundary	app/core/rag_engine.py、app/external/、AI/RAG reference
本地正常、线上异常	deployment / runtime	bootstrap/runtime、Nginx、fitdoc-core:8001

架构总览的价值不在于替代各模块 reference，而是帮助读者先把问题归位。归位之后，再进入对应模块核对源码、接口、表结构、测试或运行事实。

阅读建议

如果目标是快速接手系统：

1. 先看主业务闭环，确认系统在服务什么流程。
2. 再看系统骨架，确认 Flutter、backend、DB、RAG、部署之间的关系。
3. 最后进入 边界与主链，确认代码层面的真实边界。

如果目标是准备做变更：

1. 先判断变更位于 Flutter、backend、RAG、数据结构还是部署层。
2. 再判断它是否会穿过 profile / assessment / chat / prescription / sport / companion 主链。
3. 然后去对应板块看更细的实现与测试护栏。

接续阅读

如果你想…	推荐入口
看跨端边界怎么切	边界与主链
看当前测试为什么能代表架构边界	测试护栏与演进落点
看 Flutter 端具体怎么组织	App 前端工程
看 backend 结构细节	后端服务

来源锚点

• Flutter 入口：apps/flutter_app/lib/main.dart
• backend 装配：apps/backend_service/app/bootstrap.py
• runtime 解析：apps/backend_service/app/runtime.py
• backend use cases：apps/backend_service/app/use_cases/
• 运维事实源：docs/新服务器运维手册.md
• 过渡架构记忆：D:/Fitdoc_app/.docs/architecture/fitdoc-system-architecture-overview.md