# 数据模型和Schema变更

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | 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实体建立多对一关系映射

**优化重点**: 保持现有数据模型不变，新增文件管理功能，优化查询性能和验证逻辑

### TypeScript接口定义
```typescript
// 用户实体接口
export interface User {
  id: number;
  username: string;
  email: string | null;
  password: string;
  roles: Role[];
  createdAt: Date;
  updatedAt: Date;
}

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

// 用户创建DTO
export interface CreateUserDto {
  username: string;
  email?: string;
  password: string;
  roleIds?: number[];
}

// 用户更新DTO
export interface UpdateUserDto {
  username?: string;
  email?: string | null;
  password?: string;
  roleIds?: number[];
}

// 文件实体接口
export interface File {
  id: number;
  name: string;
  type: string | null;
  size: number | null;
  path: string;
  description: string | null;
  uploadUserId: number;
  uploadUser: User;
  uploadTime: Date;
  lastUpdated: Date | null;
  createdAt: Date;
  updatedAt: Date;
  fullUrl: Promise<string>; // 异步获取预签名URL
}

// 文件创建DTO
export interface CreateFileDto {
  name: string;
  type?: string;
  size?: number;
  description?: string;
  uploadUserId: number;
}

// 多部分上传策略响应
export interface MultipartUploadPolicy {
  uploadId: string;
  bucket: string;
  key: string;
  host: string;
  partUrls: string[];
}

// 上传策略响应
export interface UploadPolicy {
  uploadPolicy: {
    'x-amz-algorithm': string;
    'x-amz-credential': string;
    'x-amz-date': string;
    'x-amz-security-token'?: string;
    policy: string;
    'x-amz-signature': string;
    host: string;
    key: string;
    bucket: string;
  };
}

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

### 数据关系
- **User ↔ Role**: 多对多关系，通过中间表关联
- **User → (createdAt, updatedAt)**: 自动时间戳管理
- **Role → permissions**: 字符串数组存储权限列表

## Schema集成策略
- **数据库变更要求**: 新增文件管理表，优化现有表结构
- **新表**: file表（文件管理）
- **修改的表**: 无结构性变更
- **新索引**: 为文件查询字段添加索引（name, uploadUserId, uploadTime）
- **迁移策略**: 使用TypeORM迁移工具，确保数据完整性

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