jiebanke/docs/后端开发文档.md

# 后端开发文档

## 1. 项目概述

### 1.1 项目简介
结伴客后端服务是一个基于Node.js + TypeScript + Express的微服务架构系统，为小程序端、管理后台和官网提供API服务支持。

### 1.2 技术栈
- **运行环境**：Node.js 18.x
- **开发语言**：TypeScript 5.x
- **Web框架**：Express.js 4.x
- **数据库**：MySQL 8.0 + Redis 7.x
- **ORM框架**：TypeORM 0.3.x
- **认证授权**：JWT + 微信授权
- **文件存储**：阿里云OSS
- **消息队列**：Redis + Bull Queue
- **监控日志**：Winston + PM2
- **测试框架**：Jest + Supertest
- **代码规范**：ESLint + Prettier

### 1.3 项目结构
```
backend/
├── src/
│   ├── config/           # 配置文件
│   ├── controllers/      # 控制器
│   ├── services/         # 业务逻辑层
│   ├── models/          # 数据模型
│   ├── middlewares/     # 中间件
│   ├── utils/           # 工具函数
│   ├── types/           # 类型定义
│   ├── routes/          # 路由定义
│   ├── jobs/            # 队列任务
│   └── app.ts           # 应用入口
├── tests/               # 测试文件
├── docs/                # 接口文档
├── scripts/             # 脚本文件
├── docker/              # Docker配置
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

## 2. 开发环境搭建

### 2.1 环境要求
- Node.js >= 18.0.0
- npm >= 9.0.0
- MySQL >= 8.0
- Redis >= 7.0
- Git >= 2.30

### 2.2 环境搭建步骤

#### 2.2.1 克隆项目
```bash
git clone https://github.com/your-org/jiebanke-backend.git
cd jiebanke-backend
```

#### 2.2.2 安装依赖
```bash
npm install
```

#### 2.2.3 配置环境变量
```bash
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息
```

#### 2.2.4 数据库初始化
```bash
# 创建数据库
npm run db:create

# 运行迁移
npm run db:migrate

