外观
后端服务总览
本板块说明 FastAPI backend 当前的工程骨架、装配入口、主链落点和模块边界。它的目标不是重复 API reference，而是帮助读者先建立后端整体理解，再进入更细的接口、数据库和部署文档。
结论
当前 backend 已形成一条比较稳定的装配与编排骨架：
main.py暴露薄入口bootstrap.py创建 FastAPI app 并注册 outer layerruntime.py负责运行时依赖解析api/承担 HTTP adapteruse_cases/承担关键主链编排services / repositories / models承担业务服务、数据访问与持久化
这意味着后端已经不是单纯把所有逻辑堆在 router 里的状态，但也还没有完全收敛成纯粹的 port-and-adapter 形态；当前最准确的描述是“主链 use case 已建立，装配边界已集中，存量服务层仍承担一部分 legacy 业务逻辑”。
当前目录骨架
| 目录 / 文件 | 当前职责 |
|---|---|
app/main.py | ASGI 入口与兼容导出 |
app/bootstrap.py | create_app、router 注册、CORS、static delivery |
app/runtime.py | settings、session、db、rag、storage resolver |
app/api/ | auth / user / chat / prescription / assessment / safety / companion / sport |
app/use_cases/ | chat、prescription、assessment、companion 主链编排 |
app/core/ | config、DB、RAG、safety、payload helper、validation rules |
app/services/ | auth、sport、prescription、user、avatar、sms 等服务层 |
app/repositories/ | 用户、运动、对话、陪伴、日志等数据访问层 |
app/models/ | SQLAlchemy 持久化模型 |
app/external/ | LLM manager、Spark client、OpenAI-compatible client |
内容地图
| 文档 | 用途 |
|---|---|
| 服务架构 | backend 的整体层次、核心组件与技术边界 |
| 入口与运行时装配 | main / bootstrap / runtime / runtime_dependencies 的装配边界 |
| Use Case 边界 | 当前已建立的主链 use case 与推荐扩展落点 |
| 模块边界 | auth/chat/sport/prescription/companion/user/safety/assessment 的职责划分 |
| 核心链路 | 登录、聊天、处方、运动记录等端到端链路 |
后端阅读顺序
如果目标是快速接手后端，建议按这个顺序读：
- 先看 服务架构，确认整体骨架。
- 再看 入口与运行时装配，确认依赖从哪里进入系统。
- 然后看 Use Case 边界，确认主链编排落点。
- 最后再读 模块边界 和 核心链路。
当前需要明确的工程事实
- 路由前缀当前是混合 surface，不是统一
/api/v1/。 api/层已经开始消费 use case，但services/仍然承接一部分业务逻辑与兼容层职责。core/既包含规则，也包含 RAG 和 payload helper，不应简单理解成纯领域层。external/层主要用于 LLM provider 接入，不等于所有外部依赖都已彻底 gateway 化。
变更落点判断
| 变更类型 | 优先落点 | 同步检查 |
|---|---|---|
| 新增 HTTP endpoint | app/api/<module>.py | route prefix、auth、schema、API test、前端 consumer |
| 新增主链业务编排 | app/use_cases/<feature>/ | command/result、service/repository 依赖、use case test |
| 扩展存量业务服务 | app/services/ | 是否已有 use case 调用，是否会扩大 legacy service 边界 |
| 新增数据读写 | app/repositories/ + app/models/ | 表名、关系、事务、migration、database reference |
| 新增运行时依赖 | app/bootstrap.py + app/runtime.py | 是否挂入 app.state，是否有 resolver / dependency |
| 新增 LLM provider 或外部服务 | app/external/ 或 app/core/ 专项边界 | 超时、重试、降级、安全过滤和日志脱敏 |
后端文档的总览层只负责帮助读者判断落点。完整 method、path、request、response、errors、DB touchpoints 应进入后续 API 和数据库 reference。
来源锚点
apps/backend_service/app/main.pyapps/backend_service/app/bootstrap.pyapps/backend_service/app/runtime.pyapps/backend_service/app/api/apps/backend_service/app/use_cases/