sftp-manager/docs/02-数据模型设计.md

模块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）

字段说明

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）

字段说明

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）

设计说明

package com.sftp.manager.dto;

import lombok.Data;

@Data
public class ApiResponse<T> {
    private boolean success;            // 操作是否成功
    private String message;             // 响应消息
    private T data;                     // 响应数据
    private String error;               // 错误信息

    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setSuccess(true);
        response.setData(data);
        return response;
    }

    public static <T> ApiResponse<T> success(String message, T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setSuccess(true);
        response.setMessage(message);
        response.setData(data);
        return response;
    }

    public static <T> ApiResponse<T> error(String message) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setSuccess(false);
        response.setMessage(message);
        return response;
    }

    public static <T> ApiResponse<T> error(String message, String error) {
        ApiResponse<T> 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）

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）

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）

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）

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：连接管理功能