# 后端架构文档

## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| 1.0 | 2024-01-20 | 后端团队 | 初始版本 |

## 1. 后端架构概述

### 1.1 架构目标
- **高性能**：支持高并发请求处理
- **高可用**：99.9%以上的服务可用性
- **可扩展**：支持水平和垂直扩展
- **易维护**：模块化设计，便于开发和维护
- **安全性**：完善的安全防护机制

### 1.2 技术栈
- **运行环境**：Node.js 18.x LTS
- **Web框架**：Express.js 4.x
- **开发语言**：TypeScript 5.x
- **ORM框架**：Sequelize 6.x (MySQL) + Mongoose 7.x (MongoDB)
- **缓存**：Redis 6.x
- **消息队列**：Redis Pub/Sub + Bull Queue
- **文件存储**：阿里云OSS
- **监控**：Winston + Prometheus

## 2. 系统架构设计

### 2.1 分层架构
```
┌─────────────────────────────────────────────────────────────┐
│                    Controller Layer                         │
│                   (路由控制层)                               │
├─────────────────────────────────────────────────────────────┤
│                    Service Layer                            │
│                   (业务逻辑层)                               │
├─────────────────────────────────────────────────────────────┤
│                    Repository Layer                         │
│                   (数据访问层)                               │
├─────────────────────────────────────────────────────────────┤
│                    Model Layer                              │
│                   (数据模型层)                               │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 微服务架构
```
┌─────────────────────────────────────────────────────────────┐
│                      API Gateway                           │
│                    (Nginx + Kong)                          │
└─────────────────────────────────────────────────────────────┘
                           │
┌─────────────┬─────────────┬─────────────┬─────────────────┐
│  用户服务   │  养殖服务   │  交易服务   │    通知服务     │
│ user-service│farm-service │trade-service│notify-service   │
│   :3001     │   :3002     │   :3003     │    :3004        │
└─────────────┴─────────────┴─────────────┴─────────────────┘
```

## 3. 核心服务设计

### 3.1 用户服务 (User Service)
**端口**: 3001
**职责**: 用户管理、认证授权、权限控制

**核心模块**:
- **认证模块**: JWT Token生成和验证
- **用户管理**: 用户注册、登录、信息管理
- **权限管理**: RBAC权限控制
- **微信集成**: 微信小程序授权登录

**API设计**:
```typescript
// 用户注册
POST /api/v1/users/register
// 用户登录
POST /api/v1/users/login
// 获取用户信息
GET /api/v1/users/profile
// 更新用户信息
PUT /api/v1/users/profile
```

### 3.2 养殖服务 (Farm Service)
**端口**: 3002
**职责**: 养殖场管理、动物管理、饲料管理

**核心模块**:
- **养殖场管理**: 养殖场信息、环境监控
- **动物管理**: 动物档案、健康记录、生长数据
- **饲料管理**: 饲料库存、投喂记录、营养分析
- **数据统计**: 养殖数据分析和报表

**API设计**:
```typescript
// 养殖场管理
GET /api/v1/farms
POST /api/v1/farms
PUT /api/v1/farms/:id
DELETE /api/v1/farms/:id

// 动物管理
GET /api/v1/animals
POST /api/v1/animals
PUT /api/v1/animals/:id
```

### 3.3 交易服务 (Trade Service)
**端口**: 3003
**职责**: 订单管理、支付管理、物流管理

**核心模块**:
- **订单管理**: 订单创建、状态跟踪、订单历史
- **支付管理**: 微信支付、支付宝支付集成
- **物流管理**: 物流信息、配送跟踪
- **财务管理**: 收支记录、财务报表

**API设计**:
```typescript
// 订单管理
GET /api/v1/orders
POST /api/v1/orders
PUT /api/v1/orders/:id/status

// 支付管理
POST /api/v1/payments/wechat
POST /api/v1/payments/alipay
GET /api/v1/payments/:id/status
```

### 3.4 通知服务 (Notify Service)
**端口**: 3004
**职责**: 消息推送、邮件发送、短信通知

**核心模块**:
- **推送管理**: 小程序消息推送
- **邮件服务**: 邮件模板、批量发送
- **短信服务**: 验证码、通知短信
- **消息队列**: 异步消息处理

## 4. 数据库设计

### 4.1 MySQL数据库
**用途**: 核心业务数据存储

**数据库分片策略**:
- **用户库**: 按用户ID分片
- **业务库**: 按业务类型分库
- **日志库**: 按时间分表

**主要数据表**:
```sql
-- 用户表
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    phone VARCHAR(20),
    email VARCHAR(100),
    status TINYINT DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 养殖场表