# 填充测试数据
npm run db:seed
```

#### 2.2.5 启动开发服务器
```bash
npm run dev
```

### 2.3 开发工具配置

#### 2.3.1 VSCode配置
推荐安装以下插件：
- TypeScript Importer
- ESLint
- Prettier
- REST Client
- GitLens

#### 2.3.2 代码规范配置
```json
// .eslintrc.json
{
  "extends": [
    "@typescript-eslint/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/explicit-function-return-type": "warn"
  }
}
```

## 3. 开发计划与任务分解

### 3.1 开发阶段划分

#### 阶段一：基础架构搭建（预计15个工作日）
- 项目初始化和环境配置
- 数据库设计和迁移
- 基础中间件和工具类开发
- 认证授权系统

#### 阶段二：核心业务模块（预计25个工作日）
- 用户管理模块
- 旅行结伴模块
- 动物认领模块
- 支付系统模块

#### 阶段三：辅助功能模块（预计15个工作日）
- 文件上传模块
- 消息通知模块
- 搜索功能模块
- 统计分析模块

#### 阶段四：系统优化和测试（预计10个工作日）
- 性能优化
- 安全加固
- 单元测试和集成测试
- 部署和运维配置

### 3.2 详细任务分解

#### 3.2.1 阶段一：基础架构搭建

##### 任务1.1：项目初始化（2个工作日）
**负责人**：架构师 + 后端开发工程师  
**工时估算**：16人时  
**任务描述**：
- 创建项目目录结构
- 配置TypeScript和构建工具
- 设置代码规范和Git hooks
- 配置开发环境和调试工具

**具体子任务**：
1. 初始化npm项目和依赖安装（4人时）
2. 配置TypeScript编译选项（2人时）
3. 设置ESLint和Prettier规范（2人时）
4. 配置Webpack/Vite构建工具（4人时）
5. 设置Git hooks和CI/CD基础配置（4人时）

**验收标准**：
- 项目可以正常启动和热重载
- 代码规范检查通过
- Git提交触发自动化检查

##### 任务1.2：数据库设计和迁移（3个工作日）
**负责人**：数据库设计师 + 后端开发工程师  
**工时估算**：24人时  
**任务描述**：
- 设计数据库表结构
- 创建TypeORM实体模型
- 编写数据库迁移脚本
- 创建种子数据

**具体子任务**：
1. 设计用户相关表结构（6人时）
2. 设计旅行和动物相关表结构（8人时）
3. 设计订单和支付相关表结构（4人时）
4. 创建TypeORM实体和关系映射（4人时）
5. 编写迁移脚本和种子数据（2人时）

**验收标准**：
- 数据库表结构符合设计要求
- 实体关系映射正确
- 迁移脚本可以正常执行

##### 任务1.3：基础中间件开发（4个工作日）
**负责人**：后端开发工程师  
**工时估算**：32人时  
**任务描述**：
- 开发认证中间件
- 开发权限控制中间件
- 开发日志记录中间件
- 开发错误处理中间件

**具体子任务**：
1. JWT认证中间件开发（8人时）
2. 权限控制中间件开发（6人时）
3. 请求日志中间件开发（4人时）
4. 全局错误处理中间件开发（6人时）
5. 参数验证中间件开发（4人时）
6. 限流中间件开发（4人时）

**验收标准**：
- 中间件功能正常
- 单元测试覆盖率达到80%
- 性能测试通过

##### 任务1.4：工具类和配置管理（2个工作日）
**负责人**：后端开发工程师  
**工时估算**：16人时  
**任务描述**：
- 开发通用工具类
- 配置管理系统
- 缓存工具类
- 文件处理工具类

**具体子任务**：
1. 加密解密工具类（4人时）
2. 日期时间工具类（2人时）
3. 字符串处理工具类（2人时）
4. 配置管理工具（4人时）
5. Redis缓存工具类（4人时）

**验收标准**：
- 工具类功能完整
- 配置可以动态加载
- 缓存操作正常

##### 任务1.5：认证授权系统（4个工作日）
**负责人**：后端开发工程师  
**工时估算**：32人时  
**任务描述**：
- 微信登录集成
- JWT Token管理
- 用户权限系统
- 会话管理

**具体子任务**：
1. 微信小程序登录接口（8人时）
2. JWT Token生成和验证（6人时）
3. 用户权限模型设计（6人时）
4. 会话管理和刷新机制（6人时）
5. 权限装饰器开发（6人时）

**验收标准**：
- 微信登录流程正常
- Token验证机制完善
- 权限控制精确

#### 3.2.2 阶段二：核心业务模块

##### 任务2.1：用户管理模块（6个工作日）
**负责人**：后端开发工程师  
**工时估算**：48人时  
**任务描述**：
- 用户信息管理
- 用户认证和授权
- 用户资料完善
- 用户状态管理

**具体子任务**：
1. 用户注册和登录接口（8人时）
2. 用户信息CRUD接口（8人时）
3. 用户头像上传功能（6人时）
4. 用户实名认证功能（8人时）
5. 用户状态管理（6人时）
6. 用户统计信息接口（6人时）
7. 用户关注和粉丝功能（6人时）

**验收标准**：
- 用户注册登录流程完整
- 用户信息管理功能正常
- 实名认证流程通畅

##### 任务2.2：旅行结伴模块（8个工作日）
**负责人**：后端开发工程师  
**工时估算**：64人时  
**任务描述**：
- 旅行活动管理
- 参与申请处理
- 活动状态管理
- 评论和互动功能

**具体子任务**：
1. 旅行活动CRUD接口（12人时）
2. 活动搜索和筛选功能（8人时）
3. 参与申请管理接口（10人时）
4. 活动状态流转管理（8人时）
5. 活动评论和点赞功能（8人时）
6. 活动图片和视频管理（6人时）
7. 活动推荐算法（8人时）
8. 活动统计分析接口（4人时）

**验收标准**：
- 旅行活动管理功能完整
- 申请审核流程正常
- 搜索和推荐准确

##### 任务2.3：动物认领模块（7个工作日）
**负责人**：后端开发工程师  
**工时估算**：56人时  
**任务描述**：
- 动物信息管理
- 认领申请处理
- 认领状态跟踪
- 动物成长记录

**具体子任务**：
1. 动物信息CRUD接口（10人时）
2. 动物搜索和筛选功能（8人时）
3. 认领申请管理接口（10人时）
4. 认领状态管理（8人时）
5. 动物成长记录功能（8人时）
6. 动物健康档案管理（6人时）
7. 认领费用计算（6人时）

**验收标准**：
- 动物信息管理完整
- 认领流程顺畅
- 成长记录功能正常

##### 任务2.4：支付系统模块（4个工作日）
**负责人**：后端开发工程师  
**工时估算**：32人时  
**任务描述**：
- 订单管理系统
- 微信支付集成
- 支付状态跟踪
- 退款处理

**具体子任务**：
1. 订单创建和管理接口（8人时）
2. 微信支付接口集成（10人时）
3. 支付回调处理（6人时）
4. 退款功能开发（6人时）
5. 支付状态同步（2人时）

**验收标准**：
- 订单管理功能完整
- 微信支付流程正常
- 退款处理准确

#### 3.2.3 阶段三：辅助功能模块

##### 任务3.1：文件上传模块（3个工作日）
**负责人**：后端开发工程师  
**工时估算**：24人时  
**任务描述**：
- 文件上传接口
- 图片处理功能
- 文件存储管理
- CDN集成

**具体子任务**：
1. 文件上传接口开发（8人时）
2. 图片压缩和处理（6人时）
3. 阿里云OSS集成（6人时）
4. 文件管理接口（4人时）

**验收标准**：
- 文件上传功能正常
- 图片处理效果良好
- 存储和访问稳定

##### 任务3.2：消息通知模块（4个工作日）
**负责人**：后端开发工程师  
**工时估算**：32人时  
**任务描述**：
- 站内消息系统
- 微信模板消息
- 消息推送功能
- 消息状态管理

**具体子任务**：
1. 站内消息CRUD接口（8人时）
2. 微信模板消息集成（8人时）
3. 消息推送队列（8人时）
4. 消息状态管理（4人时）
5. 消息统计功能（4人时）

**验收标准**：
- 消息发送接收正常
- 推送功能稳定
- 状态管理准确

##### 任务3.3：搜索功能模块（4个工作日）
**负责人**：后端开发工程师  
**工时估算**：32人时  
**任务描述**：
- 全文搜索功能
- 搜索建议
- 搜索统计
- 搜索优化

**具体子任务**：
1. 搜索接口开发（10人时）
2. 搜索建议功能（6人时）
3. 搜索结果排序（8人时）
4. 搜索统计分析（4人时）
5. 搜索性能优化（4人时）

**验收标准**：
- 搜索结果准确
- 响应速度快
- 建议功能智能

##### 任务3.4：统计分析模块（4个工作日）
**负责人**：后端开发工程师  
**工时估算**：32人时  
**任务描述**：
- 用户行为统计
- 业务数据分析
- 报表生成
- 数据可视化接口

**具体子任务**：
1. 用户行为统计接口（8人时）
2. 业务数据统计接口（8人时）
3. 报表生成功能（8人时）
4. 数据导出功能（4人时）
5. 统计数据缓存优化（4人时）

**验收标准**：
- 统计数据准确
- 报表生成正常
- 性能满足要求

#### 3.2.4 阶段四：系统优化和测试

##### 任务4.1：性能优化（3个工作日）
**负责人**：后端开发工程师  
**工时估算**：24人时  
**任务描述**：
- 数据库查询优化
- 缓存策略优化
- 接口性能优化
- 系统监控

**具体子任务**：
1. SQL查询优化（8人时）
2. Redis缓存策略优化（6人时）
3. 接口响应时间优化（6人时）
4. 系统监控配置（4人时）

**验收标准**：
- 接口响应时间<200ms
- 数据库查询效率提升50%
- 缓存命中率>80%

##### 任务4.2：安全加固（2个工作日）
**负责人**：后端开发工程师  
**工时估算**：16人时  
**任务描述**：
- 安全漏洞检查
- 数据加密处理
- 接口安全加固
- 安全审计

**具体子任务**：
1. SQL注入防护（4人时）
2. XSS攻击防护（4人时）
3. 敏感数据加密（4人时）
4. 接口访问控制（4人时）

**验收标准**：
- 安全扫描无高危漏洞
- 敏感数据加密存储
- 接口访问控制完善

##### 任务4.3：测试开发（3个工作日）
**负责人**：后端开发工程师 + 测试工程师  
**工时估算**：24人时  
**任务描述**：
- 单元测试编写
- 集成测试开发
- 接口测试自动化
- 性能测试

**具体子任务**：
1. 单元测试编写（10人时）
2. 集成测试开发（8人时）
3. 接口自动化测试（4人时）
4. 性能测试脚本（2人时）

**验收标准**：
- 单元测试覆盖率>80%
- 集成测试通过率100%
- 接口测试自动化完成

##### 任务4.4：部署和运维配置（2个工作日）
**负责人**：运维工程师 + 后端开发工程师  
**工时估算**：16人时  
**任务描述**：
- Docker容器化
- CI/CD流水线
- 监控告警配置
- 日志收集配置

**具体子任务**：
1. Docker镜像构建（4人时）
2. CI/CD流水线配置（6人时）
3. 监控告警配置（4人时）
4. 日志收集配置（2人时）

**验收标准**：
- 容器化部署成功
- CI/CD流水线正常
- 监控告警及时

## 4. 开发规范

### 4.1 代码规范

#### 4.1.1 命名规范
- **文件命名**：使用kebab-case，如`user-service.ts`
- **类命名**：使用PascalCase，如`UserService`
- **方法命名**：使用camelCase，如`getUserById`
- **常量命名**：使用UPPER_SNAKE_CASE，如`MAX_FILE_SIZE`

#### 4.1.2 目录结构规范
```
src/
├── controllers/
│   ├── user.controller.ts
│   ├── travel.controller.ts
│   └── animal.controller.ts
├── services/
│   ├── user.service.ts
│   ├── travel.service.ts
│   └── animal.service.ts
├── models/
│   ├── user.model.ts
│   ├── travel.model.ts
│   └── animal.model.ts
└── routes/
    ├── user.routes.ts
    ├── travel.routes.ts
    └── animal.routes.ts
