aiotagro/jiebanke

Fork 0

Files

ylweng 14aca938de 重构动物认领页面和导航菜单，统一使用SVG图标并优化交互体验

2025-09-21 21:12:27 +08:00

40 KiB

Raw Permalink Blame History

后端管理开发文档

1. 项目概述

1.1 项目简介

解班客后端管理系统是一个基于Node.js的企业级后端服务，为管理后台、小程序和官网提供统一的API服务和数据管理功能。

1.2 技术栈

运行环境：Node.js 18.x
开发框架：Express.js 4.x
开发语言：TypeScript 5.x
数据库：MySQL 8.0 + Redis 7.x
ORM框架：TypeORM 0.3.x
认证授权：JWT + RBAC
文件存储：阿里云OSS
消息队列：Redis + Bull
日志系统：Winston
API文档：Swagger/OpenAPI
测试框架：Jest + Supertest
代码规范：ESLint + Prettier

1.3 项目结构

backend/
├── src/
│   ├── controllers/     # 控制器
│   │   ├── admin/       # 管理后台控制器
│   │   ├── app/         # 小程序控制器
│   │   └── common/      # 通用控制器
│   ├── services/        # 业务服务层
│   │   ├── user/        # 用户服务
│   │   ├── travel/      # 旅行服务
│   │   ├── animal/      # 动物服务
│   │   ├── order/       # 订单服务
│   │   └── common/      # 通用服务
│   ├── models/          # 数据模型
│   │   ├── entities/    # 实体定义
│   │   ├── dto/         # 数据传输对象
│   │   └── vo/          # 视图对象
│   ├── middleware/      # 中间件
│   │   ├── auth/        # 认证中间件
│   │   ├── validation/  # 验证中间件
│   │   └── common/      # 通用中间件
│   ├── utils/           # 工具函数
│   │   ├── database/    # 数据库工具
│   │   ├── cache/       # 缓存工具
│   │   ├── file/        # 文件处理
│   │   └── common/      # 通用工具
│   ├── config/          # 配置文件
│   │   ├── database.ts  # 数据库配置
│   │   ├── redis.ts     # Redis配置
│   │   └── app.ts       # 应用配置
│   ├── routes/          # 路由定义
│   │   ├── admin/       # 管理后台路由
│   │   ├── app/         # 小程序路由
│   │   └── common/      # 通用路由
│   ├── jobs/            # 定时任务
│   ├── migrations/      # 数据库迁移
│   ├── seeds/           # 数据种子
│   ├── app.ts           # 应用入口
│   └── server.ts        # 服务器启动
├── tests/               # 测试文件
│   ├── unit/            # 单元测试
│   ├── integration/     # 集成测试
│   └── e2e/             # 端到端测试
├── docs/                # 文档
├── scripts/             # 脚本文件
├── .env.example         # 环境变量示例
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

2. 开发环境搭建

2.1 环境要求

Node.js >= 18.0.0
npm >= 9.0.0 或 yarn >= 1.22.0
MySQL >= 8.0.0
Redis >= 7.0.0
Git >= 2.0.0

2.2 环境搭建步骤

2.2.1 克隆项目

git clone https://github.com/jiebanke/backend.git
cd backend

2.2.2 安装依赖

npm install
# 或
yarn install

2.2.3 配置环境变量

# 复制环境配置文件
cp .env.example .env.development
cp .env.example .env.production

# 编辑配置文件
vim .env.development

2.2.4 数据库初始化

# 创建数据库
npm run db:create

# 运行迁移
npm run migration:run

# 运行种子数据
npm run seed:run

2.2.5 启动开发服务器

npm run dev
# 或
yarn dev

2.3 开发工具配置

2.3.1 VSCode配置

推荐安装以下插件：

TypeScript Importer
ESLint
Prettier
REST Client
MySQL
Redis

2.3.2 数据库工具

MySQL Workbench
Navicat
DBeaver
Redis Desktop Manager

3. 开发计划与任务分解

3.1 开发阶段划分

阶段一：基础框架搭建（预计8个工作日）

项目初始化和环境配置
数据库设计和迁移
基础中间件开发
认证授权系统

阶段二：核心业务开发（预计25个工作日）

用户管理系统
旅行结伴功能
动物认领功能
订单支付系统

阶段三：管理功能开发（预计15个工作日）

管理后台API
数据统计分析
系统配置管理
日志审计功能

阶段四：优化和部署（预计10个工作日）

性能优化
安全加固
测试和修复
部署和监控

3.2 详细任务分解

3.2.1 阶段一：基础框架搭建

任务1.1：项目初始化（2个工作日）

负责人：后端架构师 + 后端开发工程师
工时估算：16人时
任务描述：

创建Express.js项目结构
配置TypeScript和构建工具
设置代码规范和Git hooks
配置开发环境

具体子任务：

创建Express + TypeScript项目（4人时）
配置ESLint、Prettier和Git hooks（4人时）
设置环境变量和配置管理（4人时）
配置开发和构建脚本（4人时）

