mini-starter/docs/architecture/data-model-schema-changes.md

数据模型和Schema变更

版本信息

版本	日期	描述	作者
3.1	2025-10-15	更新乘客信息支持多种证件类型	Winston
3.0	2025-10-15	更新为出行服务数据模型	Winston

现有数据模型状态

用户模型:

• 现状: 设计良好，包含完整的用户管理和权限系统
• 关键属性:
  • id: number - 主键标识符
  • username: string - 唯一用户名（主要登录标识）
  • email: string | null - 可选邮箱地址
  • password: string - 加密密码（bcrypt哈希）
  • avatarFileId: number | null - 头像文件ID
  • roles: Role[] - 用户角色多对多关系
• 关系:
  • 与Role实体建立正确的多对多关系映射
  • 与File实体建立头像文件的多对一关系映射

文件管理模型:

• 现状: 新增完整的文件管理系统，支持MinIO对象存储
• 关键属性:
  • id: number - 主键标识符
  • name: string - 文件名
  • path: string - MinIO存储路径
  • size: number - 文件大小（字节）
  • type: string - 文件类型
  • uploadUserId: number - 上传用户ID
  • uploadTime: Date - 上传时间
• 关系: 与User实体建立多对一关系映射

新增出行服务数据模型

订单模型:

• 用途: 管理出行订单信息
• 关键属性:
  • id: number - 主键标识符
  • userId: number - 用户ID
  • routeId: number - 路线ID
  • passengerCount: number - 乘客数量
  • totalAmount: number - 订单总金额
  • status: string - 订单状态（待支付、待出发、行程中、已完成、已取消）
  • paymentStatus: string - 支付状态
  • passengerSnapshots: JSON - 乘客信息快照数组（下单时的多个乘客信息）
  • routeSnapshot: JSON - 路线信息快照（下单时的路线信息）
  • createdAt: Date - 创建时间

乘客模型:

• 用途: 管理乘客信息
• 关键属性:
  • id: number - 主键标识符
  • userId: number - 用户ID
  • name: string - 乘客姓名
  • idType: IdType - 证件类型（身份证、港澳通行证、台湾通行证、护照等）
  • idNumber: string - 证件号码
  • phone: string - 手机号
  • isDefault: boolean - 是否默认乘客

活动模型:

• 用途: 管理出行活动，关联多条路线
• 关键属性:
  • id: number - 主键标识符
  • name: string - 活动名称
  • description: string - 活动描述
  • type: ActivityType - 活动类型（去程活动/返程活动）
  • startDate: Date - 活动开始日期
  • endDate: Date - 活动结束日期
  • status: ActivityStatus - 活动状态（进行中、已结束、已取消）
  • createdAt: Date - 创建时间

路线模型:

• 用途: 管理出行路线，关联到活动
• 关键属性:
  • id: number - 主键标识符
  • activityId: number - 关联的活动ID
  • startPoint: string - 上车点
  • endPoint: string - 下车点
  • departureTime: Date - 出发时间
  • vehicleType: string - 车型
  • maxPassengers: number - 最大乘客数
  • price: number - 价格

积分模型:

• 用途: 管理用户积分（MVP阶段暂不实现）
• 关键属性:
  • id: number - 主键标识符
  • userId: number - 用户ID
  • points: number - 积分余额
  • earnedPoints: number - 累计获得积分
  • usedPoints: number - 累计使用积分

TypeScript接口定义

// 用户实体接口
export interface User {
  id: number;
  username: string;
  email: string | null;
  password: string;
  avatarFileId: number | null;
  avatarFile?: File; // 头像文件关联
  roles: Role[];
  createdAt: Date;
  updatedAt: Date;
}

// 角色实体接口
export interface Role {
  id: number;
  name: string;
  permissions: string[];
  users: User[];
  createdAt: Date;
  updatedAt: Date;
}

// 订单实体接口
export interface Order {
  id: number;
  userId: number;
  user: User;
  routeId: number;
  route: Route;
  activityId: number;
  activity: Activity; // 订单关联的活动
  passengerCount: number;
  totalAmount: number;
  status: OrderStatus;
  paymentStatus: PaymentStatus;
  passengerSnapshots: PassengerSnapshot[]; // 下单时的多个乘客信息快照
  routeSnapshot: RouteSnapshot; // 下单时的路线信息快照
  activitySnapshot: ActivitySnapshot; // 下单时的活动信息快照
  passengers: Passenger[];
  createdAt: Date;
  updatedAt: Date;
}