```

#### 4.1.3 注释规范
```typescript
/**
 * 用户服务类
 * 处理用户相关的业务逻辑
 */
export class UserService {
  /**
   * 根据ID获取用户信息
   * @param id 用户ID
   * @returns 用户信息对象
   * @throws {NotFoundError} 用户不存在时抛出
   */
  async getUserById(id: number): Promise<User> {
    // 实现逻辑
  }
}
```

### 4.2 API设计规范

#### 4.2.1 RESTful接口规范
- **GET** `/api/v1/users` - 获取用户列表
- **GET** `/api/v1/users/{id}` - 获取单个用户
- **POST** `/api/v1/users` - 创建用户
- **PUT** `/api/v1/users/{id}` - 更新用户
- **DELETE** `/api/v1/users/{id}` - 删除用户

#### 4.2.2 响应格式规范
```typescript
interface ApiResponse<T> {
  code: number;
  message: string;
  data?: T;
  timestamp: string;
  request_id: string;
}
```

#### 4.2.3 错误处理规范
```typescript
export class ApiError extends Error {
  constructor(
    public code: number,
    public message: string,
    public details?: any
  ) {
    super(message);
  }
}
```

### 4.3 数据库操作规范

#### 4.3.1 实体定义规范
```typescript
@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 50, unique: true })
  username: string;

  @CreateDateColumn()
  created_at: Date;

  @UpdateDateColumn()
  updated_at: Date;
}
```

#### 4.3.2 查询规范
```typescript
// 使用Repository模式
const user = await this.userRepository.findOne({
  where: { id },
  relations: ['profile']
});