验收标准：

项目可以正常启动和热重载
代码规范检查通过
TypeScript编译无错误

任务1.2：数据库设计和迁移（3个工作日）

负责人：后端开发工程师 + 数据库工程师
工时估算：24人时
任务描述：

设计数据库表结构
创建TypeORM实体
编写数据库迁移
创建种子数据

具体子任务：

设计核心业务表结构（8人时）
创建TypeORM实体和关系（8人时）
编写数据库迁移脚本（4人时）
创建测试和演示数据（4人时）

验收标准：

数据库表结构完整
实体关系正确
迁移脚本可正常执行

任务1.3：基础中间件开发（2个工作日）

负责人：后端开发工程师
工时估算：16人时
任务描述：

请求日志中间件
错误处理中间件
参数验证中间件
跨域处理中间件

具体子任务：

请求日志和响应时间中间件（4人时）
全局错误处理中间件（4人时）
请求参数验证中间件（4人时）
CORS和安全头中间件（4人时）

验收标准：

中间件功能完整
错误处理规范
日志记录准确

任务1.4：认证授权系统（1个工作日）

负责人：后端开发工程师
工时估算：8人时
任务描述：

JWT认证实现
RBAC权限控制
用户会话管理
权限验证中间件

具体子任务：

JWT生成和验证（3人时）
RBAC权限模型实现（3人时）
权限验证中间件（2人时）

验收标准：

JWT认证正常
权限控制精确
会话管理安全

3.2.2 阶段二：核心业务开发

任务2.1：用户管理系统（6个工作日）

负责人：后端开发工程师
工时估算：48人时
任务描述：

用户注册登录
用户信息管理
实名认证功能
用户行为记录

具体子任务：

微信登录和手机号登录（12人时）
用户信息CRUD操作（10人时）
实名认证流程和验证（12人时）
用户行为日志记录（8人时）
用户状态管理（6人时）

验收标准：

登录流程完整
用户信息管理功能齐全
实名认证流程正确

任务2.2：旅行结伴功能（7个工作日）

负责人：后端开发工程师
工时估算：56人时
任务描述：

旅行活动管理
参与申请处理
活动状态管理
地理位置服务

具体子任务：

旅行活动CRUD操作（14人时）
参与申请和审核流程（12人时）
活动状态和生命周期管理（10人时）
地理位置搜索和推荐（10人时）
活动评价和反馈（10人时）

验收标准：

活动管理功能完整
申请流程顺畅
地理位置服务准确

任务2.3：动物认领功能（6个工作日）

负责人：后端开发工程师
工时估算：48人时
任务描述：

动物信息管理
认领申请处理
认领记录跟踪
动物状态更新

具体子任务：

动物信息CRUD操作（12人时）
认领申请和审核流程（12人时）
认领记录和历史跟踪（10人时）
动物状态和健康记录（8人时）
认领动态和通知（6人时）

验收标准：

动物信息管理完整
认领流程清晰
状态跟踪准确

任务2.4：订单支付系统（6个工作日）

负责人：后端开发工程师
工时估算：48人时
任务描述：

订单创建和管理
支付接口集成
订单状态跟踪
退款处理功能

具体子任务：

订单创建和状态管理（12人时）
微信支付接口集成（15人时）
支付回调和状态同步（10人时）
退款申请和处理（8人时）
订单查询和统计（3人时）

验收标准：

订单管理功能完整
支付流程稳定
退款处理正确

3.2.3 阶段三：管理功能开发

任务3.1：管理后台API（5个工作日）

负责人：后端开发工程师
工时估算：40人时
任务描述：

管理员认证授权
用户管理接口
内容管理接口
系统配置接口

具体子任务：

管理员登录和权限管理（10人时）
用户管理相关接口（10人时）
内容审核和管理接口（10人时）
系统配置和参数管理（10人时）

验收标准：

管理接口功能完整
权限控制严格
数据操作安全

任务3.2：数据统计分析（4个工作日）

负责人：后端开发工程师
工时估算：32人时
任务描述：

用户数据统计
业务数据分析
财务数据报表
实时数据监控

具体子任务：

用户增长和活跃度统计（10人时）
业务数据分析和报表（10人时）
财务收支统计（8人时）
实时数据监控接口（4人时）

验收标准：

统计数据准确
报表生成正确
实时监控有效

任务3.3：系统配置管理（3个工作日）

负责人：后端开发工程师
工时估算：24人时
任务描述：

系统参数配置
字典数据管理
配置缓存机制
配置变更通知

具体子任务：

系统参数CRUD操作（8人时）
字典数据管理接口（6人时）
配置缓存和更新机制（6人时）
配置变更通知和日志（4人时）

验收标准：

配置管理功能完整
缓存机制有效
变更通知及时

任务3.4：日志审计功能（3个工作日）

负责人：后端开发工程师
工时估算：24人时
任务描述：

