服务架构

本页描述 backend 内部的层次结构与关键组件关系，重点帮助读者理解请求是如何进入系统、业务是如何被编排、数据是如何被持久化的。

整体结构

入口与装配main.py / bootstrap.py

运行时依赖runtime.py / app.state

接口适配app/api/*

业务编排use_cases / services

↴

数据访问repositories / models

持久化与外部服务PostgreSQL / LLM

AI 与安全边界core / external

层次解释

层级	当前职责	说明
main.py	暴露应用入口	负责把 create_app() 暴露为 ASGI app
bootstrap.py	创建与装配 FastAPI app	注册 router、CORS、health、root、static delivery
runtime.py	运行时依赖解析	app.state 与默认全局依赖之间的 resolver
api/	HTTP adapter	处理 request/response、鉴权、schema、状态码
use_cases/	主链编排	将关键业务流程从 router 中剥离出来
core/	核心规则与基础设施边界	config、database、RAG、safety、payload、validation
services/	服务层与存量兼容承载	面向业务和基础设施的组合服务
repositories/	数据访问层	面向 SQLAlchemy model 的 CRUD 与查询
models/	持久化模型	PostgreSQL 表结构映射
external/	外部 provider client	Spark、OpenAI-compatible、LLM manager

当前服务层判断

1. use_cases/ 已经是主链扩展首选落点

当前已建立的 use case 覆盖：

• chat
• prescription
• assessment
• companion

2. services/ 仍然很重要

当前服务层并不是可忽略的遗留层，而是继续承担：

• 业务服务
• 基础设施服务
• 部分主链兼容承载

典型 service 包括：

• AuthService
• PrescriptionService
• SportService
• UserService
• AvatarStorageService
• SmsService

3. core/ 不是单一含义的目录

它同时包含：

• 配置与 DB
• safety / risk policy
• payload helper
• profile validation rules
• rag_engine.py

因此阅读 core/ 时，不能把它简单理解成纯领域逻辑目录。

当前 outer layer 事实

bootstrap.py

• 注册 auth、user、safety、chat、prescription、sport、companion、assessment router
• 配置 CORS
• 配置 static uploads
• 绑定 runtime context
• 暴露 / 和 /health

main.py

• 兼容导出 _build_cors_config()
• 从 bootstrap 导入 create_app()
• 最终实例化 app = create_app()

当前需要明确的限制

• backend route surface 当前不是统一 /api/v1/。
• 一部分服务与 repository 的调用边界仍带有历史演化痕迹，因此“层次存在”不等于“所有实现都已经完全均匀地落在正确层级”。

来源锚点

• apps/backend_service/app/main.py
• apps/backend_service/app/bootstrap.py
• apps/backend_service/app/runtime.py
• apps/backend_service/app/services/
• apps/backend_service/app/repositories/
• apps/backend_service/app/external/