plates-server/.kilocode/rules/memory-bank/architecture.md

系统架构与技术决策

整体架构

架构模式

• 分层架构: 采用经典的 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 状态码 + 业务错误码

响应结构

{
  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 推理优化
• 联邦学习: 隐私保护的机器学习