操作日志记录
审计日志查询
日志分析统计
日志归档清理

具体子任务：

操作日志记录和存储（8人时）
审计日志查询接口（8人时）
日志分析和统计（4人时）
日志归档和清理机制（4人时）

验收标准：

日志记录完整
查询功能强大
归档机制有效

3.2.4 阶段四：优化和部署

任务4.1：性能优化（3个工作日）

负责人：后端开发工程师
工时估算：24人时
任务描述：

数据库查询优化
缓存策略优化
接口性能优化
并发处理优化

具体子任务：

SQL查询优化和索引调整（8人时）
Redis缓存策略优化（6人时）
接口响应时间优化（6人时）
并发处理和连接池优化（4人时）

验收标准：

查询性能提升50%
缓存命中率>80%
接口响应时间<500ms

任务4.2：安全加固（2个工作日）

负责人：后端开发工程师
工时估算：16人时
任务描述：

输入验证加强
SQL注入防护
XSS攻击防护
接口限流保护

具体子任务：

输入参数验证和过滤（6人时）
SQL注入和XSS防护（4人时）
接口限流和防刷机制（4人时）
敏感数据加密存储（2人时）

验收标准：

安全漏洞修复
防护机制有效
敏感数据安全

任务4.3：测试和修复（3个工作日）

负责人：后端开发工程师 + 测试工程师
工时估算：24人时
任务描述：

单元测试编写
集成测试执行
性能测试验证
Bug修复和优化

具体子任务：

单元测试编写和执行（10人时）
集成测试和API测试（8人时）
性能测试和压力测试（4人时）
Bug修复和代码优化（2人时）

验收标准：

测试覆盖率>80%
集成测试通过
性能指标达标

任务4.4：部署和监控（2个工作日）

负责人：后端开发工程师 + 运维工程师
工时估算：16人时
任务描述：

生产环境部署
监控系统配置
日志收集配置
备份恢复机制

具体子任务：

Docker容器化和部署（6人时）
监控和告警配置（4人时）
日志收集和分析配置（4人时）
数据备份和恢复测试（2人时）

验收标准：

部署流程自动化
监控系统正常
备份机制有效

4. 开发规范

4.1 代码规范

4.1.1 项目结构规范

// src/controllers/admin/user.controller.ts
import { Request, Response } from 'express'
import { UserService } from '@/services/user/user.service'
import { CreateUserDto, UpdateUserDto, UserQueryDto } from '@/models/dto/user.dto'
import { ApiResponse } from '@/utils/response'
import { validateDto } from '@/middleware/validation'

export class AdminUserController {
  private userService: UserService

  constructor() {
    this.userService = new UserService()
  }

  /**
   * 获取用户列表
   */
  async getUsers(req: Request, res: Response) {
    try {
      const query = req.query as UserQueryDto
      const result = await this.userService.getUsers(query)
      
      return ApiResponse.success(res, result, '获取用户列表成功')
    } catch (error) {
      return ApiResponse.error(res, error.message)
    }
  }

  /**
   * 创建用户
   */
  async createUser(req: Request, res: Response) {
    try {
      const createUserDto = await validateDto(CreateUserDto, req.body)
      const user = await this.userService.createUser(createUserDto)
      
      return ApiResponse.success(res, user, '创建用户成功')
    } catch (error) {
      return ApiResponse.error(res, error.message)
    }
  }

  /**
   * 更新用户
   */
  async updateUser(req: Request, res: Response) {
    try {
      const { id } = req.params
      const updateUserDto = await validateDto(UpdateUserDto, req.body)
      const user = await this.userService.updateUser(Number(id), updateUserDto)
      
      return ApiResponse.success(res, user, '更新用户成功')
    } catch (error) {
      return ApiResponse.error(res, error.message)
    }
  }

  /**
   * 删除用户
   */
  async deleteUser(req: Request, res: Response) {
    try {
      const { id } = req.params
      await this.userService.deleteUser(Number(id))
      
      return ApiResponse.success(res, null, '删除用户成功')
    } catch (error) {
      return ApiResponse.error(res, error.message)
    }
  }
}

4.1.2 服务层规范

// src/services/user/user.service.ts
import { Repository } from 'typeorm'
import { AppDataSource } from '@/config/database'
import { User } from '@/models/entities/user.entity'
import { CreateUserDto, UpdateUserDto, UserQueryDto } from '@/models/dto/user.dto'
import { UserVo } from '@/models/vo/user.vo'
import { PageResult } from '@/types/common'
import { CacheService } from '@/utils/cache'
import { LoggerService } from '@/utils/logger'

export class UserService {
  private userRepository: Repository<User>
  private cacheService: CacheService
  private logger: LoggerService

  constructor() {
    this.userRepository = AppDataSource.getRepository(User)
    this.cacheService = new CacheService()
    this.logger = new LoggerService('UserService')
  }