// 使用QueryBuilder进行复杂查询
const users = await this.userRepository
  .createQueryBuilder('user')
  .leftJoinAndSelect('user.profile', 'profile')
  .where('user.status = :status', { status: 1 })
  .getMany();
```

### 4.4 测试规范

#### 4.4.1 单元测试规范
```typescript
describe('UserService', () => {
  let service: UserService;
  let repository: Repository<User>;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [UserService, mockUserRepository]
    }).compile();

    service = module.get<UserService>(UserService);
    repository = module.get<Repository<User>>(getRepositoryToken(User));
  });

  it('should create a user', async () => {
    const userData = { username: 'test', email: 'test@example.com' };
    const result = await service.createUser(userData);
    
    expect(result).toBeDefined();
    expect(result.username).toBe(userData.username);
  });
});
```

#### 4.4.2 集成测试规范
```typescript
describe('User API', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule]
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  it('/users (POST)', () => {
    return request(app.getHttpServer())
      .post('/users')
      .send({ username: 'test', email: 'test@example.com' })
      .expect(201)
      .expect((res) => {
        expect(res.body.data.username).toBe('test');
      });
  });
});
```

## 5. 质量保证

### 5.1 代码质量检查

#### 5.1.1 静态代码分析
- **ESLint**：代码风格和潜在问题检查
- **Prettier**：代码格式化
- **SonarQube**：代码质量分析
- **TypeScript**：类型检查

#### 5.1.2 代码审查流程
1. 开发者提交Pull Request
2. 自动化检查（ESLint、测试、构建）
3. 同行代码审查
4. 技术负责人最终审查
5. 合并到主分支

### 5.2 测试策略

#### 5.2.1 测试金字塔
- **单元测试**：70% - 测试单个函数和类
- **集成测试**：20% - 测试模块间交互
- **端到端测试**：10% - 测试完整业务流程

#### 5.2.2 测试覆盖率要求
- **代码覆盖率**：>80%
- **分支覆盖率**：>70%
- **函数覆盖率**：>90%

### 5.3 性能要求

#### 5.3.1 响应时间要求
- **简单查询接口**：<100ms
- **复杂查询接口**：<500ms
- **文件上传接口**：<2s
- **支付接口**：<1s

#### 5.3.2 并发性能要求
- **并发用户数**：1000+
- **QPS**：500+
- **数据库连接池**：20-50
- **内存使用**：<512MB

## 6. 部署和运维

### 6.1 环境配置

#### 6.1.1 开发环境
- **Node.js**：18.x
- **MySQL**：8.0
- **Redis**：7.x
- **端口**：3000

#### 6.1.2 测试环境
- **服务器**：2核4GB
- **数据库**：独立实例
- **域名**：api-test.jiebanke.com
- **HTTPS**：Let's Encrypt

#### 6.1.3 生产环境
- **服务器**：4核8GB（可扩展）
- **数据库**：主从复制
- **缓存**：Redis集群
- **CDN**：阿里云CDN
- **监控**：Prometheus + Grafana

### 6.2 CI/CD流程

#### 6.2.1 持续集成
```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run lint
      - run: npm run test
      - run: npm run build
