273 lines
9.1 KiB
Markdown
273 lines
9.1 KiB
Markdown
# 系统架构与技术决策
|
|
|
|
## 整体架构
|
|
|
|
### 架构模式
|
|
- **分层架构**: 采用经典的 NestJS 分层架构模式
|
|
- **模块化设计**: 按业务功能划分模块，保持高内聚低耦合
|
|
- **依赖注入**: 使用 NestJS 的 DI 容器管理依赖关系
|
|
- **中间件模式**: 使用中间件处理横切关注点（日志、认证等）
|
|
|
|
### 核心层次结构
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ Presentation Layer │
|
|
│ (Controllers & DTOs) │
|
|
├─────────────────────────────────────────┤
|
|
│ Business Layer │
|
|
│ (Services & Logic) │
|
|
├─────────────────────────────────────────┤
|
|
│ Data Access Layer │
|
|
│ (Models & Repositories) │
|
|
├─────────────────────────────────────────┤
|
|
│ Infrastructure Layer │
|
|
│ (Database & External Services) │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
## 模块架构
|
|
|
|
### 核心业务模块
|
|
|
|
#### 1. 用户管理模块 (Users)
|
|
- **路径**: `src/users/`
|
|
- **职责**: 用户认证、档案管理、会员体系
|
|
- **关键组件**:
|
|
- `users.controller.ts`: 用户相关 API 端点
|
|
- `users.service.ts`: 用户业务逻辑
|
|
- `models/user.model.ts`: 用户数据模型
|
|
- `services/apple-auth.service.ts`: Apple 认证服务
|
|
- `services/apple-purchase.service.ts`: Apple 购买服务
|
|
|
|
#### 2. AI 健康教练模块 (AiCoach)
|
|
- **路径**: `src/ai-coach/`
|
|
- **职责**: AI 对话、营养分析、体态评估
|
|
- **关键组件**:
|
|
- `ai-coach.service.ts`: AI 核心服务
|
|
- `services/diet-analysis.service.ts`: 饮食分析服务
|
|
- `models/ai-conversation.model.ts`: 对话记录模型
|
|
- `models/posture-assessment.model.ts`: 体态评估模型
|
|
|
|
#### 3. 饮食记录模块 (DietRecords)
|
|
- **路径**: `src/diet-records/`
|
|
- **职责**: 饮食记录、营养追踪、历史查询
|
|
- **关键组件**:
|
|
- `diet-records.service.ts`: 饮食记录业务逻辑
|
|
- `models/nutrition-analysis-record.model.ts`: 营养分析记录
|
|
|
|
#### 4. 食物库模块 (FoodLibrary)
|
|
- **路径**: `src/food-library/`
|
|
- **职责**: 食物数据库、自定义食物、收藏管理
|
|
- **关键组件**:
|
|
- `food-library.service.ts`: 食物库服务
|
|
- `models/food-library.model.ts`: 食物数据模型
|
|
- `models/user-custom-food.model.ts`: 用户自定义食物
|
|
|
|
#### 5. 运动训练模块 (Workouts)
|
|
- **路径**: `src/workouts/`
|
|
- **职责**: 训练计划、运动记录、进度追踪
|
|
- **关键组件**:
|
|
- `workouts.service.ts`: 运动训练服务
|
|
- `models/workout-session.model.ts`: 训练会话模型
|
|
|
|
### 支撑模块
|
|
|
|
#### 1. 数据库模块 (Database)
|
|
- **路径**: `src/database/`
|
|
- **职责**: 数据库连接、配置管理
|
|
- **技术栈**: Sequelize ORM + MySQL
|
|
|
|
#### 2. 通用模块 (Common)
|
|
- **路径**: `src/common/`
|
|
- **职责**: 通用工具、装饰器、守卫
|
|
- **关键组件**:
|
|
- `decorators/`: 自定义装饰器
|
|
- `guards/`: 认证守卫
|
|
- `encryption.service.ts`: 加密服务
|
|
|
|
#### 3. 活动日志模块 (ActivityLogs)
|
|
- **路径**: `src/activity-logs/`
|
|
- **职责**: 用户行为记录、审计日志
|
|
- **关键组件**:
|
|
- `activity-logs.service.ts`: 活动日志服务
|
|
- `models/activity-log.model.ts`: 活动日志模型
|
|
|
|
## 数据库设计
|
|
|
|
### 核心数据表
|
|
|
|
#### 用户相关表
|
|
- `t_users`: 用户基础信息
|
|
- `t_user_profiles`: 用户扩展档案
|
|
- `t_user_weight_history`: 体重历史记录
|
|
- `t_user_body_measurement_history`: 体围测量历史
|
|
- `t_user_diet_history`: 饮食记录历史
|
|
|
|
#### AI 相关表
|
|
- `t_ai_conversations`: AI 对话记录
|
|
- `t_ai_messages`: AI 消息详情
|
|
- `t_posture_assessments`: 体态评估记录
|
|
- `t_nutrition_analysis_records`: 营养分析记录
|
|
|
|
#### 业务功能表
|
|
- `t_food_library`: 食物库
|
|
- `t_user_custom_foods`: 用户自定义食物
|
|
- `t_workout_sessions`: 训练会话
|
|
- `t_training_plans`: 训练计划
|
|
|
|
#### 系统表
|
|
- `t_activity_logs`: 活动日志
|
|
- `t_user_purchases`: 购买记录
|
|
- `t_push_notifications`: 推送通知
|
|
|
|
### 数据库设计原则
|
|
- **命名规范**: 使用 `t_` 前缀，下划线分隔
|
|
- **字符集**: 统一使用 `utf8mb4` 支持完整 Unicode
|
|
- **索引策略**: 为常用查询字段添加复合索引
|
|
- **软删除**: 重要数据使用 `deleted` 字段实现软删除
|
|
|
|
## API 设计规范
|
|
|
|
### RESTful API 设计
|
|
- **基础路径**: `/api`
|
|
- **版本控制**: 通过路径版本控制 (`/api/v1/`)
|
|
- **响应格式**: 统一使用 `ApiResponseDto` 格式
|
|
- **状态码**: 标准 HTTP 状态码 + 业务错误码
|
|
|
|
### 响应结构
|
|
```typescript
|
|
{
|
|
code: ResponseCode.SUCCESS | ResponseCode.ERROR,
|
|
message: string,
|
|
data: T | null
|
|
}
|
|
```
|
|
|
|
### 认证授权
|
|
- **JWT Token**: 使用 JWT 进行用户认证
|
|
- **Apple Sign-In**: 集成 Apple 登录
|
|
- **游客模式**: 支持游客临时访问
|
|
- **权限控制**: 基于角色的访问控制
|
|
|
|
## 安全架构
|
|
|
|
### 数据加密
|
|
- **传输加密**: HTTPS/TLS 1.3
|
|
- **存储加密**: AES-256-GCM 敏感数据加密
|
|
- **密钥管理**: 环境变量 + 密钥轮换机制
|
|
|
|
### 访问控制
|
|
- **API 认证**: JWT Token 验证
|
|
- **权限守卫**: NestJS Guards 实现权限控制
|
|
- **速率限制**: 防止 API 滥用
|
|
- **输入验证**: class-validator 进行数据验证
|
|
|
|
### 审计日志
|
|
- **用户行为**: 完整记录用户操作
|
|
- **系统日志**: Winston 结构化日志
|
|
- **安全事件**: 记录安全相关事件
|
|
- **日志轮转**: 按时间和大小轮转日志
|
|
|
|
## 外部服务集成
|
|
|
|
### AI 服务集成
|
|
- **通义千问**: 阿里云大模型服务
|
|
- **视觉识别**: 图像分析和食物识别
|
|
- **模型配置**: 支持多模型切换和降级
|
|
|
|
### 支付服务集成
|
|
- **Apple App Store**: 应用内购买
|
|
- **RevenueCat**: 订阅管理平台
|
|
- **Webhook 处理**: 安全的支付通知处理
|
|
|
|
### 云服务集成
|
|
- **腾讯云 COS**: 文件存储服务
|
|
- **CDN 加速**: 静态资源分发
|
|
- **推送服务**: APNs (Apple Push Notification)
|
|
|
|
## 性能优化策略
|
|
|
|
### 数据库优化
|
|
- **连接池**: Sequelize 连接池管理
|
|
- **查询优化**: 避免 N+1 查询问题
|
|
- **索引策略**: 为常用查询添加合适索引
|
|
- **读写分离**: 支持主从数据库配置
|
|
|
|
### 缓存策略
|
|
- **内存缓存**: 热点数据内存缓存
|
|
- **查询缓存**: 数据库查询结果缓存
|
|
- **CDN 缓存**: 静态资源 CDN 缓存
|
|
- **API 缓存**: API 响应缓存
|
|
|
|
### 异步处理
|
|
- **队列系统**: 后台任务队列处理
|
|
- **流式响应**: AI 对话流式返回
|
|
- **批量操作**: 批量数据处理优化
|
|
|
|
## 部署架构
|
|
|
|
### 服务器配置
|
|
- **生产环境**: 阿里云 ECS
|
|
- **进程管理**: PM2 集群模式
|
|
- **负载均衡**: Nginx 反向代理
|
|
- **监控告警**: 基础监控和告警
|
|
|
|
### 部署流程
|
|
- **自动化部署**: Shell 脚本自动化部署
|
|
- **零停机部署**: 滚动更新策略
|
|
- **版本管理**: Git 版本控制
|
|
- **回滚机制**: 快速回滚到上一版本
|
|
|
|
### 环境管理
|
|
- **环境隔离**: 开发/测试/生产环境隔离
|
|
- **配置管理**: 环境变量配置管理
|
|
- **密钥管理**: 敏感信息安全管理
|
|
- **依赖管理**: npm/yarn 依赖版本锁定
|
|
|
|
## 技术决策记录
|
|
|
|
### 1. 框架选择: NestJS
|
|
- **原因**: TypeScript 原生支持、模块化架构、丰富的生态系统
|
|
- **优势**: 可维护性高、适合团队协作、内置依赖注入
|
|
- **权衡**: 学习曲线较陡、性能略低于 Express
|
|
|
|
### 2. 数据库: MySQL + Sequelize
|
|
- **原因**: 成熟稳定、事务支持好、Sequulum ORM 功能完善
|
|
- **优势**: 数据一致性强、工具链成熟、运维成本低
|
|
- **权衡**: 扩展性相对较弱、大数据量性能需优化
|
|
|
|
### 3. AI 服务: 通义千问
|
|
- **原因**: 中文支持好、成本相对较低、API 稳定
|
|
- **优势**: 本土化服务、响应速度快、技术支持好
|
|
- **权衡**: 生态相对较小、国际化程度低
|
|
|
|
### 4. 认证方式: JWT + Apple Sign-In
|
|
- **原因**: 无状态认证、Apple 生态集成、用户体验好
|
|
- **优势**: 扩展性强、安全性高、移动端友好
|
|
- **权衡**: Token 管理复杂、登出控制需要额外处理
|
|
|
|
## 未来架构演进方向
|
|
|
|
### 1. 微服务化
|
|
- **服务拆分**: 按业务域拆分微服务
|
|
- **服务发现**: 引入服务注册和发现
|
|
- **API 网关**: 统一 API 入口管理
|
|
- **分布式事务**: 处理跨服务事务
|
|
|
|
### 2. 数据架构升级
|
|
- **读写分离**: 主从数据库分离
|
|
- **分库分表**: 大数据量分片策略
|
|
- **缓存层**: Redis 分布式缓存
|
|
- **搜索引擎**: Elasticsearch 集成
|
|
|
|
### 3. 云原生架构
|
|
- **容器化**: Docker 容器部署
|
|
- **编排管理**: Kubernetes 集群管理
|
|
- **服务网格**: Istio 服务治理
|
|
- **监控体系**: Prometheus + Grafana
|
|
|
|
### 4. AI 能力增强
|
|
- **模型微调**: 领域专用模型训练
|
|
- **多模态**: 图像、语音、文本统一处理
|
|
- **边缘计算**: 本地 AI 推理优化
|
|
- **联邦学习**: 隐私保护的机器学习 |