  /**
   * 获取用户列表
   */
  async getUsers(query: UserQueryDto): Promise<PageResult<UserVo>> {
    try {
      const { page = 1, limit = 10, keyword, status } = query
      const queryBuilder = this.userRepository.createQueryBuilder('user')

      // 关键词搜索
      if (keyword) {
        queryBuilder.andWhere(
          '(user.username LIKE :keyword OR user.email LIKE :keyword OR user.phone LIKE :keyword)',
          { keyword: `%${keyword}%` }
        )
      }

      // 状态筛选
      if (status !== undefined) {
        queryBuilder.andWhere('user.status = :status', { status })
      }

      // 分页
      queryBuilder
        .skip((page - 1) * limit)
        .take(limit)
        .orderBy('user.created_at', 'DESC')

      const [users, total] = await queryBuilder.getManyAndCount()

      // 转换为VO
      const userVos = users.map(user => new UserVo(user))

      return {
        data: userVos,
        total,
        page,
        limit,
        pages: Math.ceil(total / limit)
      }
    } catch (error) {
      this.logger.error('获取用户列表失败', error)
      throw error
    }
  }

  /**
   * 根据ID获取用户
   */
  async getUserById(id: number): Promise<UserVo | null> {
    try {
      // 先从缓存获取
      const cacheKey = `user:${id}`
      let user = await this.cacheService.get<User>(cacheKey)

      if (!user) {
        // 缓存未命中，从数据库获取
        user = await this.userRepository.findOne({
          where: { id },
          relations: ['profile', 'roles']
        })

        if (user) {
          // 存入缓存，过期时间30分钟
          await this.cacheService.set(cacheKey, user, 1800)
        }
      }

      return user ? new UserVo(user) : null
    } catch (error) {
      this.logger.error('获取用户详情失败', error)
      throw error
    }
  }

  /**
   * 创建用户
   */
  async createUser(createUserDto: CreateUserDto): Promise<UserVo> {
    try {
      // 检查用户名是否已存在
      const existingUser = await this.userRepository.findOne({
        where: [
          { username: createUserDto.username },
          { email: createUserDto.email }
        ]
      })

      if (existingUser) {
        throw new Error('用户名或邮箱已存在')
      }

      // 创建用户
      const user = this.userRepository.create(createUserDto)
      const savedUser = await this.userRepository.save(user)

      this.logger.info('创建用户成功', { userId: savedUser.id })
      return new UserVo(savedUser)
    } catch (error) {
      this.logger.error('创建用户失败', error)
      throw error
    }
  }

  /**
   * 更新用户
   */
  async updateUser(id: number, updateUserDto: UpdateUserDto): Promise<UserVo> {
    try {
      const user = await this.userRepository.findOne({ where: { id } })
      if (!user) {
        throw new Error('用户不存在')
      }

      // 更新用户信息
      Object.assign(user, updateUserDto)
      const updatedUser = await this.userRepository.save(user)

      // 清除缓存
      await this.cacheService.del(`user:${id}`)

      this.logger.info('更新用户成功', { userId: id })
      return new UserVo(updatedUser)
    } catch (error) {
      this.logger.error('更新用户失败', error)
      throw error
    }
  }

  /**
   * 删除用户
   */
  async deleteUser(id: number): Promise<void> {
    try {
      const user = await this.userRepository.findOne({ where: { id } })
      if (!user) {
        throw new Error('用户不存在')
      }

      // 软删除
      await this.userRepository.softDelete(id)

      // 清除缓存
      await this.cacheService.del(`user:${id}`)

      this.logger.info('删除用户成功', { userId: id })
    } catch (error) {
      this.logger.error('删除用户失败', error)
      throw error
    }
  }
}

4.1.3 数据模型规范

// src/models/entities/user.entity.ts
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  DeleteDateColumn,
  OneToOne,
  ManyToMany,
  JoinTable
} from 'typeorm'
import { UserProfile } from './user-profile.entity'
import { Role } from './role.entity'

@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number

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

  @Column({ unique: true, length: 100 })
  email: string

  @Column({ length: 20, nullable: true })
  phone: string

  @Column({ length: 255 })
  password: string

  @Column({ type: 'tinyint', default: 1, comment: '状态：0-禁用，1-启用' })
  status: number

  @Column({ type: 'datetime', nullable: true, comment: '最后登录时间' })
  last_login_at: Date

  @CreateDateColumn()
  created_at: Date

  @UpdateDateColumn()
  updated_at: Date

  @DeleteDateColumn()
  deleted_at: Date

  // 关联关系
  @OneToOne(() => UserProfile, profile => profile.user)
  profile: UserProfile

  @ManyToMany(() => Role, role => role.users)
  @JoinTable({
    name: 'user_roles',
    joinColumn: { name: 'user_id', referencedColumnName: 'id' },
    inverseJoinColumn: { name: 'role_id', referencedColumnName: 'id' }
  })
  roles: Role[]
}

// src/models/dto/user.dto.ts
import { IsString, IsEmail, IsOptional, IsNumber, MinLength, MaxLength } from 'class-validator'

