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 克隆项目

git clone https://github.com/your-org/jiebanke-backend.git
cd jiebanke-backend

2.2.2 安装依赖

npm install

2.2.3 配置环境变量

cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息

2.2.4 数据库初始化

# 创建数据库
npm run db:create

# 运行迁移
npm run db:migrate

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

2.2.5 启动开发服务器

npm run dev

2.3 开发工具配置

2.3.1 VSCode配置

推荐安装以下插件：

• TypeScript Importer
• ESLint
• Prettier
• REST Client
• GitLens

2.3.2 代码规范配置

// .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 注释规范

/**
 * 用户服务类
 * 处理用户相关的业务逻辑
 */
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 响应格式规范

interface ApiResponse<T> {
  code: number;
  message: string;
  data?: T;
  timestamp: string;
  request_id: string;
}

4.2.3 错误处理规范

export class ApiError extends Error {
  constructor(
    public code: number,
    public message: string,
    public details?: any
  ) {
    super(message);
  }
}

4.3 数据库操作规范

4.3.1 实体定义规范

@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 查询规范

// 使用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 单元测试规范

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 集成测试规范

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 持续集成

# .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 持续部署

# .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 日志管理

// 日志配置
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 风险控制

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

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