# 系统架构与技术决策

## 整体架构

### 架构模式
- **分层架构**: 采用经典的 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 推理优化
- **联邦学习**: 隐私保护的机器学习