# 模块02：数据模型设计 --- ## 🎨 UI设计系统概览 > **完整设计系统文档请参考：** `UI设计系统.md` ### 核心设计原则 - **现代简约**：界面清晰，层次分明 - **专业高效**：减少操作步骤，提升工作效率 - **一致性**：统一的视觉语言和交互模式 - **可访问性**：符合WCAG 2.1 AA标准 ### 关键设计令牌 **颜色系统：** - 主色：`#0d6efd`（操作按钮、选中状态） - 成功：`#198754`（连接成功状态） - 危险：`#dc3545`（删除操作、错误提示） - 深灰：`#212529`（导航栏背景） - 浅灰：`#e9ecef`（工具栏背景） **字体系统：** - 字体族：系统字体栈（-apple-system, Segoe UI, Roboto等） - 正文：14px，行高1.5 - 标题：20-32px，行高1.2-1.4 - 小号文字：12px（文件大小、日期等） **间距系统：** - 基础单位：8px - 标准间距：16px（1rem） - 组件内边距：8px-16px **组件规范：** - 导航栏：高度48px，深色背景 - 工具栏：浅灰背景，按钮间距8px - 文件项：最小高度44px，悬停效果150ms - 按钮：圆角4px，过渡150ms **交互规范：** - 悬停效果：150ms过渡 - 触摸目标：最小44x44px - 键盘导航：Tab、Enter、Delete、F2、F5、Esc - 焦点状态：2px蓝色轮廓 **响应式断点：** - 移动端：< 768px（双面板垂直排列） - 平板：768px - 1024px - 桌面：> 1024px（标准布局） --- ## 2.1 连接实体（Connection.java） ### 字段说明 ```java package com.sftp.manager.model; import lombok.Data; import javax.persistence.*; import java.time.LocalDateTime; @Data @Entity @Table(name = "connections") public class Connection { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; // 连接ID（主键） @Column(nullable = false) private String name; // 连接名称（用户自定义） @Column(nullable = false) private String host; // SFTP服务器地址 private Integer port; // SFTP端口（默认22） @Column(nullable = false) private String username; // 用户名 @Column(columnDefinition = "TEXT") private String password; // 密码（加密存储） private String privateKeyPath; // 私钥路径（可选） private String passPhrase; // 私钥密码（可选） private Integer connectTimeout; // 连接超时时间 private String rootPath; // 默认登录后路径 @Column(name = "created_at") private LocalDateTime createdAt; // 创建时间 @Column(name = "updated_at") private LocalDateTime updatedAt; // 更新时间 @PrePersist protected void onCreate() { createdAt = LocalDateTime.now(); updatedAt = LocalDateTime.now(); if (port == null) { port = 22; } if (connectTimeout == null) { connectTimeout = 10000; } } @PreUpdate protected void onUpdate() { updatedAt = LocalDateTime.now(); } } ``` ### 设计要点 1. **密码字段加密**：建议使用AES或Base64加密存储 2. **双重认证支持**：支持密码认证和密钥认证两种方式 3. **时间自动记录**：使用`@PrePersist`和`@PreUpdate`自动设置创建和更新时间 4. **默认值设置**：端口默认22，超时默认10秒 ## 2.2 文件信息实体（FileInfo.java） ### 字段说明 ```java package com.sftp.manager.model; import lombok.Data; import java.time.LocalDateTime; @Data public class FileInfo { private String name; // 文件名 private String path; // 完整路径 private long size; // 文件大小（字节） private boolean isDirectory; // 是否为目录 private LocalDateTime modifiedTime; // 修改时间 private String permissions; // 文件权限（如：-rw-r--r--） } ``` ### 设计要点 1. **DTO模式**：不持久化到数据库，仅用于数据传输 2. **统一表示**：统一本地文件和SFTP文件的表示方式 3. **完整元数据**：包含文件名、路径、大小、类型、修改时间、权限等 ## 2.3 通用响应对象（ApiResponse.java） ### 设计说明 ```java package com.sftp.manager.dto; import lombok.Data; @Data public class ApiResponse { private boolean success; // 操作是否成功 private String message; // 响应消息 private T data; // 响应数据 private String error; // 错误信息 public static ApiResponse success(T data) { ApiResponse response = new ApiResponse<>(); response.setSuccess(true); response.setData(data); return response; } public static ApiResponse success(String message, T data) { ApiResponse response = new ApiResponse<>(); response.setSuccess(true); response.setMessage(message); response.setData(data); return response; } public static ApiResponse error(String message) { ApiResponse response = new ApiResponse<>(); response.setSuccess(false); response.setMessage(message); return response; } public static ApiResponse error(String message, String error) { ApiResponse response = new ApiResponse<>(); response.setSuccess(false); response.setMessage(message); response.setError(error); return response; } } ``` ### 使用场景 1. **统一响应格式**：所有API返回统一的结构 2. **便于前端处理**：前端可以根据success字段判断操作结果 3. **泛型支持**：灵活适配不同数据类型 4. **静态工厂方法**：简化对象创建 ## 2.4 数据传输对象（DTO） ### 2.4.1 连接请求DTO（ConnectionRequest.java） ```java package com.sftp.manager.dto; import lombok.Data; @Data public class ConnectionRequest { private Long id; // 连接ID（用于保存配置） private String name; // 连接名称 private String host; // 主机地址 private Integer port; // 端口 private String username; // 用户名 private String password; // 密码 private String privateKeyPath; // 私钥路径 private String passPhrase; // 私钥密码 } ``` ### 2.4.2 文件操作请求DTO（FileOperationRequest.java） ```java package com.sftp.manager.dto; import lombok.Data; @Data public class FileOperationRequest { private String sessionId; // 会话ID（标识是本地还是哪个SFTP连接） private String path; // 操作的文件路径 private String newName; // 新文件名（重命名使用） private String targetPath; // 目标路径（移动/复制使用） private String targetSessionId; // 目标会话ID（跨服务器传输使用） } ``` ### 2.4.3 文件列表请求DTO（FileListRequest.java） ```java package com.sftp.manager.dto; import lombok.Data; @Data public class FileListRequest { private String sessionId; // 会话ID（"local"表示本地，否则为SFTP连接ID） private String path; // 要浏览的目录路径 } ``` ## 2.5 文件传输请求DTO（TransferRequest.java） ```java package com.sftp.manager.dto; import lombok.Data; @Data public class TransferRequest { private String sourceSessionId; // 源会话ID private String sourcePath; // 源文件路径 private String targetSessionId; // 目标会话ID private String targetPath; // 目标路径 } ``` ## 实施步骤 1. **创建实体类** ``` # Connection.java touch src/main/java/com/sftp/manager/model/Connection.java # FileInfo.java touch src/main/java/com/sftp/manager/model/FileInfo.java ``` 2. **创建DTO类** ``` # ApiResponse.java touch src/main/java/com/sftp/manager/dto/ApiResponse.java # ConnectionRequest.java touch src/main/java/com/sftp/manager/dto/ConnectionRequest.java # FileOperationRequest.java touch src/main/java/com/sftp/manager/dto/FileOperationRequest.java # FileListRequest.java touch src/main/java/com/sftp/manager/dto/FileListRequest.java # TransferRequest.java touch src/main/java/com/sftp/manager/dto/TransferRequest.java ``` 3. **验证文件创建** ``` ls -la src/main/java/com/sftp/manager/model/ ls -la src/main/java/com/sftp/manager/dto/ ``` 4. **编译测试** ``` mvn clean compile ``` ## 注意事项 1. **Lombok注解**：`@Data`自动生成getter/setter/toString等方法 2. **JPA注解**：`@Entity`、`@Table`、`@Id`等用于数据库映射 3. **DTO vs Entity**：DTO用于数据传输，Entity用于数据库持久化 4. **序列化**：所有DTO都需要可序列化（JSON） ## 下一步 完成模块02后，继续模块03：连接管理功能