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

数据模型和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接口定义

// 用户实体接口
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端点不变
• 确保现有数据查询继续正常工作
• 不修改任何现有字段定义
• 新增功能通过可选字段或新端点实现