CREATE TABLE farms (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id BIGINT NOT NULL,
    name VARCHAR(100) NOT NULL,
    address TEXT,
    area DECIMAL(10,2),
    type VARCHAR(50),
    status TINYINT DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);
```

### 4.2 Redis缓存
**用途**: 缓存热点数据、会话存储、分布式锁

**缓存策略**:
- **用户会话**: `session:{token}` (TTL: 7天)
- **用户信息**: `user:{id}` (TTL: 1小时)
- **热点数据**: `hot:{type}:{id}` (TTL: 30分钟)
- **分布式锁**: `lock:{resource}` (TTL: 30秒)

### 4.3 MongoDB文档库
**用途**: 日志数据、统计数据、非结构化数据

**集合设计**:
```javascript
// 操作日志
{
  _id: ObjectId,
  userId: Number,
  action: String,
  resource: String,
  details: Object,
  ip: String,
  userAgent: String,
  timestamp: Date
}

// 统计数据
{
  _id: ObjectId,
  type: String, // daily, weekly, monthly
  date: Date,
  metrics: {
    userCount: Number,
    orderCount: Number,
    revenue: Number
  }
}
```

## 5. 中间件设计

### 5.1 认证中间件
```typescript
export const authMiddleware = async (req: Request, res: Response, next: NextFunction) => {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '');
    if (!token) {
      return res.status(401).json({ error: 'Token required' });
    }
    
    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
    req.user = decoded;
    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid token' });
  }
};
```

### 5.2 权限中间件
```typescript
export const permissionMiddleware = (permission: string) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    const userPermissions = await getUserPermissions(req.user.id);
    if (!userPermissions.includes(permission)) {
      return res.status(403).json({ error: 'Permission denied' });
    }
    next();
  };
};
```

### 5.3 限流中间件
```typescript
export const rateLimitMiddleware = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 最多100次请求
  message: 'Too many requests',
  standardHeaders: true,
  legacyHeaders: false,
});
```

## 6. API设计规范

### 6.1 RESTful API规范
- **URL设计**: 使用名词复数形式，如 `/api/v1/users`
- **HTTP方法**: GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)
- **状态码**: 200(成功)、201(创建)、400(参数错误)、401(未授权)、403(禁止)、404(未找到)、500(服务器错误)

### 6.2 响应格式
```typescript
// 成功响应
{
  "success": true,
  "data": {},
  "message": "操作成功"
}

// 错误响应
{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户不存在"
  }
}

// 分页响应
{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  }
}
```

### 6.3 参数验证
```typescript
import Joi from 'joi';

const userSchema = Joi.object({
  username: Joi.string().min(3).max(30).required(),
  password: Joi.string().min(6).required(),
  email: Joi.string().email().optional(),
  phone: Joi.string().pattern(/^1[3-9]\d{9}$/).optional()
});

export const validateUser = (req: Request, res: Response, next: NextFunction) => {
  const { error } = userSchema.validate(req.body);
  if (error) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: error.details[0].message
      }
    });
  }
  next();
};
```

## 7. 错误处理机制

### 7.1 全局错误处理
```typescript
export const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => {
  logger.error('Unhandled error:', err);
  
  if (err instanceof ValidationError) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: err.message
      }
    });
  }
  
  if (err instanceof AuthenticationError) {
    return res.status(401).json({
      success: false,
      error: {
        code: 'AUTHENTICATION_ERROR',
        message: '认证失败'
      }
    });
  }
  
  // 默认服务器错误
  res.status(500).json({
    success: false,
    error: {
      code: 'INTERNAL_SERVER_ERROR',
      message: '服务器内部错误'
    }
  });
};
```

### 7.2 自定义错误类
```typescript
export class BusinessError extends Error {
  constructor(
    public code: string,
    public message: string,
    public statusCode: number = 400
  ) {
    super(message);
    this.name = 'BusinessError';
  }
}

export class ValidationError extends BusinessError {
  constructor(message: string) {
    super('VALIDATION_ERROR', message, 400);
  }
}