export class CreateUserDto {
  @IsString()
  @MinLength(3)
  @MaxLength(50)
  username: string

  @IsEmail()
  email: string

  @IsOptional()
  @IsString()
  @MaxLength(20)
  phone?: string

  @IsString()
  @MinLength(6)
  password: string
}

export class UpdateUserDto {
  @IsOptional()
  @IsString()
  @MinLength(3)
  @MaxLength(50)
  username?: string

  @IsOptional()
  @IsEmail()
  email?: string

  @IsOptional()
  @IsString()
  @MaxLength(20)
  phone?: string

  @IsOptional()
  @IsNumber()
  status?: number
}

export class UserQueryDto {
  @IsOptional()
  @IsNumber()
  page?: number

  @IsOptional()
  @IsNumber()
  limit?: number

  @IsOptional()
  @IsString()
  keyword?: string

  @IsOptional()
  @IsNumber()
  status?: number
}

// src/models/vo/user.vo.ts
import { User } from '@/models/entities/user.entity'

export class UserVo {
  id: number
  username: string
  email: string
  phone: string
  status: number
  last_login_at: Date
  created_at: Date
  updated_at: Date

  constructor(user: User) {
    this.id = user.id
    this.username = user.username
    this.email = user.email
    this.phone = user.phone
    this.status = user.status
    this.last_login_at = user.last_login_at
    this.created_at = user.created_at
    this.updated_at = user.updated_at
  }
}

4.2 API设计规范

4.2.1 路由规范

// src/routes/admin/user.routes.ts
import { Router } from 'express'
import { AdminUserController } from '@/controllers/admin/user.controller'
import { authMiddleware } from '@/middleware/auth'
import { permissionMiddleware } from '@/middleware/permission'

const router = Router()
const userController = new AdminUserController()

// 用户管理路由
router.get(
  '/users',
  authMiddleware,
  permissionMiddleware('user:view'),
  userController.getUsers.bind(userController)
)

router.get(
  '/users/:id',
  authMiddleware,
  permissionMiddleware('user:view'),
  userController.getUserById.bind(userController)
)

router.post(
  '/users',
  authMiddleware,
  permissionMiddleware('user:create'),
  userController.createUser.bind(userController)
)

router.put(
  '/users/:id',
  authMiddleware,
  permissionMiddleware('user:update'),
  userController.updateUser.bind(userController)
)

router.delete(
  '/users/:id',
  authMiddleware,
  permissionMiddleware('user:delete'),
  userController.deleteUser.bind(userController)
)

export default router

4.2.2 响应格式规范

// src/utils/response.ts
import { Response } from 'express'

export interface ApiResponseData<T = any> {
  code: number
  message: string
  data: T
  timestamp: number
}

export class ApiResponse {
  /**
   * 成功响应
   */
  static success<T>(res: Response, data: T, message = '操作成功'): Response {
    return res.json({
      code: 200,
      message,
      data,
      timestamp: Date.now()
    })
  }

  /**
   * 错误响应
   */
  static error(res: Response, message = '操作失败', code = 500): Response {
    return res.status(code).json({
      code,
      message,
      data: null,
      timestamp: Date.now()
    })
  }

  /**
   * 参数错误响应
   */
  static badRequest(res: Response, message = '参数错误'): Response {
    return this.error(res, message, 400)
  }

  /**
   * 未授权响应
   */
  static unauthorized(res: Response, message = '未授权访问'): Response {
    return this.error(res, message, 401)
  }

  /**
   * 禁止访问响应
   */
  static forbidden(res: Response, message = '禁止访问'): Response {
    return this.error(res, message, 403)
  }

  /**
   * 资源不存在响应
   */
  static notFound(res: Response, message = '资源不存在'): Response {
    return this.error(res, message, 404)
  }
}

4.3 数据库操作规范

4.3.1 查询优化规范

// src/services/travel/travel.service.ts
export class TravelService {
  /**
   * 获取旅行活动列表（优化版本）
   */
  async getTravelActivities(query: TravelQueryDto): Promise<PageResult<TravelVo>> {
    const { page = 1, limit = 10, city, start_date, end_date, status } = query
    
    // 使用QueryBuilder进行复杂查询
    const queryBuilder = this.travelRepository
      .createQueryBuilder('travel')
      .leftJoinAndSelect('travel.creator', 'creator')
      .leftJoinAndSelect('travel.participants', 'participants')
      .select([
        'travel.id',
        'travel.title',
        'travel.description',
        'travel.city',
        'travel.start_date',
        'travel.end_date',
        'travel.max_participants',
        'travel.status',
        'travel.created_at',
        'creator.id',
        'creator.username',
        'creator.avatar_url',
        'participants.id'
      ])

    // 城市筛选
    if (city) {
      queryBuilder.andWhere('travel.city = :city', { city })
    }

    // 日期范围筛选
    if (start_date) {
      queryBuilder.andWhere('travel.start_date >= :start_date', { start_date })
    }
    if (end_date) {
      queryBuilder.andWhere('travel.end_date <= :end_date', { end_date })
    }

    // 状态筛选
    if (status !== undefined) {
      queryBuilder.andWhere('travel.status = :status', { status })
    }

    // 分页和排序
    queryBuilder
      .skip((page - 1) * limit)
      .take(limit)
      .orderBy('travel.created_at', 'DESC')

    const [travels, total] = await queryBuilder.getManyAndCount()

    return {
      data: travels.map(travel => new TravelVo(travel)),
      total,
      page,
      limit,
      pages: Math.ceil(total / limit)
    }
  }

