327
docs/02-数据模型设计.md
Normal file
327
docs/02-数据模型设计.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# 模块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<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）
|
||||
|
||||
```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：连接管理功能
|
||||
Reference in New Issue
Block a user