# 数据模型和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接口定义
```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;
  travelMode: TravelMode; // 出行方式：拼车/包车
  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;
  travelMode: TravelMode; // 出行方式：拼车/包车
  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 {
  BUS = '大巴',
  MINIBUS = '中巴',
  CAR = '小车',
  BUSINESS = '商务车'
}

// 出行方式枚举 - 服务模式
export enum TravelMode {
  CARPOOL = '拼车',
  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端点不变
- 确保现有数据查询继续正常工作
- 不修改任何现有字段定义
- 新增功能通过可选字段或新端点实现