  /**
   * 批量更新操作
   */
  async batchUpdateTravelStatus(ids: number[], status: number): Promise<void> {
    await this.travelRepository
      .createQueryBuilder()
      .update(Travel)
      .set({ status, updated_at: new Date() })
      .where('id IN (:...ids)', { ids })
      .execute()
  }
}

4.3.2 事务处理规范

// src/services/order/order.service.ts
import { DataSource } from 'typeorm'

export class OrderService {
  constructor(private dataSource: DataSource) {}

  /**
   * 创建订单（事务处理）
   */
  async createOrder(createOrderDto: CreateOrderDto): Promise<OrderVo> {
    const queryRunner = this.dataSource.createQueryRunner()
    await queryRunner.connect()
    await queryRunner.startTransaction()

    try {
      // 1. 创建订单
      const order = queryRunner.manager.create(Order, {
        ...createOrderDto,
        order_no: this.generateOrderNo(),
        status: OrderStatus.PENDING
      })
      const savedOrder = await queryRunner.manager.save(order)

      // 2. 创建订单项
      const orderItems = createOrderDto.items.map(item => 
        queryRunner.manager.create(OrderItem, {
          ...item,
          order_id: savedOrder.id
        })
      )
      await queryRunner.manager.save(orderItems)

      // 3. 更新库存
      for (const item of createOrderDto.items) {
        await queryRunner.manager.decrement(
          Product,
          { id: item.product_id },
          'stock',
          item.quantity
        )
      }

      // 4. 记录操作日志
      const log = queryRunner.manager.create(OperationLog, {
        user_id: createOrderDto.user_id,
        action: 'CREATE_ORDER',
        target_type: 'ORDER',
        target_id: savedOrder.id,
        details: JSON.stringify(createOrderDto)
      })
      await queryRunner.manager.save(log)

      await queryRunner.commitTransaction()
      
      return new OrderVo(savedOrder)
    } catch (error) {
      await queryRunner.rollbackTransaction()
      throw error
    } finally {
      await queryRunner.release()
    }
  }
}

5. 质量保证

5.1 测试策略

5.1.1 单元测试

// tests/unit/services/user.service.spec.ts
import { UserService } from '@/services/user/user.service'
import { User } from '@/models/entities/user.entity'
import { CreateUserDto } from '@/models/dto/user.dto'

describe('UserService', () => {
  let userService: UserService
  let mockUserRepository: any

  beforeEach(() => {
    mockUserRepository = {
      findOne: jest.fn(),
      create: jest.fn(),
      save: jest.fn(),
      softDelete: jest.fn(),
      createQueryBuilder: jest.fn()
    }
    
    userService = new UserService()
    userService['userRepository'] = mockUserRepository
  })

  describe('createUser', () => {
    it('should create user successfully', async () => {
      const createUserDto: CreateUserDto = {
        username: 'testuser',
        email: 'test@example.com',
        password: 'password123'
      }

      const mockUser = { id: 1, ...createUserDto }
      
      mockUserRepository.findOne.mockResolvedValue(null)
      mockUserRepository.create.mockReturnValue(mockUser)
      mockUserRepository.save.mockResolvedValue(mockUser)

      const result = await userService.createUser(createUserDto)

      expect(result.username).toBe(createUserDto.username)
      expect(result.email).toBe(createUserDto.email)
      expect(mockUserRepository.save).toHaveBeenCalledWith(mockUser)
    })

    it('should throw error when user already exists', async () => {
      const createUserDto: CreateUserDto = {
        username: 'testuser',
        email: 'test@example.com',
        password: 'password123'
      }

      mockUserRepository.findOne.mockResolvedValue({ id: 1 })

      await expect(userService.createUser(createUserDto))
        .rejects.toThrow('用户名或邮箱已存在')
    })
  })
})

5.1.2 集成测试

// tests/integration/controllers/user.controller.spec.ts
import request from 'supertest'
import { app } from '@/app'
import { AppDataSource } from '@/config/database'