```

#### 6.2.2 持续部署
```yaml
# .github/workflows/cd.yml
name: CD
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker image
        run: docker build -t jiebanke-backend .
      - name: Deploy to server
        run: |
          docker stop jiebanke-backend || true
          docker rm jiebanke-backend || true
          docker run -d --name jiebanke-backend -p 3000:3000 jiebanke-backend
```

### 6.3 监控和日志

#### 6.3.1 应用监控
- **健康检查**：/health端点
- **性能监控**：响应时间、吞吐量
- **错误监控**：错误率、异常堆栈
- **业务监控**：用户活跃度、订单量

#### 6.3.2 日志管理
```typescript
// 日志配置
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});
```

## 7. 风险管理

### 7.1 技术风险

#### 7.1.1 性能风险
- **风险**：高并发下性能下降
- **应对**：负载测试、缓存优化、数据库优化
- **监控**：响应时间、QPS、资源使用率

#### 7.1.2 安全风险
- **风险**：数据泄露、攻击
- **应对**：安全审计、加密存储、访问控制
- **监控**：异常访问、安全事件

### 7.2 业务风险

#### 7.2.1 数据一致性风险
- **风险**：分布式事务失败
- **应对**：事务补偿、幂等性设计
- **监控**：数据一致性检查

#### 7.2.2 第三方依赖风险
- **风险**：微信API、支付接口不可用
- **应对**：降级方案、重试机制
- **监控**：第三方服务可用性

## 8. 总结

本开发文档详细规划了结伴客后端系统的开发计划，包括：

### 8.1 开发计划
- **总工期**：65个工作日
- **团队规模**：3-4名后端开发工程师
- **关键里程碑**：基础架构、核心业务、辅助功能、系统优化

### 8.2 质量保证
- **代码规范**：统一的编码标准和最佳实践
- **测试策略**：完整的测试金字塔和覆盖率要求
- **性能要求**：明确的性能指标和优化方案

### 8.3 风险控制
- **技术风险**：性能、安全、稳定性
- **业务风险**：数据一致性、第三方依赖
- **应对措施**：监控、降级、补偿机制

通过严格按照本开发文档执行，可以确保后端系统的高质量交付和稳定运行。