export class AuthenticationError extends BusinessError {
  constructor(message: string = '认证失败') {
    super('AUTHENTICATION_ERROR', message, 401);
  }
}
```

## 8. 日志系统

### 8.1 日志配置
```typescript
import winston from 'winston';

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' }),
    new winston.transports.Console({
      format: winston.format.simple()
    })
  ]
});
```

### 8.2 日志中间件
```typescript
export const loggerMiddleware = (req: Request, res: Response, next: NextFunction) => {
  const start = Date.now();
  
  res.on('finish', () => {
    const duration = Date.now() - start;
    logger.info('HTTP Request', {
      method: req.method,
      url: req.url,
      statusCode: res.statusCode,
      duration,
      userAgent: req.get('User-Agent'),
      ip: req.ip
    });
  });
  
  next();
};
```

## 9. 缓存策略

### 9.1 多级缓存
- **L1缓存**: 内存缓存 (Node.js进程内)
- **L2缓存**: Redis缓存 (分布式缓存)
- **L3缓存**: 数据库查询缓存

### 9.2 缓存更新策略
- **Cache Aside**: 应用程序管理缓存
- **Write Through**: 写入时同步更新缓存
- **Write Behind**: 异步更新缓存

### 9.3 缓存实现
```typescript
class CacheService {
  private redis: Redis;
  private localCache: Map<string, any>;
  
  async get(key: string): Promise<any> {
    // 先查本地缓存
    if (this.localCache.has(key)) {
      return this.localCache.get(key);
    }
    
    // 再查Redis缓存
    const value = await this.redis.get(key);
    if (value) {
      this.localCache.set(key, JSON.parse(value));
      return JSON.parse(value);
    }
    
    return null;
  }
  
  async set(key: string, value: any, ttl: number = 3600): Promise<void> {
    // 更新本地缓存
    this.localCache.set(key, value);
    
    // 更新Redis缓存
    await this.redis.setex(key, ttl, JSON.stringify(value));
  }
}
```

## 10. 性能优化

### 10.1 数据库优化
- **连接池**: 使用连接池管理数据库连接
- **索引优化**: 合理创建索引提升查询性能
- **查询优化**: 避免N+1查询，使用JOIN优化
- **分页优化**: 使用游标分页替代OFFSET

### 10.2 API优化
- **响应压缩**: 启用Gzip压缩
- **静态资源**: CDN加速静态资源
- **异步处理**: 耗时操作异步处理
- **批量操作**: 支持批量API操作

### 10.3 内存优化
- **内存监控**: 监控内存使用情况
- **垃圾回收**: 优化垃圾回收策略
- **内存泄漏**: 定期检查内存泄漏

## 11. 安全设计

### 11.1 输入验证
- **参数校验**: 严格校验所有输入参数
- **SQL注入**: 使用ORM防止SQL注入
- **XSS防护**: 输出内容转义处理

### 11.2 认证安全
- **密码加密**: bcrypt加密存储密码
- **Token安全**: JWT Token + 刷新机制
- **会话管理**: 安全的会话管理

### 11.3 传输安全
- **HTTPS**: 强制使用HTTPS传输
- **CORS**: 配置跨域资源共享
- **CSP**: 内容安全策略

## 12. 监控与运维

### 12.1 健康检查
```typescript
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    memory: process.memoryUsage(),
    version: process.env.npm_package_version
  });
});
```

### 12.2 性能监控
- **响应时间**: 监控API响应时间
- **错误率**: 监控错误发生率
- **吞吐量**: 监控请求处理量
- **资源使用**: 监控CPU、内存使用

### 12.3 告警机制
- **阈值告警**: 基于指标阈值告警
- **异常告警**: 异常情况实时告警
- **趋势告警**: 基于趋势变化告警

## 13. 部署架构

### 13.1 容器化部署
```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000

CMD ["npm", "start"]
```

### 13.2 Kubernetes部署
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: backend-service
  template:
    metadata:
      labels:
        app: backend-service
    spec:
      containers:
      - name: backend
        image: backend-service:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
```

## 14. 扩展性设计

### 14.1 水平扩展
- **无状态设计**: 服务无状态，便于扩展
- **负载均衡**: 支持多实例负载均衡
- **数据分片**: 支持数据库分片扩展

### 14.2 垂直扩展
- **资源配置**: 支持动态调整资源配置
- **性能调优**: 支持性能参数调优
- **容量规划**: 基于业务增长规划容量