// 乘客实体接口
export interface Passenger {
  id: number;
  userId: number;
  user: User;
  name: string;
  idType: IdType; // 证件类型
  idNumber: string; // 证件号码
  phone: string;
  isDefault: boolean;
  createdAt: Date;
  updatedAt: Date;
}

// 路线实体接口
export interface Route {
  id: number;
  startPoint: string;
  endPoint: string;
  departureTime: Date;
  vehicleType: VehicleType;
  maxPassengers: number;
  price: number;
  availableSeats: number;
  createdAt: Date;
  updatedAt: Date;
}

// 乘客信息快照接口
export interface PassengerSnapshot {
  name: string;
  idType: IdType; // 证件类型
  idNumber: string; // 证件号码
  phone: string;
  isDefault: boolean;
}

// 路线信息快照接口
export interface RouteSnapshot {
  startPoint: string;
  endPoint: string;
  departureTime: Date;
  vehicleType: VehicleType;
  maxPassengers: number;
  price: number;
}

// 活动信息快照接口
// 用于订单中保存下单时的活动信息，确保历史数据完整性
export interface ActivitySnapshot {
  id: number;
  title: string;
  description: string;
  startTime: Date;
  endTime: Date;
  maxParticipants: number;
  currentParticipants: number;
  status: ActivityStatus;
  createdAt: Date;
}

// 积分实体接口（MVP阶段暂不实现）
export interface Points {
  id: number;
  userId: number;
  user: User;
  points: number;
  earnedPoints: number;
  usedPoints: number;
  lastUpdated: Date;
}

// 枚举定义
export enum OrderStatus {
  PENDING_PAYMENT = '待支付',
  WAITING_DEPARTURE = '待出发',
  IN_PROGRESS = '行程中',
  COMPLETED = '已完成',
  CANCELLED = '已取消'
}

export enum PaymentStatus {
  PENDING = '待支付',
  PAID = '已支付',
  FAILED = '支付失败',
  REFUNDED = '已退款'
}

export enum VehicleType {
  CARPOOL = '拼车',
  BUSINESS = '商务车',
  CHARTER = '包车'
}

export enum IdType {
  ID_CARD = '身份证',
  HONG_KONG_MACAO_PASS = '港澳通行证',
  TAIWAN_PASS = '台湾通行证',
  PASSPORT = '护照',
  OTHER = '其他证件'
}

// 分页响应接口
export interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    current: number;
    pageSize: number;
    totalPages: number;
  };
}

数据关系

• User ↔ Role: 多对多关系，通过中间表关联
• User → Order: 一对多关系，一个用户可以创建多个订单
• User → Passenger: 一对多关系，一个用户可以管理多个乘客
• Route → Order: 一对多关系，一条路线可以有多个订单
• Order ↔ Passenger: 多对多关系，一个订单可以有多个乘客，一个乘客可以出现在多个订单中
• User → (createdAt, updatedAt): 自动时间戳管理
• Role → permissions: 字符串数组存储权限列表

快照设计说明:

• passengerSnapshots: 存储下单时的多个乘客信息快照数组，确保订单历史数据完整性
• routeSnapshot: 存储下单时的路线信息快照，防止路线信息变更影响历史订单

Schema集成策略

• 数据库变更要求: 新增出行服务数据表，扩展现有用户管理
• 新表: order表（订单管理）、passenger表（乘客管理）、route表（路线管理）
• 可选表: points表（积分管理，MVP阶段暂不实现）
• 修改的表: 无结构性变更
• 新索引: 为订单查询字段添加索引（userId, status, createdAt）、为路线查询字段添加索引（startPoint, endPoint, departureTime）
• 迁移策略: 使用TypeORM迁移工具，确保数据完整性

向后兼容性

• 保持所有现有API端点不变
• 确保现有数据查询继续正常工作
• 不修改任何现有字段定义
• 新增功能通过可选字段或新端点实现