describe('User Controller Integration Tests', () => {
  let authToken: string

  beforeAll(async () => {
    await AppDataSource.initialize()
    
    // 获取认证token
    const loginResponse = await request(app)
      .post('/api/auth/login')
      .send({
        username: 'admin',
        password: 'admin123'
      })
    
    authToken = loginResponse.body.data.access_token
  })

  afterAll(async () => {
    await AppDataSource.destroy()
  })

  describe('GET /api/admin/users', () => {
    it('should return user list', async () => {
      const response = await request(app)
        .get('/api/admin/users')
        .set('Authorization', `Bearer ${authToken}`)
        .expect(200)

      expect(response.body.code).toBe(200)
      expect(response.body.data).toHaveProperty('data')
      expect(response.body.data).toHaveProperty('total')
      expect(Array.isArray(response.body.data.data)).toBe(true)
    })

    it('should return 401 without auth token', async () => {
      await request(app)
        .get('/api/admin/users')
        .expect(401)
    })
  })

  describe('POST /api/admin/users', () => {
    it('should create user successfully', async () => {
      const newUser = {
        username: 'newuser',
        email: 'newuser@example.com',
        password: 'password123'
      }

      const response = await request(app)
        .post('/api/admin/users')
        .set('Authorization', `Bearer ${authToken}`)
        .send(newUser)
        .expect(200)

      expect(response.body.code).toBe(200)
      expect(response.body.data.username).toBe(newUser.username)
      expect(response.body.data.email).toBe(newUser.email)
    })
  })
})

5.2 代码质量检查

5.2.1 ESLint配置

// .eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser',
  extends: [
    '@typescript-eslint/recommended',
    'prettier'
  ],
  plugins: ['@typescript-eslint'],
  rules: {
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/explicit-function-return-type': 'warn',
    '@typescript-eslint/no-explicit-any': 'warn',
    'prefer-const': 'error',
    'no-var': 'error'
  }
}

5.2.2 代码审查流程

开发者提交Pull Request
自动化检查（ESLint、TypeScript、测试）
同行代码审查
技术负责人审查
合并到主分支

6. 部署和运维

6.1 Docker配置

6.1.1 Dockerfile

# Dockerfile
FROM node:18-alpine

WORKDIR /app

# 复制package文件
COPY package*.json ./

# 安装依赖
RUN npm ci --only=production

# 复制源代码
COPY . .

# 构建应用
RUN npm run build

# 暴露端口
EXPOSE 3000

# 启动应用
CMD ["npm", "start"]

6.1.2 Docker Compose

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=mysql
      - REDIS_HOST=redis
    depends_on:
      - mysql
      - redis
    volumes:
      - ./logs:/app/logs

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: jiebanke
      MYSQL_USER: jiebanke
      MYSQL_PASSWORD: password
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  mysql_data:
  redis_data:

6.2 CI/CD配置

6.2.1 GitHub Actions

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: test
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3
      
      redis:
        image: redis:7-alpine
        options: >-
          --health-cmd="redis-cli ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3

    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run linting
      run: npm run lint
    
    - name: Run tests
      run: npm run test
      env:
        DB_HOST: localhost
        DB_PORT: 3306
        DB_USERNAME: root
        DB_PASSWORD: root
        DB_DATABASE: test
        REDIS_HOST: localhost
        REDIS_PORT: 6379

  deploy:
    needs: test
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Build Docker image
      run: docker build -t jiebanke/backend:${{ github.sha }} .
    
    - name: Push to registry
      run: |
        echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
        docker push jiebanke/backend:${{ github.sha }}
    
    - name: Deploy to server
      uses: appleboy/ssh-action@v0.1.5
      with:
        host: ${{ secrets.HOST }}
        username: ${{ secrets.USERNAME }}
        key: ${{ secrets.SSH_KEY }}
        script: |
          docker pull jiebanke/backend:${{ github.sha }}
          docker stop jiebanke-backend || true
          docker rm jiebanke-backend || true
          docker run -d --name jiebanke-backend \
            -p 3000:3000 \
            --env-file /opt/jiebanke/.env \
            jiebanke/backend:${{ github.sha }}

6.3 监控和日志

6.3.1 日志配置

// src/utils/logger.ts
import winston from 'winston'
import DailyRotateFile from 'winston-daily-rotate-file'

export class LoggerService {
  private logger: winston.Logger

  constructor(private context: string) {
    this.logger = winston.createLogger({
      level: process.env.LOG_LEVEL || 'info',
      format: winston.format.combine(
        winston.format.timestamp(),
        winston.format.errors({ stack: true }),
        winston.format.json()
      ),
      defaultMeta: { service: 'jiebanke-backend', context: this.context },
      transports: [
        // 控制台输出
        new winston.transports.Console({
          format: winston.format.combine(
            winston.format.colorize(),
            winston.format.simple()
          )
        }),
        
        // 错误日志文件
        new DailyRotateFile({
          filename: 'logs/error-%DATE%.log',
          datePattern: 'YYYY-MM-DD',
          level: 'error',
          maxSize: '20m',
          maxFiles: '14d'
        }),
        
        // 应用日志文件
        new DailyRotateFile({
          filename: 'logs/app-%DATE%.log',
          datePattern: 'YYYY-MM-DD',
          maxSize: '20m',
          maxFiles: '14d'
        })
      ]
    })
  }

  info(message: string, meta?: any) {
    this.logger.info(message, meta)
  }

  error(message: string, error?: any) {
    this.logger.error(message, { error: error?.stack || error })
  }

  warn(message: string, meta?: any) {
    this.logger.warn(message, meta)
  }

  debug(message: string, meta?: any) {
    this.logger.debug(message, meta)
  }
}

6.3.2 性能监控

// src/middleware/monitor.ts
import { Request, Response, NextFunction } from 'express'
import { LoggerService } from '@/utils/logger'

const logger = new LoggerService('Monitor')

export const performanceMonitor = (req: Request, res: Response, next: NextFunction) => {
  const startTime = Date.now()
  
  res.on('finish', () => {
    const duration = Date.now() - startTime
    const { method, originalUrl, ip } = req
    const { statusCode } = res
    
    // 记录请求日志
    logger.info('HTTP Request', {
      method,
      url: originalUrl,
      statusCode,
      duration,
      ip,
      userAgent: req.get('User-Agent')
    })
    
    // 慢查询告警
    if (duration > 2000) {
      logger.warn('Slow Request', {
        method,
        url: originalUrl,
        duration
      })
    }
    
    // 错误状态告警
    if (statusCode >= 500) {
      logger.error('Server Error', {
        method,
        url: originalUrl,
        statusCode
      })
    }
  })
  
  next()
}

7. 总结

本开发文档详细规划了解班客后端管理系统的开发计划，包括：

7.1 开发计划

总工期：58个工作日
团队规模：2-3名后端开发工程师
关键里程碑：基础框架、核心业务、管理功能、优化部署

7.2 技术架构

后端框架：Express.js + TypeScript
数据库：MySQL + Redis
ORM框架：TypeORM
认证授权：JWT + RBAC

7.3 质量保证

代码规范：ESLint + Prettier
测试策略：单元测试 + 集成测试
性能优化：查询优化、缓存策略
监控体系：日志监控 + 性能监控

7.4 部署运维

容器化：Docker + Docker Compose
CI/CD：GitHub Actions自动化部署
监控日志：Winston日志系统
性能监控：请求监控和告警

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

40 KiB Raw Permalink Blame History Unescape Escape

后端管理开发文档

1. 项目概述

1.1 项目简介

1.2 技术栈

1.3 项目结构

2. 开发环境搭建

2.1 环境要求

2.2 环境搭建步骤

2.2.1 克隆项目

2.2.2 安装依赖

2.2.3 配置环境变量

2.2.4 数据库初始化

2.2.5 启动开发服务器

2.3 开发工具配置

2.3.1 VSCode配置

2.3.2 数据库工具

3. 开发计划与任务分解

3.1 开发阶段划分

阶段一：基础框架搭建（预计8个工作日）

阶段二：核心业务开发（预计25个工作日）

阶段三：管理功能开发（预计15个工作日）

阶段四：优化和部署（预计10个工作日）

3.2 详细任务分解

3.2.1 阶段一：基础框架搭建

任务1.1：项目初始化（2个工作日）

任务1.2：数据库设计和迁移（3个工作日）

任务1.3：基础中间件开发（2个工作日）

任务1.4：认证授权系统（1个工作日）

3.2.2 阶段二：核心业务开发

任务2.1：用户管理系统（6个工作日）

任务2.2：旅行结伴功能（7个工作日）

任务2.3：动物认领功能（6个工作日）

任务2.4：订单支付系统（6个工作日）

3.2.3 阶段三：管理功能开发

任务3.1：管理后台API（5个工作日）

任务3.2：数据统计分析（4个工作日）

任务3.3：系统配置管理（3个工作日）

任务3.4：日志审计功能（3个工作日）

3.2.4 阶段四：优化和部署

任务4.1：性能优化（3个工作日）

任务4.2：安全加固（2个工作日）

任务4.3：测试和修复（3个工作日）

任务4.4：部署和监控（2个工作日）

4. 开发规范

4.1 代码规范

4.1.1 项目结构规范

4.1.2 服务层规范

4.1.3 数据模型规范

4.2 API设计规范

4.2.1 路由规范

4.2.2 响应格式规范

4.3 数据库操作规范

4.3.1 查询优化规范

4.3.2 事务处理规范

5. 质量保证

5.1 测试策略

5.1.1 单元测试

5.1.2 集成测试

5.2 代码质量检查

5.2.1 ESLint配置

5.2.2 代码审查流程

6. 部署和运维

6.1 Docker配置

6.1.1 Dockerfile

6.1.2 Docker Compose

6.2 CI/CD配置

6.2.1 GitHub Actions

6.3 监控和日志

6.3.1 日志配置

6.3.2 性能监控

7. 总结

7.1 开发计划

7.2 技术架构

7.3 质量保证

7.4 部署运维

40 KiB

Raw Permalink Blame History